@neetru/cli 2.32.1 → 2.34.0

package/dist/commands/environments-repoint.d.ts

@@ -0,0 +1,49 @@
+import { type TenantEnvironmentId } from '../lib/envs.js';
+/** Ambientes que dá pra re-apontar: os do Core menos o dev-local (roda na máquina do dev). */
+export type RepointEnvironment = Exclude<TenantEnvironmentId, 'dev-local'>;
+export declare const REPOINT_ENVIRONMENTS: readonly RepointEnvironment[];
+export interface RepointCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface RepointResponse {
+    ok: true;
+    productId: string;
+    slug: string | null;
+    dryRun: boolean;
+    changed: boolean;
+    alreadyPointed: boolean;
+    env: RepointEnvironment;
+    from: string | null;
+    to: string;
+    preflight: {
+        ok: boolean;
+        checks: RepointCheck[];
+    };
+    appMoved: false;
+    pendingDrain: string[];
+    auditId: string | null;
+    nextStep: string;
+}
+/** Nome legível de cada requisito do `--dry-run` (o Core manda o nome técnico). */
+export declare const REPOINT_CHECK_LABELS: Record<string, string>;
+/** Rótulo de um requisito (os de banco vêm como `database:<dbId>`). */
+export declare function checkLabel(name: string): string;
+/**
+ * O que fazer para cada código `REPOINT_*` que a rota devolve. A mensagem do
+ * Core (com VMs, bancos e o motivo) vem antes; isto é o "e agora?".
+ */
+export declare const REPOINT_GUIDANCE: Record<string, string>;
+/** Mensagem do Core primeiro (dados reais), depois o que fazer. Pura. */
+export declare function describeRepointError(code: string, serverMessage: string): string;
+export interface EnvironmentsRepointOptions {
+    to?: string;
+    expectFrom?: string;
+    reason?: string;
+    dryRun?: boolean;
+    yes?: boolean;
+    mfaToken?: string;
+    json?: boolean;
+}
+export declare function runEnvironmentsRepoint(slug: string, env: string, opts?: EnvironmentsRepointOptions): Promise<void>;

package/dist/commands/environments-repoint.js

