# Tutorial: conectar ao Spaceman e criar um app

Este guia ensina, passo a passo, a criar um app para o Spaceman (Space), testar num hub de teste e
instalar no hub de uma pessoa. Ele foi escrito para ser seguido por um agente de IA ou por quem
programa. Tudo aqui foi testado no hub 1.10.12. A referência completa da interface está em
[APP-INTERFACE.md](APP-INTERFACE.md); este guia traz o caminho que funciona e as armadilhas.

## 1. O que é um app do Spaceman

- **Um app é uma página web** (HTML, CSS e JavaScript) com um manifesto `spaceman-app.yaml`. Não há
  build, framework nem servidor próprio: o **hub** da pessoa serve a página em `/a/<id>/`.
- **Ele abre em qualquer aparelho:** como janela no painel desktop, na web (`/view`) e no celular,
  e no relógio como print.
- **Ele roda isolado.** O hub serve a página com `Content-Security-Policy: sandbox`, então ela não
  vê o cookie do aparelho nem o `localStorage`. Ela fala com o hub só pelo `/app.js`, que usa um
  token do próprio app.
- **Ele só faz o que declarou** em `capacidades`. Guardar os próprios dados não precisa de
  capacidade.

```
meu-app/
  spaceman-app.yaml   manifesto (obrigatório)
  index.html          página de entrada
  icone.svg           opcional
  ...                 outros arquivos (js, css, imagens), servidos em /a/<id>/<arquivo>
```

## 2. Um hub de teste no seu computador

Teste num hub descartável antes de tocar no hub de alguém. O pacote do servidor é público.

Requisitos: Node 20 ou mais novo, `curl`, `tar` e `python3`.

```bash
mkdir -p ~/space-teste && cd ~/space-teste
URL=$(curl -s https://space.dynami.art/downloads/spaceman/latest.json | python3 -c "import json,sys;print(json.load(sys.stdin)['servidor']['hub']['url'])")
curl -sfL "$URL" -o hub.tar.gz && tar xzf hub.tar.gz
cd spaceman-hub
SPACEMAN_HUB_PORT=17400 SPACEMAN_HUB_DATA=$HOME/space-teste/dados node hub.js
```

- **O hub fica em `http://127.0.0.1:17400`.** Ele é **aberto**: só escuta no próprio computador, e
  as páginas abrem sem pareamento.
- **O token mestre fica em `~/space-teste/dados/token`.** Ele faz tudo nesse hub.
- **Para começar do zero,** pare o hub e apague `~/space-teste/dados`.

Crie um viewport (uma "área" onde as janelas abrem) uma vez:

```bash
H=http://127.0.0.1:17400; TK=$(cat ~/space-teste/dados/token)
curl -s -X POST -H "x-spaceman-token: $TK" -H 'content-type: application/json' $H/viewport --data '{"op":"criar","novo":"Teste"}'
# {"ok":true}
```

Para ver o resultado como a pessoa vê, abra `http://127.0.0.1:17400/view/Teste` no navegador.

## 3. Conectar a um hub de verdade (pareamento)

Num hub de verdade, que fica fechado, tudo pede token. O agente ganha um token pareando um
"aparelho" para ele.

1. **A pessoa gera um código de uso único**, que vale 10 minutos. Há dois caminhos:
   - Configurações → **Aparelhos pareados** → **Parear um aparelho novo**;
   - num aparelho já conectado, menu da bolinha → **Parear dispositivo**.

   O código aparece como um link `http://<hub>/pair?c=ABCD1234` ou como QR.
2. **O agente troca o código por um token:**

   ```bash
   H=http://<endereco-do-hub>:7334
   curl -s -X POST -H 'content-type: application/json' $H/pair \
     --data '{"c":"ABCD1234","nome":"agente de apps","tipo":"agente"}'
   # {"ok":true,"id":"agente-de-apps-c6b7","token":"873e…","hub":"http://…"}
   ```
3. **Todo pedido leva o cabeçalho** `x-spaceman-token: <token>`.

