@neetru/cli 2.29.0 → 2.32.0

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

@@ -0,0 +1,13 @@
+/**
+ * Saída do processo a partir de um `NeetruCliError` (bug_89d2497e, etapa 3).
+ *
+ * O cli-kit monta o erro (puro); aqui ele é impresso — JSON no stdout em
+ * `--json`, texto humano no stderr fora dele — e o processo sai com o código
+ * de saída DO ERRO. Ponto único: `handleApiError`, `resolveStepUp`, a validação
+ * de `--env` e o trap global de `index.ts` passam por aqui.
+ */
+import { NeetruCliError } from '../cli-kit/errors.js';
+/** Imprime o erro e devolve o código de saída — sem encerrar. */
+export declare function emitCliError(error: NeetruCliError, json?: boolean): number;
+/** Imprime o erro e encerra com o código de saída dele. Nunca retorna. */
+export declare function exitWithCliError(error: NeetruCliError, json?: boolean): never;

package/dist/lib/cli-error.js

@@ -0,0 +1,24 @@
+/**
+ * Saída do processo a partir de um `NeetruCliError` (bug_89d2497e, etapa 3).
+ *
+ * O cli-kit monta o erro (puro); aqui ele é impresso — JSON no stdout em
+ * `--json`, texto humano no stderr fora dele — e o processo sai com o código
+ * de saída DO ERRO. Ponto único: `handleApiError`, `resolveStepUp`, a validação
+ * de `--env` e o trap global de `index.ts` passam por aqui.
+ */
+import { renderCliError } from '../cli-kit/errors.js';
+import { log } from '../utils/logger.js';
+import { safeExit } from '../utils/safe-exit.js';
+/** Imprime o erro e devolve o código de saída — sem encerrar. */
+export function emitCliError(error, json) {
+    if (json)
+        console.log(JSON.stringify(error.toJSON()));
+    else
+        log.error(renderCliError(error));
+    return error.exit;
+}
+/** Imprime o erro e encerra com o código de saída dele. Nunca retorna. */
+export function exitWithCliError(error, json) {
+    return safeExit(emitCliError(error, json));
+}
+//# sourceMappingURL=cli-error.js.map

package/dist/lib/cli-write.d.ts

