@neetru/cli 2.29.0 → 2.32.0

package/dist/lib/deploy-target-contract.js

@@ -0,0 +1,411 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 const WORKSPACE_SOURCE_MAX_BYTES = 2 * 1024 * 1024;
+/** Bytes em KB inteiros, como as mensagens deste módulo mostram (`2048 KB`). */
+function emKB(bytes) {
+    return `${Math.round(bytes / 1024)} KB`;
+}
+/**
+ * Extensões que identificam um PACOTE (tarball, zip, compactado), nunca um
+ * handler `.ts`. Só entra o que é inequívoco. A lista é a porta BARATA (nem
+ * lê o arquivo); a porta que não depende do nome é `farejarConteudoDePacote`.
+ *
+ * `.gz`/`.bz2`/`.xz`/`.zst` sozinhos também entram (revisão do PR #74): um
+ * arquivo compactado nunca é um handler, com ou sem `.tar` antes.
+ */
+const EXTENSOES_DE_PACOTE = [
+    '.tar.gz',
+    '.tar.bz2',
+    '.tar.xz',
+    '.tar.zst',
+    '.tgz',
+    '.tbz2',
+    '.txz',
+    '.tzst',
+    '.tar',
+    '.zip',
+    '.gz',
+    '.bz2',
+    '.xz',
+    '.zst',
+    '.7z',
+    '.rar',
+];
+/** `true` quando o caminho aponta um pacote de aplicação, não um handler. */
+export function pareceArquivoDePacote(caminho) {
+    const normalizado = caminho.trim().toLowerCase().replace(/\\/g, '/');
+    const base = normalizado.slice(normalizado.lastIndexOf('/') + 1);
+    return EXTENSOES_DE_PACOTE.some((ext) => base.endsWith(ext));
+}
+/** Quantos bytes do começo do arquivo o farejador olha. */
+export const BYTES_FAREJADOS = 8 * 1024;
+/**
+ * Assinaturas ("magic bytes") de pacote. Uso a assinatura COMPLETA quando os
+ * primeiros bytes são texto imprimível (`Rar!`, `7z`, `BZh`), pra que um
+ * handler que por acaso comece com esse texto não seja recusado.
+ */
+const ASSINATURAS_DE_PACOTE = [
+    { formato: 'gzip', bytes: [0x1f, 0x8b] },
+    { formato: 'zip', bytes: [0x50, 0x4b, 0x03, 0x04] },
+    { formato: 'zip', bytes: [0x50, 0x4b, 0x05, 0x06] }, // zip vazio
+    { formato: 'xz', bytes: [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00] },
+    { formato: 'zstd', bytes: [0x28, 0xb5, 0x2f, 0xfd] },
+    { formato: '7z', bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c] },
+    { formato: 'rar', bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07] },
+    // tar sem compressão: o campo `magic` do cabeçalho, no offset 257 — POSIX
+    // `ustar\0` ou GNU `ustar  \0`. COM o NUL de propósito (confirmação final do
+    // PR #74): só "ustar" casava texto comum — um comentário com "ajustar" ou
+    // "custar" em que `ustar` caísse no byte 257 era recusado como "arquivo tar".
+    // Texto nunca tem NUL; tar de verdade sempre tem.
+    { formato: 'tar', bytes: [0x75, 0x73, 0x74, 0x61, 0x72, 0x00], offset: 257 },
+    { formato: 'tar', bytes: [0x75, 0x73, 0x74, 0x61, 0x72, 0x20, 0x20, 0x00], offset: 257 },
+];
+function comecaCom(bytes, assinatura, offset = 0) {
+    if (bytes.length < offset + assinatura.length)
+        return false;
+    return assinatura.every((b, i) => bytes[offset + i] === b);
+}
+/**
+ * bzip2: "BZh" + nível ('1'..'9') + magia de bloco (`31 41 59 26 53 59`) ou de
+ * fim de stream (`17 72 45 38 50 90`). Só "BZh" seria texto comum.
+ */
+function pareceBzip2(bytes) {
+    if (!comecaCom(bytes, [0x42, 0x5a, 0x68]))
+        return false;
+    if (bytes.length < 10 || bytes[3] < 0x31 || bytes[3] > 0x39)
+        return false;
+    return (comecaCom(bytes, [0x31, 0x41, 0x59, 0x26, 0x53, 0x59], 4) ||
+        comecaCom(bytes, [0x17, 0x72, 0x45, 0x38, 0x50, 0x90], 4));
+}
+/** Formato do pacote cuja assinatura abre `inicio`, ou `null` se nenhuma casa. */
+function formatoDePacote(inicio) {
+    for (const a of ASSINATURAS_DE_PACOTE) {
+        if (comecaCom(inicio, a.bytes, a.offset))
+            return a.formato;
+    }
+    if (pareceBzip2(inicio))
+        return 'bzip2';
+    return null;
+}
+/**
+ * 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 function farejarConteudoDePacote(inicio) {
+    const formato = formatoDePacote(inicio);
+    if (formato)
+        return `o conteúdo tem a assinatura de um arquivo ${formato}`;
+    if (inicio.subarray(0, BYTES_FAREJADOS).includes(0x00)) {
+        return (`o conteúdo tem byte NUL nos primeiros ${emKB(BYTES_FAREJADOS)}, então é binário e ` +
+            'não texto (ou foi salvo em UTF-16, e o Core só lê UTF-8)');
+    }
+    return null;
+}
+/** Nome da flag como o dev digita — entra nas mensagens. */
+const NOME_DA_FLAG = {
+    artifact: '--artifact',
+    artifactUrl: '--artifact-url',
+    artifactSha256: '--artifact-sha256',
+    image: '--image',
+    registry: '--registry',
+    registryRepo: '--registry-repo',
+    buildLocal: '--build-local',
+    server: '--server',
+    port: '--port',
+    stack: '--stack',
+    envFile: '--env-file',
+    domain: '--domain',
+    localArtifact: '--local-artifact',
+};
+function presente(flags, k) {
+    const v = flags[k];
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v === 'string')
+        return v.length > 0;
+    if (typeof v === 'boolean')
+        return v;
+    return true;
+}
+function listaDeFlags(flags, chaves) {
+    return chaves.filter((k) => presente(flags, k));
+}
+/**
+ * Texto do destino `vm` com o artefato que o dev JÁ tem na mão — a mensagem
+ * precisa poder ser copiada e colada, não só explicar o conceito.
+ */
+function linhaDeComandoVm(flags) {
+    // Entre aspas: caminho do Windows com espaço quebrava o copia-e-cola.
+    if (flags.artifact)
+        return `  neetru deploy --target vm --artifact "${flags.artifact}"`;
+    if (flags.artifactUrl) {
+        const sha = flags.artifactSha256 ? ` --artifact-sha256 ${flags.artifactSha256}` : '';
+        return `  neetru deploy --target vm --artifact-url ${flags.artifactUrl}${sha}`;
+    }
+    return '  neetru deploy --target vm --artifact <tarball .tar.gz>';
+}
+function linhaDeComandoCloudRun(flags) {
+    if (flags.image)
+        return `  neetru deploy --target cloud-run --image ${flags.image}`;
+    if (flags.registry)
+        return `  neetru deploy --target cloud-run --registry ${flags.registry}`;
+    return '  neetru deploy --target cloud-run --image <uri>';
+}
+/**
+ * O que cada alvo RECEBE — frase curta reusada em várias mensagens pra que o
+ * dev leia a mesma definição em qualquer erro.
+ */
+const O_QUE_O_ALVO_RECEBE = {
+    workspace: 'UM handler .ts (o Core compila com esbuild e roda no runtime compartilhado)',
+    'cloud-run': 'UMA imagem de container OCI já buildada e pushada',
+    vm: 'UM tarball de aplicação já buildado (artefato + sha256 + stack)',
+};
+// ─── checagem ────────────────────────────────────────────────────────────────
+/**
+ * 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 function checkDeployTargetContract(input) {
+    const { target, runtime, flags } = input;
+    const errors = [];
+    const warnings = [];
+    const rejeitar = (chaves, code, corpo) => {
+        const achadas = listaDeFlags(flags, chaves);
+        if (achadas.length === 0)
+            return;
+        errors.push({ code, message: corpo(achadas.map((k) => NOME_DA_FLAG[k]).join(' / ')) });
+    };
+    const avisarDescarte = (chaves) => {
+        for (const k of listaDeFlags(flags, chaves)) {
+            warnings.push(`${NOME_DA_FLAG[k]} não tem efeito em --target ${target} — a flag é descartada. ` +
+                `O alvo ${target} recebe ${O_QUE_O_ALVO_RECEBE[target]}.`);
+        }
+    };
+    if (target === 'workspace') {
+        // ── runtime ──────────────────────────────────────────────────────────
+        // Uma app Next.js não roda no workspace: o Core compila a source com
+        // esbuild em `platform:'browser'`, `external: []`, `format:'iife'`, teto de
+        // 2 MiB, e executa num `vm.Context` (`_workspace-build-helpers.ts`).
+        //
+        // Mas isto é AVISO, não erro (revisão do PR #74, 2026-10-12): `runtime` é
+        // OBRIGATÓRIO no config (`config-schema.ts`) e o `neetru init` grava
+        // `nextjs` por padrão. Erro duro aqui quebraria todo produto recém-criado
+        // que faz deploy de handler no workspace — e a única saída seria apagar o
+        // `runtime`, o que faz `validate`/`doctor`/`publish` recusarem o config. O
+        // caso do bug_a8375858 (pacote no workspace) continua ERRO por duas portas
+        // que não dependem do runtime: a extensão de `--artifact` (logo abaixo) e
+        // o CONTEÚDO da source, farejado depois da leitura em `runWorkspaceDeploy`
+        // (`farejarConteudoDePacote`), que pega também o `source` do config.
+        if (runtime === 'nextjs') {
+            warnings.push('--target workspace com runtime "nextjs": o workspace roda ' +
+                `${O_QUE_O_ALVO_RECEBE.workspace}, não uma aplicação Next.js com servidor, ` +
+                'node_modules e estáticos. Se o que você quer subir é o app, o alvo é ' +
+                '`--target vm` (ou `--target cloud-run` com imagem).');
+        }
+        else if (runtime === 'node-api') {
+            // `neetru init --type node-api` scaffolda um servidor Fastify
+            // (`start: node dist/index.js`), que também não é um handler. Mas
+            // nada impede que um repo marcado `node-api` tenha um handler.ts de
+            // verdade, então aqui é AVISO: não quebra quem já deploya assim.
+            warnings.push('--target workspace com runtime "node-api": o workspace espera UM handler .ts, ' +
+                'não o servidor Fastify que `neetru init --type node-api` scaffolda. ' +
+                'Se o arquivo apontado é o entrypoint da aplicação, o alvo é `--target vm`.');
+        }
+        // ── artefato de aplicação apontado como se fosse handler ─────────────
+        // O erro central do bug_a8375858. Vale mesmo sem `runtime` no config.
+        if (flags.artifact && pareceArquivoDePacote(flags.artifact)) {
+            errors.push({
+                code: 'artifact_nao_eh_handler_workspace',
+                message: `--artifact "${flags.artifact}" é um pacote de aplicação, não um handler.\n` +
+                    '  Em --target workspace a CLI lê o arquivo de --artifact como TEXTO e manda\n' +
+                    '  o conteúdo pro Core compilar. Um pacote vira texto corrompido: se passar do\n' +
+                    `  teto de ${emKB(WORKSPACE_SOURCE_MAX_BYTES)} do Core volta como HTTP 413\n` +
+                    '  ("Falha ao resolver a source do deploy"); se for menor, como erro de\n' +
+                    '  compilação. Parece problema de TAMANHO ou de código e não é: é o TIPO do alvo.\n' +
+                    '\n' +
+                    '  Troque o alvo:\n' +
+                    linhaDeComandoVm(flags),
+            });
+        }
+        rejeitar(['artifactUrl', 'artifactSha256'], 'artefato_pre_buildado_nao_se_aplica_workspace', (nomes) => `--target workspace não usa ${nomes} (artefato pré-buildado).\n` +
+            `  O workspace recebe ${O_QUE_O_ALVO_RECEBE.workspace}; o Core builda a source.\n` +
+            '\n' +
+            '  Artefato pré-buildado é alvo vm:\n' +
+            linhaDeComandoVm(flags));
+        rejeitar(['image', 'registry', 'registryRepo'], 'imagem_nao_se_aplica_workspace', (nomes) => `--target workspace não usa ${nomes} (imagem de container).\n` +
+            `  O workspace recebe ${O_QUE_O_ALVO_RECEBE.workspace}.\n` +
+            '\n' +
+            '  Imagem de container é alvo cloud-run:\n' +
+            linhaDeComandoCloudRun(flags));
+        // `--env-file`, `--domain` e `--local-artifact` também sumiam calados aqui:
+        // `runWorkspaceDeploy` nunca lê nenhum dos três (revisão do PR #74).
+        avisarDescarte(['server', 'port', 'stack', 'buildLocal', 'envFile', 'domain', 'localArtifact']);
+        return { errors, warnings };
+    }
+    if (target === 'cloud-run') {
+        // bug_ec17af08 — mantido com o MESMO código que já estava em
+        // `runCloudRunDeploy`; só mudou de lugar pra haver uma tabela só. O texto
+        // também é o mesmo, exceto o arquivo do comando sugerido, que agora sai
+        // entre aspas (caminho com espaço quebrava o copia-e-cola).
+        // `--artifact-sha256` entrou no mesmo grupo: é par de `--artifact-url` e
+        // antes passava sozinho sem reclamação nenhuma.
+        const arquivoDoDev = flags.artifact ?? flags.artifactUrl;
+        rejeitar(['artifact', 'artifactUrl', 'artifactSha256'], 'artifact_not_supported_cloud_run', (nomes) => `target=cloud-run não aceita ${nomes} (tarball source).\n` +
+            '  Cloud Run precisa de uma imagem de container OCI já buildada e pushada.\n' +
+            '\n' +
+            '  Opções:\n' +
+            '    1. --image <uri>    — URI de imagem já no Artifact Registry.\n' +
+            '       Exemplo: --image=us-central1-docker.pkg.dev/neetru/gestovendas-staging/app:1.0.0\n' +
+            '\n' +
+            '    2. --registry <host|host/project/repo> — CLI usa Cloud Build remoto automaticamente.\n' +
+            '       Não exige Docker instalado. Requer gcloud autenticado.\n' +
+            '       Exemplo: --registry=us-central1-docker.pkg.dev/neetru/gestovendas-staging\n' +
+            '\n' +
+            '    3. Mude o target pra vm ou workspace se quiser usar o tarball:\n' +
+            `       --target=vm --artifact=${arquivoDoDev ? `"${arquivoDoDev}"` : '<file>'}`);
+        // O Core recusa `serverId` em cloud-run (`deploy-request.ts` superRefine),
+        // mas a CLI nem chega a mandar — `pickServer` só roda em target=vm. Ou
+        // seja: hoje a flag some calada. Aviso, não erro.
+        // `--domain` e `--local-artifact` só existem em vm (revisão do PR #74).
+        avisarDescarte(['server', 'domain', 'localArtifact']);
+        return { errors, warnings };
+    }
+    // target === 'vm'
+    // `--image`/`--registry`/`--registry-repo`/`--build-local` são de cloud-run e
+    // em vm somem sem dizer nada: o body do deploy vm nem tem campo pra eles, e o
+    // schema do Core (sem `.strict()`) descartaria em silêncio de qualquer jeito.
+    // `--image`/`--registry`/`--registry-repo` são a EXCEÇÃO REGISTRADA no
+    // cabeçalho: nomeiam o que subir e mesmo assim ficam como aviso, porque o
+    // deploy vm sobe o tarball e erro aqui quebraria script com flags genéricas.
+    //
+    // `--port` fica de fora de propósito: `runDeploy` já emite o aviso dele
+    // (P6/bug_6d92ef71, com texto específico sobre alocação de porta pelo Core).
+    avisarDescarte(['image', 'registry', 'registryRepo', 'buildLocal']);
+    return { errors, warnings };
+}
+const DE_ONDE_VEIO = {
+    artifact: 'apontado por --artifact',
+    config: 'apontado pelo campo "source" do neetru.config.json',
+    padrao: 'achado na busca padrão do handler (sem --artifact e sem "source" no config)',
+};
+/**
+ * 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 function mensagemSourceNaoEhHandler(relPath, motivo, origem) {
+    return (`"${relPath}" não é um handler .ts: ${motivo}.\n` +
+        `  (${DE_ONDE_VEIO[origem]})\n` +
+        '\n' +
+        '  Em --target workspace a CLI lê a source como TEXTO e manda pro Core compilar.\n' +
+        '  Um pacote vira texto corrompido e volta como erro de compilação (ou HTTP 413)\n' +
+        '  que não diz a causa. Nada foi enviado.\n' +
+        '\n' +
+        `  Se é o pacote da aplicação, o alvo certo é vm (que recebe ${O_QUE_O_ALVO_RECEBE.vm}):\n` +
+        `    neetru deploy --target vm --artifact "${relPath}"\n` +
+        (origem === 'config'
+            ? '  Se o handler é outro arquivo, corrija o "source" do neetru.config.json.\n'
+            : ''));
+}
+/**
+ * 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 function mensagemSourceAcimaDoTeto(relPath, bytes, runtime) {
+    return (`A source do deploy workspace tem ${emKB(bytes)} — o Core aceita no máximo ${emKB(WORKSPACE_SOURCE_MAX_BYTES)}.\n` +
+        `  arquivo: ${relPath}\n` +
+        '\n' +
+        '  Acima desse teto o Core responde HTTP 413 "Falha ao resolver a source do deploy",\n' +
+        '  que parece problema de rede/tamanho de upload e não é: é o teto do alvo.\n' +
+        '\n' +
+        `  Se "${relPath}" é um pacote de aplicação (tarball/zip) e não um handler .ts,\n` +
+        '  o alvo certo é vm:\n' +
+        `    neetru deploy --target vm --artifact "${relPath}"\n` +
+        (runtime === 'nextjs'
+            ? `\n  (o neetru.config.json deste produto declara runtime "nextjs" — workspace não serve esse runtime)\n`
+            : ''));
+}
+//# sourceMappingURL=deploy-target-contract.js.map

package/dist/lib/env-file-do-build.d.ts

@@ -0,0 +1,19 @@
+/**
+ * O `--env-file` do `neetru build` (bug_25ff8581): cada linha `CHAVE=valor`
+ * vira variável do PROCESSO do build (o spawn do bundler), e não um `.env` que
+ * o bundler lê. Por isso a regra é a da CLI, mais simples que a do dotenv:
+ *
+ *   KEY=value              (sem aspas; o `#` depois do `=` faz parte do valor)
+ *   KEY="value with spaces" (aspas duplas)
+ *   KEY='value'            (aspas simples)
+ *   # comentário           (ignorado)
+ *   linha vazia            (ignorada)
+ *
+ * Não suporta multi-line values nem expande `$VAR`.
+ *
+ * Mora aqui, e não em `commands/build.ts`, porque a varredura de segredo do
+ * deploy (`collectPublicEnvSecrets`) precisa da MESMA regra para procurar o
+ * valor que o build injetou (rodada final 5 do cli#81). Quem recebe o texto já
+ * decodificado e sem a marca BOM é quem chama.
+ */
+export declare function variaveisDoEnvFile(conteudo: string): Record<string, string>;