Cuidados:
- **O código vale uma vez só.** Depois de 8 códigos errados, aquele endereço espera 10 minutos.
- **O hub costuma estar só na rede Tailscale da pessoa** (ex.: `http://100.x.y.z:7334`). Se o
  agente não alcança esse endereço, ele não pareia: entrega o `.tar.gz` e a pessoa instala pela Loja
  (passo 6).
- **Esse token tem o acesso de um aparelho da pessoa.** Ele abre terminal e mexe nas janelas, por
  exemplo. Use-o só para instalar e testar o app. Ao terminar, a pessoa revoga o aparelho em
  Configurações → **Aparelhos pareados** → **revogar**.

## 4. Criar o app

Exemplo completo, testado: **Lembretes rápidos**.
- Anota textos e guarda no hub.
- Põe um item na Agenda da pessoa, com aviso em todos os aparelhos.

Os arquivos também estão em [exemplos/lembretes-rapidos/](exemplos/lembretes-rapidos/).

### spaceman-app.yaml

```yaml
id: lembretes-rapidos      # minúsculas, números e hífen; vira /a/<id>/; não pode ser nome de app do sistema
nome: Lembretes rápidos
versao: 0.1.0              # major.minor.ciclo; suba a cada entrega
icone: 📝                  # emoji curto: celular e relógio usam este
descricao: Anote algo e, se quiser, ponha na Agenda com aviso em todos os aparelhos.
autor: Exemplo do tutorial
janela: {w: 520, h: 560}   # tamanho da janela ao abrir
capacidades: [eventos:escrever, notificar]
```

Outros campos:
- `imagem: icone.svg`: ícone do launcher.
- `estado: [doc]`: parâmetros guardados na URL da janela.
- `titulo: "Doc · {doc}"`: título da janela com o estado.
- `url`: o app é um site que já existe.
- `web`: o app também roda fora do Space.

Os detalhes estão em [APP-INTERFACE.md](APP-INTERFACE.md).

### index.html

```html
<!doctype html>
<html lang="pt-BR">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Lembretes rápidos</title>
<link rel="stylesheet" href="/app.css">
<style>
  .corpo { padding: 14px; display: flex; flex-direction: column; gap: 10px; }
  form { display: flex; gap: 8px; }
  input { flex: 1; min-width: 0; background: #05070c; color: #e2e8f0; border: 1px solid #26304a; border-radius: 8px; padding: 9px 11px; font: 14px system-ui; }
  button { background: #1e6dff; color: #fff; border: 0; border-radius: 8px; padding: 9px 14px; font: 14px system-ui; cursor: pointer; }
  .item { display: flex; align-items: center; gap: 8px; background: #141926; border: 1px solid #26304a; border-radius: 10px; padding: 10px 12px; color: #e2e8f0; }
  .item span { flex: 1; min-width: 0; overflow-wrap: anywhere; }
  .item button { background: #1c2436; padding: 6px 10px; font-size: 12px; }
  .vazio { color: #8b96ad; font-size: 13px; }
</style>
</head>
<body>
<script src="/app.js"></script>
<div class="bar"><span class="ring"></span><span class="btitle">Lembretes rápidos</span><span id="st"></span></div>
<div class="corpo">
  <form id="novo"><input id="texto" placeholder="O que lembrar?" autocomplete="off"><button>Anotar</button></form>
  <div id="lista"></div>
</div>
<script>
const { el, estado } = App
let itens = []

async function carregar() {
  const r = await App.dados.ler('itens')          // documento JSON do app no hub
  itens = Array.isArray(r && r.itens) ? r.itens : []
  desenhar()
}
async function salvar() {
  const r = await App.dados.gravar('itens', { itens })
  estado(r.err ? 'não salvou: ' + r.err : 'salvo', r.err ? 'erro' : true)
}
function desenhar() {
  const l = document.getElementById('lista'); l.textContent = ''
  if (!itens.length) return el('div', 'vazio', l, 'Nada anotado ainda.')
  itens.forEach((it, i) => {
    const d = el('div', 'item', l)
    el('span', '', d, it.texto)
    el('button', '', d, 'Agenda em 1 h').onclick = () => paraAgenda(it)
    el('button', '', d, '✕').onclick = () => { itens.splice(i, 1); desenhar(); salvar() }
  })
}
// coleção central da pessoa: o compromisso aparece na Agenda e avisa em todos os aparelhos
async function paraAgenda(it) {
  const r = await App.colecao('eventos').criar({ titulo: it.texto, inicio: Date.now() + 3600000, lembretes: [0] })
  if (r.err) return estado('não foi para a Agenda: ' + r.err, 'erro')
  await App.notificar('Lembrete na Agenda', it.texto + ' (daqui a 1 h)')
  estado('na Agenda', true)
}
document.getElementById('novo').onsubmit = e => {
  e.preventDefault()
  const t = document.getElementById('texto').value.trim()
  if (!t) return
  itens.unshift({ texto: t, em: Date.now() })
  document.getElementById('texto').value = ''
  desenhar(); salvar()
}
carregar()
</script>
</body>
</html>
```