@@ -18,6 +18,27 @@ export declare function saveMfaSession(mfaSessionToken: string, expiresAt: strin
  * apagado junto com o Bearer token.
  */
 export declare function clearMfaSession(): Promise<void>;
+/**
+ * uid dono de um token de sessão MFA. O Core emite
+ * `<uid_base64url>.<issuedAt_hex>.<hmac_sha256_hex>` (`createCliMfaSessionToken`
+ * em `src/lib/auth-mfa-session.ts`): o uid é a parte ASSINADA, não segredo — o
+ * servidor só aceita a sessão se ele bater com o uid do Bearer. `null` se o
+ * formato não for reconhecido.
+ */
+export declare function mfaSessionOwnerUid(token: string): string | null;
+/**
+ * Descarta a sessão MFA salva quando ela não é do `uid` que acabou de logar.
+ *
+ * A8 (2026-10-13): `neetru login` com outra conta trocava o Bearer mas deixava
+ * o `mfa-session.json` da conta anterior. O Core recusa sessão de outro uid,
+ * então TODO comando destrutivo tomava 401 `mfa_required` por até 1h (e, antes
+ * do conserto da precedência em `resolveStepUp`, nem `--mfa-token` salvava).
+ * Sessão de dono desconhecido (arquivo corrompido, formato não reconhecido)
+ * também sai — o servidor recusaria do mesmo jeito. Sessão do MESMO uid fica
+ * (re-login na mesma conta não deve exigir TOTP de novo). Retorna `true` se
+ * apagou.
+ */
+export declare function discardMfaSessionOfOtherUid(uid: string): Promise<boolean>;
 export interface ConfirmOptions {
     /** `--yes` / `--force` — pula a confirmação (modo script/CI). */
     yes?: boolean;
@@ -25,6 +46,17 @@ export interface ConfirmOptions {
     /** Saída em JSON — não imprime prompt humano. */
     json?: boolean;
 }
+/**
+ * O que dizer quando a confirmação não pode ser perguntada (P105 /
+ * bug_89d2497e). Cita só as flags de confirmação que o comando EM EXECUÇÃO
+ * declara: o texto fixo "use --yes (ou --force)" chegava a 8 comandos que
+ * declaram `--yes` mas não `--force` (medido na árvore do Commander em
+ * 2026-10-18: `servers pgbouncer sync-userlist`, `products memory set`,
+ * `vm memory set`, `db move start|abort|decommission`, `promote execute`,
+ * `mobile revoke`) — quem seguisse com `--force` tomava "unknown option".
+ * Sem nenhuma das duas (ou fora do Commander, como no menu), não cita flag.
+ */
+export declare function confirmationAdvice(modo: 'json' | 'nao-interativo'): string;
 /**
  * Gate de confirmação pra operações DESTRUTIVAS (suspend, deactivate, delete,
  * rollback, archive, yank). Se `--yes`/`--force` foi passado, retorna sem
@@ -58,19 +90,21 @@ export interface StepUpOptions extends ConfirmOptions {
 }
 /**
  * Resolve o que uma operação destrutiva TOP-TIER precisa mandar pro servidor:
- *  - `headers`: `X-Neetru-MFA-Session` (sessão de 1h) OU `X-Neetru-MFA-Token`
- *    (TOTP fresco) e/ou `X-Neetru-Dry-Run`.
+ *  - `headers`: `X-Neetru-MFA-Token` (TOTP fresco) OU `X-Neetru-MFA-Session`
+ *    (sessão de 1h) e/ou `X-Neetru-Dry-Run`.
  *
  * Ordem de preferência:
  *   1. dry-run: sem MFA, só `X-Neetru-Dry-Run: true`.
- *   2. Sessão de 1h salva localmente (`~/.config/neetru-cli/mfa-session.json`):
- *      usa `X-Neetru-MFA-Session` sem pedir TOTP. Silencioso — o operador
- *      não precisa saber que a sessão está ativa.
- *   3. TOTP fresco: do flag `--mfa-token` ou prompt interativo.
- *      Em terminal não-interativo sem `--mfa-token`, encerra com instrução
- *      clara — o servidor recusaria de qualquer forma (fail-closed).
+ *   2. `--mfa-token` explícito: manda `X-Neetru-MFA-Token` — e também a sessão
+ *      salva, se houver (o Core tenta a sessão antes e não gasta o TOTP à toa).
+ *      O código NUNCA é descartado em favor da sessão (A8).
+ *   3. Sessão de 1h salva localmente: usa `X-Neetru-MFA-Session` sem pedir
+ *      TOTP. Silencioso — o operador não precisa saber que a sessão está ativa.
+ *   4. Prompt interativo do TOTP. Em `--json`/não-interativo sem código nem
+ *      sessão, encerra com instrução clara — o servidor recusaria de qualquer
+ *      forma (fail-closed).
  *
- * feature mfa-session (2026-06-12): o item 2 elimina o re-prompt TOTP a cada
+ * feature mfa-session (2026-06-12): o item 3 elimina o re-prompt TOTP a cada
  * comando destrutivo quando o operador já rodou `neetru auth mfa-session`.
  */
 export declare function resolveStepUp(opts: StepUpOptions): Promise<{

package/dist/lib/cli-write.js

@@ -20,6 +20,9 @@ import { requireToken, handleApiError } from './cli-read.js';
 import { CliApiError } from './api-client.js';
 import { log } from '../utils/logger.js';
 import { safeExit } from '../utils/safe-exit.js';
+import { EXIT_CODES, NeetruCliError } from '../cli-kit/errors.js';
+import { adviseCommand, adviseFlag, declaredFlags } from '../cli-kit/command-context.js';
+import { exitWithCliError } from './cli-error.js';
 export { requireToken, handleApiError };
 function getMfaSessionFilePath() {
     return join(homedir(), '.config', 'neetru-cli', 'mfa-session.json');
@@ -89,6 +92,55 @@ export async function clearMfaSession() {
         // Ignora — arquivo já inexistente ou sem permissão.
     }
 }
+/**
+ * uid dono de um token de sessão MFA. O Core emite
+ * `<uid_base64url>.<issuedAt_hex>.<hmac_sha256_hex>` (`createCliMfaSessionToken`
+ * em `src/lib/auth-mfa-session.ts`): o uid é a parte ASSINADA, não segredo — o
+ * servidor só aceita a sessão se ele bater com o uid do Bearer. `null` se o
+ * formato não for reconhecido.
+ */
+export function mfaSessionOwnerUid(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[0])
+        return null;
+    try {
+        const uid = Buffer.from(parts[0], 'base64url').toString('utf8');
+        return /^[\x21-\x7e]+$/.test(uid) ? uid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Descarta a sessão MFA salva quando ela não é do `uid` que acabou de logar.
+ *
+ * A8 (2026-10-13): `neetru login` com outra conta trocava o Bearer mas deixava
+ * o `mfa-session.json` da conta anterior. O Core recusa sessão de outro uid,
+ * então TODO comando destrutivo tomava 401 `mfa_required` por até 1h (e, antes
+ * do conserto da precedência em `resolveStepUp`, nem `--mfa-token` salvava).
+ * Sessão de dono desconhecido (arquivo corrompido, formato não reconhecido)
+ * também sai — o servidor recusaria do mesmo jeito. Sessão do MESMO uid fica
+ * (re-login na mesma conta não deve exigir TOTP de novo). Retorna `true` se
+ * apagou.
+ */
+export async function discardMfaSessionOfOtherUid(uid) {
+    const path = getMfaSessionFilePath();
+    if (!existsSync(path))
+        return false;
+    let owner = null;
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof data.mfaSessionToken === 'string')
+            owner = mfaSessionOwnerUid(data.mfaSessionToken);
+    }
+    catch {
+        // corrompido → dono desconhecido → descarta
+    }
+    if (owner !== null && owner === uid)
+        return false;
+    await clearMfaSession();
+    return true;
+}
 /**
  * Pede uma confirmação interativa `y/N` no terminal. Resolve `true` se o
  * operador digitou `y`/`yes` (case-insensitive); `false` caso contrário.
@@ -108,6 +160,31 @@ function promptYesNo(question) {
         });
     });
 }
+/** As flags que pulam a confirmação, na ordem em que o conselho as cita. */
+const FLAGS_DE_CONFIRMACAO = ['--yes', '--force'];
+/**
+ * O que dizer quando a confirmação não pode ser perguntada (P105 /
+ * bug_89d2497e). Cita só as flags de confirmação que o comando EM EXECUÇÃO
+ * declara: o texto fixo "use --yes (ou --force)" chegava a 8 comandos que
+ * declaram `--yes` mas não `--force` (medido na árvore do Commander em
+ * 2026-10-18: `servers pgbouncer sync-userlist`, `products memory set`,
+ * `vm memory set`, `db move start|abort|decommission`, `promote execute`,
+ * `mobile revoke`) — quem seguisse com `--force` tomava "unknown option".
+ * Sem nenhuma das duas (ou fora do Commander, como no menu), não cita flag.
+ */
+export function confirmationAdvice(modo) {
+    const flags = declaredFlags(FLAGS_DE_CONFIRMACAO);
+    if (modo === 'json') {
+        return flags.length > 0
+            ? `Operação destrutiva em modo --json exige ${flags[0]}.`
+            : 'Operação destrutiva em modo --json exige confirmação, e este comando não tem como confirmar sem perguntar.';
+    }
+    if (flags.length === 0) {
+        return 'Terminal não-interativo: esta operação destrutiva só pode ser confirmada num terminal interativo.';
+    }
+    const lista = flags.length > 1 ? `${flags[0]} (ou ${flags[1]})` : flags[0];
+    return `Terminal não-interativo: use ${lista} para confirmar operações destrutivas.`;
+}
 /**
  * Gate de confirmação pra operações DESTRUTIVAS (suspend, deactivate, delete,
  * rollback, archive, yank). Se `--yes`/`--force` foi passado, retorna sem
@@ -129,7 +206,7 @@ export async function confirmDestructive(message, opts) {
         console.log(JSON.stringify({
             ok: false,
             error: 'confirmation_required',
-            message: 'Operação destrutiva em modo --json exige --yes.',
+            message: confirmationAdvice('json'),
         }));
         safeExit(1);
     }
@@ -137,7 +214,7 @@ export async function confirmDestructive(message, opts) {
     const confirmed = await promptYesNo('Confirmar?');
     if (!confirmed) {
         if (!process.stdin.isTTY) {
-            log.error('Terminal não-interativo: use --yes (ou --force) para confirmar operações destrutivas.');
+            log.error(confirmationAdvice('nao-interativo'));
         }
         else {
             log.dim('Operação cancelada.');
@@ -157,21 +234,56 @@ function promptLine(question) {
         });
     });
 }
+/**
+ * O step-up que dá pra mandar SEM interação, na ordem de precedência:
+ *   1. `--mfa-token` explícito → `X-Neetru-MFA-Token`;
+ *   2. sessão de 1h salva (`~/.config/neetru-cli/mfa-session.json`) →
+ *      `X-Neetru-MFA-Session` (salvo `skipSession`).
+ * `{}` se não houver nenhum dos dois (aí o caller prompta ou falha fechado).
+ *
+ * A8 (2026-10-13): o código explícito VENCE a sessão. Antes `resolveStepUp`
+ * olhava a sessão primeiro e devolvia só `X-Neetru-MFA-Session`, descartando o
+ * `--mfa-token` em silêncio — enquanto `withStepUpRetry` fazia o contrário.
+ * Depois de `neetru login` com outra conta (sessão do uid anterior no disco,
+ * que o Core recusa), ~40 comandos destrutivos davam 401 por até 1h MESMO com
+ * `--mfa-token`. Quem digita o código está pedindo que ele seja usado. As duas
+ * funções agora decidem por aqui — uma regra só.
+ */
+function nonInteractiveStepUp(opts) {
+    const code = (opts.mfaToken ?? '').trim();
+    const savedSession = opts.skipSession ? null : loadMfaSession();
+    // Código explícito + sessão salva: manda OS DOIS (revisão do #78). O Core
+    // (`requireCliStepUpMfa`) tenta a sessão primeiro e só usa o TOTP se ela não
+    // servir — e o TOTP é de USO ÚNICO (`mfa-lockout`). Mandar só o código gastava
+    // o código à toa quando a sessão era válida, e o 2º comando com o mesmo código
+    // (agente com o código ditado, script) falhava com mfa_invalid. Com os dois, a
+    // sessão de OUTRA conta (o caso do A8) cai e o código ainda salva o pedido.
+    if (code) {
+        return savedSession
+            ? { 'X-Neetru-MFA-Token': code, 'X-Neetru-MFA-Session': savedSession }
+            : { 'X-Neetru-MFA-Token': code };
+    }
+    if (savedSession)
+        return { 'X-Neetru-MFA-Session': savedSession };
+    return {};
+}
 /**
  * Resolve o que uma operação destrutiva TOP-TIER precisa mandar pro servidor:
- *  - `headers`: `X-Neetru-MFA-Session` (sessão de 1h) OU `X-Neetru-MFA-Token`
- *    (TOTP fresco) e/ou `X-Neetru-Dry-Run`.
+ *  - `headers`: `X-Neetru-MFA-Token` (TOTP fresco) OU `X-Neetru-MFA-Session`
+ *    (sessão de 1h) e/ou `X-Neetru-Dry-Run`.
  *
  * Ordem de preferência:
  *   1. dry-run: sem MFA, só `X-Neetru-Dry-Run: true`.
- *   2. Sessão de 1h salva localmente (`~/.config/neetru-cli/mfa-session.json`):
- *      usa `X-Neetru-MFA-Session` sem pedir TOTP. Silencioso — o operador
- *      não precisa saber que a sessão está ativa.
- *   3. TOTP fresco: do flag `--mfa-token` ou prompt interativo.
- *      Em terminal não-interativo sem `--mfa-token`, encerra com instrução
- *      clara — o servidor recusaria de qualquer forma (fail-closed).
+ *   2. `--mfa-token` explícito: manda `X-Neetru-MFA-Token` — e também a sessão
+ *      salva, se houver (o Core tenta a sessão antes e não gasta o TOTP à toa).
+ *      O código NUNCA é descartado em favor da sessão (A8).
+ *   3. Sessão de 1h salva localmente: usa `X-Neetru-MFA-Session` sem pedir
+ *      TOTP. Silencioso — o operador não precisa saber que a sessão está ativa.
+ *   4. Prompt interativo do TOTP. Em `--json`/não-interativo sem código nem
+ *      sessão, encerra com instrução clara — o servidor recusaria de qualquer
+ *      forma (fail-closed).
  *
- * feature mfa-session (2026-06-12): o item 2 elimina o re-prompt TOTP a cada
+ * feature mfa-session (2026-06-12): o item 3 elimina o re-prompt TOTP a cada
  * comando destrutivo quando o operador já rodou `neetru auth mfa-session`.
  */
 export async function resolveStepUp(opts) {
@@ -180,34 +292,35 @@ export async function resolveStepUp(opts) {
         headers['X-Neetru-Dry-Run'] = 'true';
         return { headers };
     }
-    // ── Prioridade 2: sessão de 1h salva localmente ─────────────────────────
-    // Verifica ANTES de pedir TOTP — se há sessão válida, usa sem interação.
-    const savedSession = opts.skipSession ? null : loadMfaSession();
-    if (savedSession) {
-        headers['X-Neetru-MFA-Session'] = savedSession;
-        return { headers };
-    }
-    // ── Prioridade 3: TOTP fresco (flag ou prompt) ─────────────────────────
-    let code = (opts.mfaToken ?? '').trim();
-    if (!code) {
-        // bug auditoria 2026-06-30: em --json o prompt interativo de TOTP NÃO pode
-        // rodar NEM com TTY — ele escreveria a pergunta no stdout (corrompe o JSON)
-        // e penduraria um consumidor programático. Fail-CLOSED em --json OU sem TTY;
-        // só promptar em terminal interativo humano (não-json + TTY).
-        if (opts.json || opts.nonInteractive || !process.stdin.isTTY) {
-            const msg = 'Operação destrutiva top-tier exige step-up MFA: passe --mfa-token <código TOTP> ' +
-                '(modo --json/não-interativo) ou rode `neetru auth mfa-session` para obter uma sessão de 1h.';
-            if (opts.json) {
-                console.log(JSON.stringify({ ok: false, error: 'mfa_required', message: msg }));
-            }
-            else {
-                log.error(msg);
-            }
-            safeExit(1);
-            return { headers }; // safeExit não retorna em prod; satisfaz o tipo + testes
-        }
-        code = await promptLine('Código MFA (TOTP) para confirmar:');
+    // ── Prioridades 2 e 3: código explícito, depois sessão de 1h ────────────
+    const ready = nonInteractiveStepUp(opts);
+    if (Object.keys(ready).length > 0)
+        return { headers: ready };
+    // ── Prioridade 4: prompt do TOTP ─────────────────────────────────────────
+    // bug auditoria 2026-06-30: em --json o prompt interativo de TOTP NÃO pode
+    // rodar NEM com TTY — ele escreveria a pergunta no stdout (corrompe o JSON)
+    // e penduraria um consumidor programático. Fail-CLOSED em --json OU sem TTY;
+    // só promptar em terminal interativo humano (não-json + TTY).
+    if (opts.json || opts.nonInteractive || !process.stdin.isTTY) {
+        // bug_89d2497e: o conselho só cita `--mfa-token` se o comando em execução
+        // declara a flag (mesmo defeito do bug_757b9746, do lado do step-up). O
+        // código de saída segue 1 e o JSON segue `{ ok, error:'mfa_required', message }`.
+        // P105: o comando alternativo (`neetru auth mfa-session`) também só é
+        // citado se existe na árvore do Commander.
+        const sessao = (withCommand, withoutCommand) => adviseCommand({ command: 'auth mfa-session', withCommand, withoutCommand });
+        const msg = adviseFlag({
+            flag: '--mfa-token',
+            withFlag: sessao('Operação destrutiva top-tier exige step-up MFA: passe --mfa-token <código TOTP> ' +
+                '(modo --json/não-interativo) ou rode `neetru auth mfa-session` para obter uma sessão de 1h.', 'Operação destrutiva top-tier exige step-up MFA: passe --mfa-token <código TOTP> ' +
+                '(modo --json/não-interativo).'),
+            withoutFlag: sessao('Operação destrutiva top-tier exige step-up MFA: rode `neetru auth mfa-session` ' +
+                'para obter uma sessão de 1h e repita o comando.', 'Operação destrutiva top-tier exige step-up MFA, e esta CLI não tem, neste comando, ' +
+                'como enviá-lo em modo --json/não-interativo.'),
+        });
+        exitWithCliError(new NeetruCliError(msg, { code: 'mfa_required', exit: EXIT_CODES.client }), opts.json);
+        return { headers }; // safeExit não retorna em prod; satisfaz o tipo + testes
     }
+    const code = await promptLine('Código MFA (TOTP) para confirmar:');
     if (!code) {
         log.error('Código MFA não fornecido — operação cancelada.');
         safeExit(1);
@@ -237,13 +350,9 @@ export function isMfaRequiredError(error) {
 export async function withStepUpRetry(opts, doRequest, onError, 
 /** Chamado antes do prompt TOTP do retry (ex.: parar o spinner). */
 beforePrompt) {
-    const first = {};
-    const code = (opts.mfaToken ?? '').trim();
-    const savedSession = code ? null : loadMfaSession();
-    if (code)
-        first['X-Neetru-MFA-Token'] = code;
-    else if (savedSession)
-        first['X-Neetru-MFA-Session'] = savedSession;
+    // Mesma precedência do `resolveStepUp` (A8): código explícito, depois sessão.
+    const first = nonInteractiveStepUp(opts);
+    const code = first['X-Neetru-MFA-Token'];
     let firstError;
     try {
         return await doRequest(first);

package/dist/lib/compose-generator.d.ts

@@ -20,17 +20,21 @@ export declare function resolveDbConfig(engine: string): ComposeDbConfig | null;
 export interface ComposeGeneratorInput {
     productSlug: string;
     dbEngine: string;
-    appPort?: number;
-    coreUrl?: string;
-    firebaseProject?: string;
-    firebaseApiKey?: string;
 }
 /**
- * Gera o conteúdo do docker-compose.dev.yml baseado na config do produto.
- * Template em templates/dev/docker-compose.dev.yml com substituições {{VAR}}.
+ * URL de conexão do host (onde o app roda com `npm run dev`) para o banco do
+ * compose. `null` quando a engine não usa URL (Firestore usa o emulador).
  */
-export declare function generateComposeDev(input: ComposeGeneratorInput): string;
+export declare function localDatabaseUrl(dbEngine: string): string | null;
 /**
- * Escreve o compose + Dockerfile.agent no diretório do projeto.
+ * Gera o conteúdo do `neetru-compose.dev.yml` baseado na config do produto.
+ *
+ * Só o BANCO sobe em container. O agente ficou de fora de propósito
+ * (2026-10-09): o serviço `agent` antigo dependia de um `Dockerfile.agent` que
+ * nenhum caminho do `dev up` gravava (o compose falhava no build e nem o banco
+ * subia), rodava o binário do agente com `node` (é executável `pkg`, não JS) e
+ * ligava um `NEETRU_DEV_MODE` que o agente não implementa — além de montar o
+ * `docker.sock` do host num binário baixado. O agente local volta quando a
+ * sprint dev-suite entregar o modo dev no próprio agente.
  */
-export declare function writeComposeDev(cwd: string, input: ComposeGeneratorInput): string;
+export declare function generateComposeDev(input: ComposeGeneratorInput): string;

package/dist/lib/compose-generator.js

@@ -1,5 +1,3 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 /**
  * Mapeia engine de banco → config Docker Compose.
  * Usa imagens oficiais — mesmas engines que rodam em produção na VM.
@@ -57,12 +55,35 @@ export function resolveDbConfig(engine) {
     return configs['vm-postgres-single'] ?? null; // default
 }
 /**
- * Gera o conteúdo do docker-compose.dev.yml baseado na config do produto.
- * Template em templates/dev/docker-compose.dev.yml com substituições {{VAR}}.
+ * URL de conexão do host (onde o app roda com `npm run dev`) para o banco do
+ * compose. `null` quando a engine não usa URL (Firestore usa o emulador).
+ */
+export function localDatabaseUrl(dbEngine) {
+    const db = resolveDbConfig(dbEngine) ?? resolveDbConfig('vm-postgres-single');
+    switch (db.internalPort) {
+        case 5432:
+            return `postgresql://postgres:neetru_dev@localhost:${db.port}/app`;
+        case 3306:
+            return `mysql://root:neetru_dev@localhost:${db.port}/app`;
+        case 27017:
+            return `mongodb://localhost:${db.port}/app`;
+        default:
+            return null;
+    }
+}
+/**
+ * Gera o conteúdo do `neetru-compose.dev.yml` baseado na config do produto.
+ *
+ * Só o BANCO sobe em container. O agente ficou de fora de propósito
+ * (2026-10-09): o serviço `agent` antigo dependia de um `Dockerfile.agent` que
+ * nenhum caminho do `dev up` gravava (o compose falhava no build e nem o banco
+ * subia), rodava o binário do agente com `node` (é executável `pkg`, não JS) e
+ * ligava um `NEETRU_DEV_MODE` que o agente não implementa — além de montar o
+ * `docker.sock` do host num binário baixado. O agente local volta quando a
+ * sprint dev-suite entregar o modo dev no próprio agente.
  */
 export function generateComposeDev(input) {
     const db = resolveDbConfig(input.dbEngine) ?? resolveDbConfig('vm-postgres-single');
-    const appPort = input.appPort ?? 3000;
     // Bloco `environment:` só entra quando há vars — senão vira `environment:`
     // vazio, que o docker compose rejeita ("environment must be a mapping").
     // Firestore (env: {}) caía nisso → `dev up` firestore gerava compose inválido.
@@ -76,8 +97,9 @@ export function generateComposeDev(input) {
         `      timeout: ${db.healthcheck.timeout}`,
         `      retries: ${db.healthcheck.retries}`,
     ].join('\n');
-    return `# Neetru Dev Local — emulador de VM (${db.engine})
+    return `# Neetru Dev Local — banco do produto ${input.productSlug} (${db.engine})
 # Gerado por \`neetru dev up\`. Modifique o neetru.config.json e rode novamente.
+# O app roda fora do container, com \`npm run dev\`.
 
 services:
   database:
@@ -90,63 +112,9 @@ ${dbEnvBlock}    ports:
     healthcheck:
 ${dbHealthcheck}
     restart: unless-stopped
-    networks:
-      - neetru-dev-net
-
-  agent:
-    build:
-      context: .
-      dockerfile: Dockerfile.agent
-    container_name: neetru-dev-agent
-    environment:
-      - NEETRU_SERVER_ID=dev-local-${input.productSlug}
-      - NEETRU_CORE_URL=${input.coreUrl ?? 'https://core.neetru.com'}
-      - NEETRU_FIREBASE_PROJECT=${input.firebaseProject ?? 'neetru'}
-      - NEETRU_FIREBASE_API_KEY=${input.firebaseApiKey ?? ''}
-      - NEETRU_DEV_MODE=true
-      - NEETRU_APP_PORT=${appPort}
-      - DATABASE_URL=${db.internalPort === 5432 ? 'postgresql://postgres:neetru_dev@database:5432/app' : db.internalPort === 3306 ? 'mysql://root:neetru_dev@database:3306/app' : db.internalPort === 27017 ? 'mongodb://database:27017/app' : ''}
-    ports:
-      - "${appPort}:${appPort}"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - neetru-agent-data:/var/cache/neetru
-      - .:/app/product:cached
-    depends_on:
-      database:
-        condition: service_healthy
-    restart: unless-stopped
-    networks:
-      - neetru-dev-net
 
 volumes:
   neetru-db-data:
-  neetru-agent-data:
-
-networks:
-  neetru-dev-net:
-    driver: bridge
 `;
 }
-/**
- * Escreve o compose + Dockerfile.agent no diretório do projeto.
- */
-export function writeComposeDev(cwd, input) {
-    const composePath = path.join(cwd, 'neetru-compose.dev.yml');
-    const dockerfilePath = path.join(cwd, 'Dockerfile.agent');
-    const entrypointPath = path.join(cwd, 'agent-entrypoint.sh');
-    const compose = generateComposeDev(input);
-    fs.writeFileSync(composePath, compose, 'utf8');
-    // Copia o Dockerfile.agent do template embutido
-    const templateDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', 'templates', 'dev');
-    // Em modo pkg/compilado, busca do __dirname ou do diretório do CLI
-    const altTemplate = path.join(process.cwd(), 'node_modules', '@neetru', 'cli', 'templates', 'dev');
-    const dockerfileSrc = fs.existsSync(path.join(templateDir, 'Dockerfile.agent'))
-        ? path.join(templateDir, 'Dockerfile.agent')
-        : path.join(altTemplate, 'Dockerfile.agent');
-    if (fs.existsSync(dockerfileSrc)) {
-        fs.copyFileSync(dockerfileSrc, dockerfilePath);
-    }
-    return composePath;
-}
 //# sourceMappingURL=compose-generator.js.map

package/dist/lib/config-schema.d.ts

@@ -89,16 +89,43 @@ export declare const neetruConfigSchema: z.ZodObject<{
         engine?: "firestore-instance" | "vm-postgres-single" | "vm-mysql-single" | "nosql-vm" | undefined;
         dbId?: string | undefined;
     }>>;
+    /** Protocolo de docs de produto v1 (`neetru docs init` grava; ver lib/product-docs/config.ts). */
+    docs: z.ZodOptional<z.ZodObject<{
+        protocolVersion: z.ZodOptional<z.ZodNumber>;
+        root: z.ZodOptional<z.ZodString>;
+        publish: z.ZodOptional<z.ZodBoolean>;
+        publishOnDeploy: z.ZodOptional<z.ZodBoolean>;
+        api: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        protocolVersion: z.ZodOptional<z.ZodNumber>;
+        root: z.ZodOptional<z.ZodString>;
+        publish: z.ZodOptional<z.ZodBoolean>;
+        publishOnDeploy: z.ZodOptional<z.ZodBoolean>;
+        api: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        protocolVersion: z.ZodOptional<z.ZodNumber>;
+        root: z.ZodOptional<z.ZodString>;
+        publish: z.ZodOptional<z.ZodBoolean>;
+        publishOnDeploy: z.ZodOptional<z.ZodBoolean>;
+        api: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     slug: string;
     runtime: "nextjs" | "node-api";
     $schema?: string | undefined;
-    tenantId?: string | undefined;
     deploy?: z.objectOutputType<{
         region: z.ZodOptional<z.ZodString>;
         serviceName: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    tenantId?: string | undefined;
+    docs?: z.objectOutputType<{
+        protocolVersion: z.ZodOptional<z.ZodNumber>;
+        root: z.ZodOptional<z.ZodString>;
+        publish: z.ZodOptional<z.ZodBoolean>;
+        publishOnDeploy: z.ZodOptional<z.ZodBoolean>;
+        api: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
     publish?: {
         description: string;
         status: "beta" | "soon" | "live";
@@ -117,11 +144,18 @@ export declare const neetruConfigSchema: z.ZodObject<{
     slug: string;
     runtime: "nextjs" | "node-api";
     $schema?: string | undefined;
-    tenantId?: string | undefined;
     deploy?: z.objectInputType<{
         region: z.ZodOptional<z.ZodString>;
         serviceName: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    tenantId?: string | undefined;
+    docs?: z.objectInputType<{
+        protocolVersion: z.ZodOptional<z.ZodNumber>;
+        root: z.ZodOptional<z.ZodString>;
+        publish: z.ZodOptional<z.ZodBoolean>;
+        publishOnDeploy: z.ZodOptional<z.ZodBoolean>;
+        api: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
     publish?: {
         description: string;
         status: "beta" | "soon" | "live";

package/dist/lib/config-schema.js

@@ -42,6 +42,17 @@ export const neetruConfigSchema = z.object({
         engine: z.enum(['vm-postgres-single', 'vm-mysql-single', 'nosql-vm', 'firestore-instance']).optional(),
         dbId: z.string().optional(),
     }).optional(),
+    /** Protocolo de docs de produto v1 (`neetru docs init` grava; ver lib/product-docs/config.ts). */
+    docs: z
+        .object({
+        protocolVersion: z.number().int().positive().optional(),
+        root: z.string().optional(),
+        publish: z.boolean().optional(),
+        publishOnDeploy: z.boolean().optional(),
+        api: z.boolean().optional(),
+    })
+        .passthrough()
+        .optional(),
 });
 export const catalogUpsertPayloadSchema = z.object({
     slug: slugSchema,

package/dist/lib/db-local/db-json.d.ts

@@ -1,4 +1,4 @@
-import type { NeetruEnv } from './env.js';
+import { type NeetruEnv } from './env.js';
 /** Mapa de IDs de banco por ambiente canônico. */
 export type DbJsonIds = Partial<Record<NeetruEnv, string>>;
 /** Uma entrada de banco lógico no registry. */