@neetru/cli 2.8.0 → 2.9.3

package/dist/commands/db.js

@@ -46,6 +46,14 @@ const ENGINES = [
     'vm-mysql-single',
     'vm-mysql-cluster',
 ];
+/**
+ * Engines NoSQL — schemaless por natureza.
+ * Nesses engines o `neetru db apply` NÃO roda drizzle-kit nem Postgres efêmero:
+ * registra apenas um snapshot de fingerprint no Core (Fase 1 — sem JSON Schema export).
+ *
+ * Fase 2 (export de JSON Schema estruturado) é backlog — ticket pdv-agiliza #11.
+ */
+const NOSQL_ENGINES = ['nosql-vm', 'firestore-instance'];
 /** Labels amigáveis por engine pra exibição no prompt. */
 const ENGINE_LABELS = {
     'firestore-instance': 'Firestore (instância isolada)',
@@ -147,7 +155,8 @@ export async function runDbList(opts = {}) {
         { header: 'Produto', value: (r) => r.productId, maxWidth: 20 },
         { header: 'Label', value: (r) => r.label ?? '—', maxWidth: 24 },
         { header: 'Engine', value: (r) => r.engine, maxWidth: 22 },
-        { header: 'Env', value: (r) => r.env, maxWidth: 12 },
+        // gestovendas #11 fix: Core retorna `environment`; `env` é alias legado.
+        { header: 'Env', value: (r) => r.environment ?? r.env ?? '—', maxWidth: 12 },
         { header: 'Status', value: (r) => statusColor(r.status), maxWidth: 16 },
         { header: 'Criado', value: (r) => fmtTimestamp(r.createdAt), maxWidth: 18 },
     ], resp.databases);
