@neetru/cli 2.32.0 → 2.33.0

package/dist/commands/db-frontdoor.js

@@ -0,0 +1,567 @@
+/**
+ * `neetru db frontdoor` — PORTA DE ENTRADA privada de um banco Postgres em VM,
+ * SEM mover o banco (Core #727, bug_5c0e7738).
+ *
+ * Caso de uso: o banco fica onde está e o app passa a rodar (ou já roda) em
+ * OUTRA VM da rede interna — ex.: banco do Zelo na snee-003-db, app indo pra
+ * snee-002-multi. O `neetru db move` não serve (recusa destino == origem).
+ *
+ *   enable <dbId> --app-server <serverId> --reason "<motivo>"
+ *     O Core prepara o PgBouncer na VM do banco, testa a conexão a partir da VM
+ *     do app, testa o login pelo IP interno NA PRÓPRIA VM do banco e só então
+ *     grava o novo endereço no cadastro do banco. Falha em qualquer passo = nada
+ *     muda para o app. `--dry-run` só confere os requisitos (sem MFA).
+ *   status <dbId>
+ *   disable <dbId> --reason "<motivo>" [--force]
+ *     Volta o endereço do app para o local da VM do banco (desfazer).
+ *
+ * COMO ANDA (contrato do Core): a operação só avança DENTRO da chamada de
+ * `enable` (não há nada rodando no Core em segundo plano). Por isso o CLI faz o
+ * POST com espera longa e, enquanto ele roda, consulta o GET pra mostrar o
+ * passo em que está. Se o POST voltar com a operação ainda em curso, o CLI
+ * chama de novo (o Core RETOMA a mesma operação) até um fim ou o prazo total.
+ * Repetir o comando depois também retoma.
+ *
+ * MFA (igual ao `db move`/`products db set-status`): `--mfa-token` ou a sessão
+ * de 1h de `neetru auth mfa-session`; sessão recusada pelo Core ⇒ pede um TOTP
+ * fresco UMA vez. O TOTP é de uso único: nas retomadas o código já gasto não é
+ * reenviado (vale a sessão, ou um TOTP novo).
+ *
+ * Endpoints (Core):
+ *   POST /api/cli/v1/db/{id}/frontdoor          — liga/retoma/dry-run (MFA fora do dry-run)
+ *   GET  /api/cli/v1/db/{id}/frontdoor          — estado
+ *   POST /api/cli/v1/db/{id}/frontdoor/disable  — desliga (MFA)
+ *
+ * Plain PT-BR em toda string visível ao usuário.
+ */
+import { createInterface } from 'node:readline';
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiRequest, CliApiError, CliNetworkError } 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 { log } from '../utils/logger.js';
+import { isSafeExitHalt, safeExit, setSafeExitCode } from '../utils/safe-exit.js';
+// ---------------------------------------------------------------------------
+// Textos (puros — testáveis sem rede)
+// ---------------------------------------------------------------------------
+/** O que cada estado quer dizer, em português simples. */
+export const STATE_LABELS = {
+    planning: 'conferindo os requisitos',
+    preparing: 'passo 1 de 3 — preparando o PgBouncer na VM do banco',
+    verifying_app: 'passo 2 de 3 — testando a conexão a partir da VM do app',
+    verifying_local: 'passo 3 de 3 — testando o login pelo IP interno na própria VM do banco',
+    enabled: 'ligada',
+    failed: 'falhou (nada mudou para o app)',
+    cancelled: 'cancelada (nada mudou para o app)',
+    disabled: 'desligada',
+};
+const IN_FLIGHT = new Set(['preparing', 'verifying_app', 'verifying_local']);
+export function isInFlight(state) {
+    return !!state && IN_FLIGHT.has(state);
+}
+/** Nome legível de cada requisito do `--dry-run` (o Core manda o nome técnico). */
+export const CHECK_LABELS = {
+    db_active: 'banco ativo',
+    engine_supported: 'tipo de banco suportado',
+    db_server_known: 'VM do banco conhecida',
+    credentials: 'credencial do banco registrada',
+    endpoint: 'endereço do banco legível',
+    distinct_server: 'app e banco em VMs diferentes',
+    db_server_ready: 'VM do banco no ar',
+    app_server_ready: 'VM do app no ar',
+    front_door_plan: 'IPs internos das duas VMs',
+    front_door_host_consistent: 'sem outro endereço já gravado',
+    no_active_relocate: 'nenhuma mudança de VM do banco em andamento',
+    app_environment: 'onde o produto diz que o app roda',
+    app_server_fleet: 'VM do app é da frota da Neetru',
+};
+/**
+ * O que fazer para cada código `FRONT_DOOR_*` que a rota devolve. A mensagem
+ * do Core (com VMs, IPs e o motivo do agente) vem antes; isto é o "e agora?".
+ */
+export const FRONT_DOOR_GUIDANCE = {
+    FRONT_DOOR_INPUT_INVALID: 'Algum dado do pedido está fora do formato: o banco é um id que começa com pdb_ e a VM do app é o id do servidor.',
+    FRONT_DOOR_DB_NOT_FOUND: 'Banco não encontrado. Confira o id do banco com `neetru db where --product <slug>`.',
+    FRONT_DOOR_DB_NOT_ACTIVE: 'O banco não está ativo (ou o cadastro dele está incompleto). Só dá para ligar a porta de entrada de um banco ativo.',
+    FRONT_DOOR_ENGINE_UNSUPPORTED: 'A porta de entrada só existe para Postgres em VM (vm-postgres-single).',
+    FRONT_DOOR_NO_CREDENTIALS: 'O banco não tem credencial registrada, então não há como testar o login pela porta nova. Fale com o Dev Core.',
+    FRONT_DOOR_SAME_SERVER: 'A VM do app informada é a própria VM do banco. Nesse caso o app já fala com o banco pelo endereço local — não há nada a ligar.',
+    FRONT_DOOR_DB_SERVER_NOT_READY: 'A VM do banco não está no ar ou o agente dela está sem dar sinal há mais de 5 minutos. Verifique a VM e tente de novo.',
+    FRONT_DOOR_APP_SERVER_NOT_READY: 'A VM do app não existe, não está no ar ou o agente dela está sem dar sinal há mais de 5 minutos. Confira o id passado em --app-server.',
+    FRONT_DOOR_APP_SERVER_NOT_FLEET: 'A VM do app não é uma VM da Neetru (é de cliente ou não tem identidade no Google Cloud do projeto). A liberação abre o banco para a VM inteira, então só vale para VM da frota. Confira o id passado em --app-server.',
+    FRONT_DOOR_NOT_PLANNABLE: 'Não foi possível descobrir o IP interno de uma das VMs (ou ele não é da rede interna). Nada foi alterado.',
+    FRONT_DOOR_RELOCATE_IN_PROGRESS: 'Este banco está mudando de VM. Até a mudança terminar a porta de entrada é dela — acompanhe com `neetru db move status <id>` e tente depois.',
+    FRONT_DOOR_HOST_CONFLICT: 'O cadastro do banco já aponta outro IP interno, diferente do IP atual da VM do banco. Desligue primeiro com `neetru db frontdoor disable <dbId>` e ligue de novo.',
+    FRONT_DOOR_IN_PROGRESS: 'Já há uma ligação em andamento para outra VM do app. Repita o comando com aquela VM para concluir, ou cancele com `neetru db frontdoor disable <dbId>`.',
+    FRONT_DOOR_PREPARE_FAILED: 'O preparo na VM do banco falhou (o motivo acima vem da própria VM). Nada mudou para o app: ele segue usando o endereço local.',
+    FRONT_DOOR_VERIFY_APP_FAILED: 'A VM do app não conseguiu chegar ao banco pela rede interna (rede, firewall ou certificado). Nada mudou para o app.',
+    FRONT_DOOR_VERIFY_LOCAL_FAILED: 'O teste de login pelo IP interno, feito na própria VM do banco, falhou — o app que roda lá poderia perder o banco, então nada foi gravado.',
+    FRONT_DOOR_UNVERIFIED: 'Os testes ficaram antigos (mais de 10 minutos) antes da gravação. Rode o mesmo comando de novo: ele recomeça e testa outra vez.',
+    FRONT_DOOR_STATE_CHANGED: 'O banco mudou (de VM, de credencial ou de estado) enquanto a porta era testada, ou a operação foi trocada por outra. Nada foi gravado — confira com `neetru db frontdoor status <dbId>` e tente de novo.',
+    // NÃO está na lista de códigos do Core (`FRONT_DOOR_OP_ERROR_CODES`): é o
+    // `lastError.code` que o desligar grava na operação que ele cancela
+    // (`frontdoor-op-deps.ts`). A rota o devolve quando uma ligação em curso
+    // percebe o cancelamento; e o ramo "terminou sem erro" do `enable` também o
+    // sintetiza a partir do estado (`FRONT_DOOR_<ESTADO>`) — defesa em
+    // profundidade, porque o Core sempre responde erro numa operação cancelada.
+    FRONT_DOOR_CANCELLED: 'A ligação foi cancelada porque a porta de entrada foi desligada enquanto ela andava. Nada foi gravado.',
+    FRONT_DOOR_APP_ON_OTHER_VM: 'Desligar faz o app voltar a receber o endereço local da VM do banco: um app que roda em OUTRA VM fica sem banco. ' +
+        'Desligar uma porta ligada (o desfazer normal) sempre pede --force, e também quando não se sabe em que VM o app roda. ' +
+        'Leve o app de volta para a VM do banco antes ou, se é isso mesmo, repita com --force.',
+    FRONT_DOOR_HOST_NOT_OWNED: 'O endereço gravado no cadastro do banco não foi ligado por este comando (veio de outra origem, por exemplo uma mudança de VM do banco). ' +
+        'Ele não é desfeito por aqui, nem com --force. Fale com o Dev Core.',
+};
+/** Mensagem do Core primeiro (dados reais), depois o que fazer. Pura. */
+export function describeFrontDoorError(code, serverMessage) {
+    const guidance = FRONT_DOOR_GUIDANCE[code];
+    return guidance ? `${serverMessage}\n  ${guidance}` : serverMessage;
+}
+/** Erro da rota: `FRONT_DOOR_*` vira mensagem + o que fazer; o resto vai pro handler comum. */
+function failFrontDoor(err, json) {
+    if (isSafeExitHalt(err))
+        throw err;
+    if (err instanceof CliApiError && typeof err.code === 'string' && err.code.startsWith('FRONT_DOOR_')) {
+        if (json) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: err.code,
+                message: err.message,
+                guidance: FRONT_DOOR_GUIDANCE[err.code] ?? null,
+            }));
+        }
+        else {
+            log.error(describeFrontDoorError(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);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Sinal interno: o POST longo caiu por rede/tempo — retoma na próxima volta. */
+class RetomarVolta extends Error {
+}
+/**
+ * Consulta o estado em paralelo ao POST longo, só pra mostrar o passo. Erro de
+ * consulta não importa (é exibição). Devolve a função que para.
+ */
+function acompanharPassos(dbId, intervalMs, onOp) {
+    let parado = false;
+    void (async () => {
+        while (!parado) {
+            await sleep(intervalMs);
+            if (parado)
+                break;
+            try {
+                const s = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+                if (!parado && s.op)
+                    onOp(s.op);
+            }
+            catch {
+                /* só exibição */
+            }
+        }
+    })();
+    return () => {
+        parado = true;
+    };
+}
+export async function runDbFrontdoorEnable(dbId, opts = {}) {
+    if (!opts.json)
+        log.banner();
+    if (!dbId || !dbId.trim())
+        inputError('Informe o id do banco (pdb_…).', opts.json);
+    if (!opts.appServer || !opts.appServer.trim()) {
+        inputError('--app-server <serverId> é obrigatório (a VM onde o app roda ou vai rodar).', opts.json);
+    }
+    if (!opts.reason || !opts.reason.trim()) {
+        inputError('--reason "<texto>" é obrigatório (vai para o registro de auditoria).', opts.json);
+    }
+    const appServer = opts.appServer.trim();
+    await requireToken(opts.json);
+    // ── Estado ANTES: mostra o plano e falha cedo no caso óbvio. Rede instável
+    //    não bloqueia (o Core confere tudo de novo). ─────────────────────────────
+    let before = null;
+    try {
+        before = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+    }
+    catch (err) {
+        if (!(err instanceof CliNetworkError))
+            failFrontDoor(err, opts.json);
+    }
+    const dbServer = before?.ledger.serverId ?? null;
+    if (dbServer && dbServer === appServer) {
+        const msg = describeFrontDoorError('FRONT_DOOR_SAME_SERVER', `A VM do app (${appServer}) é a mesma VM do banco.`);
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, error: 'FRONT_DOOR_SAME_SERVER', message: msg }));
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+    }
+    if (!opts.json) {
+        log.heading(opts.dryRun ? 'Porta de entrada do banco (só conferência)' : 'Porta de entrada do banco');
+        log.info(`Banco:          ${chalk.cyan(dbId)}`);
+        log.info(`VM do banco:    ${dbServer ? chalk.bold(dbServer) : chalk.dim('(o Core confere)')}`);
+        log.info(`VM do app:      ${chalk.bold(appServer)}`);
+        log.info(`Hoje:           ${before?.ledger.frontDoorHost
+            ? `ligada em ${before.ledger.frontDoorHost}:5433`
+            : 'desligada — o app recebe o endereço local da VM do banco'}`);
+    }
+    const body = { appServerId: appServer, reason: opts.reason.trim() };
+    // ── Só conferência: nada é criado, sem MFA. ───────────────────────────────
+    if (opts.dryRun) {
+        const { headers } = await resolveStepUp({ dryRun: true, json: opts.json, mfaToken: opts.mfaToken });
+        let r;
+        try {
+            r = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`, {
+                method: 'POST',
+                body: { ...body, dryRun: true },
+                headers,
+            });
+        }
+        catch (err) {
+            failFrontDoor(err, opts.json);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...r, ok: r.preflight.ok }));
+            if (!r.preflight.ok)
+                setSafeExitCode(1);
+            return;
+        }
+        log.heading('Requisitos');
+        for (const c of r.preflight.checks) {
+            const mark = c.ok ? chalk.green('✓') : chalk.red('✗');
+            log.dim(`  ${mark} ${CHECK_LABELS[c.name] ?? c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+        }
+        if (r.preflight.ok) {
+            log.success('Tudo certo para ligar. Nada foi alterado. Rode de novo sem --dry-run para ligar.');
+        }
+        else {
+            log.error('Algum requisito falhou — a porta de entrada não seria ligada. Nada foi alterado.');
+            setSafeExitCode(1);
+        }
+        return;
+    }
+    await confirmDestructive(`Ligar a porta de entrada do banco ${dbId} para a VM ${appServer}? O PgBouncer da VM do banco ` +
+        'reinicia uma vez (as conexões do app caem e voltam em segundos). Depois de ligada, TODO app ' +
+        'deste banco passa a falar com ele pelo IP interno da VM do banco — isso é testado antes de gravar.', { yes: opts.yes, json: opts.json });
+    // ── Voltas de POST longo (o Core anda só durante a chamada) ───────────────
+    const intervalMs = opts.pollIntervalMs ?? 3000;
+    const totalMs = opts.timeoutMs ?? 20 * 60 * 1000;
+    const waitSeconds = opts.waitSeconds ?? 240;
+    const inicio = Date.now();
+    const spinner = opts.json ? null : ora({ text: 'Ligando a porta de entrada…', color: 'blue' }).start();
+    let ultimoEstado = '';
+    const mostrar = (state) => {
+        if (state === ultimoEstado)
+            return;
+        ultimoEstado = state;
+        if (spinner)
+            spinner.text = STATE_LABELS[state] ?? state;
+    };
+    let volta = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (Date.now() - inicio >= totalMs) {
+            spinner?.fail('Prazo esgotado esperando a porta de entrada.');
+            const msg = 'A ligação continua registrada no Core e não mudou nada para o app. ' +
+                `Rode de novo \`neetru db frontdoor enable ${dbId} --app-server ${appServer} --reason "<motivo>"\` para retomar.`;
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, error: 'watch_timeout', dbId, message: msg }));
+            else
+                log.warn(msg);
+            setSafeExitCode(1);
+            return;
+        }
+        volta += 1;
+        const parar = spinner ? acompanharPassos(dbId, intervalMs, (op) => mostrar(op.state)) : () => undefined;
+        let r = null;
+        try {
+            r = await withStepUpRetry(
+            // O TOTP é de uso único: só a 1ª volta manda o `--mfa-token`; as
+            // retomadas usam a sessão de 1h (ou pedem um TOTP fresco).
+            { mfaToken: volta === 1 ? opts.mfaToken : undefined, json: opts.json, yes: opts.yes }, (headers) => apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`, {
+                method: 'POST',
+                body: { ...body, waitSeconds },
+                headers,
+                timeoutMs: (waitSeconds + 60) * 1000,
+            }), (err) => {
+                // POST longo que caiu por rede/tempo: o Core segue com a operação
+                // registrada — a próxima volta retoma.
+                if (err instanceof CliNetworkError)
+                    throw new RetomarVolta();
+                parar();
+                spinner?.fail('A porta de entrada NÃO foi ligada.');
+                return failFrontDoor(err, opts.json);
+            }, () => {
+                parar();
+                spinner?.stop();
+            });
+        }
+        catch (err) {
+            if (!(err instanceof RetomarVolta))
+                throw err;
+        }
+        finally {
+            parar();
+        }
+        if (!r) {
+            if (spinner)
+                spinner.text = 'Conexão com o Core caiu — retomando…';
+            await sleep(Math.min(intervalMs, 3000));
+            continue;
+        }
+        mostrar(r.state);
+        if (r.done) {
+            // Só o `frontDoorHost` do cadastro diz que a porta está ligada. O Core #727
+            // grava `frontDoorCertNotAfter` antes (no despacho do preparo), inclusive
+            // em operação que depois falha — esse campo NUNCA é prova de "ligada".
+            const hostLigado = r.ledger?.frontDoorHost ?? null;
+            if (!hostLigado) {
+                spinner?.fail('A porta de entrada NÃO aparece ligada no cadastro do banco.');
+                const msg = `O Core respondeu que terminou, mas o cadastro do banco ${dbId} não tem o endereço da porta de entrada — ` +
+                    `nada é dado como ligado. Confira com \`neetru db frontdoor status ${dbId}\`.`;
+                if (opts.json)
+                    console.log(JSON.stringify({ ok: false, error: 'not_recorded', dbId, message: msg }));
+                else
+                    log.error(msg);
+                setSafeExitCode(1);
+                return;
+            }
+            spinner?.succeed(r.alreadyEnabled ? 'A porta de entrada já estava ligada.' : 'Porta de entrada LIGADA.');
+            if (opts.json) {
+                console.log(JSON.stringify(r));
+                return;
+            }
+            const op = r.op;
+            if (r.alreadyEnabled) {
+                log.info(`Já estava ligada para a VM ${appServer} — nada mudou.`);
+            }
+            else {
+                log.success(`O banco ${dbId} agora atende a VM ${appServer} pelo IP interno ${hostLigado}:${op?.port ?? 5433}.`);
+                log.dim('  Vale para todo app deste banco, inclusive o que ainda roda na VM do banco ' +
+                    '(o login por esse caminho foi testado lá antes de gravar).');
+            }
+            const vence = r.ledger?.frontDoorCertNotAfter;
+            if (vence)
+                log.dim(`  Certificado do PgBouncer vence em: ${vence}`);
+            log.info(`Próximo passo: faça o deploy do app na VM ${appServer} e confira login e uma operação real.`);
+            return;
+        }
+        if (!isInFlight(r.state)) {
+            // Não deveria acontecer (o Core responde erro na falha), mas sem mentir:
+            const code = r.op?.lastError?.code ?? `FRONT_DOOR_${String(r.state).toUpperCase()}`;
+            const message = r.op?.lastError?.message ?? `Operação terminou em ${r.state}.`;
+            spinner?.fail('A porta de entrada NÃO foi ligada.');
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, error: code, message, guidance: FRONT_DOOR_GUIDANCE[code] ?? null }));
+            }
+            else {
+                log.error(describeFrontDoorError(code, message));
+            }
+            setSafeExitCode(1);
+            return;
+        }
+        // Ainda andando depois da espera do Core: chama de novo (retoma a mesma operação).
+        await sleep(Math.min(intervalMs, 3000));
+    }
+}
+// ---------------------------------------------------------------------------
+// neetru db frontdoor status <dbId>
+// ---------------------------------------------------------------------------
+export async function runDbFrontdoorStatus(dbId, opts = {}) {
+    await requireToken(opts.json);
+    let s;
+    try {
+        s = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+    }
+    catch (err) {
+        failFrontDoor(err, opts.json);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(s));
+        return;
+    }
+    log.heading(`Porta de entrada do banco ${s.dbId}`);
+    log.info(`VM do banco:    ${s.ledger.serverId ?? '—'}`);
+    log.info(`Porta:          ${s.ledger.frontDoorHost
+        ? chalk.green(`ligada em ${s.ledger.frontDoorHost}:5433`)
+        : 'desligada — o app recebe o endereço local da VM do banco'}`);
+    if (s.ledger.frontDoorCertNotAfter) {
+        log.dim(`  certificado do PgBouncer vence em: ${s.ledger.frontDoorCertNotAfter}` +
+            (s.ledger.frontDoorHost ? '' : ' (ele segue na VM do banco mesmo com a porta desligada)'));
+    }
+    const op = s.op;
+    if (!op) {
+        log.dim('  Nenhuma ligação feita por este comando até agora.');
+        return;
+    }
+    log.heading('Última operação');
+    log.info(`Estado:         ${STATE_LABELS[op.state] ?? op.state}`);
+    log.info(`VM do app:      ${op.appServerId}${op.allowedClientCidr ? ` (liberada: ${op.allowedClientCidr})` : ''}`);
+    log.dim(`  pedido: ${op.reason}`);
+    if (op.preparedAt)
+        log.dim(`  preparado na VM do banco em: ${op.preparedAt}`);
+    if (op.appVerifiedAt)
+        log.dim(`  testado a partir da VM do app em: ${op.appVerifiedAt}`);
+    if (op.localVerifiedAt)
+        log.dim(`  login testado na VM do banco em: ${op.localVerifiedAt}`);
+    if (op.enabledAt)
+        log.dim(`  ligada em: ${op.enabledAt}`);
+    if (op.failedAt)
+        log.dim(`  falhou em: ${op.failedAt}`);
+    if (op.cancelledAt)
+        log.dim(`  cancelada em: ${op.cancelledAt}`);
+    if (op.disabledAt)
+        log.dim(`  desligada em: ${op.disabledAt}`);
+    if (op.lastError)
+        log.warn(describeFrontDoorError(op.lastError.code, op.lastError.message));
+    if (isInFlight(op.state)) {
+        log.warn('Esta ligação só anda enquanto o comando de ligar estiver rodando. Para concluir, rode de novo ' +
+            `\`neetru db frontdoor enable ${s.dbId} --app-server ${op.appServerId} --reason "<motivo>"\`; ` +
+            `para cancelar, \`neetru db frontdoor disable ${s.dbId} --reason "<motivo>"\`.`);
+    }
+}
+/** Uma pergunta no terminal (a confirmação forte do `disable --force`). */
+function perguntar(pergunta) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(`  ${pergunta} `, (resposta) => {
+            rl.close();
+            resolve(resposta.trim());
+        });
+    });
+}
+/**
+ * Desligar (desfazer) — regras do Core #727 (rodada 2), decididas na transação:
+ *  - porta LIGADA por este comando pra um app noutra VM (o desfazer normal) ⇒
+ *    exige `--force`; idem quando não se sabe em que VM o app roda;
+ *  - ligação em curso sem endereço gravado ⇒ só cancela, sem `--force`;
+ *  - endereço gravado por OUTRA origem (ex.: mudança de VM do banco) nunca é
+ *    tirado por aqui: `host_kept` (cancelou a ligação em curso) ou
+ *    `FRONT_DOOR_HOST_NOT_OWNED` (409, nem com `--force`).
+ * Com `--force` a confirmação é forte: digitar o id do banco (ou `--yes`).
+ */
+export async function runDbFrontdoorDisable(dbId, opts = {}) {
+    if (!opts.json)
+        log.banner();
+    if (!dbId || !dbId.trim())
+        inputError('Informe o id do banco (pdb_…).', opts.json);
+    if (!opts.reason || !opts.reason.trim()) {
+        inputError('--reason "<texto>" é obrigatório (vai para o registro de auditoria).', opts.json);
+    }
+    await requireToken(opts.json);
+    let before = null;
+    try {
+        before = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+    }
+    catch (err) {
+        if (!(err instanceof CliNetworkError))
+            failFrontDoor(err, opts.json);
+    }
+    const host = before?.ledger.frontDoorHost ?? null;
+    const dbServer = before?.ledger.serverId ?? null;
+    const opAntes = before?.op ?? null;
+    // A VM do app que a porta ligada atende (se a porta é deste comando e está ligada).
+    const appLigado = host && opAntes && opAntes.state === 'enabled' && opAntes.host === host && opAntes.dbServerId === dbServer
+        ? opAntes.appServerId
+        : null;
+    const appNoutraVm = appLigado && appLigado !== dbServer ? appLigado : null;
+    const vmDoBanco = dbServer ?? 'VM do banco';
+    // ── Desfazer uma porta ligada pede --force: explica ANTES de pedir MFA. ──
+    if (appNoutraVm && !opts.force) {
+        const msg = `A porta de entrada está ligada para a VM do app ${appNoutraVm}. Desligar exige --force: o app volta a ` +
+            `receber o endereço local da VM do banco ${vmDoBanco}, e um app que ainda rode em ${appNoutraVm} FICA SEM ` +
+            'BANCO até voltar para a VM do banco.';
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: 'FRONT_DOOR_APP_ON_OTHER_VM',
+                message: msg,
+                guidance: FRONT_DOOR_GUIDANCE.FRONT_DOOR_APP_ON_OTHER_VM,
+            }));
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+    }
+    if (opts.force) {
+        const efeito = `Desligar com --force: o app deixa de receber o IP interno${host ? ` ${host}:5433` : ''} e volta para o ` +
+            `endereço local da VM ${vmDoBanco}. ` +
+            (appNoutraVm
+                ? `Se o app ainda roda em ${appNoutraVm}, ele CAI (fica sem banco) até voltar para a VM do banco.`
+                : 'Um app que rode em outra VM CAI (fica sem banco).');
+        if (!opts.yes) {
+            if (opts.json || !process.stdin.isTTY) {
+                const msg = 'Desligar com --force pede confirmação forte: digite o id do banco num terminal interativo, ' +
+                    'ou passe --yes junto com --force.';
+                if (opts.json)
+                    console.log(JSON.stringify({ ok: false, error: 'confirmation_required', message: msg }));
+                else
+                    log.error(msg);
+                safeExit(1);
+            }
+            log.warn(efeito);
+            const digitado = await perguntar(`Para confirmar, digite o id do banco (${dbId}):`);
+            if (digitado !== dbId) {
+                log.error('O id não conferiu. Nada foi alterado.');
+                safeExit(1);
+            }
+        }
+        else if (!opts.json) {
+            log.warn(efeito);
+        }
+    }
+    else {
+        await confirmDestructive(`Desligar a porta de entrada do banco ${dbId}? O app volta a receber o endereço local da VM ${vmDoBanco}` +
+            (host ? ` (hoje recebe ${host}:5433)` : '') +
+            '. Uma ligação em andamento é cancelada.', { yes: opts.yes, json: opts.json });
+    }
+    const spinner = opts.json ? null : ora({ text: 'Desligando a porta de entrada…', color: 'blue' }).start();
+    const r = await withStepUpRetry({ mfaToken: opts.mfaToken, json: opts.json, yes: opts.yes }, (headers) => apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor/disable`, {
+        method: 'POST',
+        body: { reason: opts.reason.trim(), ...(opts.force ? { force: true } : {}) },
+        headers,
+    }), (err) => {
+        spinner?.fail('A porta de entrada NÃO foi desligada.');
+        return failFrontDoor(err, opts.json);
+    }, () => spinner?.stop());
+    spinner?.stop();
+    if (opts.json) {
+        console.log(JSON.stringify(r));
+        return;
+    }
+    const vmFinal = r.ledger?.serverId ?? vmDoBanco;
+    if (r.outcome === 'already_disabled') {
+        log.info('A porta de entrada já estava desligada — o endereço do app não mudou.');
+    }
+    else if (r.outcome === 'host_kept') {
+        log.warn(`A ligação em andamento (${r.opId}) foi cancelada, mas o endereço gravado no cadastro` +
+            `${r.previousFrontDoorHost ? ` (${r.previousFrontDoorHost}:5433)` : ''} não é desta porta de entrada ` +
+            '(veio de outra origem, por exemplo uma mudança de VM do banco) e FICOU como estava.');
+    }
+    else {
+        log.success(`Porta de entrada DESLIGADA. O app volta a receber o endereço local da VM ${vmFinal}` +
+            `${r.previousFrontDoorHost ? ` (antes: ${r.previousFrontDoorHost}:5433)` : ''}.`);
+        if (appNoutraVm) {
+            log.warn(`Se o app ainda roda em ${appNoutraVm}, ele está SEM BANCO agora — leve-o para a VM ${vmFinal}.`);
+        }
+    }
+    if (r.opTransition === 'cancelled' && r.outcome !== 'host_kept') {
+        log.warn(`A ligação que estava em andamento (${r.opId}) foi cancelada.`);
+    }
+    log.dim('  Na VM do banco o PgBouncer segue escutando no IP interno, liberado só para a VM do app — ' +
+        'isso não é desfeito por este comando.');
+}
+//# sourceMappingURL=db-frontdoor.js.map

package/dist/commands/db-move.d.ts

@@ -182,6 +182,11 @@ export interface DbMoveStartOptions {
     /** Somente testes: teto do wall-clock do poll (ms). Default 30min. */
     pollTimeoutMs?: number;
 }
+/**
+ * Recusas do KICKOFF (`POST /db/{id}/relocate`) com código estável e o que
+ * fazer, em PT-BR. As outras recusas seguem pelo tratamento comum.
+ */
+export declare const RELOCATE_START_REFUSAL_GUIDANCE: Record<string, string>;
 export declare function runDbMoveStart(opts: DbMoveStartOptions): Promise<void>;
 /**
  * Acompanha a máquina de estados até um estado terminal (done/rolled_back/failed)

package/dist/commands/db-move.js

@@ -283,6 +283,17 @@ async function resolveTargetDb(opts) {
     }
     return { dbId: dbs[0].id, source: dbs[0] };
 }
+/**
+ * Recusas do KICKOFF (`POST /db/{id}/relocate`) com código estável e o que
+ * fazer, em PT-BR. As outras recusas seguem pelo tratamento comum.
+ */
+export const RELOCATE_START_REFUSAL_GUIDANCE = {
+    // Core #727: o preflight do relocate recusa enquanto uma ligação da porta de
+    // entrada do banco (`neetru db frontdoor`) estiver em andamento.
+    RELOCATE_FRONT_DOOR_OP_IN_PROGRESS: 'Há uma ligação da porta de entrada deste banco em andamento. Espere ela terminar ' +
+        '(acompanhe com `neetru db frontdoor status <dbId>`) ou cancele com ' +
+        '`neetru db frontdoor disable <dbId> --reason "<motivo>"`, e então rode a mudança de VM de novo.',
+};
 export async function runDbMoveStart(opts) {
     if (!opts.json)
         log.banner();
@@ -371,6 +382,22 @@ export async function runDbMoveStart(opts) {
     }
     catch (err) {
         spinner?.fail('Falha ao iniciar relocação.');
+        // Recusa conhecida do kickoff (409 com código estável) ⇒ o que significa +
+        // o que fazer, em vez da mensagem genérica.
+        if (err instanceof CliApiError && RELOCATE_START_REFUSAL_GUIDANCE[err.code]) {
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    error: err.code,
+                    message: err.message,
+                    guidance: RELOCATE_START_REFUSAL_GUIDANCE[err.code],
+                }));
+            }
+            else {
+                log.error(`${err.message}\n  ${RELOCATE_START_REFUSAL_GUIDANCE[err.code]}`);
+            }
+            safeExit(1);
+        }
         handleApiError(err, opts.json);
     }
     // ── Dry-run: só o preflight. Nada foi provisionado. ─────────────────────────

package/dist/commands/db.js

@@ -37,16 +37,10 @@ import { exitWithCliError } from '../lib/cli-error.js';
 import { safeExit } from '../utils/safe-exit.js';
 import { runApplyPipeline, runExecSqlPipeline, buildPipelineDeps, isPipelineError, } from '../lib/db-pipeline/index.js';
 import { resolveStepUp } from '../lib/cli-write.js';
+import { carregarInquirer } from '../lib/inquirer-sob-demanda.js';
 import { loadProductConfig } from '../lib/product-config.js';
-/**
- * `inquirer` sob demanda (bug_b1e9af59): ~0,5s de carga, e so os prompts
- * interativos usam. Era o unico import estatico dele no grafo de `neetru db`
- * — `db list`/`db status`/`db apply --json` (e os testes) pagavam a carga sem
- * nunca perguntar nada.
- */
-async function carregarInquirer() {
-    return (await import('inquirer')).default;
-}
+// `inquirer` sob demanda (bug_b1e9af59): só os prompts interativos o carregam,
+// pelo `carregarInquirer()` único de `lib/inquirer-sob-demanda.ts` (P115).
 // ---------------------------------------------------------------------------
 // Constantes e tipos locais
 // ---------------------------------------------------------------------------