@neetru/cli 2.29.0 → 2.32.0

package/dist/lib/envs.js

@@ -0,0 +1,127 @@
+import { formatChoices, invalidChoiceError } from '../cli-kit/choices.js';
+import { exitWithCliError } from './cli-error.js';
+/** Ambientes de tenant/workspace/deployment aceitos pelo Core. */
+export const TENANT_ENVIRONMENT_IDS = ['dev-local', 'staging', 'prod'];
+/**
+ * Padrão canônico. É `'dev-local'`, nunca `'dev'` — ver o cabeçalho do módulo.
+ */
+export const DEFAULT_TENANT_ENVIRONMENT_ID = 'dev-local';
+/**
+ * Apelidos históricos tolerados na entrada do usuário. Existem só para que
+ * scripts e dedos-na-memória que escrevem `--env dev` continuem funcionando
+ * em vez de tomar 400 do Core — a saída é sempre o token canônico.
+ */
+const APELIDOS = {
+    dev: 'dev-local',
+    devlocal: 'dev-local',
+    'dev-local': 'dev-local',
+    local: 'dev-local',
+    stage: 'staging',
+    staging: 'staging',
+    prod: 'prod',
+    producao: 'prod',
+    production: 'prod',
+};
+/** Lista legível para mensagens de erro e textos de ajuda. */
+export function listarAmbientesTenant() {
+    return formatChoices(TENANT_ENVIRONMENT_IDS);
+}
+/**
+ * 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 function normalizarAmbienteTenant(bruto) {
+    if (bruto === undefined || bruto === null)
+        return null;
+    const chave = String(bruto).trim().toLowerCase();
+    if (!chave)
+        return null;
+    return APELIDOS[chave] ?? 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 const ESCOLHAS_AMBIENTE_TENANT = TENANT_ENVIRONMENT_IDS.map((value) => ({
+    name: value === DEFAULT_TENANT_ENVIRONMENT_ID ? `${value} (padrão — sua máquina)` : value,
+    value,
+}));
+/**
+ * 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 const VOCABULARIOS_DE_AMBIENTE = {
+    'dev-local': { deploy: 'dev', runtime: 'dev' },
+    staging: { deploy: 'staging', runtime: 'workspace' },
+    prod: { deploy: 'prod', runtime: 'prod' },
+};
+/** `dev | staging | prod` — o `--env` do `neetru deploy`, na ordem de promoção. */
+export const DEPLOY_ENVIRONMENT_IDS = TENANT_ENVIRONMENT_IDS.map((id) => VOCABULARIOS_DE_AMBIENTE[id].deploy);
+/** `dev | workspace | prod` — o `NEETRU_ENV` do SDK, na ordem de promoção. */
+export const RUNTIME_ENVIRONMENT_IDS = TENANT_ENVIRONMENT_IDS.map((id) => VOCABULARIOS_DE_AMBIENTE[id].runtime);
+/**
+ * `--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 function deployEnvParaRuntime(env) {
+    const id = TENANT_ENVIRONMENT_IDS.find((t) => VOCABULARIOS_DE_AMBIENTE[t].deploy === env);
+    return id ? VOCABULARIOS_DE_AMBIENTE[id].runtime : 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 function erroAmbienteTenantInvalido(bruto) {
+    return invalidChoiceError({
+        flag: '--env',
+        value: bruto,
+        valid: TENANT_ENVIRONMENT_IDS,
+        subject: 'Ambiente',
+        code: 'invalid_environment',
+        hint: 'Dica: o ambiente de desenvolvimento chama-se "dev-local" (não "dev").',
+    });
+}
+/**
+ * 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 function mensagemAmbienteInvalido(bruto) {
+    return erroAmbienteTenantInvalido(bruto).message;
+}
+/**
+ * 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 function resolverAmbienteTenant(bruto, json) {
+    const canonico = normalizarAmbienteTenant(bruto);
+    if (canonico) {
+        // Mesma convenção de `normalizeEnv` em src/lib/db-local/env.ts: traduzir o
+        // apelido em silêncio faria o dev continuar escrevendo "dev" pra sempre.
+        // Vai pro stderr de propósito — o stdout em `--json` é contrato de máquina.
+        if (bruto.trim().toLowerCase() !== canonico) {
+            process.stderr.write(`Aviso: ambiente "${bruto}" é um apelido — o nome canônico é "${canonico}". ` +
+                `Atualize seus scripts e config para usar "${canonico}" diretamente.\n`);
+        }
+        return canonico;
+    }
+    return exitWithCliError(erroAmbienteTenantInvalido(bruto), json);
+}
+//# sourceMappingURL=envs.js.map

package/dist/lib/fs-seguro.d.ts

@@ -0,0 +1,63 @@
+/**
+ * fs-seguro — apagar DE VERDADE com caminho não-ASCII, e conferir.
+ *
+ * POR QUE (reproduzido no Node 24.13, Windows, página ANSI 1252, 2026-10-13):
+ * algumas APIs síncronas do `fs`, reescritas em C++, leem o caminho na página
+ * ANSI em vez de UTF-8. Com acento (NFC ou NFD) ou fora do cp1252 (`日本`):
+ *
+ *   - `fs.rmSync(arquivo)` volta SEM ERRO e não apaga, com ou sem `force`;
+ *   - `fs.rmSync(dir, { recursive })` não apaga, inclusive quando o acento está
+ *     só num diretório acima (`C:\Users\João\AppData\Local\Temp\...`);
+ *   - com um `ação.txt` na mesma pasta, `rmSync('ação.txt')` apaga o
+ *     `ação.txt`, o arquivo ERRADO;
+ *   - `fs.rmdirSync(dir, { recursive: true })` não apaga;
+ *   - `fs.cpSync(dirAcentuado, ...)` MATA o processo calado (exit 127, sem
+ *     stdout nem stderr) e cria o destino em mojibake.
+ *
+ * A CLI roda na máquina do dev: uma home com acento (`C:\Users\João`) põe o
+ * `%TEMP%` e o projeto inteiro nesse caminho.
+ *
+ * O QUE FUNCIONA (testado com NFC, NFD, `日本`, arquivo somente-leitura e
+ * junction em `fs-seguro.test.ts`): `unlinkSync` e `fs.promises.rm`. Mesmo
+ * assim, os dois helpers abaixo CONFEREM que o caminho sumiu e LANÇAM se não
+ * sumiu: "apagou" foi justamente a mentira, e remoção que não aconteceu não
+ * pode ser relatada como feita.
+ *
+ * `rmSync`, `rmdirSync` e `cpSync` estão proibidos no repo inteiro pela guarda
+ * `src/__tests__/regressions/fs-sync-acento.regression.test.ts`.
+ */
+import * as fs from 'node:fs';
+/** Dependências injetáveis só para teste. */
+export interface OpcoesRemoverArquivo {
+    unlink?: (caminho: string) => void;
+}
+/**
+ * Apaga UM arquivo (ou link) e confere que ele sumiu; se não sumiu, LANÇA.
+ *
+ * Caminho inexistente não é erro (como o `force: true` do `rmSync`). Diretório
+ * de verdade é recusado: use `removerDiretorio`.
+ */
+export declare function removerArquivo(caminho: string, { unlink }?: OpcoesRemoverArquivo): void;
+/** Dependências injetáveis só para teste. */
+export interface OpcoesRemoverDiretorio {
+    rm?: (caminho: string, opcoes: fs.RmOptions) => Promise<void>;
+}
+/**
+ * Apaga um diretório com tudo dentro (ou um arquivo) e confere que o caminho
+ * sumiu; se não sumiu, LANÇA.
+ *
+ * Caminho inexistente não é erro. Não segue link nem junction: apaga o link,
+ * e o alvo fica intacto. `maxRetries` cobre o EBUSY/EPERM passageiro do
+ * Windows (antivírus, indexador).
+ */
+export declare function removerDiretorio(caminho: string, { rm }?: OpcoesRemoverDiretorio): Promise<void>;
+/**
+ * Avisa no stderr que um temporário NÃO foi apagado, com o caminho e o motivo.
+ * Nunca lança.
+ *
+ * Para limpeza best-effort, em que a falha não pode derrubar o resultado nem
+ * esconder o erro original, mas também não pode sumir calada: o temporário
+ * que sobra (`neetru-drizzle-*`, `*.tmp-*`) é o sintoma que o `fs-seguro`
+ * existe para evitar. Vai pro stderr para não sujar a saída `--json` no stdout.
+ */
+export declare function avisarSobraDeTemporario(caminho: string, motivo: unknown, escrever?: (texto: string) => unknown): void;

