@neetru/cli 2.29.0 → 2.32.0

package/dist/cli-kit/command-context.js

@@ -0,0 +1,108 @@
+let atual = null;
+let raiz = null;
+/** Registra o comando que o Commander vai executar. */
+export function setCurrentCommand(cmd) {
+    atual = cmd;
+}
+/** O comando em execução, ou `null` fora do Commander. */
+export function getCurrentCommand() {
+    return atual;
+}
+/** Registra a raiz da árvore de comandos (o `program`). */
+export function setRootCommand(cmd) {
+    raiz = cmd;
+}
+/**
+ * A raiz da árvore de comandos: a do comando em execução, se houver; senão a
+ * registrada por `installCommandContext`; senão `null`.
+ */
+export function getRootCommand() {
+    if (atual) {
+        let c = atual;
+        while (c.parent)
+            c = c.parent;
+        return c;
+    }
+    return raiz;
+}
+/**
+ * Liga o contexto no programa raiz: guarda a raiz e, antes de cada `.action()`,
+ * o comando que vai rodar. Chamar uma vez, no entry-point.
+ */
+export function installCommandContext(program) {
+    setRootCommand(program);
+    program.hook('preAction', (_raiz, comandoDaAcao) => {
+        setCurrentCommand(comandoDaAcao);
+    });
+}
+/**
+ * O comando declara a flag (forma longa ou curta, inclusive alias oculto)?
+ * `false` sem comando — ver o cabeçalho.
+ */
+export function commandDeclaresFlag(cmd, flag) {
+    if (!cmd)
+        return false;
+    return cmd.options.some((o) => o.long === flag || o.short === flag);
+}
+/**
+ * O comando aceita esta entrada? Flag (`--server`, `-y`) ou argumento
+ * posicional escrito como no `.command()` (`<id>`, `[serverId]`, `<args...>`).
+ * `false` sem comando.
+ */
+export function commandDeclaresInput(cmd, input) {
+    if (!cmd)
+        return false;
+    if (input.startsWith('-'))
+        return commandDeclaresFlag(cmd, input);
+    const m = /^[<[]([^>\]]+?)(?:\.\.\.)?[>\]]$/.exec(input.trim());
+    if (!m)
+        return false;
+    return cmd.registeredArguments.some((a) => a.name() === m[1]);
+}
+/**
+ * Das flags pedidas, as que o comando declara — na ordem pedida. Base dos
+ * conselhos que oferecem mais de uma saída (`--yes (ou --force)`).
+ */
+export function declaredFlags(flags, cmd = getCurrentCommand()) {
+    return flags.filter((f) => commandDeclaresFlag(cmd, f));
+}
+/**
+ * Das entradas pedidas (flags ou `<posicional>`), as que o comando aceita —
+ * na ordem pedida.
+ */
+export function declaredInputs(inputs, cmd = getCurrentCommand()) {
+    return inputs.filter((i) => commandDeclaresInput(cmd, i));
+}
+/**
+ * O comando existe na árvore? `path` sem o `neetru` (ex.: `'auth mfa-session'`).
+ * Cada palavra casa com o nome ou um apelido de um subcomando. `false` sem
+ * árvore conhecida ou com caminho vazio.
+ */
+export function commandExists(path, root = getRootCommand()) {
+    if (!root)
+        return false;
+    const palavras = path.trim().split(/\s+/).filter(Boolean);
+    if (palavras.length === 0)
+        return false;
+    let no = root;
+    for (const p of palavras) {
+        const filho = no.commands.find((c) => c.name() === p || c.aliases().includes(p));
+        if (!filho)
+            return false;
+        no = filho;
+    }
+    return true;
+}
+/**
+ * Escolhe o conselho conforme o comando em execução declare ou não a flag.
+ * `withoutFlag` citar a flag seria bug de quem chamou — o teste de cada call
+ * site trava os dois textos, e a guarda estática confere todos os call sites.
+ */
+export function adviseFlag(advice, cmd = getCurrentCommand()) {
+    return commandDeclaresFlag(cmd, advice.flag) ? advice.withFlag : advice.withoutFlag;
+}
+/** Escolhe a dica conforme o comando citado exista ou não na árvore. */
+export function adviseCommand(advice, root = getRootCommand()) {
+    return commandExists(advice.command, root) ? advice.withCommand : advice.withoutCommand;
+}
+//# sourceMappingURL=command-context.js.map

