@reachysdk/sdk-wizard

CLI determinístico para instrumentar projetos Next.js com o @reachysdk/sdk: detecta o projeto, autentica, instala o SDK, escreve o instrumentation-client, faz o merge do .env.local/.gitignore e verifica o primeiro evento — tudo com um plano de escrita transacional (mostra o diff, pede confirmação, aplica tudo ou nada) e idempotente (rodar de novo não muda nada).

Pacote independente do SDK (subdiretório wizard/, sem npm workspaces). O backend /setup-wizard ainda não existe → use o modo --ci --api-key enquanto isso (ver abaixo).

Uso

npx @reachysdk/sdk-wizard

Rode na raiz do seu projeto Next.js. O wizard:

1. Detecta o projeto (Next? versão? TypeScript? src/? App/Pages Router? qual gerenciador de pacotes?).
2. Verifica o git — exige working tree limpo (ou confirmação explícita) para você poder revisar/reverter o diff.
3. Autentica — abre o navegador em /setup-wizard#<state> e faz polling até você autorizar (a URL é sempre impressa, como fallback para SSH/CI).
4. Instala o @reachysdk/sdk com o gerenciador detectado.
5. Instrumenta — Next ≥ 15.3 + App Router → escreve instrumentation-client.{ts,js}. Outros casos → imprime instruções manuais (Provider / Pages Router).
6. Env — adiciona NEXT_PUBLIC_REACHY_PASSCODE/NEXT_PUBLIC_REACHY_ENDPOINT ao .env.local (só as chaves faltantes; nunca sobrescreve) e garante .env.local no .gitignore.
7. Confirma o diff agregado e aplica tudo de uma vez.
8. Verifica — envia um wizard_test_event e confirma a recepção no ingest.

Flags

| Flag | Efeito | | --- | --- | | --ci | Modo não-interativo: sem navegador nem polling. Exige --api-key (ou $REACHY_PERSONAL_API_KEY) e --endpoint (ou $NEXT_PUBLIC_REACHY_ENDPOINT). | | --api-key <key> | Credencial do projeto no modo --ci. | | --endpoint <url> | Endpoint de ingest (modo --ci). | | --api-base <url> | Base do backend /setup-wizard (default: produção). | | --app-base <url> | Base web da autorização no navegador. | | --yes | Aplica sem perguntar (assume "sim" na confirmação e no gate de git). | | --verbose | Logs detalhados (segredos sempre mascarados). |

Exemplo CI:

npx @reachysdk/sdk-wizard --ci --api-key "$REACHY_KEY" --endpoint https://ingest.example/e --yes

Caminho manual (fallback)

Quando o caminho automático não se aplica (Next < 15.3, Pages Router, ou qualquer falha), o wizard imprime instruções manuais em vez de editar arquivos frágeis:

• Next ≥ 15.3 + App Router — crie instrumentation-client.ts (ou src/):

  import { init } from '@reachysdk/sdk';
  init(process.env.NEXT_PUBLIC_REACHY_PASSCODE!, {
    endpoint: process.env.NEXT_PUBLIC_REACHY_ENDPOINT,
  });

• Next < 15.3 ou contexto React — use <ReachyProvider> de @reachysdk/sdk/react (ver docs/nextjs-adapter.md §2).

• Pages Router — Provider em pages/_app.

Em todos os casos, adicione ao .env.local:

NEXT_PUBLIC_REACHY_PASSCODE=<seu-passcode>
NEXT_PUBLIC_REACHY_ENDPOINT=<seu-endpoint>

Segurança e garantias

• Working tree limpo: o wizard pede árvore git limpa antes de escrever, então o git diff mostra só o que ele mudou.
• Plano transacional: nada é escrito até você confirmar o diff; em falha parcial, ele lista exatamente o que faltou e imprime o conteúdo completo a aplicar à mão.
• Idempotência: rodar 2× não muda nada (instrumentação já presente → skip; chaves já no .env → no-op).
• Segredos nunca vazam: api-key/passcode são mascarados ([redacted]) em qualquer saída — logs, diffs e telemetria (auditado por teste).
• TTL na autorização: o state da autenticação expira (~10min) e é de entrega única.

Desenvolvimento

Comandos da raiz do repositório (delegam ao subpacote via --prefix wizard):

npm install --prefix wizard   # instala as deps do wizard (uma vez)
npm run wizard:typecheck       # tsc --noEmit (strict)
npm run wizard:test            # Jest (node env)
npm run wizard:build           # tsc → wizard/dist/

Toolchain: TypeScript strict + ESM + Node ≥ 18.17, build via tsc puro; testes via babel-jest (type-strip), espelhando a divisão Babel/tsc do SDK. O Jest da raiz ignora /wizard/ — as suítes são independentes.

Layout

wizard/src/
  bin.ts          # entry (#!/usr/bin/env node) → run()
  cli.ts          # parse de flags
  run.ts          # orquestrador do pipeline
  detect.ts       # ProjectInfo (framework/versão/TS/src/router/pm)
  git.ts          # gate de working tree limpo
  api.ts          # WizardApi (interface) + HttpWizardApi
  auth.ts         # browser + state + polling | --ci
  install.ts      # install via pm detectado
  templates.ts    # instrumentation-client + instruções manuais
  instrument.ts   # create/skip/append idempotente
  env.ts          # merge .env.local + .gitignore
  write-plan.ts   # plano transacional (diff + apply atômico)
  verify.ts       # wizard_test_event + polling de recepção
  telemetry.ts    # funil dogfooding (whitelist + fire-and-forget)
  ui.ts           # wrappers clack + cancel limpo + logger com redact
  payload.ts      # shape de payload protocolo-SDK (compartilhado)