package/dist/lib/env-file-do-build.js

@@ -0,0 +1,44 @@
+/**
+ * O `--env-file` do `neetru build` (bug_25ff8581): cada linha `CHAVE=valor`
+ * vira variável do PROCESSO do build (o spawn do bundler), e não um `.env` que
+ * o bundler lê. Por isso a regra é a da CLI, mais simples que a do dotenv:
+ *
+ *   KEY=value              (sem aspas; o `#` depois do `=` faz parte do valor)
+ *   KEY="value with spaces" (aspas duplas)
+ *   KEY='value'            (aspas simples)
+ *   # comentário           (ignorado)
+ *   linha vazia            (ignorada)
+ *
+ * Não suporta multi-line values nem expande `$VAR`.
+ *
+ * Mora aqui, e não em `commands/build.ts`, porque a varredura de segredo do
+ * deploy (`collectPublicEnvSecrets`) precisa da MESMA regra para procurar o
+ * valor que o build injetou (rodada final 5 do cli#81). Quem recebe o texto já
+ * decodificado e sem a marca BOM é quem chama.
+ */
+export function variaveisDoEnvFile(conteudo) {
+    const vars = {};
+    for (const line of conteudo.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        let val = trimmed.slice(eq + 1).trim();
+        // Remove aspas simétricas.
+        if (val.length >= 2) {
+            const open = val[0];
+            const close = val[val.length - 1];
+            if ((open === '"' && close === '"') || (open === "'" && close === "'")) {
+                val = val.slice(1, -1);
+            }
+        }
+        if (!key)
+            continue;
+        vars[key] = val;
+    }
+    return vars;
+}
+//# sourceMappingURL=env-file-do-build.js.map