package/dist/cli-kit/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Erro tipado da CLI (bug_89d2497e, etapa 3).
+ *
+ * Antes cada comando decidia sozinho como morrer: montava a mensagem à mão,
+ * escolhia um `safeExit(n)` e, em `--json`, um formato de payload. O modelo é o
+ * `FirebaseError` do firebase-tools (`lib/error.js`): o erro carrega o código
+ * de saída, a causa original e os filhos agregados — e quem imprime/encerra é
+ * um ponto só (`exitWithCliError`, em `src/lib/cli-error.ts`).
+ *
+ * Função pura: nada aqui imprime nem encerra o processo. O cli-kit continua sem
+ * dependência de logger/process — quem decide a saída é o call site.
+ */
+/**
+ * Convenção ÚNICA de códigos de saída (a mesma do `handleApiError` desde a
+ * auditoria de 2026-06-20 — ver `src/lib/api-error.ts`):
+ *   1 — erro do cliente (entrada/recurso: 400, 404, 409, 422, validação)
+ *   2 — não autenticado (401)
+ *   3 — sem permissão (403)
+ *   4 — erro do servidor (5xx), rede ou desconhecido
+ */
+export declare const EXIT_CODES: {
+    readonly client: 1;
+    readonly unauthenticated: 2;
+    readonly forbidden: 3;
+    readonly server: 4;
+};
+export interface NeetruCliErrorOptions {
+    /** Código de máquina — vira o campo `error` do JSON. Padrão: `'cli_error'`. */
+    code?: string;
+    /**
+     * Código de saída do processo. Padrão: o MAIS ALTO entre os filhos (a escala
+     * de `EXIT_CODES` cresce com a gravidade), senão `EXIT_CODES.client`.
+     */
+    exit?: number;
+    /** Erro original — preservado em `cause` (nunca engolido). */
+    cause?: unknown;
+    /** Falhas agregadas (ex.: itens de um lote que não passaram). */
+    children?: readonly NeetruCliError[];
+    /**
+     * Quantos itens do mesmo lote deram certo. Com filhos E sucessos, a falha é
+     * PARCIAL — e se reporta como parcial, não como "deu tudo errado" nem como
+     * "já existia" (bug_6e9fe576).
+     */
+    succeeded?: number;
+    /**
+     * Campos extras do JSON (`status`, `flag`, `valid`, …). Entram entre `error`
+     * e `message`, na ordem dada — preserva o formato que os comandos já emitiam.
+     */
+    details?: Readonly<Record<string, unknown>>;
+    /**
+     * Texto para humanos. Padrão: `message`. O JSON sempre leva `message` — o
+     * texto humano pode trazer prefixo e dica que não são contrato de máquina.
+     */
+    human?: string;
+}
+export declare class NeetruCliError extends Error {
+    readonly code: string;
+    readonly exit: number;
+    readonly children: readonly NeetruCliError[];
+    readonly succeeded: number;
+    readonly details: Readonly<Record<string, unknown>>;
+    readonly human: string;
+    constructor(message: string, opts?: NeetruCliErrorOptions);
+    /** Falha parcial: parte do lote falhou e parte deu certo. */
+    get partial(): boolean;
+    /**
+     * Payload `--json`. Sem filhos, é exatamente `{ ok:false, error, ...details,
+     * message }` — o formato que os comandos já emitiam. Com filhos, acrescenta
+     * `partial`, `succeeded`, `failed` e `children`.
+     */
+    toJSON(): Record<string, unknown>;
+    private corpoJson;
+}
+export declare function isNeetruCliError(x: unknown): x is NeetruCliError;
+/**
+ * Texto humano completo do erro, com os filhos indentados. Uma falha parcial
+ * diz que é parcial e quanto deu certo.
+ */
+export declare function renderCliError(error: NeetruCliError): string;