@@ -0,0 +1,219 @@
+/**
+ * `neetru environments repoint <slug> <env> --to <serverId> --expect-from <serverId> --reason "<motivo>"`
+ * — RE-APONTA o ambiente (`staging` | `prod`) de um produto para outra VM
+ * (Core bug_7446f7f2).
+ *
+ * Antes não havia comando para isso: só um PATCH manual no Firestore pelo Dev
+ * Core, e o go-live de um produto travava quando ele estava fora.
+ *
+ * O que muda: SÓ o ponteiro do ambiente (a VM que o ambiente aponta). O app NÃO
+ * muda de VM: o próximo `neetru deploy --target vm --env <env> --server <id>`
+ * é que leva o app, acerta a porta e o domínio. A promoção de staging para prod
+ * passa a usar a VM apontada. A VM antiga continua rodando o que estava lá e
+ * fica contada como ocupada por este ambiente.
+ *
+ * `--dry-run` confere os requisitos sem gravar e sem MFA. Fora dele: admin +
+ * MFA (`--mfa-token` ou a sessão de 1h de `neetru auth mfa-session`; sessão
+ * recusada pelo Core ⇒ pede um TOTP fresco UMA vez).
+ *
+ * Endpoint (Core): POST /api/cli/v1/products/{slug}/environments/{env}/server
+ *   body `{ toServerId, expectedServerId, reason, dryRun? }`.
+ *
+ * Plain PT-BR em toda string visível ao usuário. O grupo `neetru env` é do
+ * NEETRU_ENV local e das variáveis do Cloud Run — por isso o nome `environments`.
+ */
+import chalk from 'chalk';
+import { apiRequest, CliApiError } from '../lib/api-client.js';
+import { handleApiError } from '../lib/api-error.js';
+import { requireToken } from '../lib/cli-read.js';
+import { confirmDestructive, resolveStepUp, withStepUpRetry } from '../lib/cli-write.js';
+import { TENANT_ENVIRONMENT_IDS } from '../lib/envs.js';
+import { log } from '../utils/logger.js';
+import { isSafeExitHalt, safeExit, setSafeExitCode } from '../utils/safe-exit.js';
+export const REPOINT_ENVIRONMENTS = TENANT_ENVIRONMENT_IDS.filter((e) => e !== 'dev-local');
+const SERVER_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const MAX_REASON = 500;
+// ---------------------------------------------------------------------------
+// Textos (puros — testáveis sem rede)
+// ---------------------------------------------------------------------------
+/** Nome legível de cada requisito do `--dry-run` (o Core manda o nome técnico). */
+export const REPOINT_CHECK_LABELS = {
+    environment: 'o ambiente existe',
+    environment_target_vm: 'o ambiente roda em VM',
+    environment_active: 'o ambiente não está arquivado nem suspenso',
+    expected_server: 'o ambiente aponta a VM informada em --expect-from',
+    no_deploy_in_flight: 'nenhum lançamento em andamento',
+    target_ready: 'VM nova no ar e pronta',
+    target_fleet: 'VM nova é da frota da Neetru',
+    target_role: 'VM nova aceita app e é compartilhada',
+    target_public_ip: 'VM nova tem IP público (o ambiente tem domínio público)',
+    target_capacity: 'VM nova tem espaço para mais um app',
+    same_vm: 'nenhum outro ambiente do produto na VM nova',
+    databases: 'bancos do ambiente',
+};
+/** Rótulo de um requisito (os de banco vêm como `database:<dbId>`). */
+export function checkLabel(name) {
+    if (name.startsWith('database:'))
+        return `banco ${name.slice('database:'.length)} alcançável da VM nova`;
+    return REPOINT_CHECK_LABELS[name] ?? name;
+}
+/**
+ * O que fazer para cada código `REPOINT_*` que a rota devolve. A mensagem do
+ * Core (com VMs, bancos e o motivo) vem antes; isto é o "e agora?".
+ */
+export const REPOINT_GUIDANCE = {
+    REPOINT_INPUT_INVALID: 'Algum dado do pedido está fora do formato: o ambiente é staging ou prod, e as VMs são ids de servidor (letras, números, _ ou -).',
+    REPOINT_PRODUCT_NOT_FOUND: 'Produto não encontrado. Confira o slug ou o id do produto.',
+    REPOINT_ENV_NOT_FOUND: 'O produto não tem esse ambiente. Ele nasce no primeiro deploy.',
+    REPOINT_ENV_NOT_VM: 'Esse ambiente não roda em VM, então não há VM para re-apontar.',
+    REPOINT_ENV_INACTIVE: 'O ambiente está arquivado ou suspenso. Re-apontar só vale para ambiente ativo.',
+    REPOINT_EXPECTED_MISMATCH: 'O ambiente não aponta a VM que você informou: alguém mudou desde que você olhou. Veja a VM atual no requisito ' +
+        '"o ambiente aponta a VM informada" rodando ' +
+        '`neetru environments repoint <slug> <env> --to <serverId> --expect-from <serverId> --reason "<motivo>" --dry-run`, ' +
+        'e repita com o valor certo. Nada foi gravado.',
+    REPOINT_DEPLOY_IN_PROGRESS: 'Há um lançamento em andamento neste ambiente. Espere ele terminar e repita. Nada foi gravado.',
+    REPOINT_TARGET_NOT_READY: 'A VM nova não existe, não está no ar, está sem dar sinal há mais de 5 minutos ou ainda não terminou de se preparar.',
+    REPOINT_TARGET_NOT_FLEET: 'A VM nova não é uma VM da Neetru (é de cliente ou não tem identidade no Google Cloud do projeto).',
+    REPOINT_TARGET_ROLE: 'A VM nova não recebe apps (é só de banco) ou é exclusiva. Escolha uma VM que aceite apps.',
+    REPOINT_TARGET_NO_CAPACITY: 'A VM nova está sem espaço para mais um app. Escolha outra VM ou libere espaço nela.',
+    REPOINT_TARGET_IP_NOT_PUBLIC: 'O ambiente tem domínio público e a VM nova não tem IP público — o domínio não teria para onde apontar.',
+    REPOINT_SAME_VM_COLLISION: 'Outro ambiente do mesmo produto está (ou pode estar) rodando na VM nova. Os dois se sobrescreveriam: use uma VM por ambiente.',
+    REPOINT_DB_UNREACHABLE: 'Um banco deste ambiente fica em outra VM e não tem a porta de entrada ligada para a VM nova — o app ficaria sem banco. ' +
+        'Ligue antes com `neetru db frontdoor enable <dbId> --app-server <serverId> --reason "<motivo>"` e repita.',
+    REPOINT_DB_ENGINE_UNSUPPORTED: 'Um banco deste ambiente fica em outra VM e é de um tipo sem porta de entrada (MySQL, Mongo ou cluster). ' +
+        'O app precisa ficar na mesma VM desse banco. Fale com o Dev Core.',
+    REPOINT_DB_OP_IN_PROGRESS: 'Um banco deste ambiente está mudando de VM ou ligando a porta de entrada. Espere terminar e repita.',
+    REPOINT_READ_FAILED: 'Não foi possível ler um dos requisitos agora. Nada foi gravado — repita em instantes.',
+    REPOINT_STATE_CHANGED: 'O ambiente ou um requisito mudou entre a conferência e a gravação. Nada foi gravado — confira e repita.',
+    REPOINT_COMMIT_FAILED: 'A gravação não conseguiu terminar. Nada foi gravado — repita em instantes.',
+};
+/** Mensagem do Core primeiro (dados reais), depois o que fazer. Pura. */
+export function describeRepointError(code, serverMessage) {
+    const guidance = REPOINT_GUIDANCE[code];
+    return guidance ? `${serverMessage}\n  ${guidance}` : serverMessage;
+}
+/** Erro da rota: `REPOINT_*` vira mensagem + o que fazer; o resto vai pro handler comum. */
+function failRepoint(err, json) {
+    if (isSafeExitHalt(err))
+        throw err;
+    if (err instanceof CliApiError && typeof err.code === 'string' && err.code.startsWith('REPOINT_')) {
+        if (json) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: err.code,
+                message: err.message,
+                guidance: REPOINT_GUIDANCE[err.code] ?? null,
+            }));
+        }
+        else {
+            log.error(describeRepointError(err.code, err.message));
+        }
+        return safeExit(1);
+    }
+    return handleApiError(err, json);
+}
+function inputError(message, json) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, error: 'input', message }));
+    else
+        log.error(message);
+    return safeExit(1);
+}
+function printChecks(checks) {
+    log.heading('Requisitos');
+    for (const c of checks) {
+        const mark = c.ok ? chalk.green('✓') : chalk.red('✗');
+        log.dim(`  ${mark} ${checkLabel(c.name)}${c.detail ? ` — ${c.detail}` : ''}`);
+    }
+}
+export async function runEnvironmentsRepoint(slug, env, opts = {}) {
+    if (!opts.json)
+        log.banner();
+    if (!slug || !slug.trim() || slug.includes('/'))
+        inputError('Informe o produto (slug ou id).', opts.json);
+    if (!REPOINT_ENVIRONMENTS.includes(env)) {
+        inputError(`Ambiente inválido: "${env}". Use ${REPOINT_ENVIRONMENTS.join(' ou ')}.`, opts.json);
+    }
+    // Literal aqui (não num helper): a guarda de step-up da CLI precisa enxergar a rota.
+    const rota = `/api/cli/v1/products/${encodeURIComponent(slug)}/environments/${encodeURIComponent(env)}/server`;
+    const to = (opts.to ?? '').trim();
+    const expectFrom = (opts.expectFrom ?? '').trim();
+    const reason = (opts.reason ?? '').trim();
+    if (!SERVER_ID_RE.test(to))
+        inputError('--to <serverId> é obrigatório (o id da VM nova).', opts.json);
+    if (!SERVER_ID_RE.test(expectFrom)) {
+        inputError('--expect-from <serverId> é obrigatório (a VM que o ambiente aponta hoje — se mudou, nada é gravado).', opts.json);
+    }
+    if (!reason || reason.length > MAX_REASON) {
+        inputError(`--reason "<texto>" é obrigatório (1 a ${MAX_REASON} caracteres; vai para a auditoria).`, opts.json);
+    }
+    await requireToken(opts.json);
+    if (!opts.json) {
+        log.heading(opts.dryRun ? 'Re-apontar a VM do ambiente (só conferência)' : 'Re-apontar a VM do ambiente');
+        log.info(`Produto:        ${chalk.cyan(slug)}`);
+        log.info(`Ambiente:       ${chalk.bold(env)}`);
+        log.info(`Aponta hoje:    ${expectFrom}`);
+        log.info(`Vai apontar:    ${chalk.bold(to)}`);
+        log.dim('  Só o ponteiro muda — o app não muda de VM até o próximo deploy na VM nova.');
+    }
+    const body = { toServerId: to, expectedServerId: expectFrom, reason };
+    // ── Só conferência: nada é gravado, sem MFA. ──────────────────────────────
+    if (opts.dryRun) {
+        const { headers } = await resolveStepUp({ dryRun: true, json: opts.json, mfaToken: opts.mfaToken });
+        let r;
+        try {
+            r = await apiRequest(rota, {
+                method: 'POST',
+                body: { ...body, dryRun: true },
+                headers,
+            });
+        }
+        catch (err) {
+            failRepoint(err, opts.json);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...r, ok: r.preflight.ok || r.alreadyPointed }));
+            if (!r.preflight.ok && !r.alreadyPointed)
+                setSafeExitCode(1);
+            return;
+        }
+        if (r.alreadyPointed) {
+            log.info(`O ambiente ${env} já aponta ${to} — não há o que re-apontar.`);
+            return;
+        }
+        printChecks(r.preflight.checks);
+        if (r.preflight.ok) {
+            log.success('Tudo certo para re-apontar. Nada foi alterado. Rode de novo sem --dry-run para gravar.');
+        }
+        else {
+            log.error('Algum requisito falhou — o ambiente não seria re-apontado. Nada foi alterado.');
+            setSafeExitCode(1);
+        }
+        return;
+    }
+    await confirmDestructive(`Re-apontar o ambiente ${env} do produto ${slug} de ${expectFrom} para ${to}? Só o ponteiro muda: o app ` +
+        'continua onde está até o próximo deploy na VM nova, e a promoção de staging para prod passa a usar a VM nova.', { yes: opts.yes, json: opts.json });
+    const r = await withStepUpRetry({ mfaToken: opts.mfaToken, json: opts.json, yes: opts.yes }, (headers) => apiRequest(rota, { method: 'POST', body, headers }), (err) => failRepoint(err, opts.json));
+    if (opts.json) {
+        console.log(JSON.stringify(r));
+        return;
+    }
+    if (r.alreadyPointed) {
+        log.info(`O ambiente ${env} já apontava ${to} — nada foi gravado.`);
+        return;
+    }
+    if (!r.changed) {
+        // Não deveria acontecer (o Core responde erro quando não grava), mas sem mentir:
+        log.error('O Core respondeu sem gravar o ponteiro. Nada mudou — confira com --dry-run.');
+        setSafeExitCode(1);
+        return;
+    }
+    log.success(`Ambiente ${env} agora aponta ${r.to} (antes: ${r.from ?? 'nenhuma VM'}).`);
+    log.warn('O app NÃO mudou de VM: só o ponteiro do ambiente.');
+    if (r.pendingDrain.length > 0) {
+        log.dim(`  Continua rodando o que estava em ${r.pendingDrain.join(', ')} (nada é desligado), e essa VM segue ` +
+            'contada como ocupada por este ambiente.');
+    }
+    log.info(`Próximo passo: ${r.nextStep}`);
+}
+//# sourceMappingURL=environments-repoint.js.map