package/dist/lib/envs.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Fonte única do alfabeto de ambiente de **tenant/workspace/deployment** que o
+ * Core aceita nas rotas `/api/cli/v1/{tenants,workspaces,deployments}`.
+ *
+ * POR QUE ESTE ARQUIVO EXISTE
+ * ---------------------------
+ * bug_7dcb68e2666a43f69ef362d2cbff94ed — a CLI oferecia (e usava como padrão)
+ * o token `'dev'`, que NÃO existe no enum do Core. As rotas citadas validam
+ * por igualdade ESTRITA contra `ENVIRONMENT_IDS`
+ * (`neetru-core/src/lib/schemas/envs.ts` = `['dev-local','staging','prod']`) e
+ * devolvem HTTP 400 `validation_failed`. Resultado: quem aceitava o default
+ * sugerido pela própria ferramenta tomava 400 — e o `neetru new` quebrava no
+ * passo [2/5]. O dev não tinha como adivinhar `'dev-local'`.
+ *
+ * O defeito estava copiado em 4 comandos (workspaces/tenants create+update/
+ * deployments/new). Centralizar aqui é o mesmo remédio que o Core já aplicou
+ * do lado servidor: um alfabeto só, para que a próxima mudança não deixe uma
+ * cópia para trás.
+ *
+ * ATENÇÃO — não confundir com o alfabeto de BANCO (`neetru db *`), que usa
+ * `'production'` (e não `'prod'`) e vive em `src/commands/db.ts`. A divergência
+ * é intencional do lado do Core; ver o doc de `DATABASE_ENVIRONMENTS` lá.
+ */
+import type { NeetruCliError } from '../cli-kit/errors.js';
+/** Ambientes de tenant/workspace/deployment aceitos pelo Core. */
+export declare const TENANT_ENVIRONMENT_IDS: readonly ["dev-local", "staging", "prod"];
+export type TenantEnvironmentId = (typeof TENANT_ENVIRONMENT_IDS)[number];
+/**
+ * Padrão canônico. É `'dev-local'`, nunca `'dev'` — ver o cabeçalho do módulo.
+ */
+export declare const DEFAULT_TENANT_ENVIRONMENT_ID: TenantEnvironmentId;
+/** Lista legível para mensagens de erro e textos de ajuda. */
+export declare function listarAmbientesTenant(): string;
+/**
+ * Normaliza um `--env` cru para o token que o Core aceita.
+ *
+ * @returns o id canônico, ou `null` quando o valor não corresponde a nenhum
+ *   ambiente conhecido — o chamador decide como reportar.
+ */
+export declare function normalizarAmbienteTenant(bruto: string | undefined | null): TenantEnvironmentId | null;
+/**
+ * Opções do prompt "Ambiente:" — mesma ordem de promoção do painel, e da
+ * MESMA lista que valida (P105: era uma cópia à mão de `TENANT_ENVIRONMENT_IDS`).
+ */
+export declare const ESCOLHAS_AMBIENTE_TENANT: ReadonlyArray<{
+    name: string;
+    value: TenantEnvironmentId;
+}>;
+/**
+ * Os OUTROS vocabulários de ambiente da CLI, derivados deste alfabeto por UMA
+ * tabela (P105 / bug_89d2497e, item 7). Antes, `deploy.ts` tinha
+ * `new Set(['dev','staging','prod'])` e `build.ts`/`env.ts` repetiam
+ * `'dev' | 'workspace' | 'prod'` à mão em oito lugares — cópias que podiam
+ * envelhecer em separado, como o `--env dev` envelheceu (bug_7dcb68e2).
+ *
+ *  - `deploy`: o que `neetru deploy --env` aceita e manda como
+ *    `environmentId`. O Core aceita `dev` como apelido de `dev-local` no
+ *    deploy (`deployRequestSchema` faz `dev → dev-local`, conferido na
+ *    origin/main do neetru-core em 2026-10-18).
+ *  - `runtime`: o `NEETRU_ENV` do SDK / `neetru build --target-env` /
+ *    `neetru env switch`. `staging` vira `workspace` (o mesmo estágio
+ *    não-dev/não-prod, com o nome que o SDK usa).
+ *
+ * A tabela é exaustiva por tipo: um ambiente novo em `TENANT_ENVIRONMENT_IDS`
+ * não compila até ganhar sua linha aqui.
+ */
+export declare const VOCABULARIOS_DE_AMBIENTE: {
+    readonly 'dev-local': {
+        readonly deploy: "dev";
+        readonly runtime: "dev";
+    };
+    readonly staging: {
+        readonly deploy: "staging";
+        readonly runtime: "workspace";
+    };
+    readonly prod: {
+        readonly deploy: "prod";
+        readonly runtime: "prod";
+    };
+};
+export type DeployEnvironmentId = (typeof VOCABULARIOS_DE_AMBIENTE)[TenantEnvironmentId]['deploy'];
+export type RuntimeEnvironmentId = (typeof VOCABULARIOS_DE_AMBIENTE)[TenantEnvironmentId]['runtime'];
+/** `dev | staging | prod` — o `--env` do `neetru deploy`, na ordem de promoção. */
+export declare const DEPLOY_ENVIRONMENT_IDS: readonly DeployEnvironmentId[];
+/** `dev | workspace | prod` — o `NEETRU_ENV` do SDK, na ordem de promoção. */
+export declare const RUNTIME_ENVIRONMENT_IDS: readonly RuntimeEnvironmentId[];
+/**
+ * `--env` do deploy → `NEETRU_ENV` do build, pela tabela. `undefined` para
+ * valor fora do vocabulário do deploy (quem chama decide o padrão).
+ */
+export declare function deployEnvParaRuntime(env: string): RuntimeEnvironmentId | undefined;
+/**
+ * Erro único de `--env` inválido (bug_89d2497e): os valores válidos saem de
+ * `TENANT_ENVIRONMENT_IDS` — a MESMA lista que valida —, e o JSON leva
+ * `flag`, `value` e `valid` além de `error`/`message`.
+ */
+export declare function erroAmbienteTenantInvalido(bruto: string): NeetruCliError;
+/**
+ * Mensagem única de `--env` inválido. Mantida aqui para que todos os comandos
+ * falhem com o mesmo texto e o dev aprenda o alfabeto de uma vez só.
+ */
+export declare function mensagemAmbienteInvalido(bruto: string): string;
+/**
+ * Normaliza um `--env` vindo da linha de comando e ABORTA quando não dá para
+ * mapear. Falhar aqui — antes de qualquer chamada de rede — é melhor do que
+ * mandar lixo pro Core e traduzir um 400 genérico depois.
+ */
+export declare function resolverAmbienteTenant(bruto: string, json?: boolean): TenantEnvironmentId;