@neetru/cli 2.29.0 → 2.32.0

package/dist/index.js

@@ -5,6 +5,9 @@ import { CLI_VERSION } from './version.js';
 import { installTelemetryFlushHook, markCommandStart, markCommandEnd, } from './lib/telemetry.js';
 import { safeExit, isSafeExitHalt } from './utils/safe-exit.js';
 import { CliApiError } from './lib/api-client.js';
+import { NeetruCliError } from './cli-kit/errors.js';
+import { installCommandContext, getCurrentCommand } from './cli-kit/command-context.js';
+import { emitCliError } from './lib/cli-error.js';
 // UV_HANDLE_CLOSING no Windows (bug_818cf6d): o double-destroy de stdin (handler
 // 'exit' redundante) foi removido em 2026-07-15 (ddd479f), MAS isso não bastou
 // — a causa dominante é o `uv_async_t` do undici (fetch) ainda vivo quando o
@@ -29,6 +32,20 @@ installTelemetryFlushHook();
 function handleFatalSignal(err) {
     if (isSafeExitHalt(err))
         return; // saída já agendada dentro do safeExit
+    // bug_89d2497e: erro tipado lançado e não tratado sai com o código DELE (e,
+    // se o comando em execução recebeu --json, como JSON) — não com o 1 genérico.
+    if (err instanceof NeetruCliError) {
+        let code = err.exit;
+        try {
+            code = emitCliError(err, Boolean(getCurrentCommand()?.opts().json));
+        }
+        catch {
+            /* logger indisponível — segue direto pro exit deferido */
+        }
+        process.exitCode = code;
+        setTimeout(() => process.exit(code), 300);
+        return;
+    }
     try {
         log.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
         // LABS #6 (2026-09-28): se o erro carrega o x-correlation-id do Core, mostra
@@ -89,6 +106,10 @@ program.hook('preAction', (_thisCmd, actionCmd) => {
 process.once('exit', (code) => {
     markCommandEnd(typeof code === 'number' ? code : 0);
 });
+// bug_89d2497e: guarda o comando que o Commander vai executar, para que um
+// conselho de erro (ex.: "passe --mfa-token") só cite flag que ESSE comando
+// declara. Ver `src/cli-kit/command-context.ts`.
+installCommandContext(program);
 // ── neetru ai ─────────────────────────────────────────────────────────
 const aiCommand = program
     .command('ai')
@@ -157,6 +178,7 @@ program
     .option('--force', 'sobrescreve arquivos existentes em conflito (cuidado!)')
     // -y padronizado com bootstrap (`-y, --yes`) — muscle-memory (auditoria UX 2026-09).
     .option('-y, --yes', 'modo non-interactive (assume defaults, sai com erro se conflito sem flag)')
+    .option('--sem-docs', 'não cria o docs/ do produto (o padrão é rodar `neetru docs init`)')
     .action(async (name, opts) => {
     const { runInit } = await import('./commands/init.js');
     await runInit({
@@ -166,6 +188,7 @@ program
         path: opts.path,
         force: opts.force,
         yes: opts.yes,
+        semDocs: !!opts.semDocs,
     });
 });
 // ── neetru new (macro end-to-end) ─────────────────────────────────────
@@ -174,13 +197,14 @@ program
     .command('new <name>')
     .description('Criar produto, workspace, scaffold e abrir painel')
     .option('--product-slug <slug>', 'slug do produto (default: derivado de <name>)')
-    .option('--env <env>', 'dev (default) | staging | prod', 'dev')
+    .option('--env <env>', 'dev-local (padrão) | staging | prod')
     .option('--tier <tier>', 'standard (default) | dev | enterprise', 'standard')
-    .option('--customer <customerId>', 'customerId dono do workspace (default: self)')
+    .option('--customer <customerId>', 'customerId dono do workspace (OBRIGATÓRIO se o produto não for Neetru-owned)')
     .option('--skip-init', 'pula o scaffold local')
     .option('--open', 'abre o browser após criar o workspace (opt-in)')
     .option('--skip-open', '(obsoleto — browser não abre por default; use --open para abrir)')
     .option('--skip-db-init', 'pula o 5º passo de inicialização do banco de dados')
+    .option('--sem-docs', 'não cria o docs/ do produto no scaffold')
     .option('--json', 'saída em JSON (machine-readable)')
     .action(async (name, opts) => {
     const { runNewMacro } = await import('./commands/new.js');
@@ -193,6 +217,7 @@ program
         open: !!opts.open,
         skipOpen: !!opts.skipOpen,
         skipDbInit: !!opts.skipDbInit,
+        semDocs: !!opts.semDocs,
         json: !!opts.json,
     });
 });
@@ -309,11 +334,11 @@ program
 // ── neetru dev ────────────────────────────────────────────────────────
 // `neetru dev` (sem subcomando) = banco local Docker + watch de schema (M1
 // GAP-M1-4) — comportamento legado preservado (action + options intactos).
-// `neetru dev up` = ambiente dev-local (banco + agente) via Docker Compose.
+// `neetru dev up` = banco do produto em container via Docker Compose.
 // Subcomando aditivo: a action de `dev` só dispara quando nenhum subcomando casa.
 const devCmd = program
     .command('dev')
-    .description('Ambiente de dev local — banco Docker (default) ou ambiente completo (`dev up`)')
+    .description('Ambiente de dev local — banco Docker + watch de schema (default) ou só o banco (`dev up`)')
     .option('--db <name>', 'banco alvo do .neetru/db.json (default: único registrado)')
     .option('--schema <path>', 'caminho do arquivo de schema (default: db/schema.ts)')
     .action(async (opts) => {
@@ -322,8 +347,8 @@ const devCmd = program
 });
 devCmd
     .command('up')
-    .description('Sobe o ambiente dev-local (banco + agente) via Docker Compose')
-    .option('--core-port <port>', 'porta do app SaaS local (default 3000)')
+    .description('Sobe o banco do produto em container (Docker Compose) e mostra a conexão')
+    .option('--core-port <port>', 'porta do app local mostrada nas instruções (default 3000)')
     .action(async (opts) => {
     const { runDevUp } = await import('./commands/dev-up.js');
     await runDevUp({
@@ -399,11 +424,15 @@ program
     .command('build')
     .description('Construir tarball do produto pronto para deploy')
     .option('--product <slug>', 'override do slug (default: lê neetru.config.json)')
+    // bug_678ddc98: monorepo — aponta pro diretório do app sem precisar de `cd`.
+    // `--cwd` é alias porque é o nome que a maioria das ferramentas usa.
+    .option('--app <dir>', 'diretório do app a construir (monorepo: ex. apps/web). O artefato continua saindo no diretório atual')
+    .option('--cwd <dir>', 'alias de --app')
     .option('--stack <stack>', 'node | docker | php-apache | static (default: detectado)')
     .option('--output <dir>', 'diretório de saída', '.neetru-build')
     .option('--version <version>', 'versão (default: detectada de package.json ou timestamp)')
     .option('--no-cache', 'invalida caches do build (recria lockfile, --no-cache no docker)')
-    .option('--no-install', 'pula `npm install` (assume node_modules pronto — útil quando `next dev` ativo no Windows)')
+    .option('--no-install', 'pula o install (assume node_modules pronto — útil quando `next dev` ativo no Windows)')
     .option('--env-file <path>', 'arquivo .env com vars de ambiente a injetar no build (ex: NEXT_PUBLIC_API_URL)')
     .option('--target-env <env>', 'dev | workspace | prod — força NEXT_PUBLIC_NEETRU_ENV no bundle (default: prod; ' +
     'neutraliza .env.local vencendo .env.production — incidente 2026-07-22)', 'prod')
@@ -412,6 +441,9 @@ program
     const { runBuild } = await import('./commands/build.js');
     await runBuild({
         product: opts.product,
+        // bug_678ddc98: `--app` vence `--cwd` quando os dois vêm juntos (o
+        // canônico ganha do alias, em vez de escolher em silêncio).
+        app: opts.app ?? opts.cwd,
         stack: opts.stack,
         output: opts.output,
         version: opts.version,
@@ -449,6 +481,9 @@ program
     .option('--non-interactive', 'falha em vez de perguntar (modo CI)')
     .option('--force', 'ignora o gate de schema e prossegue mesmo com divergência de fingerprint')
     .option('--skip-health-probe', 'NÃO faz o GET de saúde a https://<domain>/api/health?deep=1 pós-deploy (default: sempre faz; use só em serviço sem HTTP)')
+    .option('--allow-public-secret <motivo>', 'EMERGÊNCIA: deploya mesmo com segredo (nrt_/npk_/chave privada/env pública sensível) no pacote público. ' +
+    'Motivo obrigatório; fica registrado no deploy. Rotacione a chave depois.')
+    .option('--sem-docs', 'pula a checagem dos docs (só aviso) e a publicação automática (docs.publishOnDeploy)')
     .option('--json', 'saída em JSON estruturado (implica --non-interactive)')
     .action(async (opts) => {
     const { runDeploy } = await import('./commands/deploy.js');
@@ -474,6 +509,8 @@ program
         force: !!opts.force,
         skipHealthProbe: !!opts.skipHealthProbe,
         mfaToken: opts.mfaToken,
+        allowPublicSecret: opts.allowPublicSecret,
+        semDocs: !!opts.semDocs,
         json: !!opts.json,
     });
 });
@@ -593,7 +630,7 @@ tenantsCmd
     .option('--slug <slug>', 'slug do tenant')
     .option('--customer <customerId>', 'id do customer')
     .option('--product <productId>', 'id do produto (interativo se ausente)')
-    .option('--env <env>', 'dev | staging | prod (default: dev)')
+    .option('--env <env>', 'dev-local | staging | prod (default: dev-local)')
     .option('--domain <domain>', 'domínio primário')
     .option('--json', 'saída em JSON')
     .action(async (opts) => {
@@ -615,7 +652,7 @@ tenantsCmd
     .option('--slug <slug>', 'slug do tenant')
     .option('--customer <customerId>', 'id do customer')
     .option('--product <productId>', 'id do produto (interativo se ausente)')
-    .option('--env <env>', 'dev | staging | prod (default: dev)')
+    .option('--env <env>', 'dev-local | staging | prod (default: dev-local)')
     .option('--domain <domain>', 'domínio primário')
     .option('--json', 'saída em JSON')
     .action(async (id, opts) => {
@@ -892,8 +929,8 @@ workspacesCmd
     .command('create')
     .description('Criar workspace (retorna OAuth secret one-time)')
     .option('--product <productId>', 'id do produto (interativo se ausente)')
-    .option('--customer <customerId>', 'id do customer (default: self/Neetru)')
-    .option('--env <env>', 'dev | staging | prod (default: dev)')
+    .option('--customer <customerId>', 'id do customer (omitir só em produto Neetru-owned)')
+    .option('--env <env>', 'dev-local | staging | prod (default: dev-local)')
     .option('--tier <tier>', 'dev | standard | enterprise (default: standard)')
     .option('--name <name>', 'label do workspace')
     .option('--bind-config', 'grava tenantId retornado no neetru.config.json do cwd')
@@ -930,7 +967,7 @@ workspacesCmd
     .command('list')
     .description('Listar workspaces')
     .option('--product <productId>', 'filtra por productId')
-    .option('--env <env>', 'dev | staging | prod')
+    .option('--env <env>', 'dev-local | staging | prod')
     .option('--status <status>', 'active | paused | provisioning | …')
     .option('--json', 'saída em JSON')
     .action(async (opts) => {
@@ -967,7 +1004,7 @@ deploymentsCmd
     .option('--product <productId>', 'id do produto (interativo se ausente)')
     .option('--tenant <tenantId>', 'id do tenant alvo (interativo se ausente)')
     .option('--version <version>', 'versao a deployar')
-    .option('--env <env>', 'dev | staging | prod (default: dev)')
+    .option('--env <env>', 'dev-local | staging | prod (default: dev-local)')
     .option('--server <serverId>', 'id do server alvo (interativo se ausente)')
     .option('--json', 'saída em JSON')
     .action(async (opts) => {
@@ -1200,7 +1237,10 @@ productsCmd
     .option('--description <text>', 'descrição (opcional)')
     .option('--owner-team <team>', 'time dono (default: neetru-eng)')
     .option('--plan-template <tier>', 'free | starter | pro (default: free)')
-    .option('--env <csv>', 'ambientes separados por vírgula (default: dev,prod)')
+    // bug bug_db50b21f84e8400f9c3f6286b69c353b: o Core descarta `environments` no
+    // POST. A flag segue aceita pra não quebrar script existente, mas o texto
+    // precisa dizer a verdade — antes prometia uma escolha que não acontecia.
+    .option('--env <csv>', 'IGNORADO hoje: o Core provisiona staging e prod sozinho')
     .option('--yes', 'pula prompts (exige --name; resto usa defaults)')
     .option('--json', 'saída em JSON (machine-readable)')
     .action(async (opts) => {
@@ -1380,10 +1420,15 @@ adminDatabaseCmd
     .command('delete [id]')
     .description('[Staff] Arquivar banco por soft-delete')
     .option('--force', 'Requerido para DBs em status=active (passa force=true ao Core)')
+    // bug_757b9746: a rota exige step-up MFA e o hint de erro já mandava usar
+    // `--mfa-token`, mas o subcomando não declarava a flag. Sem sessão de 1h
+    // ativa (`neetru auth mfa-session`), em --json/não-interativo este era o
+    // único caminho possível — e ele não existia.
+    .option('--mfa-token <codigo>', 'Código TOTP para o step-up MFA (dispensado com `neetru auth mfa-session`)')
     .option('--json')
     .action(async (id, opts) => {
     const { runDbDelete } = await import('./commands/products-db.js');
-    await runDbDelete(id, { json: !!opts.json, force: !!opts.force });
+    await runDbDelete(id, { json: !!opts.json, force: !!opts.force, mfaToken: opts.mfaToken });
 });
 // ── neetru admin sdk-credential ────────────────────────────────────────────
 // Gerencia credenciais OIDC de MÁQUINA (M2M / client_credentials) por produto —
@@ -1604,10 +1649,14 @@ productsDbCmd
     .command('set-status [id] [status]')
     .description('[RENOMEADO — use: neetru admin database set-status]')
     .option('--reason <text>')
+    // A7 (2026-10-13): a rota exige step-up MFA com o banco active/degraded; o
+    // alias depreciado não declarava a flag e, em --json/CI sem sessão de 1h,
+    // não havia como mandar o código (o `admin database set-status` já tinha).
+    .option('--mfa-token <code>', 'código TOTP para step-up MFA (exigido se o banco está active/degraded)')
     .option('--json')
     .action(async (id, status, opts) => {
     const { runDbSetStatus } = await import('./commands/products-db.js');
-    await runDbSetStatus(id, status, { reason: opts.reason, json: !!opts.json });
+    await runDbSetStatus(id, status, { reason: opts.reason, mfaToken: opts.mfaToken, json: !!opts.json });
 });
 productsDbCmd
     .command('retry [id]')
@@ -1629,10 +1678,14 @@ productsDbCmd
 productsDbCmd
     .command('delete [id]')
     .description('[RENOMEADO — use: neetru admin database delete]')
+    // bug_757b9746: o alias roteia pro MESMO runDbDelete, que agora faz step-up
+    // MFA. Sem a flag aqui o alias reproduziria o bug inteiro (401 com instrução
+    // de usar uma flag inexistente).
+    .option('--mfa-token <codigo>', 'Código TOTP para o step-up MFA (dispensado com `neetru auth mfa-session`)')
     .option('--json')
     .action(async (id, opts) => {
     const { runDbDelete } = await import('./commands/products-db.js');
-    await runDbDelete(id, { json: !!opts.json });
+    await runDbDelete(id, { json: !!opts.json, mfaToken: opts.mfaToken });
 });
 // ── neetru logs ───────────────────────────────────────────────────────
 program
@@ -1648,7 +1701,7 @@ program
     .option('--channel <channel>', 'filtrar por channel (stdout | stderr | app)')
     .option('--correlation-id <id>', 'filtrar por correlationId (UUID)')
     .option('--json', 'saída em JSON (NDJSON linha a linha, útil para pipes)')
-    .option('--local [path]', 'ler NDJSON local do emulador (dev up) em vez do Core; default .neetru/dev/logs.ndjson')
+    .option('--local [path]', 'ler NDJSON local (coletor do Core local) em vez do Core; default .neetru/dev/logs.ndjson')
     .action(async (opts) => {
     const { runLogs } = await import('./commands/logs.js');
     await runLogs({
@@ -2043,7 +2096,7 @@ dbMigrationsCmd
     .description('Confirmar migração destrutiva (POST /api/cli/v1/db/migrations/[id]/confirm — exige MFA)')
     // Era `requiredOption('--mfa')` — o commander rejeitava ANTES de rodar, matando
     // o caminho de sessão MFA de 1h (`neetru auth mfa-session`) que o resolveStepUp
-    // promete honrar. Agora `option`: resolveStepUp faz o fail-closed (sessão → --mfa-token
+    // promete honrar. Agora `option`: resolveStepUp faz o fail-closed (--mfa-token → sessão
     // → erro acionável). Flag canônica `--mfa-token`; `--mfa` fica como alias oculto. (auditoria UX 2026-09)
     .option('--mfa-token <token>', 'código TOTP step-up MFA (ou use `neetru auth mfa-session`)')
     .addOption(new Option('--mfa <token>').hideHelp())
@@ -2769,7 +2822,7 @@ drCmd
 // entrada pra quem quer LER docs, não publicar.
 const docsCmd = program
     .command('docs')
-    .description('Documentação + registry de docs publicados em gs://neetru-docs');
+    .description('Docs do produto (init/new/check/sync) + registry de docs do Core em gs://neetru-docs');
 docsCmd
     .command('open [topic]')
     .description('Abrir documentação no browser (ex: sdk, cli, db, webhooks, auth)')
@@ -2837,6 +2890,63 @@ docsCmd
         json: !!opts.json,
     });
 });
+// ── neetru docs init|new|check|sync — docs do PRODUTO ─────────────────
+// PROTOCOLO_DOCS_PRODUTOS_SAAS v1 (2026-10-03). Os subcomandos acima são o
+// control plane dos docs do Core; estes cuidam do `docs/` do repo do produto.
+docsCmd
+    .command('init')
+    .description('Criar o mínimo do primeiro dia do docs/ do produto (idempotente; nunca sobrescreve)')
+    .option('--com-api', 'inclui docs/api/API_V1.md (produto expõe /api/v1) e grava docs.api=true')
+    .option('--migrar', 'repo que já tem docs: só acrescenta frontmatter inferido + relatório (não move nem renomeia nada)')
+    .option('--dry-run', 'mostra o que faria, sem escrever')
+    .option('--json', 'saída em JSON')
+    .action(async (opts) => {
+    const { runDocsInit } = await import('./commands/docs-produto.js');
+    await runDocsInit({ comApi: !!opts.comApi, migrar: !!opts.migrar, dryRun: !!opts.dryRun, json: !!opts.json });
+});
+docsCmd
+    .command('new <tipo> <titulo>')
+    .description('Criar doc a partir do modelo (guia|referencia|arquitetura|adr|runbook|norma|plano|relatorio|incidente|ata|rfc|spec|politica|ameacas)')
+    .option('--categoria <categoria>', 'categoria da taxonomia (ex.: "Integrações")')
+    .option('--subcategoria <subcategoria>', 'subcategoria da categoria (ex.: marketplaces)')
+    .option('--audience <audience>', 'dev-produto | staff | publico (padrão: o da pasta)')
+    .option('--descricao <frase>', 'description (uma frase de 40 a 200 caracteres)')
+    .option('--data <AAAA-MM-DD>', 'data do registro (relatório, incidente, ata); padrão hoje')
+    .option('--dry-run', 'mostra o que faria, sem escrever')
+    .option('--json', 'saída em JSON')
+    .action(async (tipo, titulo, opts) => {
+    const { runDocsNew } = await import('./commands/docs-produto.js');
+    await runDocsNew(tipo, titulo, {
+        categoria: opts.categoria,
+        subcategoria: opts.subcategoria,
+        audience: opts.audience,
+        descricao: opts.descricao,
+        data: opts.data,
+        dryRun: !!opts.dryRun,
+        json: !!opts.json,
+    });
+});
+docsCmd
+    .command('check')
+    .description('Validar os docs do produto (offline; mesmos códigos do Core + PR001–PR004)')
+    .option('--changed', 'só os arquivos alterados contra a branch principal (catraca)')
+    .option('--strict', 'aviso também falha')
+    .option('--offline', 'não consulta a taxonomia do Core (usa a embutida)')
+    .option('--json', 'saída em JSON')
+    .action(async (opts) => {
+    const { runDocsCheck } = await import('./commands/docs-produto.js');
+    await runDocsCheck({ changed: !!opts.changed, strict: !!opts.strict, offline: !!opts.offline, json: !!opts.json });
+});
+docsCmd
+    .command('sync')
+    .description('Publicar os docs do produto no Core (só os sem erro; nada é apagado)')
+    .option('--dry-run', 'mostra o que enviaria, sem enviar')
+    .option('--offline', 'checa com a taxonomia embutida (o envio continua precisando do Core)')
+    .option('--json', 'saída em JSON')
+    .action(async (opts) => {
+    const { runDocsSync } = await import('./commands/docs-produto.js');
+    await runDocsSync({ dryRun: !!opts.dryRun, offline: !!opts.offline, json: !!opts.json });
+});
 // ── neetru webhooks ──────────────────────────────────────────────────
 // Produtos SaaS registram endpoints de webhook pra receber eventos do Core.
 const webhooksCmd = program
@@ -2875,6 +2985,7 @@ webhooksCmd
     .requiredOption('--product-id <id>', 'ID do produto')
     .option('--yes', 'pula a confirmação interativa (necessário em --json/CI)')
     .option('--force', 'alias de --yes')
+    .option('--mfa-token <code>', 'código TOTP para step-up MFA (ou use `neetru auth mfa-session`)')
     .option('--json', 'saída em JSON')
     .action(async (id, opts) => {
     const { runWebhooksUnregister } = await import('./commands/webhooks.js');
@@ -2883,6 +2994,7 @@ webhooksCmd
         productId: opts.productId,
         yes: !!opts.yes,
         force: !!opts.force,
+        mfaToken: opts.mfaToken,
         json: !!opts.json,
     });
 });
@@ -2951,6 +3063,16 @@ domainsCmd
     const { runDomainsRetry } = await import('./commands/domains.js');
     await runDomainsRetry({ product: opts.product, sub: opts.sub, json: !!opts.json });
 });
+// ── neetru secrets ──────────────────────────────────────────────────
+// Segredos PRÓPRIOS do produto (bug_8b85353b, Parte 3): registrar/trocar
+// (`set`, inclusive `--generate`), listar só nomes (`list`) e arquivar
+// (`archive`). O valor vai direto pro Secret Manager e nunca entra pelo argv.
+// Contrato: core#632 (GET/POST/DELETE /api/cli/v1/products/{slug}/secrets).
+// @top-level: secrets
+{
+    const { registerSecretsCommand } = await import('./commands/secrets.js');
+    registerSecretsCommand(program);
+}
 // ── neetru mobile ───────────────────────────────────────────────────
 // Devs/IAs registram/listam/revogam Apps Mobile (iOS/Android) do produto
 // atual (lido de neetru.config.json no cwd). Dev-facing, self-service —

package/dist/lib/api-client.d.ts

@@ -11,8 +11,15 @@ export declare class CliApiError extends Error {
      * de debug de campo (usuário informa o `ref:` ao suporte).
      */
     readonly correlationId?: string;
-    constructor(status: number, code: string, message: string, correlationId?: string);
+    /**
+     * Segundos pedidos pelo `Retry-After` (429/503), quando o Core manda. Usado
+     * por quem faz vários envios em sequência (ex.: `neetru docs sync`).
+     */
+    readonly retryAfterSeconds?: number;
+    constructor(status: number, code: string, message: string, correlationId?: string, retryAfterSeconds?: number);
 }
+/** `Retry-After` em segundos (aceita número ou data HTTP). undefined se ausente/ilegível. */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
 export declare class CliNetworkError extends Error {
     readonly cause?: unknown;
     constructor(message: string, cause?: unknown);
@@ -43,6 +50,20 @@ interface StreamOptions {
 export declare function assertTrustedApiHost(rawUrl: string): void;
 /** @deprecated Nome legado — agora é fail-closed (throw), não só warning. Use `assertTrustedApiHost`. */
 export declare const maybeWarnUntrustedHost: typeof assertTrustedApiHost;
+/**
+ * URL absoluta de um path da API do Core: MESMA base (`neetruApiUrl`) e MESMA
+ * guarda fail-closed de `apiRequest`/`apiStream`. Lança `CliNetworkError` se a
+ * base estiver fora da allowlist — antes de qualquer Bearer sair da máquina.
+ *
+ * Todo `fetch` que leve o token da CLI e não passe por `apiRequest`/`apiStream`
+ * (ex.: o SSE de `neetru logs -f`, que precisa ler o corpo aos poucos) monta a
+ * URL por aqui. C7 (2026-10-13): o stream do `logs -f` lia uma chave
+ * `apiBase` (que nem existe no schema do config) e fazia `fetch` direto, sem a
+ * guarda — com `"apiBase":"https://coletor.malicioso"` no `config.json`, o
+ * segundo request ia pra lá com `Bearer nrt_…`, reabrindo o ataque que o
+ * LABS #4 fechou aqui; e o `neetruApiUrl` de staging/local era ignorado.
+ */
+export declare function resolveTrustedApiUrl(path: string): string;
 /** @deprecated Sem estado agora (fail-closed não tem flag one-shot). No-op mantido p/ compat de teste. */
 export declare function _resetUntrustedHostWarningForTests(): void;
 export declare function apiRequest<T>(path: string, opts?: RequestOptions): Promise<T>;

package/dist/lib/api-client.js

@@ -12,14 +12,32 @@ export class CliApiError extends Error {
      * de debug de campo (usuário informa o `ref:` ao suporte).
      */
     correlationId;
-    constructor(status, code, message, correlationId) {
+    /**
+     * Segundos pedidos pelo `Retry-After` (429/503), quando o Core manda. Usado
+     * por quem faz vários envios em sequência (ex.: `neetru docs sync`).
+     */
+    retryAfterSeconds;
+    constructor(status, code, message, correlationId, retryAfterSeconds) {
         super(message);
         this.name = 'CliApiError';
         this.status = status;
         this.code = code;
         this.correlationId = correlationId;
+        this.retryAfterSeconds = retryAfterSeconds;
     }
 }
+/** `Retry-After` em segundos (aceita número ou data HTTP). undefined se ausente/ilegível. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (!value)
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return Number.parseInt(v, 10);
+    const at = Date.parse(v);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - now) / 1000));
+}
 export class CliNetworkError extends Error {
     cause;
     constructor(message, cause) {
@@ -51,16 +69,32 @@ export function assertTrustedApiHost(rawUrl) {
 }
 /** @deprecated Nome legado — agora é fail-closed (throw), não só warning. Use `assertTrustedApiHost`. */
 export const maybeWarnUntrustedHost = assertTrustedApiHost;
+/**
+ * URL absoluta de um path da API do Core: MESMA base (`neetruApiUrl`) e MESMA
+ * guarda fail-closed de `apiRequest`/`apiStream`. Lança `CliNetworkError` se a
+ * base estiver fora da allowlist — antes de qualquer Bearer sair da máquina.
+ *
+ * Todo `fetch` que leve o token da CLI e não passe por `apiRequest`/`apiStream`
+ * (ex.: o SSE de `neetru logs -f`, que precisa ler o corpo aos poucos) monta a
+ * URL por aqui. C7 (2026-10-13): o stream do `logs -f` lia uma chave
+ * `apiBase` (que nem existe no schema do config) e fazia `fetch` direto, sem a
+ * guarda — com `"apiBase":"https://coletor.malicioso"` no `config.json`, o
+ * segundo request ia pra lá com `Bearer nrt_…`, reabrindo o ataque que o
+ * LABS #4 fechou aqui; e o `neetruApiUrl` de staging/local era ignorado.
+ */
+export function resolveTrustedApiUrl(path) {
+    const baseUrl = buildBaseUrl();
+    assertTrustedApiHost(baseUrl);
+    return `${baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+}
 /** @deprecated Sem estado agora (fail-closed não tem flag one-shot). No-op mantido p/ compat de teste. */
 export function _resetUntrustedHostWarningForTests() {
     /* no-op */
 }
 export async function apiRequest(path, opts = {}) {
-    const baseUrl = buildBaseUrl();
-    const url = `${baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
     // LABS #4 (2026-09-28): fail-closed — bloqueia host fora da allowlist ANTES
     // de anexar o Bearer (era só warning que mandava o token assim mesmo).
-    assertTrustedApiHost(baseUrl);
+    const url = resolveTrustedApiUrl(path);
     // MASTER-HIGH-048 (2.11.0): prefere auth.json (canonico) sobre Conf (legacy).
     const token = opts.token ?? getActiveTokenSync();
     const headers = {
@@ -167,9 +201,48 @@ export async function apiRequest(path, opts = {}) {
         else if (typeof parsed === 'string' && parsed.trim() !== '') {
             message = parsed;
         }
+        else if (errBody && typeof errBody === 'object') {
+            // bug_a3c4d7a8 / achado 2026-10-12: o Core tem TRÊS formatos de erro e
+            // este ramo cobre o terceiro, que antes caía no chão inteiro.
+            //
+            //   1. `{ error: { code, message } }`      — canônico (`cliJsonError`)
+            //   2. `{ error: "x", error_description }` — RFC 6749 (OAuth)
+            //   3. `{ ok: false, code, reason, ... }`  — rotas que respondem direto
+            //
+            // O formato 3 NÃO tem a chave `error`, então o `if (errBody?.error)` acima
+            // era pulado e tudo virava `Erro HTTP <status>`. Medido no campo: o
+            // `GET /servers/{id}/logs?source=startup` devolve 410 com `code`, um
+            // `reason` de dez linhas e quatro `alternatives` acionáveis — e o operador
+            // lia apenas "Requisição rejeitada (410): Erro HTTP 410". Pior: o
+            // `servers get` RECOMENDA esse comando justamente quando o agente morreu,
+            // então a mensagem inútil chega no pior momento possível.
+            const cru = errBody;
+            if (typeof cru.code === 'string' && cru.code)
+                code = cru.code;
+            // `reason` primeiro: é o campo que as rotas do formato 3 usam pro texto
+            // longo. `message`/`detail`/`hint` cobrem as variações que já existem.
+            for (const chave of ['reason', 'message', 'detail', 'hint']) {
+                const v = cru[chave];
+                if (typeof v === 'string' && v.trim() !== '') {
+                    message = v;
+                    break;
+                }
+            }
+            // O que fazer EM VEZ disso é a parte que salva o operador; sem anexar
+            // aqui, ela morre no servidor. Só strings — nada de despejar objeto na
+            // cara de quem lê.
+            const alt = cru.alternatives;
+            if (alt && typeof alt === 'object' && !Array.isArray(alt)) {
+                const linhas = Object.entries(alt)
+                    .filter(([, v]) => typeof v === 'string' && v.trim() !== '')
+                    .map(([k, v]) => `  ${k}: ${v}`);
+                if (linhas.length > 0)
+                    message = `${message}\n\nAlternativas:\n${linhas.join('\n')}`;
+            }
+        }
         // LABS #6 (2026-09-28): captura o x-correlation-id do Core p/ o rodapé do erro.
         const correlationId = response.headers.get('x-correlation-id') ?? undefined;
-        throw new CliApiError(response.status, code, message, correlationId);
+        throw new CliApiError(response.status, code, message, correlationId, parseRetryAfter(response.headers.get('retry-after')));
     }
     return parsed;
 }
@@ -182,10 +255,8 @@ export async function apiRequest(path, opts = {}) {
  * `opts.signal` (Ctrl-C). Erros HTTP antes do stream abrir viram `CliApiError`.
  */
 export async function* apiStream(path, opts = {}) {
-    const baseUrl = buildBaseUrl();
-    const url = `${baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
     // LABS #4 (2026-09-28): fail-closed também no stream.
-    assertTrustedApiHost(baseUrl);
+    const url = resolveTrustedApiUrl(path);
     // MASTER-HIGH-048 (2.11.0): mesmo helper aplica ao stream NDJSON.
     const token = opts.token ?? getActiveTokenSync();
     const headers = {

package/dist/lib/api-error.d.ts

@@ -1,3 +1,4 @@
+import { NeetruCliError } from '../cli-kit/errors.js';
 /** Exit codes canônicos, exportados pra teste/documentação. */
 export declare const API_ERROR_EXIT: {
     readonly client: 1;
@@ -5,4 +6,17 @@ export declare const API_ERROR_EXIT: {
     readonly forbidden: 3;
     readonly server: 4;
 };
+/**
+ * O que fazer diante de `401 mfa_required`. bug_757b9746 nasceu aqui: o texto
+ * mandava passar `--mfa-token` a qualquer comando, inclusive aos que não
+ * declaravam a flag. Agora a flag só é citada se o comando em execução a
+ * declara; senão, a alternativa que existe sempre — a sessão de 1h.
+ */
+export declare function mfaRequiredAdvice(): string;
+/**
+ * Traduz qualquer erro para o `NeetruCliError` canônico — sem imprimir nem
+ * encerrar. Exportado para teste e para quem precise agregar erros de API
+ * como filhos de uma falha parcial.
+ */
+export declare function cliErrorFromApiError(error: unknown): NeetruCliError;
 export declare function handleApiError(error: unknown, json?: boolean): never;