package/dist/commands/init.js

@@ -80,7 +80,13 @@ async function resolveTarget(name, cwd, opts) {
         // Default: cria subdir <cwd>/<name>
         const insp = await inspectDir(subDir);
         if (insp.exists && !insp.isEmpty) {
-            log.error(`Diretório "${name}" já existe com arquivos. Use --here ou --path ou --force.`);
+            // bug_89d2497e (etapa 1): o `neetru new` chega aqui pelo `runInit` e não
+            // declara --here/--path/--force — "Use --here" mandava o usuário repetir
+            // o `neetru new` com uma flag que ele recusa. O conselho cita o comando
+            // inteiro. E `--force` com `--yes` cai de novo neste mesmo ramo (ele não
+            // lê `opts.force`); sobrescrever é `--path <dir> --force`.
+            log.error(`Diretório "${name}" já existe com arquivos. Rode \`neetru init ${name} --here\` (mescla no diretório atual), ` +
+                `\`neetru init ${name} --path <outro-diretório>\` ou, para sobrescrever, \`neetru init ${name} --path ${name} --force\`.`);
             safeExit(1); // erro hard em non-interactive — consistente com pre-2.2.0
         }
         return { dir: subDir, mode: 'new', force: false };

package/dist/commands/new.js

@@ -195,6 +195,20 @@ export async function runNewMacro(name, opts = {}) {
         safeExit(1);
     }
     let slug = (opts.productSlug ?? deriveSlug(name)) || deriveSlug(name);
+    // bug_89d2497e (etapa 1): nome sem letra nem dígito ("!!!") deriva slug
+    // vazio, e quem recusava era o `products create`, com "informe --slug" —
+    // flag que o `neetru new` não tem (a dele é --product-slug). Recusa aqui,
+    // antes de autenticar e de criar qualquer coisa no Core.
+    if (!slug) {
+        const msg = `Não dá para derivar um slug de "${name}" — informe --product-slug <slug>.`;
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, error: 'invalid_input', message: msg }));
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+    }
     // bug_7dcb68e2666a43f69ef362d2cbff94ed: o padrão era 'dev', token que o Core
     // não conhece — a macro morria no passo [2/5] com 400 validation_failed.
     const env = opts.env

