@neetru/cli 2.26.6 → 2.27.1

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 Convenção: [Keep a Changelog](https://keepachangelog.com/) + [SemVer](https://semver.org/).
 
+## [2.27.1] — 2026-08-03 (diagnóstico acionável quando `db migrations confirm` falha)
+
+> Correção do que o 2.27.0 assumiu errado: `exec-sql`/`db apply` SEMPRE conectam
+> no Postgres como a role do app (via agente na VM, privilégio mínimo — nunca
+> superuser), então NENHUM dos dois alcança um fix real de ownership drift —
+> `ALTER TABLE ... OWNER TO` exige ser o dono atual ou superuser. Isso só foi
+> descoberto ao vivo, em produção, com o pdv-agiliza: `exec-sql` classificou o
+> `ALTER TABLE idempotency_keys OWNER TO app_ae263834e537;` como destrutiva
+> corretamente, mas a migração falhou com `must be owner of table` mesmo após
+> confirmar com MFA — 2 tentativas reais queimadas até entender a causa, porque
+> `db migrations confirm` só reportava `status: failed`, sem mostrar o erro.
+>
+> O fix de ownership em si PRECISA de uma conexão superuser local na VM — fora
+> do escopo deste CLI por design (ver runbook interno). O que este release
+> resolve é a experiência de diagnóstico: `db migrations confirm` agora busca
+> o erro real automaticamente e, para padrões conhecidos (ownership drift),
+> mostra de cara que retry não resolve e qual o próximo passo.
+
+### Corrigido
+
+- `neetru db migrations confirm <id>`: quando o resultado é `status: 'failed'`, busca automaticamente o detalhe da migração (mesma chamada de `db migrations show`) e imprime o erro real — antes só aparecia "status: failed", exigindo um segundo comando pra descobrir o motivo.
+- Diagnóstico acionável para o padrão `must be owner of` (ownership drift): explica que NÃO é falha transitória, que `db apply`/`exec-sql` nunca alcançam esse fix (conectam sempre como a role do app), e dá o comando exato (`gcloud compute ssh ... --tunnel-through-iap` + `sudo -u postgres psql`) pra resolver manualmente, uma vez.
+
+### Verificação
+
+- 1143 testes (suíte completa, +2 novos cobrindo o caminho `failed` com/sem diagnóstico conhecido), tsc limpo.
+
+## [2.27.0] — 2026-07-28 (novo: `neetru db exec-sql` — SQL administrativo avulso pelo mesmo pipeline de segurança)
+
+> Incidente pdv-agiliza: uma tabela (`idempotency_keys`) ficou com owner errado (`postgres` em vez de `app_ae263834e537`) por drift de uma recuperação de incidente fora do pipeline — bloqueando `ADD CONSTRAINT` (exige ser owner). O fix é 1 linha (`ALTER TABLE idempotency_keys OWNER TO app_ae263834e537;`), mas não existia um jeito de rodar SQL administrativo avulso contra produção: `neetru db apply` só aceita SQL gerado de `schema.ts` via drizzle-kit. Investigação confirmou que `POST /api/cli/v1/db/apply` já aceita `sql` livre no Core (audit+lock+classify+MFA-gate iguais a qualquer migração) — só faltava o CLI expor isso.
+
+### Adicionado
+
+- `neetru db exec-sql --sql "<SQL>"` (ou `--file <caminho.sql>`) — roda 1 instrução SQL administrativa pelo MESMO pipeline de `db apply` (rehearse → classify → push, mesmo gate de MFA se destrutivo). Não é um jeito de contornar o schema.ts declarativo pra mudanças de rotina — é uma válvula de escape auditada pra correções administrativas pontuais (ex.: drift de ownership).
+- `--skip-rehearse` (mesmo contrato do `db apply`, aviso obrigatório) — necessário quando o SQL depende de estado que só existe em produção (ex.: uma role específica que não existe no Postgres efêmero em branco).
+
+### Corrigido (achado em code review adversarial antes de publicar)
+
+- A confirmação interativa rodava ANTES do pipeline — o operador confirmava "sim, rodar" sem saber se o SQL classificaria como aditivo ou destrutivo. Movida pra DEPOIS de rehearse+classify (via novo hook `confirmBeforePush`), mostrando a severidade real antes de perguntar.
+
+### Verificação
+
+- 1141 testes (suíte completa), tsc limpo.
+- Codex review adversarial: sem bypass de MFA — `exec-sql` reusa o MESMO `@neetru/db-classifier` sem parser paralelo; achou a lacuna de ordem de confirmação (corrigida acima) e confirmou que o risco de `dbId`/diretório errado é herdado de `db apply`, não uma regressão nova.
+
 ## [2.26.6] — 2026-07-28 (fix crítico: DDL de `neetru db apply` não era idempotente — CREATE TYPE, CREATE TABLE, CREATE INDEX, ADD CONSTRAINT)
 
 > Depois de 2.26.4/2.26.5 resolverem `--dialect` e o path Windows, o pdv-agiliza aplicou a migração e chegou até o Core — mas quebrou em `type "ft_entity_type" already exists`. Causa raiz: a premissa de que `drizzle-kit generate` embrulha `CREATE TYPE` num guard idempotente por padrão (escrita no fix da 2.26.3) estava ERRADA — confirmado ao vivo contra o schema real que `generate` emite DDL puro, sem guard nenhum, pra CREATE TYPE **nem** CREATE TABLE/INDEX/ADD CONSTRAINT. Qualquer produto com enum/FK no schema colide com "already exists" assim que o objeto existir no banco por qualquer via fora do pipeline (ex.: recuperação de incidente) — não é bug do schema do produto.

package/dist/commands/db.d.ts

@@ -52,6 +52,37 @@ export interface DbApplyOptions {
     skipRehearse?: boolean;
 }
 export declare function runDbApply(opts?: DbApplyOptions): Promise<void>;
+export interface DbExecSqlOptions {
+    dbName?: string;
+    env?: string;
+    /** SQL inline — mutuamente exclusivo com `filePath`. */
+    sql?: string;
+    /** Caminho de um arquivo .sql — mutuamente exclusivo com `sql`. */
+    filePath?: string;
+    dryRun?: boolean;
+    yes?: boolean;
+    json?: boolean;
+    /** Mesmo contrato de `DbApplyOptions.skipRehearse` — precisa ser logado. */
+    skipRehearse?: boolean;
+}
+/**
+ * `neetru db exec-sql` — roda UMA instrução SQL administrativa avulsa contra
+ * o banco de um produto, pelo MESMO pipeline de segurança do `db apply`
+ * (rehearse → classify → push ao Core, com o MESMO gate de MFA se a
+ * classificação for destrutiva).
+ *
+ * bug_pdv_ownership_drift_2026-07-28: existe pra corrigir drift administrativo
+ * que não é parte do schema declarativo do produto (ex.: `ALTER TABLE x OWNER
+ * TO y` depois de uma tabela ter sido criada fora do pipeline numa recuperação
+ * de incidente) — sem isto, o único jeito de rodar SQL avulso contra produção
+ * seria chamar `/api/cli/v1/db/apply` manualmente por fora do CLI (o endpoint
+ * já aceita `sql` livre; isto só expõe essa capacidade já existente do Core).
+ *
+ * NÃO é um jeito de contornar o schema.ts declarativo pra mudanças de rotina
+ * — é uma válvula de escape auditada (mesmo lock/classify/MFA-gate do
+ * `db apply`) pra correções administrativas pontuais.
+ */
+export declare function runDbExecSql(opts?: DbExecSqlOptions): Promise<void>;
 export interface DbMigrationsListOptions {
     dbId?: string;
     json?: boolean;

package/dist/commands/db.js

@@ -32,7 +32,7 @@ import { handleApiError } from '../lib/api-error.js';
 import { renderTable, fmtTimestamp } from '../lib/render.js';
 import { readDbJson, writeDbJson, normalizeEnv, } from '../lib/db-local/index.js';
 import { safeExit } from '../utils/safe-exit.js';
-import { runApplyPipeline, buildPipelineDeps, isPipelineError, } from '../lib/db-pipeline/index.js';
+import { runApplyPipeline, runExecSqlPipeline, buildPipelineDeps, isPipelineError, } from '../lib/db-pipeline/index.js';
 import { resolveStepUp } from '../lib/cli-write.js';
 // ---------------------------------------------------------------------------
 // Constantes e tipos locais
@@ -73,6 +73,31 @@ const ENGINE_LABELS = {
     'vm-mysql-cluster': 'VM — MySQL (cluster HA)',
     'nosql-vm': 'VM — MongoDB/NoSQL (self-hosted)',
 };
+/**
+ * bug_pdv_ownership_drift_2026-08-03: diagnóstico amigável pra erros
+ * conhecidos do Postgres/MySQL que o operador vai bater sem contexto — sem
+ * isso, `db migrations confirm` só mostrava "status: failed" e o operador
+ * tinha que rodar `db migrations show` à parte pra ver o erro cru do driver,
+ * e MESMO ASSIM não sabia o que fazer (queimou 2 tentativas de MFA achando
+ * que era falha transitória, quando era ownership drift — impossível de
+ * corrigir via `db apply`/`exec-sql`, que sempre conecta como a role app,
+ * nunca como superuser). Cada entrada aqui é (regex do erro cru → mensagem
+ * acionável). `null` de `diagnoseMigrationError` = sem padrão conhecido,
+ * mostra só o erro cru (comportamento anterior).
+ */
+function diagnoseMigrationError(rawError) {
+    if (/must be owner of/i.test(rawError)) {
+        return ('Isso é ownership drift, não falha transitória — NÃO adianta tentar de novo. ' +
+            'A tabela foi criada fora do fluxo normal (ex.: recuperação manual) e pertence a ' +
+            'outra role. `db apply`/`db exec-sql` SEMPRE conectam como a role do app (privilégio ' +
+            'mínimo, por design) — nenhum dos dois alcança um fix de ownership, mesmo com MFA. ' +
+            'Precisa de UMA conexão superuser local na VM, uma única vez:\n' +
+            '    gcloud compute ssh <vm> --zone=<zona> --project=<projeto> --tunnel-through-iap\n' +
+            '    sudo -u postgres psql -d <database> -c \'ALTER TABLE <tabela> OWNER TO <role_app>;\'\n' +
+            '  Ache <vm>/<zona> com `neetru db status <dbId>` (serverId) + `neetru servers list`.');
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // Helpers internos
 // ---------------------------------------------------------------------------
@@ -926,6 +951,301 @@ export async function runDbApply(opts = {}) {
         log.success(`Migração ${chalk.bold(result.migrationId)} enviada ao Core (${result.status}).`);
     }
 }
+/**
+ * `neetru db exec-sql` — roda UMA instrução SQL administrativa avulsa contra
+ * o banco de um produto, pelo MESMO pipeline de segurança do `db apply`
+ * (rehearse → classify → push ao Core, com o MESMO gate de MFA se a
+ * classificação for destrutiva).
+ *
+ * bug_pdv_ownership_drift_2026-07-28: existe pra corrigir drift administrativo
+ * que não é parte do schema declarativo do produto (ex.: `ALTER TABLE x OWNER
+ * TO y` depois de uma tabela ter sido criada fora do pipeline numa recuperação
+ * de incidente) — sem isto, o único jeito de rodar SQL avulso contra produção
+ * seria chamar `/api/cli/v1/db/apply` manualmente por fora do CLI (o endpoint
+ * já aceita `sql` livre; isto só expõe essa capacidade já existente do Core).
+ *
+ * NÃO é um jeito de contornar o schema.ts declarativo pra mudanças de rotina
+ * — é uma válvula de escape auditada (mesmo lock/classify/MFA-gate do
+ * `db apply`) pra correções administrativas pontuais.
+ */
+export async function runDbExecSql(opts = {}) {
+    if (!opts.json) {
+        log.banner();
+        log.heading('neetru db exec-sql');
+    }
+    if (!opts.sql && !opts.filePath) {
+        const msg = 'Forneça --sql "<SQL>" ou --file <caminho.sql>.';
+        if (opts.json) {
+            jsonError(msg, 'sql_required');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    if (opts.sql && opts.filePath) {
+        const msg = '--sql e --file são mutuamente exclusivos. Use só um.';
+        if (opts.json) {
+            jsonError(msg, 'sql_and_file_conflict');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    let sql;
+    if (opts.filePath) {
+        const sqlAbs = path.resolve(process.cwd(), opts.filePath);
+        if (!fsSync.existsSync(sqlAbs)) {
+            const msg = `Arquivo não encontrado: ${opts.filePath}`;
+            if (opts.json) {
+                jsonError(msg, 'file_not_found');
+            }
+            else {
+                log.error(msg);
+            }
+            safeExit(1);
+            return;
+        }
+        sql = fsSync.readFileSync(sqlAbs, 'utf8');
+    }
+    else {
+        sql = opts.sql;
+    }
+    if (sql.trim().length === 0) {
+        const msg = 'SQL vazio — nada para executar.';
+        if (opts.json) {
+            jsonError(msg, 'sql_empty');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    const cfg = await loadProductConfig();
+    if (!cfg) {
+        const msg = 'neetru.config.json não encontrado. Rode `neetru init` primeiro.';
+        if (opts.json) {
+            jsonError(msg, 'config_not_found');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    const cwd = process.cwd();
+    const dbJsonPath = path.resolve(cwd, DB_JSON_REL);
+    const dbJson = readDbJson(dbJsonPath);
+    if (dbJson.databases.length === 0) {
+        const msg = 'Nenhum banco registrado em .neetru/db.json. Rode `neetru db init` primeiro.';
+        if (opts.json) {
+            jsonError(msg, 'no_databases');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    let dbEntry = dbJson.databases[0];
+    if (opts.dbName) {
+        const found = dbJson.databases.find((d) => d.name === opts.dbName);
+        if (!found) {
+            const msg = `Banco "${opts.dbName}" não encontrado em .neetru/db.json. Disponíveis: ${dbJson.databases.map((d) => d.name).join(', ')}`;
+            if (opts.json) {
+                jsonError(msg, 'db_not_found');
+            }
+            else {
+                log.error(msg);
+            }
+            safeExit(1);
+            return;
+        }
+        dbEntry = found;
+    }
+    else if (dbJson.databases.length > 1) {
+        const msg = 'Múltiplos bancos em .neetru/db.json. Use --db <nome>.';
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, error: 'db_required', message: msg, available: dbJson.databases.map((d) => d.name) }));
+        }
+        else {
+            log.error(msg);
+            log.dim(`  Bancos disponíveis: ${dbJson.databases.map((d) => d.name).join(', ')}`);
+        }
+        safeExit(1);
+        return;
+    }
+    if (NOSQL_ENGINES.includes(dbEntry.engine)) {
+        const msg = `Banco "${dbEntry.name}" é engine NoSQL (${dbEntry.engine}) — exec-sql só vale pra engines SQL.`;
+        if (opts.json) {
+            jsonError(msg, 'engine_not_sql');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    let env;
+    try {
+        env = normalizeEnv(opts.env ?? 'dev-local');
+    }
+    catch {
+        const msg = `Ambiente inválido: "${opts.env}". Use dev-local, staging ou production.`;
+        if (opts.json) {
+            jsonError(msg, 'invalid_env');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    const canonicalEnv = env;
+    const dbId = dbEntry.ids[canonicalEnv];
+    if (!dbId) {
+        const msg = `Banco "${dbEntry.name}" não tem ID registrado para o ambiente "${env}". Execute \`neetru db init\` novamente ou verifique .neetru/db.json.`;
+        if (opts.json) {
+            jsonError(msg, 'missing_db_id');
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+        return;
+    }
+    const rehearseEngine = dbEntry.engine.includes('mysql') ? 'mysql' : 'postgres';
+    if (!opts.json) {
+        log.dim(`  Banco:   ${dbEntry.name} (${dbEntry.engine})`);
+        log.dim(`  Env:     ${env}`);
+        log.dim(`  DB ID:   ${dbId}`);
+        log.dim('');
+        log.dim('  SQL:');
+        for (const line of sql.trim().split('\n'))
+            log.dim(`    ${line}`);
+        log.dim('');
+        if (opts.dryRun)
+            log.warn('  Modo --dry-run: nenhuma alteração será enviada ao Core.');
+    }
+    // Mesmo contrato de aviso obrigatório que `db apply` (bug_pdv_rehearse_2026-07-27).
+    if (opts.skipRehearse) {
+        const msg = 'AVISO: --skip-rehearse ativo — o ensaio local (Postgres/MySQL efêmero) ' +
+            'foi pulado. O SQL NÃO foi validado localmente; o Core/agente ainda vai ' +
+            'rodá-lo contra a VM real.';
+        if (opts.json) {
+            process.stderr.write(JSON.stringify({ warning: msg }) + '\n');
+        }
+        else {
+            log.warn(msg);
+        }
+    }
+    const phaseLabels = {
+        rehearse: `Ensaiando em ${rehearseEngine === 'mysql' ? 'MySQL' : 'Postgres'} efêmero…`,
+        classify: 'Classificando…',
+        push: 'Enviando ao Core…',
+    };
+    let spinner = opts.json ? null : ora({ text: 'Iniciando…', color: 'blue' }).start();
+    let result;
+    try {
+        const deps = buildPipelineDeps({
+            onPhase: (phase) => {
+                if (spinner)
+                    spinner.text = phaseLabels[phase] ?? phase;
+            },
+            ...(opts.dryRun
+                ? {
+                    pushToCore: async () => {
+                        return { migrationId: '(dry-run)', status: 'dry_run' };
+                    },
+                }
+                : {}),
+        }, rehearseEngine, !!opts.skipRehearse);
+        // BUG FIX (Codex review adversarial, bug_pdv_ownership_drift_2026-07-28):
+        // a confirmação rodava ANTES do pipeline — o operador confirmava "sim" às
+        // cegas, sem saber se o SQL ia classificar como aditivo ou destrutivo.
+        // Movido pra DEPOIS de rehearse+classify (via `confirmBeforePush`), pra
+        // mostrar a severidade real antes de perguntar.
+        const execDeps = {
+            ...deps,
+            confirmBeforePush: opts.yes || opts.json
+                ? undefined
+                : async ({ classification }) => {
+                    spinner?.stop();
+                    log.dim('');
+                    log.dim(`  Severidade:   ${severityColor(classification.overallSeverity)}`);
+                    const { confirmed } = await inquirer.prompt([
+                        {
+                            type: 'confirm',
+                            name: 'confirmed',
+                            message: `Executar este SQL (${classification.overallSeverity}) contra "${dbEntry.name}" (${env})?`,
+                            default: false,
+                        },
+                    ]);
+                    if (confirmed)
+                        spinner = ora({ text: 'Enviando ao Core…', color: 'blue' }).start();
+                    return confirmed;
+                },
+        };
+        result = await runExecSqlPipeline({ sql, env: canonicalEnv, dbId }, execDeps);
+        spinner?.stop();
+        if (result.status === 'cancelled') {
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, status: 'cancelled' }));
+            }
+            else {
+                log.dim('Cancelado.');
+            }
+            return;
+        }
+    }
+    catch (err) {
+        spinner?.fail('Pipeline falhou.');
+        if (isPipelineError(err)) {
+            const pe = err;
+            if (opts.json) {
+                jsonError(`Fase "${pe.phase}": ${pe.message}`, 'pipeline_failed');
+            }
+            else {
+                log.error(`Fase "${pe.phase}": ${pe.message}`);
+            }
+            safeExit(5);
+            return;
+        }
+        if (opts.json) {
+            jsonError(err.message ?? String(err), 'pipeline_failed');
+        }
+        else {
+            log.error(err.message ?? String(err));
+        }
+        safeExit(5);
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            status: result.status,
+            migrationId: result.migrationId ?? null,
+            severity: result.severity ?? null,
+            dryRun: !!opts.dryRun,
+        }));
+        return;
+    }
+    log.dim('');
+    log.dim(`  Severidade:   ${severityColor(result.severity)}`);
+    log.dim(`  Migração ID:  ${result.migrationId}`);
+    log.dim(`  Status:       ${result.status}`);
+    if (result.severity === 'destrutiva' && !opts.dryRun) {
+        log.warn('Este SQL é destrutivo e requer confirmação antes de ser aplicado.');
+        log.dim(`  Execute: neetru db migrations confirm ${result.migrationId} --mfa <token>`);
+    }
+    else if (!opts.dryRun) {
+        log.success(`SQL enviado ao Core como migração ${chalk.bold(result.migrationId)} (${result.status}).`);
+    }
+}
 export async function runDbMigrationsList(opts = {}) {
     log.banner();
     const qs = opts.dbId ? `?dbId=${encodeURIComponent(opts.dbId)}` : '';
@@ -984,8 +1304,34 @@ export async function runDbMigrationsConfirm(migrationId, opts) {
         spinner.fail('Falha ao confirmar migração.');
         handleApiError(err);
     }
+    // bug_pdv_ownership_drift_2026-08-03: `resp` (confirm) não carrega o erro —
+    // só {ok, migrationId, status}. Em `status: 'failed'`, busca o detalhe
+    // (mesmo endpoint de `db migrations show`) pra mostrar o erro real e um
+    // diagnóstico acionável AGORA, em vez do operador ter que rodar um segundo
+    // comando e ainda ficar sem saber que retry não resolve (ownership drift
+    // não é falha transitória — ver `diagnoseMigrationError`).
+    let detail;
+    if (resp.status === 'failed') {
+        try {
+            const detailResp = await apiRequest(`/api/cli/v1/db/migrations/${encodeURIComponent(resp.migrationId)}`);
+            detail = detailResp.migration;
+        }
+        catch {
+            // Best-effort — a confirmação em si já foi reportada acima.
+        }
+    }
     if (opts.json) {
-        console.log(JSON.stringify(resp, null, 2));
+        console.log(JSON.stringify(detail ? { ...resp, error: detail.error, diagnosis: diagnoseMigrationError(detail.error ?? '') } : resp, null, 2));
+        return;
+    }
+    if (detail?.error) {
+        log.dim('');
+        log.error(`  Erro: ${detail.error}`);
+        const diagnosis = diagnoseMigrationError(detail.error);
+        if (diagnosis) {
+            log.dim('');
+            log.warn(diagnosis);
+        }
     }
 }
 /**