site-to-cli — do site logado a uma CLI tipo-API

Transforma um site que só tem interface gráfica numa CLI: a skill observa o tráfego de rede real (Playwright), descobre os endpoints do backend e gera um pacote onde cada função do site é um subcomando, autenticado com a sua própria sessão — sem cliques.

Guardrails (não negociáveis). Só rode contra sites onde o usuário tem conta e autorização de uso, com as credenciais dele. Respeite ToS/robots.txt, use rate-limit (já embutido) e não faça mass-scraping, evasão de detecção para fins abusivos, nem mire contas de terceiros. A sessão/cookies ficam locais (out/.session/) e nunca são commitados. Se o alvo proíbe automação no ToS, avise o usuário e pare.

Os 3 atos

[Capturar network]  →  [Consolidar + curar catálogo]  →  [Gerar CLI + OpenAPI + cache]
   (Playwright)            (catalog.json)                   (pacote standalone)

Tudo passa pelo orquestrador único scripts/run.ps1 (resolve Node, garante o Playwright na 1ª vez reusando os browsers já instalados, e despacha). Saídas vão para um run dir: <out>/ (default ./<slug>-cli/), com capture/, catalog.json, openapi.(json|yaml), e o pacote da CLI.

Antes de tudo: pwsh -NoProfile -File scripts/run.ps1 doctor — confere Node/Playwright/browser.

Ato 1 — Capturar o tráfego (3 modos; combine à vontade)

(a) Gravação dirigida por você [principal, recomendado]. Abre um browser headed; você loga e usa as funções que quer mapear. Ao fechar o browser (ou esgotar --duration), a skill salva o network + a sessão.

pwsh -NoProfile -File scripts/run.ps1 record --url "<URL>" --out "<run>" [--duration 0] [--filter "api|ajax|graphql"]

--duration 0 = grava até você fechar a janela. A sessão vai para <run>/.session/storage_state.json.

(b) Import de HAR pronto. Você já exportou um .har do DevTools (aba Network → Export HAR):

pwsh -NoProfile -File scripts/run.ps1 import-har --har "<arquivo.har>" --out "<run>"

(c) Crawl autônomo [use com cautela]. Navega sozinho same-origin disparando endpoints. Frágil e mais arriscado em ToS/rate-limit — prefira (a). Requer sessão já salva para áreas logadas.

pwsh -NoProfile -File scripts/run.ps1 crawl --url "<URL>" --out "<run>" [--max-pages 20] [--session "<run>/.session/storage_state.json"]

Sites com parâmetros assinados/criptografados: rode record com --hooks crypto,fetch — a captura injeta hooks (CryptoJS/JSEncrypt/WebCrypto/btoa, fetch/XHR) e registra como os params são gerados, em capture/*.jsonl. Detalhe em references/AUTH_PATTERNS.md.

Ato 2 — Consolidar e curar o catálogo (seu julgamento entra aqui)

pwsh -NoProfile -File scripts/run.ps1 analyze --out "<run>"

O script deduplica os requests, infere path-templates (/orders/123 → /orders/{id}), une query/headers/body, amostra respostas, detecta o padrão de auth e marca headers sensíveis como fromSession (o token nunca é gravado no catálogo). Resultado: <run>/catalog.json.

Depois você (modelo) cura o catalog.json — esta é a parte de julgamento, não automatize cega:

• Renomeie cada endpoint.id para um subcomando claro (get_v1_orders → orders-list).
• Escreva summary em 1 linha por endpoint.
• Marque primary: true nas principais funções e primary: false no ruído (telemetria, health, assets dinâmicos que escaparam do filtro).
• Confirme baseUrl e o bloco auth (tipo, onde vive o token).

Contrato do catalog.json e exemplos: references/CATALOG_SCHEMA.md.

Ato 3 — Gerar o pacote (CLI + OpenAPI + cache)

pwsh -NoProfile -File scripts/run.ps1 generate --out "<run>"     # gera o pacote da CLI a partir do catalog.json (curado)
pwsh -NoProfile -File scripts/run.ps1 openapi  --out "<run>"     # gera openapi.json + openapi.yaml do backend mapeado

generate produz uma CLI data-driven: um runtime fixo lê o catalog.json e expõe um subcomando por endpoint. Nada de código por-endpoint frágil. O pacote sai em <run>/cli/ com README.md.

Usar a CLI gerada (o produto final)

cd <run>/cli
node cli.mjs login                 # abre o browser p/ você logar; persiste a sessão (1x)
node cli.mjs list                  # lista os subcomandos (endpoints) disponíveis
node cli.mjs <comando> [--param v] # chama o endpoint; resposta em JSON
node cli.mjs auth check            # confirma se a sessão está válida
node cli.mjs import-cookies --cdp 9222   # alternativa: importa sessão de um Chrome já aberto

• Saída JSON pura quando redirecionada (pipe), tabela amigável no terminal; --json força JSON.
• Exit codes tipados (0 ok · 2 uso · 3 auth/401 · 5 erro HTTP · 7 rede) p/ scripting.
• Cache local de GETs em <run>/cli/.cache/ (TTL), --no-cache ignora. Sessão em .session/.
• Auth e refresh de sessão: references/AUTH_PATTERNS.md. Erros comuns: references/TROUBLESHOOTING.md.

Fim

A skill fica inerte no ateliê. Para usá-la num projeto: /install-skill site-to-cli lá dentro. Créditos de inspiração (MIT) nos cabeçalhos dos scripts: AUTO_REVERSE/web-api-analyzer (captura + hooks), claude-skill-registry/reverse-engineering-api (filtro + workflow), notebooklm-py (modelo de sessão), cli-printing-press (padrões de CLI).