@@ -180,7 +189,7 @@ export async function runDbStatus(dbId, opts = {}) {
     log.dim(`  ID:       ${db.id}`);
     log.dim(`  Produto:  ${db.productId}`);
     log.dim(`  Engine:   ${db.engine}`);
-    log.dim(`  Env:      ${db.env}`);
+    log.dim(`  Env:      ${db.environment ?? db.env ?? '—'}`);
     log.dim(`  Status:   ${statusColor(db.status)}`);
     if (db.region)
         log.dim(`  Região:   ${db.region}`);
@@ -198,8 +207,49 @@ export async function runDbStatus(dbId, opts = {}) {
     log.dim(`  Criado:   ${fmtTimestamp(db.createdAt)}`);
     log.dim(`  Atualizado: ${fmtTimestamp(db.updatedAt)}`);
 }
-/** Conteúdo do `db/schema.ts` gerado durante o init. */
-const SCHEMA_STARTER = (productId, engine) => `/**
+// pdv #7 fix: template diferenciado por família de engine.
+/** Template para engines NoSQL (firestore-instance). */
+const SCHEMA_STARTER_NOSQL = (productId, engine) => `/**
+ * Schema do banco "${productId}" — ${ENGINE_LABELS[engine] ?? engine}.
+ *
+ * Gerado por \`neetru db init\`.
+ * Edite este arquivo com as collections do seu produto.
+ * Rode \`neetru db apply\` pra enviar a definição ao Core.
+ *
+ * Para bancos NoSQL (Firestore), o schema define a estrutura esperada
+ * dos documentos. O Core usa essa definição para validação e auditoria —
+ * o banco em si é schemaless (primeira escrita cria a estrutura).
+ *
+ * Documentação: https://core.neetru.com/docs/dev/db/nosql-schema
+ */
+
+// Exemplo de collection com tipagem TypeScript pura:
+
+export interface Produto {
+  id: string;
+  nome: string;
+  preco: number;
+  ativo: boolean;
+  criadoEm: Date;
+}
+
+export interface Pedido {
+  id: string;
+  produtoId: string;
+  quantidade: number;
+  total: number;
+  status: 'pendente' | 'pago' | 'cancelado';
+  criadoEm: Date;
+}
+
+// Exporte as collections que o SDK vai usar:
+// import { createNeetruClient } from '@neetru/sdk';
+// const neetru = createNeetruClient({ ... });
+// const produtos = neetru.db.collection<Produto>('produtos');
+// const pedidos = neetru.db.collection<Pedido>('pedidos');
+`;
+/** Template padrão para engines SQL (PostgreSQL/MySQL). */
+const SCHEMA_STARTER_SQL = (productId, engine) => `/**
  * Schema do banco "${productId}" — ${ENGINE_LABELS[engine] ?? engine}.
  *
  * Gerado por \`neetru db init\`.
@@ -218,24 +268,46 @@ const SCHEMA_STARTER = (productId, engine) => `/**
 // Remova o comentário acima e adapte ao seu schema.
 export {};
 `;
+/** Conteúdo do `db/schema.ts` gerado durante o init. */
+const SCHEMA_STARTER = (productId, engine) => {
+    // Engines NoSQL recebem template diferente.
+    if (engine === 'firestore-instance') {
+        return SCHEMA_STARTER_NOSQL(productId, engine);
+    }
+    return SCHEMA_STARTER_SQL(productId, engine);
+};
+// gestovendas #9: helper para saída JSON uniforme em db init / db apply.
+function jsonError(message, error = 'error') {
+    console.log(JSON.stringify({ ok: false, error, message }));
+}
 export async function runDbInit(opts = {}) {
-    log.banner();
-    log.heading('neetru db init');
+    if (!opts.json) {
+        log.banner();
+        log.heading('neetru db init');
+    }
     // ── D-3: opções legadas removidas (Sprint 10 — schema.manifest.json) ────
     // `--out` e `--force` eram usados para gerar schema.manifest.json.
     // O branch legado foi cortado. Passar essas flags agora é um erro.
     if (opts.out !== undefined || opts.force !== undefined) {
-        log.error('As opções --out e --force foram removidas (D-3).\n' +
-            'O `neetru db init` agora faz UMA coisa: registra o banco no Core + ' +
-            'grava .neetru/db.json + scaffolda db/schema.ts.\n' +
-            'Para inicializar o banco, use:\n' +
-            '  neetru db init --name <nome> --engine <engine> --env dev-local');
+        const msg = 'As opções --out e --force foram removidas (D-3). Use: neetru db init --name <nome> --engine <engine> --env dev-local';
+        if (opts.json) {
+            jsonError(msg, 'invalid_option');
+        }
+        else {
+            log.error(msg);
+        }
         process.exit(1);
         return;
     }
     const cfg = await loadProductConfig();
     if (!cfg) {
-        log.error('neetru.config.json não encontrado. Rode `neetru init` primeiro.');
+        const msg = 'neetru.config.json não encontrado. Rode `neetru init` primeiro.';
+        if (opts.json) {
+            jsonError(msg, 'config_not_found');
+        }
+        else {
+            log.error(msg);
+        }
         process.exit(1);
         return;
     }
@@ -269,13 +341,34 @@ export async function runDbInit(opts = {}) {
         dbName = dbJson.databases.length === 0 ? 'principal' : `db${dbJson.databases.length + 1}`;
     }
     if (dbJson.databases.some((d) => d.name === dbName)) {
-        log.error(`Banco "${dbName}" já registrado. Use outro nome ou edite .neetru/db.json.`);
+        const msg = `Banco "${dbName}" já registrado. Use outro nome ou edite .neetru/db.json.`;
+        if (opts.json) {
+            jsonError(msg, 'duplicate_name');
+        }
+        else {
+            log.error(msg);
+        }
         process.exit(2);
         return;
     }
     // ── engine ───────────────────────────────────────────────────────────────
+    // pdv #4 fix: quando --engine é passado mas não reconhecido, abortar com
+    // mensagem clara em vez de ignorar silenciosamente e usar o default.
     let engine;
-    if (opts.engine && ENGINES.includes(opts.engine)) {
+    if (opts.engine) {
+        if (!ENGINES.includes(opts.engine)) {
+            const msg = `Engine inválido: "${opts.engine}". Engines disponíveis: ${ENGINES.join(', ')}\n` +
+                `Nota: o campo "engine" no SDK (rest | firestore | nosql-vm) é o TRANSPORTE da conexão, ` +
+                `diferente do engine de ARMAZENAMENTO passado aqui para o plano de controle.`;
+            if (opts.json) {
+                jsonError(msg, 'invalid_engine');
+            }
+            else {
+                log.error(msg);
+            }
+            process.exit(1);
+            return;
+        }
         engine = opts.engine;
     }
     else if (opts.yes) {
@@ -306,16 +399,12 @@ export async function runDbInit(opts = {}) {
         process.exit(1);
         return;
     }
-    // ── grava .neetru/db.json (stub inicial — ids preenchidos depois do register)
-    const stubEntry = { name: dbName, productId, engine, ids: {} };
-    const withStub = {
-        ...dbJson,
-        databases: [...dbJson.databases, stubEntry],
-    };
-    writeDbJson(dbJsonPath, withStub);
-    log.success(`Banco "${dbName}" registrado localmente em ${chalk.bold(DB_JSON_REL)}`);
-    // ── BL-6 fix: registra o banco no Core e persiste os IDs por ambiente ────
-    const registerSpinner = ora({ text: 'Registrando banco no Core…', color: 'blue' }).start();
+    // ── HIGH-3: registra o banco no Core ANTES de gravar o stub local.
+    // Gravar localmente antes e deixar o registro falhar resultava em entrada
+    // órfã em .neetru/db.json — re-rodar db init adicionava banco duplicado.
+    const registerSpinner = opts.json
+        ? null
+        : ora({ text: 'Registrando banco no Core…', color: 'blue' }).start();
     let registerResp;
     try {
         registerResp = await apiRequest('/api/cli/v1/db/register', {
@@ -327,12 +416,20 @@ export async function runDbInit(opts = {}) {
                 provisioning: { type: engine.startsWith('vm-') ? 'vm' : 'managed' },
             },
         });
-        registerSpinner.succeed('Banco registrado no Core.');
+        registerSpinner?.succeed('Banco registrado no Core.');
     }
     catch (err) {
-        registerSpinner.fail('Falha ao registrar banco no Core.');
+        registerSpinner?.fail('Falha ao registrar banco no Core.');
+        if (opts.json) {
+            jsonError(err.message ?? String(err), 'register_failed');
+            process.exit(4);
+        }
         handleApiError(err);
+        return; // handleApiError nunca retorna mas TS não sabe disso
     }
+    // ── Grava .neetru/db.json somente após sucesso do Core ───────────────────
+    if (!opts.json)
+        log.success(`Banco "${dbName}" registrado localmente em ${chalk.bold(DB_JSON_REL)}`);
     // Persiste os IDs retornados pelo Core em `.neetru/db.json`.
     const ids = {
         'dev-local': registerResp.ids.devLocal,
@@ -342,32 +439,121 @@ export async function runDbInit(opts = {}) {
     const finalEntry = { name: dbName, productId, engine, ids };
     const withIds = {
         version: 2,
-        databases: [...withStub.databases.slice(0, -1), finalEntry],
+        databases: [...dbJson.databases, finalEntry],
     };
     writeDbJson(dbJsonPath, withIds);
-    log.success(`IDs de ambiente gravados em ${chalk.bold(DB_JSON_REL)}`);
+    if (!opts.json)
+        log.success(`IDs de ambiente gravados em ${chalk.bold(DB_JSON_REL)}`);
     // ── scaffolda db/schema.ts se não existir ─────────────────────────────────
     const schemaPath = path.resolve(cwd, DEFAULT_SCHEMA_PATH);
+    let schemaCreated = false;
     if (!fsSync.existsSync(schemaPath)) {
         await fs.mkdir(path.dirname(schemaPath), { recursive: true });
         await fs.writeFile(schemaPath, SCHEMA_STARTER(productId, engine), 'utf8');
-        log.success(`Schema gerado em ${chalk.bold(DEFAULT_SCHEMA_PATH)}`);
+        schemaCreated = true;
+        if (!opts.json)
+            log.success(`Schema gerado em ${chalk.bold(DEFAULT_SCHEMA_PATH)}`);
     }
     else {
-        log.dim(`  Schema existente em ${DEFAULT_SCHEMA_PATH} — não sobrescrito.`);
+        if (!opts.json)
+            log.dim(`  Schema existente em ${DEFAULT_SCHEMA_PATH} — não sobrescrito.`);
+    }
+    // gestovendas #9: saída JSON uniforme.
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            name: dbName,
+            productId,
+            engine,
+            env,
+            ids: {
+                devLocal: registerResp.ids.devLocal,
+                staging: registerResp.ids.staging,
+                production: registerResp.ids.production,
+            },
+            schemaPath: DEFAULT_SCHEMA_PATH,
+            schemaCreated,
+        }));
+        return;
     }
     log.dim('');
     log.dim('Próximos passos:');
-    log.dim(`  1. Edite ${DEFAULT_SCHEMA_PATH} com as tabelas do seu produto.`);
-    log.dim(`  2. Execute \`neetru db apply\` pra enviar a migração ao Core.`);
-    log.dim(`  3. O Core irá provisionar o banco ${chalk.bold(engine)} em ${chalk.bold(env)}.`);
+    log.dim(`  1. Edite ${DEFAULT_SCHEMA_PATH} com as estruturas do seu produto.`);
+    if (engine === 'firestore-instance') {
+        // pdv-agiliza #11 (Bug 11 Fase 1): branch NoSQL agora implementada no db apply.
+        log.dim(`  2. Para Firestore, o banco é schemaless — não há migração SQL.`);
+        log.dim(`     O \`neetru db apply\` registra o fingerprint do schema no Core.`);
+        log.dim(`     Use o SDK para criar collections diretamente:`);
+        log.dim(`       neetru.db.collection<Produto>('produtos')`);
+        log.dim(`  3. O Core irá provisionar a instância ${chalk.bold(engine)} em ${chalk.bold(env)}.`);
+    }
+    else {
+        log.dim(`  2. Execute \`neetru db apply\` pra enviar a migração ao Core.`);
+        log.dim(`  3. O Core irá provisionar o banco ${chalk.bold(engine)} em ${chalk.bold(env)}.`);
+    }
+}
+/**
+ * Pipeline NoSQL — sem drizzle-kit, sem Postgres efêmero.
+ *
+ * Engines NoSQL (`nosql-vm`, `firestore-instance`) são schemaless — não há SQL
+ * pra gerar nem rehearsear. O apply registra apenas o fingerprint do schema.ts
+ * no Core, que persiste em `product_db_schema_snapshots/{id}`.
+ *
+ * Fase 1 (implementada): snapshot de fingerprint sem export de JSON Schema.
+ * Fase 2 (backlog pdv-agiliza #11): export de JSON Schema estruturado + validação de coleções.
+ */
+async function runNoSqlApply(input) {
+    const { dbId, productId, engine, schemaPath, env, dryRun } = input;
+    // Fase 1: calcular fingerprint do schema.ts
+    const { schemaFingerprint } = await import('../lib/db-local/index.js');
+    const { default: fsDefault } = await import('node:fs');
+    const schemaContent = fsDefault.readFileSync(schemaPath, 'utf8');
+    const fingerprint = schemaFingerprint(schemaContent);
+    if (dryRun) {
+        return {
+            ok: true,
+            status: 'dry_run',
+            engine,
+            snapshotId: null,
+            fingerprint,
+            dryRun: true,
+        };
+    }
+    const resp = await apiRequest('/api/cli/v1/db/apply', {
+        method: 'POST',
+        body: {
+            dbId,
+            productId,
+            engine,
+            fingerprint,
+            env,
+            // Fase 1 — JSON Schema export ainda não implementado (Fase 2 / pdv #11).
+            schemaDefinition: null,
+        },
+    });
+    return {
+        ok: true,
+        status: resp.status ?? 'applied',
+        engine,
+        snapshotId: resp.snapshotId ?? null,
+        fingerprint,
+        dryRun: false,
+    };
 }
 export async function runDbApply(opts = {}) {
-    log.banner();
-    log.heading('neetru db apply');
+    if (!opts.json) {
+        log.banner();
+        log.heading('neetru db apply');
+    }
     const cfg = await loadProductConfig();
     if (!cfg) {
-        log.error('neetru.config.json não encontrado. Rode `neetru init` primeiro.');
+        const msg = 'neetru.config.json não encontrado. Rode `neetru init` primeiro.';
+        if (opts.json) {
+            jsonError(msg, 'config_not_found');
+        }
+        else {
+            log.error(msg);
+        }
         process.exit(1);
         return;
     }
@@ -375,7 +561,13 @@ export async function runDbApply(opts = {}) {
     const dbJsonPath = path.resolve(cwd, DB_JSON_REL);
     const dbJson = readDbJson(dbJsonPath);
     if (dbJson.databases.length === 0) {
-        log.error('Nenhum banco registrado em .neetru/db.json. Rode `neetru db init` primeiro.');
+        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);
+        }
         process.exit(1);
         return;
     }
@@ -384,14 +576,39 @@ export async function runDbApply(opts = {}) {
     if (opts.dbName) {
         const found = dbJson.databases.find((d) => d.name === opts.dbName);
         if (!found) {
-            log.error(`Banco "${opts.dbName}" não encontrado em .neetru/db.json.`);
-            log.dim(`  Bancos disponíveis: ${dbJson.databases.map((d) => d.name).join(', ')}`);
+            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);
+            }
             process.exit(1);
             return;
         }
         dbEntry = found;
     }