Regras da página:

- **`<script src="/app.js"></script>` logo depois de `<body>`.** Ele cria o objeto `App` e aplica o
  modo da janela.
- **`/app.css` dá a barra padrão e o corpo** (`.bar`, `.ring`, `.btitle`, `#st`, `.bt`, `.corpo`).
  Dentro de uma janela (`?janela=1`) a barra fica fina, porque a janela já tem a dela.
- **`App.api`, `App.dados` e `App.colecao` nunca lançam erro.** Eles devolvem um objeto, com `err`
  quando falham. Sempre confira `r.err`.
- **Funciona em toque e em tela pequena.** O mesmo app abre no celular: nada de hover obrigatório,
  e alvos de toque com pelo menos 36 px.

## 5. O que o app pode usar

| Para | Use | Capacidade |
|---|---|---|
| Guardar dados do app (JSON, até 4 MB por chave) | `App.dados.listar()` · `ler(chave)` · `gravar(chave, obj)` · `apagar(chave)` | nenhuma |
| Lembrar o estado da janela (doc aberto, aba) em todos os aparelhos | `App.salvarEstado({ chave: valor })` + `estado: [chave]` no manifesto | nenhuma |
| Mensagem na barra | `App.estado('texto', true \| 'erro')` | nenhuma |
| Tentar de novo com espera quando o hub some | `App.repetir(fn, ms)` (fn devolve `false` para recuar) | nenhuma |
| Compromissos da pessoa (Agenda) | `App.colecao('eventos')` · `listar()` · `criar(obj)` · `atualizar(id, obj)` · `apagar(id)` · `ouvir(fn)` | `eventos:ler`, `eventos:escrever` (muda só o que o app criou) ou `eventos:gerir` |
| Timers que tocam em todos os aparelhos | `App.colecao('timers')` | `timers:ler` / `timers:escrever` / `timers:gerir` |
| Aviso em todos os aparelhos | `App.notificar(titulo, texto, nivel?)` | `notificar` |
| Abrir outra janela do catálogo | `App.abrir(id, extra?)` | `abrir` |
| Arquivos das mídias (pen drive, disco) | `App.permissoes.solicitar(...)` + `App.armazenamento.*` (a pessoa autoriza cada uso) | `arquivo:ler`, `arquivo:listar`... |

Os campos de cada coleção:
- `eventos`: `titulo`, `inicio` (ms ou ISO), `fim?`, `diaInteiro?`, `lembretes` (minutos antes),
  `local?`, `notas?`, `link?`.
- `timers`: `titulo`, `duracao` (ms), `estado`.

Pedir capacidade que não está no manifesto devolve `err`: nas coleções vem
`"este app não tem permissão para isso"`; no `App.abrir` o pedido é barrado antes de chegar e vem
`"hub inacessível"`. Se aparecer um desses, confira `capacidades` no manifesto. Configurações e a
Loja mostram as capacidades à pessoa antes de instalar, então peça só o que o app usa.

### Armadilhas do isolamento