package/dist/lib/fs-seguro.js

@@ -0,0 +1,108 @@
+/**
+ * fs-seguro — apagar DE VERDADE com caminho não-ASCII, e conferir.
+ *
+ * POR QUE (reproduzido no Node 24.13, Windows, página ANSI 1252, 2026-10-13):
+ * algumas APIs síncronas do `fs`, reescritas em C++, leem o caminho na página
+ * ANSI em vez de UTF-8. Com acento (NFC ou NFD) ou fora do cp1252 (`日本`):
+ *
+ *   - `fs.rmSync(arquivo)` volta SEM ERRO e não apaga, com ou sem `force`;
+ *   - `fs.rmSync(dir, { recursive })` não apaga, inclusive quando o acento está
+ *     só num diretório acima (`C:\Users\João\AppData\Local\Temp\...`);
+ *   - com um `ação.txt` na mesma pasta, `rmSync('ação.txt')` apaga o
+ *     `ação.txt`, o arquivo ERRADO;
+ *   - `fs.rmdirSync(dir, { recursive: true })` não apaga;
+ *   - `fs.cpSync(dirAcentuado, ...)` MATA o processo calado (exit 127, sem
+ *     stdout nem stderr) e cria o destino em mojibake.
+ *
+ * A CLI roda na máquina do dev: uma home com acento (`C:\Users\João`) põe o
+ * `%TEMP%` e o projeto inteiro nesse caminho.
+ *
+ * O QUE FUNCIONA (testado com NFC, NFD, `日本`, arquivo somente-leitura e
+ * junction em `fs-seguro.test.ts`): `unlinkSync` e `fs.promises.rm`. Mesmo
+ * assim, os dois helpers abaixo CONFEREM que o caminho sumiu e LANÇAM se não
+ * sumiu: "apagou" foi justamente a mentira, e remoção que não aconteceu não
+ * pode ser relatada como feita.
+ *
+ * `rmSync`, `rmdirSync` e `cpSync` estão proibidos no repo inteiro pela guarda
+ * `src/__tests__/regressions/fs-sync-acento.regression.test.ts`.
+ */
+import * as fs from 'node:fs';
+/** Diz se ALGO (arquivo, diretório ou link, mesmo quebrado) ainda ocupa o caminho. */
+function aindaExiste(caminho) {
+    try {
+        fs.lstatSync(caminho);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw err;
+    }
+}
+function naoApagou(caminho, tipo) {
+    return new Error(`não consegui apagar o ${tipo} "${caminho}": a remoção voltou sem erro, mas ele continua lá`);
+}
+/**
+ * Apaga UM arquivo (ou link) e confere que ele sumiu; se não sumiu, LANÇA.
+ *
+ * Caminho inexistente não é erro (como o `force: true` do `rmSync`). Diretório
+ * de verdade é recusado: use `removerDiretorio`.
+ */
+export function removerArquivo(caminho, { unlink = fs.unlinkSync } = {}) {
+    let st;
+    try {
+        st = fs.lstatSync(caminho);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return;
+        throw err;
+    }
+    if (st.isDirectory()) {
+        throw new Error(`"${caminho}" é um diretório; use removerDiretorio`);
+    }
+    try {
+        unlink(caminho);
+    }
+    catch (err) {
+        // Sumiu entre o lstat e o unlink: o objetivo foi atingido.
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    if (aindaExiste(caminho))
+        throw naoApagou(caminho, 'arquivo');
+}
+/**
+ * Apaga um diretório com tudo dentro (ou um arquivo) e confere que o caminho
+ * sumiu; se não sumiu, LANÇA.
+ *
+ * Caminho inexistente não é erro. Não segue link nem junction: apaga o link,
+ * e o alvo fica intacto. `maxRetries` cobre o EBUSY/EPERM passageiro do
+ * Windows (antivírus, indexador).
+ */
+export async function removerDiretorio(caminho, { rm = fs.promises.rm } = {}) {
+    await rm(caminho, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    if (aindaExiste(caminho))
+        throw naoApagou(caminho, 'diretório');
+}
+/**
+ * Avisa no stderr que um temporário NÃO foi apagado, com o caminho e o motivo.
+ * Nunca lança.
+ *
+ * Para limpeza best-effort, em que a falha não pode derrubar o resultado nem
+ * esconder o erro original, mas também não pode sumir calada: o temporário
+ * que sobra (`neetru-drizzle-*`, `*.tmp-*`) é o sintoma que o `fs-seguro`
+ * existe para evitar. Vai pro stderr para não sujar a saída `--json` no stdout.
+ */
+export function avisarSobraDeTemporario(caminho, motivo, escrever = (texto) => process.stderr.write(texto)) {
+    const msg = motivo instanceof Error ? motivo.message : String(motivo);
+    try {
+        escrever(`aviso: o temporário "${caminho}" não foi apagado (${msg}). Pode apagar à mão.\n`);
+    }
+    catch {
+        /* avisar não pode virar outro erro */
+    }
+}
+//# sourceMappingURL=fs-seguro.js.map

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

@@ -11,6 +11,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { avisarSobraDeTemporario, removerArquivo } from '../fs-seguro.js';
 /** Registry v1 vazio — usado quando o arquivo ainda não existe. */
 function emptyMobileJson() {
     return { version: 1, apps: [] };
@@ -147,12 +148,17 @@ export function writeMobileJson(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/pickers.d.ts

@@ -3,16 +3,42 @@ export interface InteractivityOptions {
     nonInteractive?: boolean;
 }
 export declare function isInteractive(opts?: InteractivityOptions): boolean;
-interface ResolveOptions<T> extends InteractivityOptions {
+/**
+ * Como o comando em execução recebe o valor que o picker escolhe: flags
+ * (`--server`) e/ou posicional como no `.command()` (`<serverId>`). O picker
+ * cita só o que o comando declara (P105 / bug_89d2497e).
+ */
+export interface PickerInputOptions {
+    inputs?: readonly string[];
+}
+interface ResolveOptions<T> extends InteractivityOptions, PickerInputOptions {
     fromFlag?: string;
     fetcher: () => Promise<T[]>;
     format: (item: T) => string;
     getId: (item: T) => string;
     message: string;
     emptyError: string;
+    /** A entrada padrão do picker — usada quando `inputs` não vem. */
     flagName: string;
+    /** O que está sendo escolhido, para a frase sem flag (ex.: `'o produto'`). */
+    subject?: string;
     allowManual?: boolean;
 }
+/**
+ * A entrada que o conselho pode citar, já validada contra o comando em
+ * execução: `'--tenant'`, `'<id>'`, `'<serverId> ou --server'`… — ou `null`
+ * quando o comando não declara nenhuma das candidatas (ou não há comando).
+ *
+ * P105: o texto fixo citava a entrada padrão do picker. Medido na árvore do
+ * Commander em 2026-10-18, ela não existia em 10 comandos: `tenants get|
+ * update|suspend|reactivate` (recebem `[id]`, não `--tenant`), `servers
+ * deactivate|dispatch` (`[serverId]`, não `--server`), `products publish|
+ * unpublish` (`[slug]`, não `--product`) e `admin database create`/`products
+ * db create` (`--product-id`/`--server-id`, não `--product`/`--server`).
+ */
+export declare function entradaDoPicker(opts: {
+    flagName: string;
+} & PickerInputOptions): string | null;
 export declare function resolveOrPick<T>(opts: ResolveOptions<T>): Promise<string>;
 export declare function promptText(message: string, opts?: InteractivityOptions & {
     default?: string;
@@ -25,6 +51,17 @@ export declare function promptChoice<T extends string>(message: string, choices:
 }>, opts?: InteractivityOptions & {
     default?: T;
 }): Promise<T>;
+/**
+ * Versão só-slug da heurística abaixo, para quando o produto AINDA NÃO existe
+ * no Core — caso do `neetru new`, que precisa decidir o customer antes de
+ * criar qualquer coisa.
+ *
+ * bug_7dcb68e2666a43f69ef362d2cbff94ed: como a lista de fallback tem apenas
+ * dois slugs, todo produto novo cai no caminho "não é Neetru-owned", que é
+ * justamente o caminho em que o Core exige `--customer`. O ponto é avisar
+ * ANTES, e não quebrar no passo [2/5] com o produto já criado.
+ */
+export declare function isNeetruOwnedSlug(slug: string | null | undefined): boolean;
 /**
  * Verifica (via GET /api/cli/v1/products/{id}) se um produto é Neetru-owned.
  * Usa heurísticas de cliente: ownedBy==='neetru' | ownerTeam==='Neetru Core' | slug fallback.
@@ -100,7 +137,7 @@ export declare function listProductDatabases(token: string, filters?: {
     status?: string;
 }): Promise<ProductDatabaseSummary[]>;
 export declare function productLabel(product: ProductSummary): string;
-export declare function pickProductId(token: string, opts?: InteractivityOptions & {
+export declare function pickProductId(token: string, opts?: InteractivityOptions & PickerInputOptions & {
     fromFlag?: string;
     message?: string;
 }): Promise<string>;
@@ -116,29 +153,29 @@ export declare function pickProductId(token: string, opts?: InteractivityOptions
  * `--product qkcWzQ43LthAIRlVUSQ6` em qualquer comando que aceite produto.
  */
 export declare function resolveProductIdentifier(token: string, input: string, opts?: InteractivityOptions): Promise<string>;
-export declare function pickProductSlug(token: string, opts?: InteractivityOptions & {
+export declare function pickProductSlug(token: string, opts?: InteractivityOptions & PickerInputOptions & {
     fromFlag?: string;
     message?: string;
 }): Promise<string>;
-export declare function pickTenant(token: string, opts?: InteractivityOptions & {
+export declare function pickTenant(token: string, opts?: InteractivityOptions & PickerInputOptions & {
     fromFlag?: string;
     product?: string;
     status?: string;
     message?: string;
 }): Promise<string>;
-export declare function pickWorkspace(token: string, opts?: InteractivityOptions & {
+export declare function pickWorkspace(token: string, opts?: InteractivityOptions & PickerInputOptions & {
     fromFlag?: string;
     product?: string;
     status?: string;
     message?: string;
 }): Promise<string>;
-export declare function pickServer(token: string, opts?: InteractivityOptions & {
+export declare function pickServer(token: string, opts?: InteractivityOptions & PickerInputOptions & {
     fromFlag?: string;
     status?: string;
     capacity?: boolean;
     message?: string;
 }): Promise<string>;
-export declare function pickDatabase(token: string, opts?: InteractivityOptions & {
+export declare function pickDatabase(token: string, opts?: InteractivityOptions & PickerInputOptions & {
     fromFlag?: string;
     productId?: string;
     engine?: string;

package/dist/lib/pickers.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { apiRequest } from './api-client.js';
 import { handleApiError } from './api-error.js';
+import { adviseCommand, declaredInputs } from '../cli-kit/command-context.js';
 import { log } from '../utils/logger.js';
 import { safeExit } from '../utils/safe-exit.js';
 export function isInteractive(opts = {}) {
@@ -26,12 +27,32 @@ function failLookup(error, json) {
     // →2) divergentes dos comandos, contribuindo pro conflito que quebrava CI.
     return handleApiError(error, json);
 }
+/**
+ * A entrada que o conselho pode citar, já validada contra o comando em
+ * execução: `'--tenant'`, `'<id>'`, `'<serverId> ou --server'`… — ou `null`
+ * quando o comando não declara nenhuma das candidatas (ou não há comando).
+ *
+ * P105: o texto fixo citava a entrada padrão do picker. Medido na árvore do
+ * Commander em 2026-10-18, ela não existia em 10 comandos: `tenants get|
+ * update|suspend|reactivate` (recebem `[id]`, não `--tenant`), `servers
+ * deactivate|dispatch` (`[serverId]`, não `--server`), `products publish|
+ * unpublish` (`[slug]`, não `--product`) e `admin database create`/`products
+ * db create` (`--product-id`/`--server-id`, não `--product`/`--server`).
+ */
+export function entradaDoPicker(opts) {
+    const declaradas = declaredInputs(opts.inputs ?? [opts.flagName]);
+    return declaradas.length > 0 ? declaradas.join(' ou ') : null;
+}
 export async function resolveOrPick(opts) {
     const flagged = opts.fromFlag?.trim();
     if (flagged)
         return flagged;
+    const entrada = entradaDoPicker(opts);
+    const sujeito = opts.subject ?? 'o valor';
     if (opts.json) {
-        failInput(`${opts.flagName} e obrigatorio em modo --json.`, true);
+        failInput(entrada
+            ? `${entrada} e obrigatorio em modo --json.`
+            : `Este comando precisa escolher ${sujeito} e, em modo --json, não há como perguntar qual.`, true);
     }
     let items;
     try {
@@ -50,7 +71,10 @@ export async function resolveOrPick(opts) {
         const available = items
             .map((item) => `  - ${opts.getId(item)}: ${stripAnsi(opts.format(item))}`)
             .join('\n');
-        failInput(`Multiplos candidatos encontrados. Passe ${opts.flagName} explicitamente.\nDisponiveis:\n${available}`, opts.json);
+        failInput(entrada
+            ? `Multiplos candidatos encontrados. Passe ${entrada} explicitamente.\nDisponiveis:\n${available}`
+            : `Múltiplos candidatos encontrados, e este comando não recebe ${sujeito} por argumento: ` +
+                `rode num terminal interativo para escolher.\nDisponiveis:\n${available}`, opts.json);
     }
     const choices = items.map((item) => ({
         name: opts.format(item),
@@ -122,6 +146,21 @@ export async function promptChoice(message, choices, opts = {}) {
 // Slugs Neetru-owned conhecidos no cliente CLI (espelho do fallback server-side).
 // Atualizar junto com NEETRU_PRODUCT_SLUGS_FALLBACK em resolve-default.ts.
 const NEETRU_SLUGS_CLI = ['gestovendas', 'pdv-agiliza'];
+/**
+ * Versão só-slug da heurística abaixo, para quando o produto AINDA NÃO existe
+ * no Core — caso do `neetru new`, que precisa decidir o customer antes de
+ * criar qualquer coisa.
+ *
+ * bug_7dcb68e2666a43f69ef362d2cbff94ed: como a lista de fallback tem apenas
+ * dois slugs, todo produto novo cai no caminho "não é Neetru-owned", que é
+ * justamente o caminho em que o Core exige `--customer`. O ponto é avisar
+ * ANTES, e não quebrar no passo [2/5] com o produto já criado.
+ */
+export function isNeetruOwnedSlug(slug) {
+    if (!slug)
+        return false;
+    return NEETRU_SLUGS_CLI.includes(slug.trim().toLowerCase());
+}
 /**
  * Verifica (via GET /api/cli/v1/products/{id}) se um produto é Neetru-owned.
  * Usa heurísticas de cliente: ownedBy==='neetru' | ownerTeam==='Neetru Core' | slug fallback.
@@ -220,6 +259,17 @@ export function productLabel(product) {
     const team = product.ownerTeam ? chalk.dim(`- ${product.ownerTeam}`) : '';
     return compact([statusDot(product.status), chalk.bold(name), slug, status, team]).join(' ');
 }
+/**
+ * "Nenhum produto": a dica de criar só cita `neetru products create` se o
+ * comando existe na árvore (P105).
+ */
+function semProdutoAinda() {
+    return adviseCommand({
+        command: 'products create',
+        withCommand: 'Nenhum produto encontrado. Crie com: neetru products create',
+        withoutCommand: 'Nenhum produto encontrado.',
+    });
+}
 export async function pickProductId(token, opts = {}) {
     return resolveOrPick({
         ...opts,
@@ -227,8 +277,9 @@ export async function pickProductId(token, opts = {}) {
         format: productLabel,
         getId: (product) => product.id,
         message: opts.message ?? 'Escolha o produto:',
-        emptyError: 'Nenhum produto encontrado. Crie com: neetru products create',
+        emptyError: semProdutoAinda(),
         flagName: '--product',
+        subject: 'o produto',
     });
 }
 /**
@@ -272,8 +323,9 @@ export async function pickProductSlug(token, opts = {}) {
         format: productLabel,
         getId: (product) => product.slug ?? product.id,
         message: opts.message ?? 'Escolha o produto:',
-        emptyError: 'Nenhum produto encontrado. Crie com: neetru products create',
+        emptyError: semProdutoAinda(),
         flagName: '--product',
+        subject: 'o produto',
     });
 }
 export async function pickTenant(token, opts = {}) {
@@ -285,6 +337,7 @@ export async function pickTenant(token, opts = {}) {
         message: opts.message ?? 'Escolha o tenant:',
         emptyError: 'Nenhum tenant encontrado no escopo atual.',
         flagName: '--tenant',
+        subject: 'o tenant',
     });
 }
 export async function pickWorkspace(token, opts = {}) {
@@ -296,6 +349,7 @@ export async function pickWorkspace(token, opts = {}) {
         message: opts.message ?? 'Escolha o workspace:',
         emptyError: 'Nenhum workspace encontrado no escopo atual.',
         flagName: '<workspaceId>',
+        subject: 'o workspace',
     });
 }
 export async function pickServer(token, opts = {}) {
@@ -307,6 +361,7 @@ export async function pickServer(token, opts = {}) {
         message: opts.message ?? 'Escolha o server:',
         emptyError: 'Nenhum server encontrado no escopo atual.',
         flagName: '--server',
+        subject: 'o server',
     });
 }
 export async function pickDatabase(token, opts = {}) {
@@ -322,6 +377,7 @@ export async function pickDatabase(token, opts = {}) {
         message: opts.message ?? 'Escolha o banco:',
         emptyError: 'Nenhum banco encontrado no escopo atual.',
         flagName: '<id>',
+        subject: 'o banco',
     });
 }
 function workspaceLabel(workspace) {

package/dist/lib/product-docs/check.d.ts

@@ -0,0 +1,62 @@
+import { type DocsTaxonomy } from './taxonomy.js';
+import { type ProductRepo } from './config.js';
+export type Level = 'erro' | 'aviso' | 'sugestao';
+export interface Finding {
+    /** Caminho relativo à raiz do repositório, com `/`. */
+    file: string;
+    line?: number;
+    code: string;
+    level: Level;
+    message: string;
+}
+export interface FileContext {
+    taxonomy: DocsTaxonomy;
+    slug: string;
+    /** Caminho relativo à raiz do repo da pasta de docs (ex.: `docs`). */
+    docsRoot: string;
+    /** Existe este caminho (relativo à raiz do repo)? */
+    exists: (repoRel: string) => boolean;
+    legacyNames: Set<string>;
+    /** AAAA-MM-DD de hoje (injetável em teste). */
+    today: string;
+    /** O arquivo foi alterado na branch (LK001 vira erro). */
+    changed: boolean;
+}
+/** Valida UM doc. `relInDocs` é relativo à pasta de docs, com `/`. Função pura. */
+export declare function checkDocFile(relInDocs: string, raw: string, ctx: FileContext): Finding[];
+export interface CheckOptions {
+    /** Só os arquivos alterados contra a branch principal (catraca). */
+    changed?: boolean;
+    /** Aviso vira erro. */
+    strict?: boolean;
+    taxonomy: DocsTaxonomy;
+    today?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    findings: Finding[];
+    counts: {
+        erro: number;
+        aviso: number;
+        sugestao: number;
+    };
+    filesChecked: number;
+    docsRoot: string;
+    changedBase?: string;
+    /** --changed pedido mas o git não respondeu: checou tudo. */
+    changedFallback?: boolean;
+}
+/** Lista os `.md` da pasta de docs (relativos a ela, com `/`). */
+export declare function listDocFiles(repo: ProductRepo): Promise<string[]>;
+/** Lê `docs/_nomes-legados.json` (array ou `{ arquivos: [...] }`). */
+export declare function readLegacyNames(repo: ProductRepo): Set<string>;
+/** Hoje no fuso dos docs (America/Sao_Paulo ou NEETRU_TZ) — nunca UTC. */
+export { todayIso } from './dates.js';
+/** Checagens do repositório inteiro: mínimo do primeiro dia (PR002), README, CHANGELOG (PR004). */
+export declare function checkRepoLevel(repo: ProductRepo): Finding[];
+export declare function summarize(findings: Finding[], strict: boolean): {
+    ok: boolean;
+    counts: CheckResult['counts'];
+};
+/** Roda o validador no repositório do produto. Nunca lança por conteúdo de doc. */
+export declare function checkProductDocs(repo: ProductRepo, opts: CheckOptions): Promise<CheckResult>;