@neetru/cli 2.31.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')
@@ -176,9 +197,9 @@ 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)')
@@ -403,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')
@@ -416,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,
@@ -602,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) => {
@@ -624,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) => {
@@ -901,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')
@@ -939,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) => {
@@ -976,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) => {
@@ -1209,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) => {
@@ -1389,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 —
@@ -1613,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]')
@@ -1638,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
@@ -2052,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())
@@ -2941,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');
@@ -2949,6 +2994,7 @@ webhooksCmd
         productId: opts.productId,
         yes: !!opts.yes,
         force: !!opts.force,
+        mfaToken: opts.mfaToken,
         json: !!opts.json,
     });
 });
@@ -3017,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

@@ -50,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

@@ -69,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 = {
@@ -185,6 +201,45 @@ 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, parseRetryAfter(response.headers.get('retry-after')));
@@ -200,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;

package/dist/lib/api-error.js

@@ -16,23 +16,29 @@
  *
  * Imprime a mensagem adequada (texto humano ou JSON com `--json`) e encerra o
  * processo — nunca retorna (`never`).
+ *
+ * bug_89d2497e (2026-10-17): o erro de API vira um `NeetruCliError` (cli-kit)
+ * com o exit code da tabela acima e o erro original em `cause`; quem imprime e
+ * encerra é `exitWithCliError`. O formato do JSON e os códigos de saída são os
+ * mesmos de antes. Um `NeetruCliError` que chegue aqui (ex.: lançado dentro do
+ * `try` de um comando) sai com o código DELE, sem ser reclassificado.
  */
 import { CliApiError, CliNetworkError } from './api-client.js';