- **`localStorage`, `sessionStorage` e cookies dão `SecurityError`.** Use `App.dados`.
- **`fetch` direto para rotas do hub falha** ("Failed to fetch", bloqueio de origem, ou 403). Só
  as rotas do app passam, sempre pelo `App.*`. Para dados de fora, o app pode chamar APIs públicas
  com CORS. Não há proxy do hub.
- **Arquivos estáticos do app são públicos** para quem alcança o hub. Nada de segredo no código.
- **`alert`, `confirm` e `prompt` funcionam,** mas prefira mensagens na página e `App.estado`.

## 6. Empacotar e instalar

O pacote é a pasta do app num `.tar.gz`, com o manifesto na raiz. Não pode haver links nem caminhos
com `..`, e o limite é 30 MB.

```bash
tar czf lembretes-rapidos-0.1.0.tar.gz -C lembretes-rapidos .
```

Há dois jeitos de instalar:

- **Pelo agente,** com um token do passo 2 ou do passo 3:

  ```bash
  curl -s -X POST -H "x-spaceman-token: $TK" -H 'content-type: application/gzip' \
    --data-binary @lembretes-rapidos-0.1.0.tar.gz $H/app-instalar
  # {"ok":true,"id":"lembretes-rapidos","nome":"Lembretes rápidos","versao":"0.1.0","capacidades":["eventos:escrever","notificar"]}
  ```

  Se der erro, a resposta vem como `{"err":"..."}` (ex.: manifesto inválido, id de app do sistema,
  página de entrada ausente).
- **Pela pessoa, sem dar acesso ao agente:** Loja → **Instalados** → **Instalar de um arquivo**, e
  escolher o `.tar.gz`.

Para **atualizar**, suba `versao` no manifesto e instale de novo: o pacote substitui o anterior e os
dados (`App.dados`) ficam. Para **remover**:
`POST /app-remover {"id":"lembretes-rapidos"}`. Com `"dados": true`, apaga os dados também.

## 7. Abrir e testar

Abrir como janela num viewport:

```bash
curl -s -X POST -H "x-spaceman-token: $TK" -H 'content-type: application/json' $H/abrir \
  --data '{"id":"lembretes-rapidos","page":"Teste","x":40,"y":40}'
# {"ok":true,"wid":"w-…"}
```

A janela aparece em todos os aparelhos daquele viewport. O app também fica no launcher, em
**Outros apps**.

Para testar só a página, abra `http://127.0.0.1:17400/a/lembretes-rapidos/?janela=1` no navegador.
Num hub fechado, o navegador precisa estar pareado: abra o link `/pair?c=…` nele.

Lista de conferência (é o que foi feito para validar este tutorial):

1. A página abre sem erro no console, e `App.isolado` é `true`.
2. Gravar e recarregar: o dado volta (`App.dados`).
3. Cada capacidade funciona. Neste exemplo, o compromisso aparece em
   `GET /colecoes/eventos` com `origem: { tipo: "app", id: "lembretes-rapidos" }`, e o aviso em
   `GET /notificacoes`.
4. A tela funciona com 360 px de largura (celular) e com a janela grande.
5. Os dados do app no hub: `GET /app-dados/lembretes-rapidos/itens`.

## 8. Entregar

Entregue à pessoa:
- o `.tar.gz`;
- a pasta-fonte;
- uma linha dizendo o que o app faz e quais capacidades pede, e por quê.

A pessoa instala pela Loja, ou o agente instala com o token e depois a pessoa o revoga.

**Publicar na loja pública** (`space.dynami.art`, para todos os hubs) é com a DYNAMI.art: o app
entra no `catalogo.json` pelo `publicar-app.py` do repositório do site. Mande o pacote e peça a
publicação.

## Referência

- [APP-INTERFACE.md](APP-INTERFACE.md): interface completa, apps site (um site existente dentro do
  Space), permissões de arquivos, rodar também na web.
- [DADOS-CENTRAIS.md](DADOS-CENTRAIS.md): coleções.
- [LAUNCHER-E-LOJA.md](LAUNCHER-E-LOJA.md): launcher e loja.
- Página para desenvolvedores: https://space.dynami.art/desenvolver