package/dist/commands/secrets.d.ts

@@ -28,10 +28,12 @@
  * '--value=sk_live…'", "unknown command 'sk_live…'") imprimiria o segredo de
  * volta no terminal.
  *
- * ATENÇÃO (2026-10-16): a entrega ao app na VM depende do lado do AGENTE
- * (Parte 2 de bug_8b85353b, `neetru-agent-service-vm`), que ainda não foi
- * liberado. Até lá o registro funciona mas o segredo não chega ao app — e a
- * CLI diz isso ao gravar, em vez de deixar o dev descobrir em produção.
+ * Entrega ao app na VM: é o lado do AGENTE (Parte 2 de bug_8b85353b,
+ * `neetru-agent-service-vm`), publicado na 1.6.80 (2026-10-20). No deploy, o
+ * agente busca os valores no Core e grava `/etc/neetru/<slug>.product.env`
+ * (root, 0600). Por isso o app só vê uma gravação no PRÓXIMO deploy — e a CLI
+ * diz isso ao gravar (`notaEntregaDoSegredo`). Até a 2.33.0 ela dizia que o
+ * agente "ainda não entrega", frase falsa desde a 1.6.80.
  */
 import type { Command } from 'commander';
 import { type StepUpOptions } from '../lib/cli-write.js';

