@neetru/cli 2.31.0 → 2.32.0

package/dist/lib/segredo-produto.js

@@ -0,0 +1,336 @@
+/**
+ * Entrada e validação do VALOR de um segredo próprio do produto
+ * (bug_8b85353b, Parte 3 — `neetru secrets`).
+ *
+ * REGRA DURA que molda este módulo: o valor NUNCA vem da linha de comando.
+ * Tudo o que vai no argv fica no histórico do shell (`~/.bash_history`,
+ * `PSReadLine`), aparece em `ps`/Gerenciador de Tarefas para qualquer
+ * processo da máquina e costuma ir parar em log de CI. Por isso o valor só
+ * entra por três portas:
+ *
+ *   1. `--stdin`              — lido da entrada padrão (pipe);
+ *   2. `--from-file <caminho>` — lido de um arquivo;
+ *   3. prompt SEM ECO         — o terminal não mostra o que é digitado.
+ *
+ * (A quarta saída — `--generate` — nem passa por aqui: o Core sorteia o valor
+ * e ninguém o vê.)
+ *
+ * E o valor NUNCA é impresso: nenhuma mensagem deste módulo repete o que foi
+ * digitado — nem quando a entrada está errada, porque a entrada errada pode
+ * ser justamente o valor colado no lugar do nome.
+ *
+ * Espelhos do Core (`neetru_core/src/lib/product-secrets.ts`, origin/main):
+ * `CHAVE_SEGREDO_RE` = `PRODUCT_SECRET_KEY_RE`, `TETO_VALOR_BYTES` =
+ * `PRODUCT_SECRET_MAX_VALUE_BYTES`, `problemaNoValor` = `productSecretValueProblem`,
+ * `BYTES_GERADO_*` = os limites de `generateProductSecretValue`, e
+ * `problemaNaChaveReservada` = `isReservedProductSecretKey` (listas de
+ * `core-injected-env.ts`). Validar aqui também é para o valor recusado não
+ * sair da máquina. Se o Core mudar a regra, ele continua sendo o juiz final —
+ * aqui é só falhar mais cedo.
+ */
+import { open } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { normalizarAmbienteTenant } from './envs.js';
+import { CARACTERE_DE_TROCA, decodificarUtf8, recusaNaoUtf8, semBomInicial } from './texto-utf8.js';
+// A leitura estrita em UTF-8 mora em `texto-utf8.ts` (o `--env-file` do deploy e do build usa a
+// mesma). Reexportada para quem já importava daqui.
+export { CARACTERE_DE_TROCA, CodificacaoInvalida, decodificarUtf8, semBomInicial, } from './texto-utf8.js';
+/**
+ * Aviso de que o segredo registrado ainda não chega ao app na VM. Com data:
+ * quando o agente for liberado, a frase fica visivelmente velha em vez de
+ * mentir calada. Mesmo fato que o Core declara no `assertNoSecretEnvVars`.
+ */
+export const AVISO_AGENTE_PENDENTE = 'Atenção: em 2026-10-16 o agente da VM ainda não entrega segredos do produto ao app ' +
+    '(Parte 2 de bug_8b85353b). O registro já vale e passa a chegar ao app no primeiro ' +
+    'deploy depois que o agente for atualizado.';
+/**
+ * O comando que registra `chave` no ambiente do deploy. `env` é o `--env` cru
+ * do deploy (`dev`, `production`…): sai no nome canônico que o Core aceita, ou
+ * `<ambiente>` quando não dá para saber.
+ */
+export function comandoParaRegistrarSegredo(chave, env) {
+    return `neetru secrets set ${chave} --env ${normalizarAmbienteTenant(env) ?? '<ambiente>'}`;
+}
+/** Nome de variável de ambiente em CAIXA_ALTA, 2 a 64 caracteres. */
+export const CHAVE_SEGREDO_RE = /^[A-Z][A-Z0-9_]{1,63}$/;
+/** Teto do valor: o do arquivo de ambiente que o agente escreve na VM. */
+export const TETO_VALOR_BYTES = 4096;
+/** Entropia aceita no `--generate` (bytes sorteados pelo Core). */
+export const BYTES_GERADO_MIN = 16;
+export const BYTES_GERADO_MAX = 128;
+/**
+ * Teto do que se aceita LER (arquivo/stdin) antes de validar. Bem acima do
+ * `TETO_VALOR_BYTES` para a mensagem de "grande demais" sair certa, e baixo o
+ * bastante para um `--from-file` apontado por engano para um arquivo enorme
+ * (ou que nunca acaba, como `/dev/zero`) não encher a memória: a leitura para
+ * em `TETO_LEITURA_BYTES + 1` bytes, nunca lê o arquivo inteiro.
+ */
+export const TETO_LEITURA_BYTES = 64 * 1024;
+/**
+ * Variáveis que o Core e o agente JÁ entregam ao app na VM, por outro canal.
+ * Espelho de `CORE_INJECTED_ENV_KEYS` (`neetru_core/src/lib/core-injected-env.ts`),
+ * na mesma ordem: o teste `reservadas de hoje` trava o literal e a conferência
+ * opt-in (`NEETRU_CORE_DIR`) compara com o Core.
+ */
+export const CHAVES_INJETADAS_PELO_CORE = [
+    'PORT',
+    'NODE_ENV',
+    'HOME',
+    'NODE_OPTIONS',
+    'NEETRU_ENV',
+    'NEETRU_SDK_CLIENT_SECRET',
+    'NEETRU_CLIENT_ID',
+    'NEETRU_CLIENT_SECRET',
+    'NEETRU_OIDC_CLIENT_ID',
+    'NEETRU_OIDC_CLIENT_SECRET',
+    'NEETRU_OAUTH_CLIENT_ID',
+    'NEETRU_OAUTH_CLIENT_SECRET',
+    'NEETRU_API_KEY',
+];
+/** Famílias inteiras entregues por um canal do Core (hoje: módulos). Espelho de `CORE_INJECTED_ENV_PREFIXES`. */
+export const PREFIXOS_INJETADOS_PELO_CORE = ['NEETRU_MODULE_'];
+/**
+ * Variáveis que mudam como o processo carrega código: um "segredo" com esse
+ * nome é execução de código na VM. Espelho de `LOADER_ENV_KEYS` do Core.
+ */
+export const CHAVES_DO_CARREGADOR = [
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'LD_AUDIT',
+    'DYLD_INSERT_LIBRARIES',
+    'DYLD_LIBRARY_PATH',
+    'PATH',
+    'NODE_PATH',
+    'NODE_OPTIONS',
+];
+/** O Core já entrega esta variável ao app na VM (nome exato ou família)? */
+export function chaveInjetadaPeloCore(chave) {
+    return CHAVES_INJETADAS_PELO_CORE.includes(chave) || PREFIXOS_INJETADOS_PELO_CORE.some((p) => chave.startsWith(p));
+}
+/**
+ * Por que o Core recusaria registrar esta chave como segredo do produto, ou
+ * `null` se ele aceita. Só chama depois de `problemaNaChave` aprovar o
+ * formato. Espelho de `assertValidProductSecretKey` (a parte da reserva).
+ *
+ * Revisão do #81 (M1): sem isto, a CLI pedia o valor, mandava, e só então o
+ * Core dizia "reservada". O nome exato é repetido na mensagem porque é um nome
+ * da lista fixa; a família `NEETRU_MODULE_` é citada pelo prefixo, sem
+ * repetir o resto do que foi digitado.
+ */
+export function problemaNaChaveReservada(chave) {
+    if (CHAVES_DO_CARREGADOR.includes(chave)) {
+        return (`A chave ${chave} é reservada: ela muda como o processo carrega código (bibliotecas, ` +
+            'caminhos, opções do Node) e não pode vir de um segredo do produto. Escolha outro nome.');
+    }
+    if (CHAVES_INJETADAS_PELO_CORE.includes(chave)) {
+        return (`A chave ${chave} é reservada: o Core já a entrega ao app na VM por outro canal ` +
+            '(credencial SDK, OIDC ou CLI, ambiente ou unit do app). Não precisa registrá-la; ' +
+            'para um segredo seu, escolha outro nome.');
+    }
+    const prefixo = PREFIXOS_INJETADOS_PELO_CORE.find((p) => chave.startsWith(p));
+    if (prefixo) {
+        return (`Chaves que começam com ${prefixo} são reservadas: o Core já as entrega ao app na VM ` +
+            'quando o módulo está ativo. Não precisa registrá-las; para um segredo seu, escolha ' +
+            'outro nome.');
+    }
+    return null;
+}
+/**
+ * Por que a chave é recusada, ou `null` se serve. NUNCA repete o que foi
+ * digitado: `KEY=valor` e o valor colado no lugar do nome são os dois erros
+ * mais prováveis, e ecoar a entrada imprimiria o segredo.
+ */
+export function problemaNaChave(chave) {
+    if (typeof chave === 'string' && CHAVE_SEGREDO_RE.test(chave))
+        return null;
+    if (typeof chave === 'string' && chave.includes('=')) {
+        return ('Parece que você passou CHAVE=VALOR. O valor do segredo nunca vai na linha de ' +
+            'comando (fica no histórico do shell). Passe só o nome e mande o valor por ' +
+            '--stdin, --from-file ou pelo pedido na tela. Se o valor já foi digitado, ' +
+            'considere-o exposto e troque-o.');
+    }
+    return ('Nome de segredo inválido. Use CAIXA_ALTA com letras, dígitos e underscore, ' +
+        'começando por letra, de 2 a 64 caracteres (ex.: NEETRU_WEBHOOK_SECRET). ' +
+        'O que foi digitado não é repetido aqui, caso seja o próprio valor.');
+}
+/**
+ * Por que o valor é recusado, ou `null` se serve. Mesma regra do Core e do
+ * agente: o valor vira uma linha de `EnvironmentFile` do systemd, e o agente
+ * recusa a resposta INTEIRA (todos os segredos do produto) se um valor tiver
+ * quebra de linha, NUL, aspas, barra invertida ou espaço nas pontas.
+ */
+export function problemaNoValor(valor) {
+    if (valor.length === 0)
+        return 'O valor do segredo está vazio.';
+    if (Buffer.byteLength(valor, 'utf8') > TETO_VALOR_BYTES) {
+        return `O valor do segredo passa de ${TETO_VALOR_BYTES} bytes (teto do arquivo de ambiente na VM).`;
+    }
+    if (/[\r\n\0"'\\]/.test(valor) || valor !== valor.trim()) {
+        return ('O valor do segredo tem caractere que o arquivo de ambiente da VM não aceita ' +
+            '(quebra de linha, NUL, aspas, barra invertida, ou espaço ou caractere invisível ' +
+            'nas pontas, como a marca BOM de arquivo salvo em "UTF-8 com BOM"). Para chave ' +
+            'PEM ou JSON, grave em base64 e decodifique no app.');
+    }
+    return null;
+}
+/** Valida `--bytes` (só faz sentido com `--generate`). `null` se serve. */
+export function problemaNosBytes(bytes) {
+    if (!Number.isInteger(bytes) || bytes < BYTES_GERADO_MIN || bytes > BYTES_GERADO_MAX) {
+        return `--bytes deve ser um número inteiro de ${BYTES_GERADO_MIN} a ${BYTES_GERADO_MAX}.`;
+    }
+    return null;
+}
+/**
+ * Tira UMA quebra de linha do fim (`\n` ou `\r\n`) — a que `echo`, `cat` e
+ * os editores deixam. Só uma: o resto de espaço ou quebra nas pontas é
+ * recusado por `problemaNoValor`, com mensagem, em vez de ser "consertado"
+ * em silêncio (cortar demais grava um segredo diferente do que o dev tem).
+ */
+export function semQuebraFinal(texto) {
+    if (texto.endsWith('\r\n'))
+        return texto.slice(0, -2);
+    if (texto.endsWith('\n'))
+        return texto.slice(0, -1);
+    return texto;
+}
+/**
+ * Texto que OUTRO decodificador já converteu (o `readline` do pedido na tela,
+ * ou um fluxo com `setEncoding`): os bytes originais se perderam e o U+FFFD é
+ * o único rastro de byte que não era UTF-8. Recusa quando ele aparece.
+ * Limite declarado: um U+FFFD digitado de propósito também é recusado — por
+ * esta porta não dá para distinguir.
+ */
+export function problemaNoTextoDoTerminal(texto) {
+    if (!texto.includes(CARACTERE_DE_TROCA))
+        return null;
+    return ('O terminal mandou um caractere que não está em UTF-8, e ele foi trocado por um caractere de ' +
+        'substituição: o segredo gravado seria diferente do digitado. Ajuste o terminal para UTF-8 ' +
+        '(ex.: LANG=pt_BR.UTF-8), ou grave o valor num arquivo UTF-8 e use --from-file. ' +
+        'O conteúdo não é repetido aqui. Nada foi enviado.');
+}
+/** Nunca repete o caminho: o engano provável é colar o VALOR no lugar dele. */
+const CAMINHO_NAO_REPETIDO = '(o caminho não é repetido aqui, caso seja o próprio valor)';
+function mensagemDeLeitura(err) {
+    const codigo = err?.code;
+    if (codigo === 'ENOENT')
+        return `Arquivo não encontrado ${CAMINHO_NAO_REPETIDO}.`;
+    if (codigo === 'EISDIR')
+        return `O caminho é uma pasta, não um arquivo ${CAMINHO_NAO_REPETIDO}.`;
+    return `Não consegui ler o arquivo (${codigo ?? 'erro desconhecido'}) ${CAMINHO_NAO_REPETIDO}.`;
+}
+/**
+ * Lê o valor de um arquivo. Erro de leitura vira mensagem sem conteúdo e sem
+ * o caminho (revisão do #81, B2: `--from-file <valor>` repetia o valor em
+ * "Arquivo não encontrado: <valor>").
+ *
+ * Lê no máximo `TETO_LEITURA_BYTES + 1` bytes (revisão do #81: o `readFile`
+ * de antes punha o arquivo inteiro na memória antes de conferir o teto).
+ */
+export async function lerValorDeArquivo(caminho, abrir = (c) => open(c, 'r')) {
+    const bruto = Buffer.alloc(TETO_LEITURA_BYTES + 1);
+    let lidos = 0;
+    let arquivo;
+    try {
+        arquivo = await abrir(caminho);
+        while (lidos < bruto.length) {
+            const { bytesRead } = await arquivo.read(bruto, lidos, bruto.length - lidos, null);
+            if (bytesRead === 0)
+                break;
+            lidos += bytesRead;
+        }
+    }
+    catch (err) {
+        throw new Error(mensagemDeLeitura(err));
+    }
+    finally {
+        await arquivo?.close().catch(() => undefined);
+    }
+    if (lidos > TETO_LEITURA_BYTES) {
+        throw new Error(`O arquivo passa de ${TETO_LEITURA_BYTES} bytes — não parece um segredo.`);
+    }
+    return semQuebraFinal(semBomInicial(decodificarUtf8(bruto.subarray(0, lidos), 'arquivo')));
+}
+/** Lê o valor inteiro de um fluxo (a entrada padrão, no `--stdin`). */
+export async function lerValorDeFluxo(fluxo) {
+    const partes = [];
+    let total = 0;
+    for await (const pedaco of fluxo) {
+        // Pedaço em texto = alguém já decodificou o fluxo (`setEncoding`), e o
+        // U+FFFD é o único rastro de byte trocado. Os pedaços em bytes são
+        // conferidos JUNTOS no fim: uma letra acentuada pode vir partida em dois.
+        // Revisão do #81 (M-r3-1): o U+FFFD que chega em bytes (EF BF BD, a
+        // conversão com perda feita antes da CLI) também é recusado, lá no fim,
+        // por `decodificarUtf8` — a regra não depende mais do formato do pedaço.
+        if (typeof pedaco === 'string' && pedaco.includes(CARACTERE_DE_TROCA))
+            throw recusaNaoUtf8('entrada');
+        const buf = typeof pedaco === 'string' ? Buffer.from(pedaco, 'utf8') : pedaco;
+        total += buf.length;
+        if (total > TETO_LEITURA_BYTES) {
+            throw new Error(`A entrada passa de ${TETO_LEITURA_BYTES} bytes — não parece um segredo.`);
+        }
+        partes.push(buf);
+    }
+    return semQuebraFinal(semBomInicial(decodificarUtf8(Buffer.concat(partes), 'entrada')));
+}
+/** Pedido cancelado (Ctrl+C ou fim da entrada antes da resposta). */
+export class PedidoCancelado extends Error {
+    constructor() {
+        super('Pedido cancelado — nada foi enviado.');
+        this.name = 'PedidoCancelado';
+    }
+}
+/**
+ * Faz as perguntas SEM ECO, numa interface só (duas interfaces seguidas no
+ * mesmo fluxo perdem a linha que a primeira já tinha lido).
+ *
+ * Como o eco some: o `readline` desenha o que é digitado no `output` dele —
+ * aqui um fluxo MUDO, que descarta tudo. A pergunta vai direto para `saida`,
+ * fora do `readline`. Com `terminal: true` o `readline` também liga o modo
+ * cru do terminal (`setRawMode`), então nem o eco do próprio sistema
+ * operacional aparece.
+ */
+export function perguntarSemEco(perguntas, fluxos) {
+    const mudo = new Writable({
+        write(_pedaco, _codificacao, pronto) {
+            pronto();
+        },
+    });
+    const rl = createInterface({ input: fluxos.entrada, output: mudo, terminal: true });
+    const respostas = [];
+    return new Promise((resolve, reject) => {
+        let terminado = false;
+        const encerrar = (erro) => {
+            if (terminado)
+                return;
+            terminado = true;
+            rl.close();
+            if (erro)
+                reject(erro);
+            else
+                resolve(respostas);
+        };
+        // Ctrl+C em modo cru não vira sinal: chega aqui. Sem este ouvinte o
+        // readline só pausa, e o comando ficaria pendurado.
+        rl.on('SIGINT', () => {
+            fluxos.saida.write('\n');
+            encerrar(new PedidoCancelado());
+        });
+        rl.on('close', () => encerrar(new PedidoCancelado()));
+        const proxima = (i) => {
+            if (i >= perguntas.length) {
+                encerrar();
+                return;
+            }
+            fluxos.saida.write(`  ${perguntas[i]} `);
+            rl.question('', (resposta) => {
+                // O Enter também não foi ecoado: a quebra de linha é nossa.
+                fluxos.saida.write('\n');
+                respostas.push(resposta);
+                proxima(i + 1);
+            });
+        };
+        proxima(0);
+    });
+}
+//# sourceMappingURL=segredo-produto.js.map

package/dist/lib/texto-utf8.d.ts

@@ -0,0 +1,96 @@
+/**
+ * O texto não está em UTF-8 (ou traz U+FFFD) — recusa com o código
+ * `invalid_encoding`. A mensagem diz como salvar o arquivo, nunca o que ele
+ * contém.
+ */
+export declare class CodificacaoInvalida extends Error {
+    constructor(mensagem: string);
+}
+/** U+FFFD: o caractere que um decodificador UTF-8 põe no lugar de byte que não é UTF-8. */
+export declare const CARACTERE_DE_TROCA = "\uFFFD";
+/**
+ * De onde vieram os bytes (só muda o texto da recusa): `arquivo` e `entrada`
+ * são o `--from-file` e o `--stdin` do segredo; `env-file` é o `--env-file`
+ * do deploy e do build.
+ */
+export type OrigemDosBytes = 'arquivo' | 'entrada' | 'env-file';
+/**
+ * Tira UMA marca BOM (U+FEFF) do começo — a que o Bloco de Notas ("UTF-8 com
+ * BOM") e o `Set-Content -Encoding utf8` do Windows PowerShell 5.1 gravam no
+ * arquivo (medido: `ef bb bf …`). O PowerShell 7 grava sem a marca. Revisão do
+ * #81 (B3): sem isto o `trim()` de `problemaNoValor` via a marca como espaço
+ * e recusava com "espaço nas pontas", sem espaço nenhum à vista. Só uma, pelo
+ * mesmo motivo de `semQuebraFinal`.
+ */
+export declare function semBomInicial(texto: string): string;
+/**
+ * Como converter um arquivo ANSI para UTF-8 — uma receita por versão do
+ * PowerShell, porque o `Get-Content` lê diferente nas duas.
+ *
+ * Revisão do #81 (M-r3-1): a receita era só a do 5.1. No Windows PowerShell
+ * 5.1, o `Get-Content` lê arquivo sem marca em ANSI, e o `Set-Content
+ * -Encoding utf8` grava UTF-8 COM a marca BOM (`semBomInicial` a tira). No
+ * PowerShell 7, o `Get-Content` lê arquivo sem marca em UTF-8 (o padrão é
+ * `utf8NoBOM`): o "é" do ANSI vira U+FFFD antes de chegar à CLI, e o
+ * `Set-Content -Encoding utf8` (no 7, sem BOM) grava esse U+FFFD em UTF-8
+ * válido. Lá a leitura certa é `-Encoding ansi` (página ANSI da cultura,
+ * existe a partir do 7.4, segundo a documentação do `Get-Content`). No 5.1,
+ * `-Encoding ansi` dá erro de parâmetro e não cria o arquivo novo (medido), e
+ * a receita do 5.1 rodada no 7 grava U+FFFD — que `decodificarUtf8` recusa.
+ * Assim, a receita da versão errada nunca passa calada.
+ */
+export declare const COMO_CONVERTER_ANSI: string;
+/**
+ * UTF-16 tem marca (FF FE / FE FF), e a marca vence o `-Encoding` na leitura
+ * (medido no 5.1: o arquivo do `>` lido com `-Encoding UTF8` sai certo). Por
+ * isso a mesma receita serve nas duas versões.
+ */
+export declare const COMO_CONVERTER_UTF16: string;
+/** Exportada para o `--stdin` que já chega decodificado (`setEncoding`). */
+export declare function recusaNaoUtf8(origem: OrigemDosBytes): CodificacaoInvalida;
+/**
+ * O que impede estes bytes de serem lidos como o arquivo de origem — ou `null`
+ * quando são UTF-8 limpo:
+ *
+ *   1. `utf16`: marca UTF-16 (FF FE / FE FF) — antes caía em recusa que
+ *      citava "UTF-8 com BOM" (segredo) ou virava chave com NUL (env-file);
+ *   2. `nao-utf8`: bytes que não são UTF-8 (`isUtf8`) — o ANSI do 5.1;
+ *   3. `troca-gravada`: U+FFFD em UTF-8 válido (revisão do #81, M-r3-1) — a
+ *      conversão com perda feita antes da CLI. Limite declarado: um U+FFFD
+ *      gravado de propósito cai aqui também (não dá para distinguir).
+ *
+ * A marca BOM do UTF-8 (EF BB BF) é UTF-8 válido: não é problema.
+ *
+ * Fonte única da regra: `decodificarUtf8` recusa por ela, e o `env switch` e a
+ * varredura de segredo público decidem por ela (rodada final 2 do #81).
+ */
+export type ProblemaDeCodificacao = 'utf16' | 'nao-utf8' | 'troca-gravada';
+export declare function problemaDeCodificacao(bruto: Buffer): ProblemaDeCodificacao | null;
+/**
+ * Converte os bytes lidos em texto, RECUSANDO o que não é o arquivo de origem
+ * (os três casos de `problemaDeCodificacao`). No U+FFFD, a CLI fica mais
+ * estrita que o Core.
+ *
+ * A marca BOM do UTF-8 (EF BB BF) passa daqui, e quem chama a tira com
+ * `semBomInicial`.
+ */
+export declare function decodificarUtf8(bruto: Buffer, origem: OrigemDosBytes): string;
+/**
+ * `neetru env switch` (rodada final 2 do #81, achado BAIXA): o comando lia o
+ * `.env.local` com `readFile(…, 'utf-8')` e REGRAVAVA o arquivo inteiro. Medido
+ * no processo real: um `.env.local` ANSI com `NOME_LOJA=Café` terminava com
+ * `ef bf bd` no lugar do `e9`, e um UTF-16 virava texto ilegível — exit 0 e
+ * "✓" nos dois. Agora ele recusa ANTES de gravar e não toca no arquivo.
+ *
+ * Recusa só o que a regravação estragaria (`utf16` e `nao-utf8`). Um U+FFFD
+ * que já está no arquivo (`troca-gravada`) sai byte a byte igual — o comando
+ * não perde nada ali, então segue.
+ */
+export declare function recusaDoEnvSwitch(arquivo: string, problema: 'utf16' | 'nao-utf8'): CodificacaoInvalida;
+/**
+ * Varredura de segredo público do `neetru deploy` (rodada final 2 do #81): um
+ * `.env*` que o bundler lê não está em UTF-8 limpo. A varredura segue — ela
+ * confere o valor como o bundler o lê —, mas o app vai receber outro valor, e
+ * isso não passa calado. Nunca repete o conteúdo.
+ */
+export declare function avisoEnvDoBundlerForaDeUtf8(arquivo: string, problema: ProblemaDeCodificacao): string;

package/dist/lib/texto-utf8.js

@@ -0,0 +1,196 @@
+/**
+ * Bytes lidos de arquivo ou da entrada padrão → texto, SÓ quando são UTF-8 de
+ * verdade e não trazem o rastro de uma conversão que perdeu letra.
+ *
+ * Por que existe: `Buffer#toString('utf8')` e `fs.readFile(…, 'utf8')` trocam
+ * cada byte que não é UTF-8 por U+FFFD, sem erro. Um arquivo ANSI com "é"
+ * virava "senha\uFFFD" (ou "Caf\uFFFD"), e o valor seguia adiante diferente do
+ * arquivo, sem aviso. Quem usa:
+ *
+ *   - `neetru secrets set --from-file | --stdin` (`segredo-produto.ts`): o
+ *     Secret Manager guardaria outro segredo (revisão do #81, M-r2-1);
+ *   - o `--env-file` do `neetru deploy` e do `neetru build`: o app ou o build
+ *     receberiam outro valor (revisão do #81, N-r3-1);
+ *   - o `neetru env switch`, que regrava o `.env.local` (rodada final 2 do
+ *     #81): recusa antes de gravar o que a regravação estragaria;
+ *   - a varredura de segredo do deploy (`collectPublicEnvSecrets`), que lê os
+ *     `.env*` COMO O BUNDLER LÊ e só avisa (rodada final 2 do #81).
+ *
+ * As mensagens dizem como converter, e nunca repetem o conteúdo.
+ */
+import { isUtf8 } from 'node:buffer';
+/**
+ * O texto não está em UTF-8 (ou traz U+FFFD) — recusa com o código
+ * `invalid_encoding`. A mensagem diz como salvar o arquivo, nunca o que ele
+ * contém.
+ */
+export class CodificacaoInvalida extends Error {
+    constructor(mensagem) {
+        super(mensagem);
+        this.name = 'CodificacaoInvalida';
+    }
+}
+/** U+FFFD: o caractere que um decodificador UTF-8 põe no lugar de byte que não é UTF-8. */
+export const CARACTERE_DE_TROCA = '\uFFFD';
+/**
+ * Tira UMA marca BOM (U+FEFF) do começo — a que o Bloco de Notas ("UTF-8 com
+ * BOM") e o `Set-Content -Encoding utf8` do Windows PowerShell 5.1 gravam no
+ * arquivo (medido: `ef bb bf …`). O PowerShell 7 grava sem a marca. Revisão do
+ * #81 (B3): sem isto o `trim()` de `problemaNoValor` via a marca como espaço
+ * e recusava com "espaço nas pontas", sem espaço nenhum à vista. Só uma, pelo
+ * mesmo motivo de `semQuebraFinal`.
+ */
+export function semBomInicial(texto) {
+    return texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto;
+}
+/**
+ * Como converter um arquivo ANSI para UTF-8 — uma receita por versão do
+ * PowerShell, porque o `Get-Content` lê diferente nas duas.
+ *
+ * Revisão do #81 (M-r3-1): a receita era só a do 5.1. No Windows PowerShell
+ * 5.1, o `Get-Content` lê arquivo sem marca em ANSI, e o `Set-Content
+ * -Encoding utf8` grava UTF-8 COM a marca BOM (`semBomInicial` a tira). No
+ * PowerShell 7, o `Get-Content` lê arquivo sem marca em UTF-8 (o padrão é
+ * `utf8NoBOM`): o "é" do ANSI vira U+FFFD antes de chegar à CLI, e o
+ * `Set-Content -Encoding utf8` (no 7, sem BOM) grava esse U+FFFD em UTF-8
+ * válido. Lá a leitura certa é `-Encoding ansi` (página ANSI da cultura,
+ * existe a partir do 7.4, segundo a documentação do `Get-Content`). No 5.1,
+ * `-Encoding ansi` dá erro de parâmetro e não cria o arquivo novo (medido), e
+ * a receita do 5.1 rodada no 7 grava U+FFFD — que `decodificarUtf8` recusa.
+ * Assim, a receita da versão errada nunca passa calada.
+ */
+export const COMO_CONVERTER_ANSI = 'No Windows PowerShell 5.1: Get-Content <arquivo> | Set-Content -Encoding utf8 <arquivo-novo>. ' +
+    'No PowerShell 7.4 ou mais novo: Get-Content -Encoding ansi <arquivo> | Set-Content -Encoding utf8 ' +
+    '<arquivo-novo>. Ou, no Bloco de Notas, "Salvar como" com a codificação UTF-8.';
+/**
+ * UTF-16 tem marca (FF FE / FE FF), e a marca vence o `-Encoding` na leitura
+ * (medido no 5.1: o arquivo do `>` lido com `-Encoding UTF8` sai certo). Por
+ * isso a mesma receita serve nas duas versões.
+ */
+export const COMO_CONVERTER_UTF16 = 'No PowerShell (5.1 ou 7): Get-Content <arquivo> | Set-Content -Encoding utf8 <arquivo-novo>. Ou, ' +
+    'no Bloco de Notas, "Salvar como" com a codificação UTF-8.';
+const SEM_CONTEUDO = 'O conteúdo não é repetido aqui. Nada foi enviado.';
+const SEM_CONTEUDO_ENV = 'O conteúdo não é repetido aqui, e nenhuma variável do arquivo foi usada.';
+function recusaUtf16(origem) {
+    const motivo = 'o `>` e o Out-File do Windows PowerShell 5.1 gravam em UTF-16';
+    if (origem === 'arquivo') {
+        return new CodificacaoInvalida(`O arquivo está gravado em UTF-16, e o valor só é lido em UTF-8 (${motivo}). Salve-o em UTF-8 e ` +
+            `rode de novo. ${COMO_CONVERTER_UTF16} ${SEM_CONTEUDO}`);
+    }
+    if (origem === 'env-file') {
+        return new CodificacaoInvalida(`O --env-file está gravado em UTF-16, e ele só é lido em UTF-8 (${motivo}). Salve-o em UTF-8 e ` +
+            `rode de novo. ${COMO_CONVERTER_UTF16} ${SEM_CONTEUDO_ENV}`);
+    }
+    return new CodificacaoInvalida('A entrada chegou em UTF-16, e o valor só é lido em UTF-8. Mande o valor em UTF-8, ou grave-o ' +
+        `num arquivo UTF-8 e use --from-file. ${SEM_CONTEUDO}`);
+}
+const PROVAVEL_ANSI = 'provavelmente ANSI (Windows-1252), que é o que o Set-Content do Windows PowerShell 5.1 grava ' +
+    'sem -Encoding';
+/** Exportada para o `--stdin` que já chega decodificado (`setEncoding`). */
+export function recusaNaoUtf8(origem) {
+    const troca = 'Lido assim, cada letra acentuada seria trocada por um caractere de substituição';
+    if (origem === 'arquivo') {
+        return new CodificacaoInvalida(`O arquivo não está em UTF-8 — ${PROVAVEL_ANSI}. ${troca}, e o Secret Manager guardaria um ` +
+            `segredo diferente do que você tem. Salve-o em UTF-8 e rode de novo. ${COMO_CONVERTER_ANSI} ` +
+            SEM_CONTEUDO);
+    }
+    if (origem === 'env-file') {
+        return new CodificacaoInvalida(`O --env-file não está em UTF-8 — ${PROVAVEL_ANSI}. ${troca}, e o app receberia um valor ` +
+            `diferente do que está no arquivo. Salve-o em UTF-8 e rode de novo. ${COMO_CONVERTER_ANSI} ` +
+            SEM_CONTEUDO_ENV);
+    }
+    return new CodificacaoInvalida(`A entrada não está em UTF-8. ${troca}, e o Secret Manager guardaria um segredo diferente do ` +
+        `que você tem. Mande o valor em UTF-8, ou grave-o num arquivo UTF-8 e use --from-file. ` +
+        SEM_CONTEUDO);
+}
+/**
+ * Revisão do #81 (M-r3-1): o texto é UTF-8 válido, mas traz U+FFFD — o rastro
+ * de uma conversão feita ANTES da CLI que não reconheceu uma letra. É o que a
+ * receita do 5.1, rodada no PowerShell 7, grava (`… ef bf bd …`).
+ */
+function recusaTrocaGravada(origem) {
+    const rastro = 'traz o caractere de substituição (U+FFFD), o rastro de uma conversão que não reconheceu uma ' +
+        'letra — como a do Get-Content do PowerShell 7 sem -Encoding ansi, que lê o arquivo ANSI como UTF-8';
+    if (origem === 'arquivo') {
+        return new CodificacaoInvalida(`O arquivo está em UTF-8, mas ${rastro}. Gravado assim, o segredo seria diferente do original. ` +
+            `Converta de novo a partir do arquivo original. ${COMO_CONVERTER_ANSI} ${SEM_CONTEUDO}`);
+    }
+    if (origem === 'env-file') {
+        return new CodificacaoInvalida(`O --env-file está em UTF-8, mas ${rastro}. Lido assim, o app receberia um valor diferente do ` +
+            `original. Converta de novo a partir do arquivo original. ${COMO_CONVERTER_ANSI} ${SEM_CONTEUDO_ENV}`);
+    }
+    return new CodificacaoInvalida(`A entrada ${rastro}. Gravado assim, o segredo seria diferente do original. Grave o valor num ` +
+        `arquivo UTF-8 e use --from-file. ${COMO_CONVERTER_ANSI} ${SEM_CONTEUDO}`);
+}
+export function problemaDeCodificacao(bruto) {
+    const marcaUtf16 = bruto.length >= 2 && ((bruto[0] === 0xff && bruto[1] === 0xfe) || (bruto[0] === 0xfe && bruto[1] === 0xff));
+    if (marcaUtf16)
+        return 'utf16';
+    if (!isUtf8(bruto))
+        return 'nao-utf8';
+    if (bruto.toString('utf8').includes(CARACTERE_DE_TROCA))
+        return 'troca-gravada';
+    return null;
+}
+/**
+ * Converte os bytes lidos em texto, RECUSANDO o que não é o arquivo de origem
+ * (os três casos de `problemaDeCodificacao`). No U+FFFD, a CLI fica mais
+ * estrita que o Core.
+ *
+ * A marca BOM do UTF-8 (EF BB BF) passa daqui, e quem chama a tira com
+ * `semBomInicial`.
+ */
+export function decodificarUtf8(bruto, origem) {
+    const problema = problemaDeCodificacao(bruto);
+    if (problema === 'utf16')
+        throw recusaUtf16(origem);
+    if (problema === 'nao-utf8')
+        throw recusaNaoUtf8(origem);
+    if (problema === 'troca-gravada')
+        throw recusaTrocaGravada(origem);
+    return bruto.toString('utf8');
+}
+/**
+ * `neetru env switch` (rodada final 2 do #81, achado BAIXA): o comando lia o
+ * `.env.local` com `readFile(…, 'utf-8')` e REGRAVAVA o arquivo inteiro. Medido
+ * no processo real: um `.env.local` ANSI com `NOME_LOJA=Café` terminava com
+ * `ef bf bd` no lugar do `e9`, e um UTF-16 virava texto ilegível — exit 0 e
+ * "✓" nos dois. Agora ele recusa ANTES de gravar e não toca no arquivo.
+ *
+ * Recusa só o que a regravação estragaria (`utf16` e `nao-utf8`). Um U+FFFD
+ * que já está no arquivo (`troca-gravada`) sai byte a byte igual — o comando
+ * não perde nada ali, então segue.
+ */
+export function recusaDoEnvSwitch(arquivo, problema) {
+    const fecho = 'O arquivo não foi alterado, e o conteúdo dele não é repetido aqui.';
+    if (problema === 'utf16') {
+        return new CodificacaoInvalida(`O ${arquivo} está gravado em UTF-16 (o \`>\` e o Out-File do Windows PowerShell 5.1 gravam ` +
+            'assim). O env switch regrava o arquivo inteiro em UTF-8, e lido como UTF-8 ele viraria texto ' +
+            `ilegível no disco. Salve-o em UTF-8 e rode de novo. ${COMO_CONVERTER_UTF16} ${fecho}`);
+    }
+    return new CodificacaoInvalida(`O ${arquivo} não está em UTF-8 — ${PROVAVEL_ANSI}. O env switch regrava o arquivo inteiro em ` +
+        'UTF-8: cada letra acentuada viraria um caractere de substituição, e a letra original se ' +
+        `perderia no disco. Salve-o em UTF-8 e rode de novo. ${COMO_CONVERTER_ANSI} ${fecho}`);
+}
+/**
+ * Varredura de segredo público do `neetru deploy` (rodada final 2 do #81): um
+ * `.env*` que o bundler lê não está em UTF-8 limpo. A varredura segue — ela
+ * confere o valor como o bundler o lê —, mas o app vai receber outro valor, e
+ * isso não passa calado. Nunca repete o conteúdo.
+ */
+export function avisoEnvDoBundlerForaDeUtf8(arquivo, problema) {
+    const fecho = 'A varredura de segredo seguiu, conferindo o valor como o bundler o lê. O conteúdo não é repetido aqui.';
+    if (problema === 'utf16') {
+        return (`Aviso: o ${arquivo} está gravado em UTF-16. O Next e o Vite leem os .env em UTF-8, e lidas assim ` +
+            `as variáveis dele não chegam ao app como estão escritas. Salve-o em UTF-8. ${COMO_CONVERTER_UTF16} ${fecho}`);
+    }
+    if (problema === 'nao-utf8') {
+        return (`Aviso: o ${arquivo} não está em UTF-8 — ${PROVAVEL_ANSI}. O Next e o Vite leem os .env em UTF-8, e ` +
+            'cada letra acentuada chega ao app como o caractere de substituição (U+FFFD), diferente do arquivo. ' +
+            `Salve-o em UTF-8. ${COMO_CONVERTER_ANSI} ${fecho}`);
+    }
+    return (`Aviso: o ${arquivo} está em UTF-8, mas traz o caractere de substituição (U+FFFD), o rastro de uma ` +
+        'conversão que não reconheceu uma letra. O app recebe esse caractere no lugar da letra original. ' +
+        `Converta de novo a partir do arquivo original. ${COMO_CONVERTER_ANSI} ${fecho}`);
+}
+//# sourceMappingURL=texto-utf8.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neetru/cli",
-  "version": "2.31.0",
+  "version": "2.32.0",
   "type": "module",
   "description": "Neetru Developer Kit — scaffold, AI assistant, publish, build e deploy de produtos SaaS Neetru via Core (VM-based agents)",
   "keywords": [
@@ -27,6 +27,7 @@
   "main": "./dist/index.js",
   "files": [
     "dist",
+    "!dist/**/*.map",
     "templates",
     "README.md",
     "CHANGELOG.md"

package/dist/cli-kit/format.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/cli-kit/format.ts"],"names":[],"mappings":"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"}

package/dist/cli-kit/glyphs.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../src/cli-kit/glyphs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,iCAAiC;IACjC,EAAE,EAAE,GAAG;IACP,oBAAoB;IACpB,GAAG,EAAE,GAAG;IACR,uBAAuB;IACvB,IAAI,EAAE,GAAG;IACT,qEAAqE;IACrE,KAAK,EAAE,GAAG;IACV,qBAAqB;IACrB,MAAM,EAAE,GAAG;IACX,+BAA+B;IAC/B,OAAO,EAAE,GAAG;CACb,CAAC,CAAC"}

package/dist/cli-kit/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli-kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACL,IAAI,EACJ,UAAU,EACV,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/dist/cli-kit/palette.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"palette.js","sourceRoot":"","sources":["../../src/cli-kit/palette.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,mDAAmD;AACnD,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,EAAE,CAAC,CAAS;IAC1B,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,GAAG,CAAC,CAAS;IAC3B,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,IAAI,CAAC,CAAS;IAC5B,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,GAAG,CAAC,CAAS;IAC3B,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,OAAO,CAAC,CAAS;IAC/B,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC"}