conversion-agent-cli

CLI oficial da Conversion para autenticação e administração do plugin de skills.

Instalação (MVP)

Enquanto não publicamos no npm, a instalação é direta do GitHub (repo privado — precisa de acesso ao GitHub org agencia-conversion):

npm i -g github:agencia-conversion/conversion-agent#main

Limitação conhecida: isso clona o monorepo inteiro. Quando migrarmos para npm org a instalação será simplesmente npm i -g @conversion/cli.

Requer Node ≥ 20.

Uso

Cockpit TUI

conversion start          # explícito
conversion                # sem args → cockpit (quando stdin/stdout são TTY)
conversion start --ascii-only   # plain mode (terminais sem Unicode rich)

Abre uma TUI interativa (Ink / React-no-terminal) inspirada no Hermes-Agent: header, sidebar de branding, painel central com catálogo de slash commands, input bar e status bar live com tail do ~/.conversion/sync.log. Slash commands disparam conversion <argv> em subprocess; texto livre redireciona pra Claude Code (a TUI não é chat).

Atalhos: ↑/↓ histórico, ESC interrompe processo filho, /exit sai, /clear limpa output. Detalhes em docs/wiki/runbooks/RB-009-conversion-tui.md.

Login

conversion login
# ou
conversion login [email protected]

Fluxo (ver docs/wiki/adrs/ADR-003-auth-magic-link.md):

1. CLI pergunta ou recebe o email (obrigatório @conversion.com.br).
2. CLI sobe um listener em http://localhost:<porta>/cb (faixa 8765–8785).
3. Backend envia um email com link "Entrar no Conversion Agent".
4. Ao clicar, o backend redireciona o browser para o listener com o JWT.
5. CLI valida o token chamando /api/auth/me e salva no keychain do OS.

Timeout: 5 minutos. Se passar, basta rodar conversion login de novo.

Sessions / Whoami

conversion sessions  # verbose: email, estado, expiração (antes era `status`)
conversion whoami    # compact: uma linha por sessão

O comando conversion status passou a mostrar o diff do project local (Fase 16b).

Sync (Fase 16b)

conversion workspace list           # lista workspaces do usuário
conversion workspace use acme       # fixa workspace ativo
conversion projects                 # lista projects do workspace ativo
conversion pull acme/landing-page   # materializa o project local
conversion pull                     # pull do project detectado via CWD
conversion status                   # diff local vs manifest
conversion push                     # publica novo commit
conversion push --force             # sobrescreve head (DESTRUCTIVE)
conversion whereami                 # diagnóstico do estado do CLI

Logout

conversion logout                             # se só há uma sessão
conversion logout [email protected]  # escolhe explicitamente

Revoga o token no backend e remove do keychain.

Update

conversion update   # via @oclif/plugin-update

Troubleshooting

Email não chega

Confira pasta de spam. O remetente é [email protected] (Resend). Se insistir, rode conversion login novamente — links expiram em 10 min e só têm 1 uso. Pergunte a [email protected] se o domínio Resend caiu.

"Não foi possível abrir uma porta em [8765..8785]"

Algum processo está segurando as portas dessa faixa. Identifique com:

lsof -iTCP -sTCP:LISTEN -P -n | grep -E '87(6[5-9]|7[0-9]|8[0-5])'

Mate o processo e rode de novo. A faixa tem 21 portas — colisão com todas é raríssima.

"Timeout waiting for magic-link callback" após clicar no link

O backend só aceita callback_url começando com http://localhost:<porta>/cb. Se seu SO mapeia localhost para IPv6 (::1) de uma forma incomum, pode falhar porque o listener faz bind em 127.0.0.1. Rode ping -c1 localhost e confirme que resolve para 127.0.0.1.

macOS pede permissão de keychain

Na primeira chamada o macOS exibe um diálogo "'node' quer usar sua informação confidencial armazenada em …". Clique em Sempre permitir para não ver o prompt novamente nas próximas execuções.

Backend alternativo (desenvolvimento local)

Aponte o CLI para outro host:

CONVERSION_BACKEND_URL=http://localhost:3000 conversion login

Desenvolvimento

pnpm --filter @agenciaconversion/cli build
pnpm --filter @agenciaconversion/cli test
pnpm --filter @agenciaconversion/cli lint
pnpm --filter @agenciaconversion/cli typecheck
node apps/cli/bin/run.js --help

Testes com backend real (opt-in)

CONVERSION_BACKEND_URL=https://agent.conversion.com.br \
  pnpm --filter @agenciaconversion/cli test

Sem a env var, os testes em tests/integration/real-backend.test.ts pulam.

Smoke de distribuição

pnpm --filter @agenciaconversion/cli pack
# gera apps/cli/conversion-agent-cli-0.1.0.tgz (gitignored)

Arquitetura interna

src/
├── commands/
│   ├── login.ts        # magic-link + callback + keychain persist
│   ├── logout.ts       # revoke server-side + remove local
│   ├── sessions.ts     # (antes status) lista detalhada de sessões
│   ├── whoami.ts       # compact: 1 linha por sessão
│   ├── status.ts       # diff local vs manifest (fase 16b)
│   ├── whereami.ts     # diagnóstico do estado do CLI
│   ├── projects.ts     # lista projects do workspace ativo
│   ├── pull.ts         # materializa head no disco
│   ├── push.ts         # publica novo commit
│   └── workspace/
│       ├── list.ts     # lista workspaces
│       └── use.ts      # fixa workspace ativo
└── lib/
    ├── api.ts             # fetch wrapper tipado (Node 20 nativo)
    ├── active-session.ts  # resolve sessão ativa (state + keychain)
    ├── callback-server.ts # HTTP listener efêmero para magic-link
    ├── config.ts          # constantes (backend url, faixa de portas)
    ├── crypto.ts          # generateState (CSRF nonce)
    ├── fs-sync.ts         # scan + diff + canonicalize local
    ├── humanize.ts        # "em 3h 24min"
    ├── keychain.ts        # wrapper keytar
    ├── manifest.ts        # read/write .conversion/manifest.json
    ├── paths.ts           # assertValidPath (re-export de shared)
    ├── project-resolve.ts # resolve <ws-slug>/<proj-slug> → ids
    ├── project-root.ts    # findProjectRoot + getConversionRoot
    ├── prompt.ts          # askText / askChoice via readline/promises
    ├── state.ts           # ~/.config/conversion/state.json
    └── tree-hash.ts       # canonicalTreeJson + computeTreeHash

Documentação viva em docs/wiki/adrs/ADR-003-auth-magic-link.md.