-import { log } from '../utils/logger.js';
-import { safeExit } from '../utils/safe-exit.js';
-/** Exit codes canônicos, exportados pra teste/documentação. */
-export const API_ERROR_EXIT = {
-    client: 1, // 4xx de input/recurso
-    unauthenticated: 2, // 401
-    forbidden: 3, // 403
-    server: 4, // 5xx / rede / desconhecido
-};
-function emit(json, payload, text) {
-    if (json)
-        console.log(JSON.stringify(payload));
-    else
-        log.error(text);
+import { EXIT_CODES, NeetruCliError } from '../cli-kit/errors.js';
+import { adviseCommand, adviseFlag } from '../cli-kit/command-context.js';
+import { exitWithCliError } from './cli-error.js';
+/**
+ * Reconhece o `SafeExitHalt` de `utils/safe-exit.ts` pela marca, sem importar
+ * `isSafeExitHalt`: dezenas de testes mockam `safe-exit.js` só com `safeExit`,
+ * e ler outra exportação de um mock incompleto lança no vitest.
+ */
+function isSafeExitHalt(x) {
+    return (typeof x === 'object' &&
+        x !== null &&
+        x.__neetruSafeExit === true);
 }
+/** Exit codes canônicos, exportados pra teste/documentação. */
+export const API_ERROR_EXIT = EXIT_CODES;
 /**
  * A mensagem do 401 vale ser exibida? O Core legado mandava só
  * `{ error: 'Unauthorized' }` (o parser vira message='Unauthorized') — aí o
@@ -45,7 +51,30 @@ function isInformative401Message(message) {
         return false;
     return !/^(unauthori[sz]ed|erro http 401)$/i.test(m);
 }
-export function handleApiError(error, json) {
+/**
+ * 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 function mfaRequiredAdvice() {
+    // P105: o comando alternativo também é validado — contra a árvore do
+    // Commander. Sem ele (ou sem árvore conhecida), a dica não o cita.
+    const sessao = (withCommand, withoutCommand) => adviseCommand({ command: 'auth mfa-session', withCommand, withoutCommand });
+    return adviseFlag({
+        flag: '--mfa-token',
+        withFlag: sessao('  Passe --mfa-token <código TOTP> ou rode `neetru auth mfa-session` (sessão de 1h).', '  Passe --mfa-token <código TOTP>.'),
+        withoutFlag: sessao('  Rode `neetru auth mfa-session` (sessão de 1h) e repita o comando.', '  Este comando exige step-up MFA e esta CLI não tem, nele, como enviá-lo.'),
+    });
+}
+/**
+ * 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 function cliErrorFromApiError(error) {
+    if (error instanceof NeetruCliError)
+        return error;
     if (error instanceof CliApiError) {
         const s = error.status;
         if (s === 401) {
@@ -54,48 +83,80 @@ export function handleApiError(error, json) {
             // Antes TODO 401 virava "Token inválido ou revogado" — inclusive o de MFA
             // faltando, mandando o operador fazer `neetru login` à toa.
             if (error.code === 'mfa_required') {
-                emit(json, { ok: false, error: 'mfa_required', code: error.code, status: s, message: error.message }, `Step-up MFA exigido: ${error.message}
-` +
-                    '  Passe --mfa-token <código TOTP> ou rode `neetru auth mfa-session` (sessão de 1h).');
-                safeExit(API_ERROR_EXIT.unauthenticated);
+                return new NeetruCliError(error.message, {
+                    code: 'mfa_required',
+                    exit: EXIT_CODES.unauthenticated,
+                    cause: error,
+                    details: { code: error.code, status: s },
+                    human: `Step-up MFA exigido: ${error.message}\n${mfaRequiredAdvice()}`,
+                });
             }
             const serverMsg = isInformative401Message(error.message) ? error.message : '';
-            emit(json, {
-                ok: false,
-                error: 'unauthorized',
-                ...(error.code && error.code !== 'http_401' ? { code: error.code } : {}),
-                status: s,
-                message: error.message,
-            }, serverMsg
-                ? `Não autenticado: ${serverMsg}${/neetru login/.test(serverMsg) ? '' : ' — execute: neetru login'}`
-                : 'Token inválido ou revogado. Execute: neetru login');
-            safeExit(API_ERROR_EXIT.unauthenticated);
+            return new NeetruCliError(error.message, {
+                code: 'unauthorized',
+                exit: EXIT_CODES.unauthenticated,
+                cause: error,
+                details: {
+                    ...(error.code && error.code !== 'http_401' ? { code: error.code } : {}),
+                    status: s,
+                },
+                human: serverMsg
+                    ? `Não autenticado: ${serverMsg}${/neetru login/.test(serverMsg) ? '' : ' — execute: neetru login'}`
+                    : 'Token inválido ou revogado. Execute: neetru login',
+            });
         }
         if (s === 403) {
-            emit(json, { ok: false, error: 'forbidden', status: s, message: error.message }, `Acesso negado: ${error.message}`);
-            safeExit(API_ERROR_EXIT.forbidden);
+            return new NeetruCliError(error.message, {
+                code: 'forbidden',
+                exit: EXIT_CODES.forbidden,
+                cause: error,
+                details: { status: s },
+                human: `Acesso negado: ${error.message}`,
+            });
         }
         if (s >= 400 && s < 500) {
-            emit(json, {
-                ok: false,
-                error: s === 404 ? 'not_found' : (error.code ?? 'client_error'),
-                status: s,
-                message: error.message,
-            }, s === 404
-                ? error.message || 'Recurso não encontrado.'
-                : `Requisição rejeitada (${s}): ${error.message}`);
-            safeExit(API_ERROR_EXIT.client);
+            // Valores válidos de um enum recusado pelo Core (ex.: `environmentId
+            // inválido — use: dev-local | staging | prod.`) vêm no `message` do
+            // próprio Core, que é a fonte que validou: o texto passa inteiro, sem
+            // corte e sem lista copiada do lado de cá.
+            return new NeetruCliError(error.message, {
+                code: s === 404 ? 'not_found' : (error.code ?? 'client_error'),
+                exit: EXIT_CODES.client,
+                cause: error,
+                details: { status: s },
+                human: s === 404
+                    ? error.message || 'Recurso não encontrado.'
+                    : `Requisição rejeitada (${s}): ${error.message}`,
+            });
         }
         // 5xx (incl. 501 — não implementado).
-        emit(json, { ok: false, error: error.code ?? 'server_error', status: s, message: error.message }, `Erro do servidor (${s}): ${error.message}`);
-        safeExit(API_ERROR_EXIT.server);
+        return new NeetruCliError(error.message, {
+            code: error.code ?? 'server_error',
+            exit: EXIT_CODES.server,
+            cause: error,
+            details: { status: s },
+            human: `Erro do servidor (${s}): ${error.message}`,
+        });
     }
     if (error instanceof CliNetworkError) {
-        emit(json, { ok: false, error: 'network', message: error.message }, `Falha de rede: ${error.message}`);
-        safeExit(API_ERROR_EXIT.server);
+        return new NeetruCliError(error.message, {
+            code: 'network',
+            exit: EXIT_CODES.server,
+            cause: error,
+            human: `Falha de rede: ${error.message}`,
+        });
     }
     const message = error instanceof Error ? error.message : String(error);
-    emit(json, { ok: false, error: 'unknown', message }, message);
-    safeExit(API_ERROR_EXIT.server);
+    return new NeetruCliError(message, { code: 'unknown', exit: EXIT_CODES.server, cause: error });
+}
+export function handleApiError(error, json) {
+    // `safeExit` lança `SafeExitHalt` em produção para parar o caller. Dentro de
+    // `try { …; safeExit(n) } catch (e) { handleApiError(e) }` o sinal caía aqui
+    // e virava um segundo erro "[object Object]" — e, em `--json`, uma SEGUNDA
+    // linha de JSON no stdout. A saída já está agendada com o código certo:
+    // o sinal só segue adiante.
+    if (isSafeExitHalt(error))
+        throw error;
+    return exitWithCliError(cliErrorFromApiError(error), json);
 }
 //# sourceMappingURL=api-error.js.map