package/dist/commands/secrets.js

@@ -5,7 +5,7 @@ import { renderTable, fmtTimestamp } from '../lib/render.js';
 import { requireToken, handleApiError, confirmDestructive, printWriteResult, resolveStepUp, isMfaRequiredError, } from '../lib/cli-write.js';
 import { loadProductConfig } from '../lib/product-config.js';
 import { listarAmbientesTenant, resolverAmbienteTenant, } from '../lib/envs.js';
-import { AVISO_AGENTE_PENDENTE, CodificacaoInvalida, PedidoCancelado, lerValorDeArquivo, lerValorDeFluxo, perguntarSemEco, problemaNaChave, problemaNaChaveReservada, problemaNoTextoDoTerminal, problemaNoValor, problemaNosBytes, } from '../lib/segredo-produto.js';
+import { CodificacaoInvalida, PedidoCancelado, lerValorDeArquivo, lerValorDeFluxo, notaEntregaDoSegredo, perguntarSemEco, problemaNaChave, problemaNaChaveReservada, problemaNoTextoDoTerminal, problemaNoValor, problemaNosBytes, } from '../lib/segredo-produto.js';
 import { log } from '../utils/logger.js';
 import { safeExit } from '../utils/safe-exit.js';
 function entradaPadrao() {
@@ -61,8 +61,13 @@ function exigirAmbiente(env, json) {
     }
     return resolverAmbienteTenant(env, json);
 }