-    else if (dbJson.databases.length > 1 && !opts.yes) {
+    else if (dbJson.databases.length > 1 && (opts.json || opts.yes)) {
+        // HIGH-1: modo não-interativo (--json ou --yes) com múltiplos bancos e sem
+        // --db explícito é ambíguo — aplicar no primeiro silenciosamente pode causar
+        // migração no banco errado em CI. Emite erro estruturado ao invés de assumir.
+        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(', ')}`);
+        }
+        process.exit(1);
+        return;
+    }
+    else if (dbJson.databases.length > 1 && !opts.yes && !opts.json) {
         const { chosen } = await inquirer.prompt([
             {
                 type: 'list',
@@ -417,7 +634,13 @@ export async function runDbApply(opts = {}) {
         env = normalizeEnv(opts.env ?? 'dev-local');
     }
     catch {
-        log.error(`Ambiente inválido: "${opts.env}". Use dev-local, staging ou production.`);
+        const msg = `Ambiente inválido: "${opts.env}". Use dev-local, staging ou production.`;
+        if (opts.json) {
+            jsonError(msg, 'invalid_env');
+        }
+        else {
+            log.error(msg);
+        }
         process.exit(1);
         return;
     }
@@ -425,7 +648,13 @@ export async function runDbApply(opts = {}) {
     const schemaFile = opts.schemaPath ?? DEFAULT_SCHEMA_PATH;
     const schemaAbs = path.resolve(cwd, schemaFile);
     if (!fsSync.existsSync(schemaAbs)) {
-        log.error(`Schema não encontrado em ${schemaFile}. Rode \`neetru db init\` pra criar.`);
+        const msg = `Schema não encontrado em ${schemaFile}. Rode \`neetru db init\` pra criar.`;
+        if (opts.json) {
+            jsonError(msg, 'schema_not_found');
+        }
+        else {
+            log.error(msg);
+        }
         process.exit(1);
         return;
     }