package/dist/cli-kit/errors.js

@@ -0,0 +1,94 @@
+/**
+ * Erro tipado da CLI (bug_89d2497e, etapa 3).
+ *
+ * Antes cada comando decidia sozinho como morrer: montava a mensagem à mão,
+ * escolhia um `safeExit(n)` e, em `--json`, um formato de payload. O modelo é o
+ * `FirebaseError` do firebase-tools (`lib/error.js`): o erro carrega o código
+ * de saída, a causa original e os filhos agregados — e quem imprime/encerra é
+ * um ponto só (`exitWithCliError`, em `src/lib/cli-error.ts`).
+ *
+ * Função pura: nada aqui imprime nem encerra o processo. O cli-kit continua sem
+ * dependência de logger/process — quem decide a saída é o call site.
+ */
+/**
+ * Convenção ÚNICA de códigos de saída (a mesma do `handleApiError` desde a
+ * auditoria de 2026-06-20 — ver `src/lib/api-error.ts`):
+ *   1 — erro do cliente (entrada/recurso: 400, 404, 409, 422, validação)
+ *   2 — não autenticado (401)
+ *   3 — sem permissão (403)
+ *   4 — erro do servidor (5xx), rede ou desconhecido
+ */
+export const EXIT_CODES = {
+    client: 1,
+    unauthenticated: 2,
+    forbidden: 3,
+    server: 4,
+};
+export class NeetruCliError extends Error {
+    code;
+    exit;
+    children;
+    succeeded;
+    details;
+    human;
+    constructor(message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = 'NeetruCliError';
+        this.code = opts.code ?? 'cli_error';
+        this.children = [...(opts.children ?? [])];
+        this.succeeded = Math.max(0, opts.succeeded ?? 0);
+        this.details = { ...(opts.details ?? {}) };
+        this.human = opts.human ?? message;
+        this.exit =
+            opts.exit ??
+                (this.children.length > 0
+                    ? Math.max(...this.children.map((c) => c.exit))
+                    : EXIT_CODES.client);
+    }
+    /** Falha parcial: parte do lote falhou e parte deu certo. */
+    get partial() {
+        return this.children.length > 0 && this.succeeded > 0;
+    }
+    /**
+     * Payload `--json`. Sem filhos, é exatamente `{ ok:false, error, ...details,
+     * message }` — o formato que os comandos já emitiam. Com filhos, acrescenta
+     * `partial`, `succeeded`, `failed` e `children`.
+     */
+    toJSON() {
+        return { ok: false, ...this.corpoJson() };
+    }
+    corpoJson() {
+        const base = {
+            error: this.code,
+            ...this.details,
+            message: this.message,
+        };
+        if (this.children.length === 0)
+            return base;
+        return {
+            ...base,
+            partial: this.partial,
+            succeeded: this.succeeded,
+            failed: this.children.length,
+            children: this.children.map((c) => c.corpoJson()),
+        };
+    }
+}
+export function isNeetruCliError(x) {
+    return x instanceof NeetruCliError;
+}
+/**
+ * Texto humano completo do erro, com os filhos indentados. Uma falha parcial
+ * diz que é parcial e quanto deu certo.
+ */
+export function renderCliError(error) {
+    if (error.children.length === 0)
+        return error.human;
+    const falhas = error.children.length;
+    const resumo = error.partial
+        ? `Falha parcial: ${falhas} de ${falhas + error.succeeded} itens falharam (${error.succeeded} deram certo).`
+        : `${falhas} ${falhas === 1 ? 'item falhou' : 'itens falharam'}.`;
+    const filhos = error.children.map((c) => `  - ${renderCliError(c).split('\n').join('\n    ')}`);
+    return [error.human, `  ${resumo}`, ...filhos].join('\n');
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli-kit/index.d.ts

@@ -11,3 +11,11 @@ export type { Glyphs } from './glyphs.js';
 export { ok, err, warn, dim, heading } from './palette.js';
 export { step, errorBlock, sacredPause, } from './format.js';
 export type { ErrorBlockOpts, SacredPauseOpts } from './format.js';
+export { EXIT_CODES, NeetruCliError, isNeetruCliError, renderCliError } from './errors.js';
+export type { NeetruCliErrorOptions } from './errors.js';
+export { invalidChoiceError, formatChoices } from './choices.js';
+export type { InvalidChoiceInput } from './choices.js';
+export { installCommandContext, setCurrentCommand, getCurrentCommand, setRootCommand, getRootCommand, commandDeclaresFlag, commandDeclaresInput, declaredFlags, declaredInputs, commandExists, adviseFlag, adviseCommand, } from './command-context.js';
+export type { FlagAdvice, CommandAdvice } from './command-context.js';
+export { SYNONYMS, MIN_RATIO, MAX_SUGGESTIONS, isSubcommandVerb, wordScore, scoreCandidates, suggestCommands, suggestSubcommands, reservedVerbError, } from './suggest.js';
+export type { ReservedVerbInput } from './suggest.js';

package/dist/cli-kit/index.js

@@ -9,4 +9,12 @@
 export { GLYPHS } from './glyphs.js';
 export { ok, err, warn, dim, heading } from './palette.js';
 export { step, errorBlock, sacredPause, } from './format.js';
+// Camada de CORREÇÃO (bug_89d2497e): erro tipado, conselho validado contra o
+// comando em execução e valores válidos de enum vindos da fonte real.
+export { EXIT_CODES, NeetruCliError, isNeetruCliError, renderCliError } from './errors.js';
+export { invalidChoiceError, formatChoices } from './choices.js';
+export { installCommandContext, setCurrentCommand, getCurrentCommand, setRootCommand, getRootCommand, commandDeclaresFlag, commandDeclaresInput, declaredFlags, declaredInputs, commandExists, adviseFlag, adviseCommand, } from './command-context.js';
+// P105: verbo de subcomando nunca é valor livre; sugestão com piso de qualidade
+// (SYNONYMS + MIN_RATIO, o `suggest_commands` do gcloud).
+export { SYNONYMS, MIN_RATIO, MAX_SUGGESTIONS, isSubcommandVerb, wordScore, scoreCandidates, suggestCommands, suggestSubcommands, reservedVerbError, } from './suggest.js';
 //# sourceMappingURL=index.js.map

package/dist/cli-kit/suggest.d.ts

@@ -0,0 +1,74 @@
+import { NeetruCliError } from './errors.js';
+/** Verbo digitado → verbo(s) que a CLI usa. */
+export declare const SYNONYMS: Readonly<Record<string, readonly string[]>>;
+/** Mínimo da razão pontuação/pontuação-do-primeiro para entrar na sugestão. */
+export declare const MIN_RATIO = 0.7;
+/** No máximo isto de sugestões. */
+export declare const MAX_SUGGESTIONS = 10;
+/**
+ * A palavra é, de fato, verbo de subcomando DESTE comando? Sim quando é um dos
+ * subcomandos dados (nome ou apelido) ou um sinônimo (`SYNONYMS`) de um deles.
+ * Sem diferenciar caixa, sem espaços nas pontas.
+ *
+ * Revisão do #87 (BAIXO 6): a 1ª versão recusava uma lista GLOBAL de verbos em
+ * qualquer texto livre, e `neetru chat send show` (resposta comum em PT-BR)
+ * passou a ser recusado sem que `show` fosse subcomando de `chat`. A recusa
+ * agora depende dos subcomandos de verdade de quem pergunta: para `chat send`,
+ * só `channels`, `identity`/`apelido`, `send` e `history`; para
+ * `chat identity`, os verbos dele (`show`, `set`, `clear`…) e seus sinônimos.
+ */
+export declare function isSubcommandVerb(word: string, subcommands: readonly string[]): boolean;
+/**
+ * Pontuação de uma palavra digitada contra uma palavra de um comando — o
+ * `_WordScore` do gcloud, linha a linha. Sempre ≥ 0; zero = sem relação.
+ */
+export declare function wordScore(index: number, word: string, canonical: string, canonicalLength: number): number;
+/**
+ * Candidatos pontuados, do maior para o menor (empate: ordem lexicográfica).
+ * Só entra quem pontua > 0. Cada candidato é a lista de palavras do comando.
+ */
+export declare function scoreCandidates(words: readonly string[], candidates: ReadonlyArray<readonly string[]>): Array<{
+    command: readonly string[];
+    score: number;
+}>;
+/**
+ * Comandos sugeridos para as palavras digitadas — o `GetCommandSuggestions`
+ * do gcloud: só quem pontua > 0 e faz pelo menos `MIN_RATIO` da pontuação do
+ * primeiro, no máximo `MAX_SUGGESTIONS`. Vazio quando nada pontua.
+ */
+export declare function suggestCommands(words: readonly string[], candidates: ReadonlyArray<readonly string[]>): string[];
+/**
+ * Sugestões para a palavra digitada, entre os subcomandos dados. Vazio quando
+ * nada passa o piso — aí quem chama lista as escolhas, nunca chuta.
+ */
+export declare function suggestSubcommands(word: string, subcommands: readonly string[]): string[];
+export interface ReservedVerbInput {
+    /** O verbo recebido como valor, como a pessoa digitou. */
+    verb: string;
+    /** O comando onde ele chegou, sem o `neetru` (ex.: `'chat identity'`). */
+    command: string;
+    /**
+     * O comando cujos subcomandos são sugeridos, sem o `neetru`. Padrão:
+     * `command`. Ex.: a palavra chega em `chat send`, e os subcomandos são de `chat`.
+     */
+    parent?: string;
+    /** O que o comando esperava naquela posição (ex.: `'um apelido'`). */
+    what: string;
+    /**
+     * Os subcomandos/verbos que o comando aceita — a MESMA lista que ele usa
+     * para decidir. Vazio = sem sugestão possível (só a recusa).
+     */
+    subcommands: readonly string[];
+    /** Apelido → nome do subcomando (ex.: `apelido → identity`): a sugestão vai direto ao nome. */
+    aliases?: Readonly<Record<string, string>>;
+    /** Como passar a mesma palavra como texto, quando existe jeito. */
+    escapeHint?: string;
+    /** Código do JSON. Padrão: `'uso_invalido'`. */
+    code?: string;
+}
+/**
+ * Recusa um verbo usado como valor e sugere o subcomando certo — ou, sem
+ * sugestão que passe o piso, lista as escolhas. Exit 1 (erro do cliente). No
+ * JSON: `value`, `suggestions` (comandos completos) e `valid`.
+ */
+export declare function reservedVerbError(input: ReservedVerbInput): NeetruCliError;

package/dist/cli-kit/suggest.js

@@ -0,0 +1,207 @@
+/**
+ * Verbo de subcomando nunca é valor livre, e sugestão só com piso de qualidade
+ * (P105 / bug_89d2497e; o caso que nasceu daqui foi o bug_09574d4b).
+ *
+ * O bug: `neetru chat identity show` GRAVOU o apelido "show", e
+ * `identity set "X"` gravou "set". O comando recebia texto livre posicional e
+ * aceitava qualquer palavra — inclusive o verbo que a pessoa usou achando que
+ * era subcomando. O gcloud não teria aceitado essa string: ele sabe quais
+ * palavras são verbos e, quando a palavra não é escolha válida, sugere o
+ * comando certo ou lista as escolhas — nunca adivinha lixo.
+ *
+ * O MODELO é o `calliope/suggest_commands.py` do gcloud (lido no SDK instalado
+ * nesta máquina, `google-cloud-sdk/lib/googlecloudsdk/calliope`):
+ *  - `SYNONYMS`: verbo digitado → verbo que a CLI de fato usa. O gcloud mapeia
+ *    para os verbos DELE (`show → describe`); aqui o mapa aponta para os nossos
+ *    (`describe → show`), e um verbo pode ter mais de um correspondente.
+ *  - `_WordScore`: só pontua quando uma palavra CONTÉM a outra, e só em começo
+ *    de palavra (ou depois de `-`). Sem relação de texto, a pontuação é zero e
+ *    o candidato some. É esse o piso absoluto: nada de distância de edição, que
+ *    acha "parecido" em qualquer par de palavras curtas.
+ *  - `MIN_RATIO = 0.7`: entre os que pontuam, só entra quem faz pelo menos 70%
+ *    da pontuação do primeiro. `MAX_SUGGESTIONS = 10`.
+ *  - O histórico de uso do usuário (`_GetSurfaceHistoryFrequencies`) NÃO foi
+ *    portado: a CLI não guarda histórico de comandos, e inventar um seria pior
+ *    que não ranquear por ele.
+ *
+ * Quando nada passa o piso, quem chama LISTA as escolhas válidas (o gcloud faz
+ * o mesmo em erro de argumento, `parser_extensions.py`) em vez de sugerir.
+ */
+import { formatChoices } from './choices.js';
+import { EXIT_CODES, NeetruCliError } from './errors.js';
+/** Verbo digitado → verbo(s) que a CLI usa. */
+export const SYNONYMS = {
+    describe: ['show', 'get'],
+    get: ['show', 'describe'],
+    show: ['describe', 'get'],
+    view: ['show'],
+    ver: ['show'],
+    list: ['show'],
+    update: ['set'],
+    modify: ['set', 'update'],
+    patch: ['set', 'update'],
+    change: ['set', 'update'],
+    definir: ['set'],
+    unset: ['clear'],
+    remove: ['clear', 'delete'],
+    delete: ['clear', 'remove'],
+    reset: ['clear'],
+    limpar: ['clear'],
+};
+/** Mínimo da razão pontuação/pontuação-do-primeiro para entrar na sugestão. */
+export const MIN_RATIO = 0.7;
+/** No máximo isto de sugestões. */
+export const MAX_SUGGESTIONS = 10;
+/**
+ * A palavra é, de fato, verbo de subcomando DESTE comando? Sim quando é um dos
+ * subcomandos dados (nome ou apelido) ou um sinônimo (`SYNONYMS`) de um deles.
+ * Sem diferenciar caixa, sem espaços nas pontas.
+ *
+ * Revisão do #87 (BAIXO 6): a 1ª versão recusava uma lista GLOBAL de verbos em
+ * qualquer texto livre, e `neetru chat send show` (resposta comum em PT-BR)
+ * passou a ser recusado sem que `show` fosse subcomando de `chat`. A recusa
+ * agora depende dos subcomandos de verdade de quem pergunta: para `chat send`,
+ * só `channels`, `identity`/`apelido`, `send` e `history`; para
+ * `chat identity`, os verbos dele (`show`, `set`, `clear`…) e seus sinônimos.
+ */
+export function isSubcommandVerb(word, subcommands) {
+    const w = word.trim().toLowerCase();
+    if (!w)
+        return false;
+    if (subcommands.includes(w))
+        return true;
+    return (SYNONYMS[w] ?? []).some((s) => subcommands.includes(s));
+}
+/**
+ * Pontuação de uma palavra digitada contra uma palavra de um comando — o
+ * `_WordScore` do gcloud, linha a linha. Sempre ≥ 0; zero = sem relação.
+ */
+export function wordScore(index, word, canonical, canonicalLength) {
+    if (!word || !canonical)
+        return 0;
+    let shorter;
+    let longer;
+    if (canonical.includes(word)) {
+        shorter = word;
+        longer = canonical;
+    }
+    else if (word.includes(canonical)) {
+        shorter = canonical;
+        longer = word;
+    }
+    else {
+        return 0;
+    }
+    // O acerto no meio precisa cair em fronteira de palavra.
+    const hit = longer.indexOf(shorter);
+    if (hit > 0 && longer[hit - 1] !== '-')
+        return 0;
+    let score = 10;
+    if (canonicalLength === 1)
+        score += 30;
+    else if (canonicalLength === 2)
+        score += 20;
+    else if (canonicalLength === 3)
+        score += 10;
+    if (index === 0)
+        score += 25;
+    else if (index === 1)
+        score += 15;
+    else
+        score += 5;
+    let extra = longer.length - shorter.length;
+    if (extra <= 2) {
+        extra = 3 - extra;
+        if (longer.startsWith(shorter))
+            extra *= 2;
+        score += extra;
+    }
+    if (index === 0 && canonicalLength > 1)
+        score += 30;
+    else if (index > 0 && canonicalLength > index + 1)
+        score += 15;
+    return score;
+}
+/**
+ * Candidatos pontuados, do maior para o menor (empate: ordem lexicográfica).
+ * Só entra quem pontua > 0. Cada candidato é a lista de palavras do comando.
+ */
+export function scoreCandidates(words, candidates) {
+    const normalizadas = words.map((w) => w.trim().toLowerCase().replace(/_/g, '-')).filter(Boolean);
+    const out = [];
+    for (const cand of candidates) {
+        const casadas = new Set();
+        let score = 0;
+        cand.forEach((canonica, index) => {
+            for (const w of normalizadas) {
+                let inc = wordScore(index, w, canonica, cand.length);
+                for (const alt of SYNONYMS[w] ?? []) {
+                    inc = Math.max(inc, wordScore(index, alt, canonica, cand.length));
+                }
+                if (inc) {
+                    casadas.add(w);
+                    score += inc;
+                }
+            }
+        });
+        if (normalizadas.length > 0 && casadas.size === normalizadas.length)
+            score += 10;
+        if (score > 0)
+            out.push({ command: cand, score });
+    }
+    out.sort((a, b) => b.score - a.score || a.command.join(' ').localeCompare(b.command.join(' ')));
+    return out;
+}
+/**
+ * Comandos sugeridos para as palavras digitadas — o `GetCommandSuggestions`
+ * do gcloud: só quem pontua > 0 e faz pelo menos `MIN_RATIO` da pontuação do
+ * primeiro, no máximo `MAX_SUGGESTIONS`. Vazio quando nada pontua.
+ */
+export function suggestCommands(words, candidates) {
+    const pontuados = scoreCandidates(words, candidates);
+    if (pontuados.length === 0)
+        return [];
+    const topo = pontuados[0].score;
+    return pontuados
+        .filter((p) => p.score / topo >= MIN_RATIO)
+        .slice(0, MAX_SUGGESTIONS)
+        .map((p) => p.command.join(' '));
+}
+/**
+ * Sugestões para a palavra digitada, entre os subcomandos dados. Vazio quando
+ * nada passa o piso — aí quem chama lista as escolhas, nunca chuta.
+ */
+export function suggestSubcommands(word, subcommands) {
+    return suggestCommands([word], subcommands.map((s) => [s]));
+}
+/**
+ * Recusa um verbo usado como valor e sugere o subcomando certo — ou, sem
+ * sugestão que passe o piso, lista as escolhas. Exit 1 (erro do cliente). No
+ * JSON: `value`, `suggestions` (comandos completos) e `valid`.
+ */
+export function reservedVerbError(input) {
+    const pai = input.parent ?? input.command;
+    const apelidoDe = input.aliases?.[input.verb.trim().toLowerCase()];
+    const sugestoes = (apelidoDe ? [apelidoDe] : suggestSubcommands(input.verb, input.subcommands)).map((s) => `neetru ${pai} ${s}`);
+    const linhas = [
+        `"${input.verb}" é palavra de comando da CLI e não vale como ${input.what} em \`neetru ${input.command}\`.`,
+    ];
+    if (sugestoes.length > 0) {
+        linhas.push(`Você quis dizer: ${sugestoes.map((s) => `\`${s}\``).join(' ou ')}?`);
+    }
+    else if (input.subcommands.length > 0) {
+        linhas.push(`Subcomandos de \`neetru ${pai}\`: ${formatChoices(input.subcommands)}.`);
+    }
+    if (input.escapeHint)
+        linhas.push(input.escapeHint);
+    return new NeetruCliError(linhas.join('\n  '), {
+        code: input.code ?? 'uso_invalido',
+        exit: EXIT_CODES.client,
+        details: {
+            value: input.verb,
+            suggestions: sugestoes,
+            valid: [...input.subcommands],
+        },
+    });
+}
+//# sourceMappingURL=suggest.js.map

