app-to-cli — de um executável nativo a uma CLI tipo-API

Transforma um app de desktop (não um site) numa CLI: a skill observa o tráfego de rede real (via mitmproxy como proxy de sistema), descobre os endpoints do backend enquanto você usa o app, e gera um pacote onde cada função do app vira um subcomando, autenticado com a sua própria sessão — sem cliques.

Esta skill faz só a CAPTURA NATIVA. A análise e a geração do CLI são reuso da site-to-cli (mesmo catalog.json, mesmo pacote de saída). A costura é um HAR: a captura vira HAR → a site-to-cli faz import-har → analyze → generate/openapi. Se a site-to-cli não estiver no projeto: /install-skill site-to-cli.

Guardrails (não negociáveis). Só rode contra apps onde o usuário tem conta e autorização, com as credenciais dele. Nada de mirar contas de terceiros, mass-scraping ou evasão para abuso. O proxy de sistema e o CA são revertidos no cleanup (rode-o SEMPRE, mesmo se falhar). Tokens nunca entram no catálogo (a site-to-cli marca headers de credencial como fromSession, sem valor). Não invente endpoints: só existe o que foi capturado — faltou função, capture de novo usando-a.

Os 4 atos

[1 Preparar] → [2 Capturar guiado por VOCÊ] → [3 Handoff p/ site-to-cli] → [4 Gerar + verificar]
  doctor/cert/detect   start·mark·peek·flush         handoff (HAR→catalog)     generate·openapi·replay

Tudo passa pelo orquestrador scripts/run.ps1 (Windows; resolve Python, instala mitmproxy na 1ª vez, sobe/derruba o proxy). Saídas vão para um run dir <out>/ (default ./<slug>-cli/).

Como você guia (o modelo de observação)

Ao invocar, diga o que quer mapear (ex.: /app-to-cli C:\App\App.exe quero mapear login, listar pedidos e criar pedido). O agente usa isso para planejar as features e roda o loop feature a feature: para cada uma, ele rotula o segmento → você executa a feature no app → diz "pronto" → o agente faz um peek e segue para a próxima. Cada feature vira um grupo de endpoints no catálogo.

Ato 1 — Preparar

pwsh -NoProfile -File scripts/run.ps1 doctor                 # python/mitmproxy/node/site-to-cli/porta/CA
pwsh -NoProfile -File scripts/run.ps1 setup-cert             # 1x por máquina: instala mitmproxy + CA (CurrentUser\Root, sem admin)
pwsh -NoProfile -File scripts/run.ps1 detect --exe "<exe>"   # fingerprint -> método de captura (JSON)

O detect decide o método pelo tipo de app (libssl bundled, PyInstaller, Electron, .NET, Java…). Tabela completa e casos difíceis (SSL embutido, app que ignora proxy, OAuth) em references/CAPTURE_METHODS.md.

Ato 2 — Capturar guiado (você dirige o app)

pwsh -NoProfile -File scripts/run.ps1 start --exe "<exe>" --out "<run>" --label <feature1> [--method auto] [--domains api.x.com] [--no-launch]
# ... você usa a feature no app ...
pwsh -NoProfile -File scripts/run.ps1 peek  --out "<run>"                  # o que apareceu até agora
pwsh -NoProfile -File scripts/run.ps1 mark  --out "<run>" --label <feature2>   # próxima feature
# ... repete por feature ...
pwsh -NoProfile -File scripts/run.ps1 stop  --out "<run>"                  # encerra a captura (app pode seguir aberto)

• start liga o proxy de sistema, sobe o mitmdump (com scripts/capture_addon.py) e lança o app. Use --method auto (chama o detect) ou force A/B/cdp. --no-launch se preferir abrir o app na mão. --domains filtra hosts (reduz ruído) — omita p/ capturar tudo.
• mark troca a feature corrente; peek mostra um resumo por feature (method + path + status) p/ você confirmar que a feature foi capturada antes de seguir.
• App não aparece no proxy? App que ignora proxy (Java/alguns nativos) → método C (Proxifier) ou transparente; ver references/CAPTURE_METHODS.md. Erro de SSL no app? ver references/TROUBLESHOOTING.md.

Ato 3 — Handoff para a site-to-cli

pwsh -NoProfile -File scripts/run.ps1 handoff --out "<run>" --name <slug>

Converte os fluxos capturados em capture/combined.har (+ 1 HAR por feature) e chama a site-to-cli: import-har → analyze → rascunho do catalog.json. Detalhes da costura, multi-feature e nomeação de ids por feature em references/INTEGRATION.md.

Depois você (modelo) cura o catalog.json (julgamento — não automatize cego), seguindo o contrato da site-to-cli (references/CATALOG_SCHEMA.md dela): id = subcomando claro (por feature, ex. login, pedidos-list, pedidos-create), summary 1 linha, primary só nas funções reais (esconda telemetria/health/polling), confirme auth/baseUrl, e troque qualquer token literal por fromSession: true.

Ato 4 — Gerar + verificar (reuso da site-to-cli) e LIMPAR

Chame a site-to-cli via node direto nos .mjs (o run.ps1 dela engole --out por causa do CmdletBinding; o handoff já imprime os caminhos exatos). <s2c> = pasta scripts/ da site-to-cli.

node "<s2c>/scaffold-cli.mjs" --out "<run>"   # = generate: CLI data-driven a partir do catalog curado
node "<s2c>/gen-openapi.mjs"  --out "<run>"   # = openapi: openapi.json + .yaml
# verifique: rode 1 comando da CLI gerada fora do app (replay) p/ provar o mapeamento — TROUBLESHOOTING.md
pwsh -NoProfile -File scripts/run.ps1 cleanup --out "<run>"          # SEMPRE: desliga proxy, restaura, mata processos

A CLI gerada usa node cli.mjs login | list | <comando> [--param v] | auth check (a sessão é sua, persistida localmente; ver o README do pacote gerado).

Apps não-HTTP (WebSocket / gRPC / TCP cru)

O caminho HTTP(S) acima é automático. Para protocolos não-HTTP, o capture_addon.py também grava WebSocket/TCP em <run>/.capture/raw.jsonl, e o mapeamento vira guiado/semi-manual (decodificar framing, montar stubs de cliente). Quando começar e como mapear: references/NON_HTTP.md.

Scripts (determinísticos — não reimplemente)

Fim

A skill fica inerte no ateliê. Para usá-la num projeto: /install-skill app-to-cli (e a site-to-cli junto). Inspiração (MIT, crédito nos cabeçalhos): AI-OS/mitmproxy-traffic-capture (captura nativa + árvore de métodos), CLI-Anything-WEB (evidência por endpoint + gate), AuditForge/proxy-capture-replay (replay + sanitização), zotero/capture-api (HAR→OpenAPI), cli-generation/cli-api-recon (formato de recon).