@@ -434,18 +663,82 @@ export async function runDbApply(opts = {}) {
     const canonicalEnv = env;
     const dbId = dbEntry.ids[canonicalEnv];
     if (!dbId) {
-        log.error(`Banco "${dbEntry.name}" não tem ID registrado para o ambiente "${env}". ` +
-            `Execute \`neetru db init\` novamente ou verifique .neetru/db.json.`);
+        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);
+        }
         process.exit(1);
         return;
     }
-    log.dim(`  Banco:   ${dbEntry.name} (${dbEntry.engine})`);
-    log.dim(`  Schema:  ${schemaFile}`);
-    log.dim(`  Env:     ${env}`);
-    log.dim(`  DB ID:   ${dbId}`);
-    if (opts.dryRun)
-        log.warn('  Modo --dry-run: nenhuma alteração será enviada ao Core.');
-    // Executa o pipeline.
+    if (!opts.json) {
+        log.dim(`  Banco:   ${dbEntry.name} (${dbEntry.engine})`);
+        log.dim(`  Schema:  ${schemaFile}`);
+        log.dim(`  Env:     ${env}`);
+        log.dim(`  DB ID:   ${dbId}`);
+        if (opts.dryRun)
+            log.warn('  Modo --dry-run: nenhuma alteração será enviada ao Core.');
+    }
+    // ── Branch NoSQL (pdv-agiliza #11 — Bug 11 Fase 1) ─────────────────────────
+    // Engines schemaless não passam por drizzle-kit nem Postgres efêmero.
+    // O Core registra o snapshot de fingerprint em `product_db_schema_snapshots/{id}`.
+    if (NOSQL_ENGINES.includes(dbEntry.engine)) {
+        const nosqlSpinner = opts.json
+            ? null
+            : ora({ text: 'Aplicando schema NoSQL (sem rehearse — engine schemaless)…', color: 'blue' }).start();
+        try {
+            const nosqlResult = await runNoSqlApply({
+                dbId,
+                productId: dbEntry.productId,
+                engine: dbEntry.engine,
+                schemaPath: schemaAbs,
+                env: canonicalEnv,
+                dryRun: opts.dryRun,
+            });
+            nosqlSpinner?.stop();
+            // H-7 compat: persiste fingerprint pós-apply NoSQL também.
+            if (!opts.dryRun && nosqlResult.fingerprint) {
+                const dbJsonAfter = readDbJson(dbJsonPath);
+                const updatedDatabases = dbJsonAfter.databases.map((d) => d.name === dbEntry.name
+                    ? { ...d, lastAppliedFingerprint: nosqlResult.fingerprint }
+                    : d);
+                writeDbJson(dbJsonPath, { ...dbJsonAfter, databases: updatedDatabases });
+                if (!opts.json)
+                    log.dim(`  Fingerprint gravado em ${chalk.bold(DB_JSON_REL)}`);
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    ok: true,
+                    status: nosqlResult.status,
+                    engine: nosqlResult.engine,
+                    snapshotId: nosqlResult.snapshotId,
+                    fingerprint: nosqlResult.fingerprint,
+                    dryRun: nosqlResult.dryRun,
+                }));
+                return;
+            }
+            if (nosqlResult.status === 'dry_run') {
+                log.warn('  Dry-run concluído — nenhum snapshot gravado no Core.');
+            }
+            else {
+                log.success(`Schema NoSQL registrado no Core${nosqlResult.snapshotId ? ` — snapshot ${chalk.bold(nosqlResult.snapshotId)}` : ''}.`);
+            }
+            return;
+        }
+        catch (err) {
+            nosqlSpinner?.fail('Apply NoSQL falhou.');
+            if (opts.json) {
+                jsonError(err.message ?? String(err), 'nosql_apply_failed');
+                process.exit(5);
+            }
+            handleApiError(err);
+            return;
+        }
+    }
+    // Executa o pipeline SQL.
     const phaseLabels = {
         fingerprint: 'Calculando fingerprint…',
         generate: 'Gerando SQL (drizzle-kit)…',
@@ -453,12 +746,13 @@ export async function runDbApply(opts = {}) {
         classify: 'Classificando migração…',
         push: 'Enviando ao Core…',
     };
-    let spinner = ora({ text: 'Iniciando pipeline…', color: 'blue' }).start();
+    let spinner = opts.json ? null : ora({ text: 'Iniciando pipeline…', color: 'blue' }).start();
     let result;
     try {
         const deps = buildPipelineDeps({
             onPhase: (phase) => {
-                spinner.text = phaseLabels[phase] ?? phase;
+                if (spinner)
+                    spinner.text = phaseLabels[phase] ?? phase;
             },
             ...(opts.dryRun
                 ? {
@@ -474,33 +768,55 @@ export async function runDbApply(opts = {}) {
             env: canonicalEnv,
             dbId,
         }, deps);
-        spinner.stop();
+        spinner?.stop();
     }
     catch (err) {
-        spinner.fail('Pipeline falhou.');
+        spinner?.fail('Pipeline falhou.');
         if (isPipelineError(err)) {
             const pe = err;
-            log.error(`Fase "${pe.phase}": ${pe.message}`);
+            if (opts.json) {
+                jsonError(`Fase "${pe.phase}": ${pe.message}`, 'pipeline_failed');
+            }
+            else {
+                log.error(`Fase "${pe.phase}": ${pe.message}`);
+            }
             process.exit(5);
             return;
         }
-        log.error(err.message ?? String(err));
+        if (opts.json) {
+            jsonError(err.message ?? String(err), 'pipeline_failed');
+        }
+        else {
+            log.error(err.message ?? String(err));
+        }
         process.exit(5);
         return;
     }
-    if (result.status === 'no_changes') {
-        log.success('Schema sem alterações — nenhuma migração necessária.');
-        return;
-    }
-    // H-7 fix: persiste o fingerprint após push bem-sucedido (não dry-run) para
-    // que o gate de deploy (`checkSchemaGate` em deploy.ts) consiga detectar drift.
+    // H-7 fix: persiste o fingerprint após push bem-sucedido (não dry-run).
     if (!opts.dryRun && result.fingerprint) {
         const dbJsonAfter = readDbJson(dbJsonPath);
         const updatedDatabases = dbJsonAfter.databases.map((d) => d.name === dbEntry.name
             ? { ...d, lastAppliedFingerprint: result.fingerprint }
             : d);
         writeDbJson(dbJsonPath, { ...dbJsonAfter, databases: updatedDatabases });
-        log.dim(`  Fingerprint gravado em ${chalk.bold(DB_JSON_REL)}`);
+        if (!opts.json)
+            log.dim(`  Fingerprint gravado em ${chalk.bold(DB_JSON_REL)}`);
+    }
+    // gestovendas #9: saída JSON uniforme no caminho de sucesso.
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            status: result.status,
+            migrationId: result.migrationId ?? null,
+            severity: result.severity ?? null,
+            fingerprint: result.fingerprint ?? null,
+            dryRun: !!opts.dryRun,
+        }));
+        return;
+    }
+    if (result.status === 'no_changes') {
+        log.success('Schema sem alterações — nenhuma migração necessária.');
+        return;
     }
     log.dim('');
     log.dim(`  Severidade:   ${severityColor(result.severity)}`);