package/dist/commands/admin/oidc-login.js

@@ -202,7 +202,7 @@ export async function runOidcLoginList(opts) {
     }
     log.heading(`Login-clients OIDC — produto ${opts.productId} (${res.count})`);
     renderTable([
-        { header: 'CLIENT ID', value: (r) => r.clientId, maxWidth: 38 },
+        { header: 'CLIENT ID', value: (r) => r.clientId, identificador: true },
         { header: 'NOME', value: (r) => r.name, maxWidth: 24 },
         { header: 'REDIRECT_URI', value: (r) => (r.redirectUris ?? []).join(', '), maxWidth: 44 },
         {

package/dist/commands/admin/sdk-credential.js

@@ -120,7 +120,7 @@ export async function runSdkCredentialList(opts) {
     }
     log.heading(`Credenciais OIDC — produto ${opts.productId} (${res.count})`);
     renderTable([
-        { header: 'CLIENT ID', value: (r) => r.clientId, maxWidth: 38 },
+        { header: 'CLIENT ID', value: (r) => r.clientId, identificador: true },
         { header: 'NOME', value: (r) => r.name, maxWidth: 28 },
         { header: 'ESCOPOS', value: (r) => r.allowedScopes.join(', '), maxWidth: 40 },
         {

package/dist/commands/autocomplete.d.ts

@@ -6,7 +6,7 @@ export type Shell = 'bash' | 'zsh' | 'pwsh';
  * IMPORTANTE: incluir TODOS os `program.command('X')` de `src/index.ts`.
  * O regression test `top-level-commands-coverage.test.ts` exige >=95%.
  */
-export declare const TOP_LEVEL_COMMANDS: readonly ["add", "admin", "agent", "ai", "api-catalog", "ar", "archive", "artifact-registry", "audit", "auth", "autocomplete", "billing", "bootstrap", "bug", "build", "builds", "cloud-run", "code", "config", "customers", "db", "db-hosts", "deploy", "deployments", "dev", "dns", "docs", "doctor", "dr", "env", "hosting", "init", "login", "logout", "logs", "menu", "mobile", "mocks", "new", "open", "ops", "products", "promote", "publish", "schema", "servers", "smoke", "status", "support", "tenants", "ui", "upgrade", "validate", "vm", "whoami", "workspaces"];
+export declare const TOP_LEVEL_COMMANDS: readonly ["add", "admin", "agent", "ai", "api-catalog", "ar", "archive", "artifact-registry", "audit", "auth", "autocomplete", "billing", "bootstrap", "bug", "build", "builds", "cloud-run", "code", "config", "customers", "db", "db-hosts", "deploy", "deployments", "dev", "dns", "docs", "doctor", "dr", "env", "hosting", "init", "login", "logout", "logs", "menu", "mobile", "mocks", "new", "open", "ops", "products", "promote", "publish", "schema", "secrets", "servers", "smoke", "status", "support", "tenants", "ui", "upgrade", "validate", "vm", "whoami", "workspaces"];
 export interface AutocompleteOptions {
     shell?: string;
 }

package/dist/commands/autocomplete.js

@@ -73,6 +73,7 @@ export const TOP_LEVEL_COMMANDS = [
     'promote',
     'publish',
     'schema', // neetru schema — inspecionar spec OpenAPI do Core
+    'secrets', // neetru secrets — segredos do próprio produto (set/list/archive)
     'servers',
     'smoke', // neetru smoke — percorre páginas do produto local antes do deploy
     'status',