@neetru/cli 2.29.0 → 2.32.0

package/dist/lib/db-local/db-json.js

@@ -11,6 +11,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { avisarSobraDeTemporario, removerArquivo } from '../fs-seguro.js';
+import { NEETRU_ENVS } from './env.js';
 /** Registry v2 vazio — usado quando o arquivo ainda não existe. */
 function emptyDbJson() {
     return { version: 2, databases: [] };
@@ -18,7 +20,8 @@ function emptyDbJson() {
 // ---------------------------------------------------------------------------
 // migrateDbJson — qualquer entrada → v2 canônico
 // ---------------------------------------------------------------------------
-const VALID_ENV_KEYS = ['dev-local', 'staging', 'production'];
+// P105: as chaves de `ids` são o alfabeto de banco — a mesma lista que valida.
+const VALID_ENV_KEYS = NEETRU_ENVS;
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -144,12 +147,17 @@ export function writeDbJson(filePath, data) {
         fs.renameSync(tmpPath, filePath);
     }
     catch (err) {
-        // Best-effort: remove o temp pra não deixar lixo se algo falhou.
+        // Best-effort: remove o temp pra não deixar lixo se algo falhou. Não usa
+        // `fs.rmSync`: com acento no caminho (`C:\Users\João\...`), no Node 24 do
+        // Windows ele volta sem erro e não apaga (ver `lib/fs-seguro.ts`).
+        // `removerArquivo` apaga e confere; se ainda assim falhar, o erro que
+        // importa é o original, que segue abaixo — e a sobra vira aviso no stderr
+        // com o caminho, em vez de sumir calada (revisão do #79).
         try {
-            fs.rmSync(tmpPath, { force: true });
+            removerArquivo(tmpPath);
         }
-        catch {
-            /* ignora — limpeza best-effort */
+        catch (limpeza) {
+            avisarSobraDeTemporario(tmpPath, limpeza);
         }
         throw err;
     }

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

@@ -23,8 +23,20 @@
  * Ref: glossário 0.1.4 exporta normalizeEnvId() que usa 'prod' — use-o para
  * queries inter-sistema quando disponível.
  */
-/** Os 3 ambientes canônicos persistidos no `.neetru/db.json`. */
-export type NeetruEnv = 'dev-local' | 'staging' | 'production';
+import type { NeetruCliError } from '../../cli-kit/errors.js';
+/**
+ * Os 3 ambientes canônicos persistidos no `.neetru/db.json`. Fonte única: a
+ * validação e a lista de "valores válidos" das mensagens saem daqui
+ * (bug_89d2497e — antes a lista era copiada à mão em 5 mensagens).
+ */
+export declare const NEETRU_ENVS: readonly ["dev-local", "staging", "production"];
+export type NeetruEnv = (typeof NEETRU_ENVS)[number];
+/**
+ * Erro de `--env` inválido nos comandos de banco (bug_89d2497e): os valores
+ * válidos saem de `NEETRU_ENVS` e os apelidos de `ENV_ALIASES` — as mesmas
+ * fontes que validam. Sai como erro do cliente (exit 1), código `invalid_env`.
+ */
+export declare function erroAmbienteBancoInvalido(input: unknown): NeetruCliError;
 /**
  * Normaliza um nome de ambiente para um dos 3 valores canônicos.
  *
@@ -32,6 +44,6 @@ export type NeetruEnv = 'dev-local' | 'staging' | 'production';
  * no stderr listando o valor canônico. Nunca normaliza silenciosamente.
  *
  * Faz lowercase + trim antes do lookup. Entrada não-string, vazia ou
- * desconhecida lança um `Error` que lista os valores aceitos.
+ * desconhecida lança o `NeetruCliError` de `erroAmbienteBancoInvalido`.
  */
 export declare function normalizeEnv(input: string): NeetruEnv;

package/dist/lib/db-local/env.js

@@ -23,6 +23,13 @@
  * Ref: glossário 0.1.4 exporta normalizeEnvId() que usa 'prod' — use-o para
  * queries inter-sistema quando disponível.
  */
+import { invalidChoiceError } from '../../cli-kit/choices.js';
+/**
+ * Os 3 ambientes canônicos persistidos no `.neetru/db.json`. Fonte única: a
+ * validação e a lista de "valores válidos" das mensagens saem daqui
+ * (bug_89d2497e — antes a lista era copiada à mão em 5 mensagens).
+ */
+export const NEETRU_ENVS = ['dev-local', 'staging', 'production'];
 /** Mapa de aliases aceitos → valor canônico. */
 const ENV_ALIASES = {
     dev: 'dev-local',
@@ -43,6 +50,31 @@ const ALIAS_NOTICE = {
     stg: 'staging',
     prod: 'production',
 };
+/** `dev/local → dev-local, stg → staging, prod → production` — de `ENV_ALIASES`. */
+function apelidosLegiveis() {
+    const porDestino = new Map();
+    for (const [apelido, destino] of Object.entries(ENV_ALIASES)) {
+        if (apelido === destino)
+            continue;
+        porDestino.set(destino, [...(porDestino.get(destino) ?? []), apelido]);
+    }
+    return [...porDestino].map(([destino, apelidos]) => `${apelidos.join('/')} → ${destino}`).join(', ');
+}
+/**
+ * Erro de `--env` inválido nos comandos de banco (bug_89d2497e): os valores
+ * válidos saem de `NEETRU_ENVS` e os apelidos de `ENV_ALIASES` — as mesmas
+ * fontes que validam. Sai como erro do cliente (exit 1), código `invalid_env`.
+ */
+export function erroAmbienteBancoInvalido(input) {
+    return invalidChoiceError({
+        flag: '--env',
+        value: typeof input === 'string' ? input : `(${typeof input})`,
+        valid: NEETRU_ENVS,
+        subject: 'Ambiente',
+        code: 'invalid_env',
+        hint: `Apelidos aceitos: ${apelidosLegiveis()}.`,
+    });
+}
 /**
  * Normaliza um nome de ambiente para um dos 3 valores canônicos.
  *
@@ -50,20 +82,15 @@ const ALIAS_NOTICE = {
  * no stderr listando o valor canônico. Nunca normaliza silenciosamente.
  *
  * Faz lowercase + trim antes do lookup. Entrada não-string, vazia ou
- * desconhecida lança um `Error` que lista os valores aceitos.
+ * desconhecida lança o `NeetruCliError` de `erroAmbienteBancoInvalido`.
  */
 export function normalizeEnv(input) {
-    if (typeof input !== 'string') {
-        throw new Error(`normalizeEnv: ambiente inválido (esperava string, recebeu ${typeof input}). ` +
-            `Valores aceitos: dev-local, staging, production.`);
-    }
+    if (typeof input !== 'string')
+        throw erroAmbienteBancoInvalido(input);
     const key = input.trim().toLowerCase();
     const canonical = ENV_ALIASES[key];
-    if (!canonical) {
-        throw new Error(`normalizeEnv: ambiente "${input}" não reconhecido. ` +
-            `Valores aceitos: dev-local, staging, production. ` +
-            `Aliases aceitos: dev/local → dev-local, stg → staging, prod → production.`);
-    }
+    if (!canonical)
+        throw erroAmbienteBancoInvalido(input);
     // D-4: aviso explícito quando alias não-canônico é usado
     const notice = ALIAS_NOTICE[key];
     if (notice) {

package/dist/lib/db-pipeline/build-deps.d.ts

@@ -1,6 +1,10 @@
 import { type RehearseEngine } from './rehearse.js';
 import type { PipelineDeps } from './types.js';
-export declare function generateSql(schemaPath: string, engine?: RehearseEngine): Promise<string>;
+export interface OpcoesGenerateSql {
+    /** Remove o `--out` temporário. Injetável só para teste. */
+    remover?: (dir: string) => Promise<void>;
+}
+export declare function generateSql(schemaPath: string, engine?: RehearseEngine, { remover }?: OpcoesGenerateSql): Promise<string>;
 /**
  * Constrói o conjunto de `PipelineDeps` de PRODUÇÃO.
  *

package/dist/lib/db-pipeline/build-deps.js

@@ -25,6 +25,7 @@ import * as path from 'node:path';
 import { spawn } from 'node:child_process';
 import { classifyMigration } from '@neetru/db-classifier';
 import { apiRequest } from '../api-client.js';
+import { avisarSobraDeTemporario, removerDiretorio } from '../fs-seguro.js';
 import { buildRehearseInContainer, buildDockerExecFn, } from './rehearse.js';
 /**
  * Prova em COMPILE-TIME que `classifyMigration` do `@neetru/db-classifier` é
@@ -273,7 +274,7 @@ function makeTableAndIndexIdempotent(sql) {
         .replace(/CREATE TABLE (?!IF NOT EXISTS\b)/g, 'CREATE TABLE IF NOT EXISTS ')
         .replace(/CREATE (UNIQUE )?INDEX (?!IF NOT EXISTS\b)/g, (_match, unique) => `CREATE ${unique ?? ''}INDEX IF NOT EXISTS `);
 }
-export function generateSql(schemaPath, engine = 'postgres') {
+export function generateSql(schemaPath, engine = 'postgres', { remover = removerDiretorio } = {}) {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'neetru-drizzle-'));
     return new Promise((resolve, reject) => {
         const child = spawn('npx', [
@@ -333,8 +334,27 @@ export function generateSql(schemaPath, engine = 'postgres') {
                 reject(new Error(`falha lendo o .sql gerado em ${tmpDir}: ${err.message}`));
             }
         });
-    }).finally(() => {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }).then(
+    // Limpa o --out temporário. Não usa `fs.rmSync`: o `os.tmpdir()` de quem tem
+    // acento na home (`C:\Users\João\AppData\Local\Temp`) faz o rmSync do
+    // Node 24 no Windows voltar sem erro e não apagar nada — um `neetru-drizzle-*`
+    // perdido por geração. `removerDiretorio` apaga e confere (ver `lib/fs-seguro.ts`).
+    //
+    // A falha da limpeza nunca derruba o resultado nem esconde o erro da
+    // geração, mas também não some calada: vira aviso no stderr com o caminho
+    // que sobrou (revisão do #79).
+    async (sql) => {
+        try {
+            await remover(tmpDir);
+        }
+        catch (limpeza) {
+            avisarSobraDeTemporario(tmpDir, limpeza);
+        }
+        return sql;
+    }, async (err) => {
+        // O erro da geração é o que importa: falha na limpeza não pode escondê-lo.
+        await remover(tmpDir).catch((limpeza) => avisarSobraDeTemporario(tmpDir, limpeza));
+        throw err;
     });
 }
 /**

package/dist/lib/db-pipeline/types.d.ts

@@ -16,12 +16,16 @@
  * Postgres e sem rede. A fiação real (drizzle-kit / container / HTTP) vive
  * no `buildPipelineDeps()`.
  */
+import type { NeetruEnv } from '../db-local/env.js';
 /** As 5 fases do pipeline, na ordem de execução. */
 export type PipelinePhase = 'fingerprint' | 'generate' | 'rehearse' | 'classify' | 'push';
 /** Severidade global da migração — espelha o `@neetru/db-classifier`. */
 export type MigrationSeverity = 'aditiva' | 'destrutiva';
-/** Os 3 ambientes canônicos do `neetru db apply`. */
-export type ApplyEnv = 'dev-local' | 'staging' | 'production';
+/**
+ * Os 3 ambientes canônicos do `neetru db apply` — o alfabeto de BANCO
+ * (`NEETRU_ENVS`, `db-local/env.ts`). P105: era a união escrita à mão.
+ */
+export type ApplyEnv = NeetruEnv;
 /**
  * Relatório de classificação — subconjunto estrutural do `ClassificationReport`
  * do `@neetru/db-classifier`. Tipado localmente pra que o orquestrador e seus

package/dist/lib/db-pipeline/types.js

@@ -1,20 +1,2 @@
-/**
- * `@neetru/db-pipeline` — contratos do orquestrador do `neetru db apply`.
- *
- * O pipeline roda CLIENT-SIDE as fases 1-5 do `neetru db apply`:
- *  1. `fingerprint` — hash determinístico do schema.
- *  2. `generate`    — `drizzle-kit generate` produz o `.sql`.
- *  3. `rehearse`    — ensaia o `.sql` num Postgres efêmero real.
- *  4. `classify`    — `@neetru/db-classifier` marca aditiva/destrutiva.
- *  5. `push`        — adquire lock + envia o artefato validado pro Core.
- *
- * O pipeline NÃO decide política — ele produz um `.sql` validado e
- * classificado e o envia. A decisão de aplicar (ou exigir confirmação numa
- * migração destrutiva) é do Core.
- *
- * Tudo aqui é deps-injetado: o orquestrador é unit-testável sem Docker, sem
- * Postgres e sem rede. A fiação real (drizzle-kit / container / HTTP) vive
- * no `buildPipelineDeps()`.
- */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/lib/deploy-target-contract.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Contrato de compatibilidade `--target` × runtime × flags do `neetru deploy`.
+ *
+ * bug_a8375858 (o caso que motivou o módulo): um produto `runtime: nextjs`
+ * rodou `deploy --target workspace --artifact <tarball de 20 MB>`. A CLI leu o
+ * tarball como TEXTO (`readFile(…, 'utf8')`), o gzip virou ~35 MB de U+FFFD,
+ * subiu pro GCS como `source-*.ts`, e o Core respondeu
+ * **413 "Falha ao resolver a source do deploy"** — que manda o dev caçar
+ * TAMANHO quando o problema era TIPO DE ALVO. Dois uploads de 35 MB e meia
+ * hora perdida.
+ *
+ * ─── O padrão, em uma frase ─────────────────────────────────────────────────
+ *
+ *   "Uma flag (ou campo do neetru.config.json) cujo significado depende do
+ *    `--target` é aceita pela CLI, silenciosamente reinterpretada ou
+ *    descartada, e só aparece como erro do Core DEPOIS do passo caro — ou não
+ *    aparece nunca."
+ *
+ * Antes deste módulo o padrão era combatido um `if` por vez (bug_ec17af08
+ * cobriu cloud-run+`--artifact`; bug_b919e729 cobriu o espelho disso no Core),
+ * e cada combinação nova nascia desprotegida. Aqui ele vira UMA TABELA: cada
+ * alvo declara o que RECEBE, o que REJEITA (erro antes de qualquer trabalho
+ * caro) e o que DESCARTA (aviso — a flag some mas o deploy segue certo).
+ *
+ * ─── Regra pra classificar erro vs aviso (a que o código segue) ──────────────
+ *
+ *   ERRO  — a flag diz O QUE subir (pacote, URL de artefato, imagem) e o alvo
+ *           subiria OUTRA coisa:
+ *             · workspace sobe só um handler .ts → erro em `--artifact` com
+ *               pacote, `--artifact-url`, `--artifact-sha256`, `--image`,
+ *               `--registry`, `--registry-repo`;
+ *             · cloud-run sobe só imagem → erro em `--artifact`,
+ *               `--artifact-url`, `--artifact-sha256`.
+ *           Nesses casos o Core também recusaria o payload (superRefine do
+ *           `deploy-request.ts`), só que DEPOIS do build/upload caro.
+ *   AVISO — a flag NÃO diz o que subir (servidor, porta, stack, env-file,
+ *           domínio, build local, empacotamento local, `runtime` do config):
+ *           ela é descartada e o deploy segue subindo a coisa certa.
+ *
+ *   EXCEÇÃO REGISTRADA — vm + `--image` / `--registry` / `--registry-repo` é
+ *   AVISO, embora a flag diga o que subir. O deploy vm sobe o tarball (o body
+ *   nem tem campo de imagem, e o Core não recusa nada por isso), e virar erro
+ *   quebraria script/CI que passa o mesmo conjunto de flags genéricas pra
+ *   mais de um alvo. Decisão tomada na revisão do PR #74 (2026-10-12).
+ *
+ * O pacote que chega ao workspace por um caminho que a tabela não enxerga —
+ * campo `source` do neetru.config.json, ou extensão que nenhuma lista prevê —
+ * é recusado depois da leitura, PELO CONTEÚDO (`farejarConteudoDePacote`),
+ * com o mesmo código de erro. O teto de 2 MiB fica só pra handler grande.
+ *
+ * Módulo propositalmente PURO (zero fs, zero rede, zero processo) pra ser
+ * testável sem rodar deploy nenhum: quem lê o arquivo é o `deploy.ts`.
+ */
+/** Alvos aceitos pelo `neetru deploy` (espelha `DEPLOY_TARGETS` do Core). */
+export type DeployTarget = 'workspace' | 'cloud-run' | 'vm';
+/** Runtimes declaráveis no `neetru.config.json` (espelha `RUNTIMES`). */
+export type ProductRuntime = 'nextjs' | 'node-api';
+/**
+ * Teto ABSOLUTO da source de um deploy workspace, em bytes UTF-8.
+ *
+ * Espelha `WORKSPACE_SOURCE_MAX_BYTES` do Core
+ * (`src/lib/schemas/deploy-request.ts`), que o aplica nos DOIS caminhos:
+ * `source` inline (zod `.max()`) e `sourceUrl` baixada do GCS
+ * (`fetchWorkspaceSource` → `SourceFetchError(413, 'source_too_large')`).
+ *
+ * A CLI tinha só o limiar de 1.5 MiB do bug_eae4bef6, que decide *inline vs
+ * GCS* — e nunca o teto do Core. Resultado: tudo entre 2 MiB e infinito subia
+ * pro GCS e voltava como 413 opaco. Conhecer o teto aqui é o que permite
+ * recusar local com o número real.
+ */
+export declare const WORKSPACE_SOURCE_MAX_BYTES: number;
+/** `true` quando o caminho aponta um pacote de aplicação, não um handler. */
+export declare function pareceArquivoDePacote(caminho: string): boolean;
+/** Quantos bytes do começo do arquivo o farejador olha. */
+export declare const BYTES_FAREJADOS: number;
+/**
+ * Olha os BYTES CRUS do começo da source de um deploy workspace e diz se ela é
+ * pacote/binário. Devolve o motivo em PT-BR, ou `null` quando parece texto.
+ *
+ * Por que pelo conteúdo: a recusa por extensão só olhava `--artifact`. Um
+ * pacote apontado pelo `source` do neetru.config.json, ou com extensão que a
+ * lista não prevê, só batia no teto de 2 MiB. E lido como UTF-8 um binário
+ * incha ~1,75x (cada byte inválido vira U+FFFD, 3 bytes), então um pacote
+ * abaixo de ~1,15 MiB passava no teto, subia e voltava do Core como erro de
+ * COMPILAÇÃO do esbuild, que não diz a causa (revisão do PR #74).
+ *
+ * Tem que receber os bytes CRUS: depois de decodificado em UTF-8 o gzip já
+ * virou U+FFFD e a assinatura sumiu.
+ */
+export declare function farejarConteudoDePacote(inicio: Uint8Array): string | null;
+/** Flags do `neetru deploy` que mudam de sentido conforme o `--target`. */
+export interface DeployFlagsSnapshot {
+    artifact?: string;
+    artifactUrl?: string;
+    artifactSha256?: string;
+    image?: string;
+    registry?: string;
+    registryRepo?: string;
+    buildLocal?: boolean;
+    server?: string;
+    port?: number;
+    stack?: string;
+    /** Lido só em vm e cloud-run (`loadEnvFile`); workspace nunca olha. */
+    envFile?: string;
+    /** Usado só em vm (subdomínio do vhost). */
+    domain?: string;
+    /** Empacotamento local do tarball — só existe em vm. */
+    localArtifact?: boolean;
+}
+export interface DeployContractError {
+    /** Código estável — vai pro `{ok:false,error}` do `--json`. */
+    code: string;
+    /** Mensagem PT-BR que diz O QUE FAZER, não só o que está errado. */
+    message: string;
+}
+export interface DeployContractVerdict {
+    errors: DeployContractError[];
+    warnings: string[];
+}
+export interface DeployContractInput {
+    target: DeployTarget;
+    /** `runtime` do neetru.config.json. Ausente = sem opinião (não bloqueia). */
+    runtime?: string;
+    flags: DeployFlagsSnapshot;
+}
+/**
+ * Avalia a combinação `target × runtime × flags` ANTES de qualquer build,
+ * upload ou chamada ao Core.
+ *
+ * Fail-open pro desconhecido: `runtime` ausente ou fora do enum nunca bloqueia
+ * (repos anteriores ao campo continuam deployando). Fail-closed só no que está
+ * provado impossível.
+ */
+export declare function checkDeployTargetContract(input: DeployContractInput): DeployContractVerdict;
+/** De onde veio o arquivo de source de um deploy workspace. */
+export type OrigemDaSource = 'artifact' | 'config' | 'padrao';
+/**
+ * Mensagem da recusa de uma source de workspace que é pacote, achada pelo nome
+ * ou pelo conteúdo DEPOIS da leitura. Usa o mesmo código de erro da recusa por
+ * `--artifact` (`artifact_nao_eh_handler_workspace`): é o mesmo erro, achado
+ * por outra porta.
+ */
+export declare function mensagemSourceNaoEhHandler(relPath: string, motivo: string, origem: OrigemDaSource): string;
+/**
+ * Mensagem do estouro do teto de source do workspace, usada depois que a
+ * source já foi lida e o farejador de pacote não a recusou: na prática, um
+ * handler que ficou grande demais.
+ *
+ * Diz o número real, o teto real, e o alvo certo — em vez do 413 do Core, que
+ * diz só "Falha ao resolver a source do deploy".
+ */
+export declare function mensagemSourceAcimaDoTeto(relPath: string, bytes: number, runtime?: string): string;