-function exigirChave(chave, json) {
-    const problema = problemaNaChave(chave);
+/**
+ * `comoMandarOValor`: só o `set` passa (é ele que recebe valor, por --stdin,
+ * --from-file ou pelo pedido na tela). O `archive` não passa: lá o conselho é
+ * só "passe só o nome" (bug_89d2497e, etapa 1).
+ */
+function exigirChave(chave, json, comoMandarOValor) {
+    const problema = problemaNaChave(chave, comoMandarOValor);
     if (problema)
         return falhar(json, 'invalid_key', problema);
     return chave;
@@ -170,7 +175,7 @@ function cabeRepetirComTotp(ambiente, headers, erro) {
 }
 export async function runSecretsSet(opts, entrada = entradaPadrao()) {
     recusarArgumentosExtras(opts.extras, opts.json);
-    const chave = exigirChave(opts.key, opts.json);
+    const chave = exigirChave(opts.key, opts.json, 'por --stdin, --from-file ou pelo pedido na tela');
     exigirChaveRegistravel(chave, opts.json);
     const ambiente = exigirAmbiente(opts.env, opts.json);
     const origens = [!!opts.generate, opts.fromFile !== undefined, !!opts.stdin].filter(Boolean).length;
@@ -245,7 +250,7 @@ export async function runSecretsSet(opts, entrada = entradaPadrao()) {
         revision: res.revision,
         created: res.created,
         secretRef: res.secretRef,
-        note: AVISO_AGENTE_PENDENTE,
+        note: notaEntregaDoSegredo(res.environmentId),
     }, `Segredo ${chalk.bold(res.key)} ${acao} em ${res.environmentId} (revisão ${res.revision})` +
         (gerado ? ' — o Core sorteou o valor; ninguém o vê, nem você.' : '.'), opts.json);
     if (opts.json)
@@ -253,8 +258,10 @@ export async function runSecretsSet(opts, entrada = entradaPadrao()) {
     if (!res.created)
         log.dim('O valor anterior deixa de ser entregue a partir do próximo deploy.');
     log.dim(`Nome no Secret Manager: ${res.secretRef} (é o nome, não o valor).`);
-    log.dim(`Para o app receber: faça um novo deploy em ${res.environmentId}.`);
-    log.warn(AVISO_AGENTE_PENDENTE);
+    // Até a 2.33.0 saía aqui um aviso de que o agente da VM "ainda não entrega"
+    // segredos do produto — falso desde a 1.6.80 (bug_8b85353b). Fica só o fato:
+    // o app recebe no próximo deploy.
+    log.info(notaEntregaDoSegredo(res.environmentId));
 }
 export async function runSecretsList(opts) {
     const ambiente = opts.env?.trim() ? resolverAmbienteTenant(opts.env, opts.json) : undefined;

package/dist/commands/servers.d.ts

@@ -53,7 +53,36 @@ export declare function runServersDeactivate(id: string | undefined, opts: StepU
  */
 export interface ServersForceCleanupOptions extends StepUpOptions {
     reason: string;
+    /**
+     * core#732 (bug_90ec21cd): id numérico da instância no Google Cloud que o
+     * operador CONFERIU. Só faz falta quando o servidor não tem o id da VM
+     * registrado (`externalId`) e existe uma VM com o mesmo nome — o Core recusa
+     * com `vm_sem_externalid` e mostra o id visto + o comando de conferência.
+     * A CLI NUNCA preenche este id a partir da resposta: o operador digita.
+     */
+    confirmInstanceId?: string;
+}
+/**
+ * core#732: recusas da guarda de identidade da VM no force-cleanup. A mensagem
+ * do Core (com o id visto e o comando de conferência) vem antes; isto é o que
+ * fazer. Nenhum texto monta o comando com o id preenchido — de propósito.
+ */
+export declare const FORCE_CLEANUP_IDENTITY_GUIDANCE: Record<string, string>;
+/**
+ * Detalhes que o core#732 manda junto da recusa (`{ error: { …, instanceId?,
+ * instanceCreatedAt?, docCreatedAt?, outrosServidores?, comandoConferencia? } }`),
+ * só os campos conhecidos e com o tipo certo. Nunca vira comando com o id.
+ */
+export interface ForceCleanupIdentityDetails {
+    instanceId?: string;
+    instanceCreatedAt?: string;
+    docCreatedAt?: string;
+    outrosServidores?: string[];
+    comandoConferencia?: string;
 }
+export declare function forceCleanupIdentityDetails(raw: unknown): ForceCleanupIdentityDetails | undefined;
+/** Linhas legíveis dos detalhes (texto). Mostra o id VISTO, mas não monta comando com ele. */
+export declare function forceCleanupIdentityDetailLines(d: ForceCleanupIdentityDetails | undefined): string[];
 export declare function runServersForceCleanup(id: string, opts: ServersForceCleanupOptions): Promise<void>;
 export interface ServersDispatchOptions extends StepUpOptions {
     params?: string;

package/dist/commands/servers.js

@@ -342,6 +342,73 @@ export async function runServersDeactivate(id, opts) {
     }
     printWriteResult(res.dryRun ? res : { serverId: res.serverId, status: res.status }, `Servidor ${res.serverId} → ${res.status}`, opts.json);
 }
+/** Formato que a rota do Core aceita (id numérico da instância no GCP). */
+const INSTANCE_ID_RE = /^[1-9][0-9]{0,19}$/;
+/**
+ * core#732: recusas da guarda de identidade da VM no force-cleanup. A mensagem
+ * do Core (com o id visto e o comando de conferência) vem antes; isto é o que
+ * fazer. Nenhum texto monta o comando com o id preenchido — de propósito.
+ */
+export const FORCE_CLEANUP_IDENTITY_GUIDANCE = {
+    vm_sem_externalid: 'Este servidor não tem o id da VM registrado, e existe no Google Cloud uma VM com o mesmo nome — ' +
+        'pode ser OUTRA VM (nome reaproveitado). Nada foi apagado. Rode o comando de conferência acima; se a VM ' +
+        'for mesmo a deste servidor, repita o force-cleanup com --confirm-instance-id <id que você conferiu>. ' +
+        'A CLI não preenche esse id por você.',
+    vm_confirmacao_nao_confere: 'O id passado em --confirm-instance-id não é o da VM que o Core leu (a mensagem acima mostra os dois). ' +
+        'Nada foi apagado. Confira de novo antes de repetir.',
+    vm_id_divergente: 'O Google Cloud devolveu outra instância ao ler o id registrado deste servidor. Nada foi apagado — ' +
+        'fale com o Dev Core antes de tentar de novo.',
+    vm_leitura_falhou: 'Não deu para ler a VM no Google Cloud agora. Nada foi apagado. Tente de novo em alguns minutos; ' +
+        'se continuar, fale com o Dev Core.',
+    // core#732 rodada 2: a confirmação do id NÃO destrava este caso — nada de
+    // orientar "repita com o id".
+    vm_nome_em_uso_por_outro_servidor: 'Outro servidor registrado e ativo usa uma VM com o mesmo nome e zona — a VM pode ser dele. Nada foi apagado, ' +
+        'e NÃO adianta confirmar o id: o Core recusa este caso mesmo com --confirm-instance-id. Confira de qual servidor ' +
+        'é a VM e registre o id dela no servidor certo antes de excluir (fale com o Dev Core).',
+};
+export function forceCleanupIdentityDetails(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const texto = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+    const out = {};
+    const instanceId = texto(r.instanceId);
+    const instanceCreatedAt = texto(r.instanceCreatedAt);
+    const docCreatedAt = texto(r.docCreatedAt);
+    const comandoConferencia = texto(r.comandoConferencia);
+    const outros = Array.isArray(r.outrosServidores)
+        ? r.outrosServidores.map(texto).filter((x) => !!x)
+        : [];
+    if (instanceId)
+        out.instanceId = instanceId;
+    if (instanceCreatedAt)
+        out.instanceCreatedAt = instanceCreatedAt;
+    if (docCreatedAt)
+        out.docCreatedAt = docCreatedAt;
+    if (outros.length > 0)
+        out.outrosServidores = outros;
+    if (comandoConferencia)
+        out.comandoConferencia = comandoConferencia;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Linhas legíveis dos detalhes (texto). Mostra o id VISTO, mas não monta comando com ele. */
+export function forceCleanupIdentityDetailLines(d) {
+    if (!d)
+        return [];
+    const linhas = [];
+    if (d.outrosServidores) {
+        linhas.push(`Outro(s) servidor(es) ativo(s) com o mesmo nome e zona: ${d.outrosServidores.join(', ')}`);
+    }
+    if (d.instanceId)
+        linhas.push(`VM vista no Google Cloud: id ${d.instanceId}`);
+    if (d.instanceCreatedAt || d.docCreatedAt) {
+        linhas.push(`Criação da VM: ${d.instanceCreatedAt ?? '?'} · criação deste servidor: ${d.docCreatedAt ?? '?'} ` +
+            '(a VM do próprio servidor nasce segundos depois dele; diferença grande indica VM recriada)');
+    }
+    if (d.comandoConferencia)
+        linhas.push(`Para conferir (só leitura): ${d.comandoConferencia}`);
+    return linhas;
+}
 export async function runServersForceCleanup(id, opts) {
     if (!id || !/^[a-zA-Z0-9_-]{1,64}$/.test(id)) {
         log.error('serverId inválido. Uso: neetru servers force-cleanup <serverId> --reason="<motivo min 10 chars>"');
@@ -351,6 +418,16 @@ export async function runServersForceCleanup(id, opts) {
         log.error('--reason obrigatório com pelo menos 10 caracteres (paper-trail audit).');
         safeExit(1);
     }
+    // `--confirm-instance-id ""` (ou só espaços) é RECUSADO — não vira "flag não passada".
+    const confirmInstanceId = opts.confirmInstanceId === undefined ? undefined : opts.confirmInstanceId.trim();
+    if (confirmInstanceId !== undefined && !INSTANCE_ID_RE.test(confirmInstanceId)) {
+        const msg = '--confirm-instance-id deve ser o id numérico da VM no Google Cloud (o que você conferiu no comando de conferência).';
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, error: 'invalid_param', message: msg }));
+        else
+            log.error(msg);
+        safeExit(1);
+    }
     const token = await requireToken(opts.json);
     // Double-confirm (digitar o ID) — dry-run não aplica nada, então pula: nada
     // destrutivo acontece, não faz sentido travar numa confirmação interativa.
@@ -369,7 +446,11 @@ export async function runServersForceCleanup(id, opts) {
         }
         console.log(chalk.yellow.bold('\n⚠  FORCE-CLEANUP é IRREVERSÍVEL.'));
         console.log(chalk.dim('   Server stuck em provisioning/timeout que está bloqueando o pipeline.'));
-        console.log(chalk.dim('   Audit pesado + notification all staff serão gerados.\n'));
+        console.log(chalk.dim('   Audit pesado + notification all staff serão gerados.'));
+        if (confirmInstanceId) {
+            console.log(chalk.dim(`   VM a apagar: a instância de id ${confirmInstanceId}, conferida por você.`));
+        }
+        console.log('');
         const inquirer = await carregarInquirer();
         const ans = await inquirer.prompt([
             {
@@ -396,12 +477,28 @@ export async function runServersForceCleanup(id, opts) {
             body: {
                 reason: opts.reason.trim(),
                 confirm: 'I-UNDERSTAND-FORCE-CLEANUP',
+                ...(confirmInstanceId ? { confirmInstanceId } : {}),
             },
         });
         spinner?.stop();
     }
     catch (error) {
         spinner?.fail('Falha no force-cleanup.');
+        // core#732: a guarda de identidade da VM recusou — nada foi apagado. Mostra
+        // a mensagem do Core (id visto + comando de conferência) e o que fazer. Sem
+        // nova tentativa automática e sem montar o comando com o id: o operador
+        // confere e digita.
+        if (error instanceof CliApiError && FORCE_CLEANUP_IDENTITY_GUIDANCE[error.code]) {
+            const guidance = FORCE_CLEANUP_IDENTITY_GUIDANCE[error.code];
+            const details = forceCleanupIdentityDetails(error.details);
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, error: error.code, message: error.message, guidance, ...(details ? { details } : {}) }));
+            }
+            else {
+                log.error([error.message, ...forceCleanupIdentityDetailLines(details), guidance].join('\n  '));
+            }
+            safeExit(1);
+        }
         handleApiError(error, opts.json);
     }
     if (opts.json) {
@@ -414,6 +511,16 @@ export async function runServersForceCleanup(id, opts) {
     }
     log.success(`Server ${res.serverId} force-cleanup concluído.`);
     log.dim(`  Status anterior: ${res.previousStatus} (há ${res.ageMinutes}min)`);
+    if (res.vmIdentidade) {
+        const identidade = {
+            'confere:externalId': 'conferida pelo id registrado no servidor',
+            'confere:confirmacao': 'conferida pelo id que você confirmou',
+            'ausente:id_ausente': 'a VM registrada já não existia',
+            'ausente:nome_ausente': 'não havia VM com o nome do servidor',
+            'ausente:nome_de_outro_servidor': 'a VM com esse nome é de OUTRO servidor — não foi tocada',
+        };
+        log.dim(`  Identidade da VM: ${identidade[res.vmIdentidade] ?? res.vmIdentidade}`);
+    }
     if (res.vmDeleted) {
         log.dim('  VM GCP: deletada com sucesso.');
     }

package/dist/commands/ui.js

@@ -1080,7 +1080,7 @@ async function authMenu() {
 }
 export async function runTerminalUi() {
     if (!canPrompt()) {
-        log.error('A interface interativa exige um terminal TTY. Use comandos diretos ou --json em CI.');
+        log.error('A interface interativa exige um terminal TTY. Em CI, use os comandos diretos (ex.: `neetru products list --json`).');
         safeExit(1);
     }
     // Blindagem contra auto-encerramento: enquanto o menu interativo roda, um

package/dist/commands/workspaces.js

@@ -31,6 +31,7 @@ import { renderTable, fmtTimestamp } from '../lib/render.js';
 import { pickProductId, pickProductSlug, pickWorkspace, resolveProductIdentifier, isInteractive, promptChoice, promptText, resolveCustomer, } from '../lib/pickers.js';
 import { DEFAULT_TENANT_ENVIRONMENT_ID, ESCOLHAS_AMBIENTE_TENANT, resolverAmbienteTenant, erroAmbienteTenantInvalido, normalizarAmbienteTenant, } from '../lib/envs.js';
 import { exitWithCliError } from '../lib/cli-error.js';
+import { adviseFlag } from '../cli-kit/command-context.js';
 import { log } from '../utils/logger.js';
 import { safeExit } from '../utils/safe-exit.js';
 /** Formata o erro 400 "Nenhum customer ativo" de forma acionável. */
@@ -100,11 +101,25 @@ export async function runWorkspacesCreate(opts) {
             const label = existingTenant.name ?? existingTenant.id ?? '(sem nome)';
             // Modo script/JSON (--json ou --yes implícito): bloqueia com 409.
             if (opts.json) {
+                // bug_89d2497e (etapa 1): o `neetru new` chama este runner com
+                // `json: true` e este envelope é o que o usuário dele lê — e o `new`
+                // não declara --force-duplicate. O texto sai conforme o comando em
+                // execução: só quem declara a flag (o `workspaces create`) ouve "Use
+                // --force-duplicate"; os outros recebem o caminho que existe — o
+                // `workspaces create` num terminal interativo pergunta se reusa o
+                // ambiente existente ou cria outro.
+                const message = adviseFlag({
+                    flag: '--force-duplicate',
+                    withFlag: `Já existe ambiente ativo '${label}' para produto=${product} env=${env}. Use --force-duplicate para criar mesmo assim.`,
+                    withoutFlag: `Já existe ambiente ativo '${label}' para produto=${product} env=${env}. Para criar um segundo, rode ` +
+                        `\`neetru workspaces create --product ${product} --env ${env}\` num terminal interativo: ele pergunta se ` +
+                        'reusa o existente ou cria outro.',
+                });
                 console.log(JSON.stringify({
                     ok: false,
                     error: 'tenant_already_exists',
                     status: 409,
-                    message: `Já existe ambiente ativo '${label}' para produto=${product} env=${env}. Use --force-duplicate para criar mesmo assim.`,
+                    message,
                     existing: existingTenant,
                 }));
                 safeExit(1);