@actuate-media/cli 0.7.0 → 0.10.0

package/dist/vercel/env-matrix.d.ts

@@ -0,0 +1,34 @@
+import { type VercelEnvVar, type VercelTarget } from './client.js';
+/**
+ * Pure evaluation helpers over a project's Vercel env vars. Kept free of I/O so
+ * the matrix / blob logic is unit-testable without hitting the Vercel API.
+ */
+export type TargetPresence = Record<VercelTarget, boolean>;
+/** Which targets a given env var key is defined for. */
+export declare function presenceForKey(envVars: VercelEnvVar[], key: string): TargetPresence;
+export interface EnvMatrixRow {
+    key: string;
+    required: boolean;
+    presence: TargetPresence;
+}
+export interface EnvMatrix {
+    rows: EnvMatrixRow[];
+    /** Required vars missing on production or preview (deploy-blocking). */
+    missingCritical: {
+        key: string;
+        targets: VercelTarget[];
+    }[];
+}
+export declare function buildEnvMatrix(envVars: VercelEnvVar[], requiredKeys: readonly string[], optionalKeys?: readonly string[]): EnvMatrix;
+export type BlobLinkStatus = 'ok' | 'partial' | 'none';
+export interface BlobLinkReport {
+    /** True when any BLOB_* var indicates a store is connected to the project. */
+    linked: boolean;
+    tokenByTarget: TargetPresence;
+    /** Targets (any) where BLOB_READ_WRITE_TOKEN is absent while linked. */
+    missingTargets: VercelTarget[];
+    /** 'partial' when production/preview lack the token (deploy-blocking). */
+    status: BlobLinkStatus;
+}
+export declare function evaluateBlobLink(envVars: VercelEnvVar[]): BlobLinkReport;
+//# sourceMappingURL=env-matrix.d.ts.map

package/dist/vercel/env-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-matrix.d.ts","sourceRoot":"","sources":["../../src/vercel/env-matrix.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAElF;;;GAGG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;AAM1D,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAWnF;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,YAAY,EAAE,CAAA;IACpB,wEAAwE;IACxE,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,EAAE,CAAA;KAAE,EAAE,CAAA;CAC5D;AAKD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EAAE,EACvB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,SAAS,CAoBX;AAED,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAA;AAEtD,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAA;IACf,aAAa,EAAE,cAAc,CAAA;IAC7B,wEAAwE;IACxE,cAAc,EAAE,YAAY,EAAE,CAAA;IAC9B,0EAA0E;IAC1E,MAAM,EAAE,cAAc,CAAA;CACvB;AAID,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,cAAc,CAkBxE"}

package/dist/vercel/env-matrix.js

@@ -0,0 +1,57 @@
+import { VERCEL_TARGETS } from './client.js';
+function emptyPresence() {
+    return { production: false, preview: false, development: false };
+}
+/** Which targets a given env var key is defined for. */
+export function presenceForKey(envVars, key) {
+    const presence = emptyPresence();
+    for (const env of envVars) {
+        if (env.key !== key)
+            continue;
+        for (const target of env.target) {
+            if (VERCEL_TARGETS.includes(target)) {
+                presence[target] = true;
+            }
+        }
+    }
+    return presence;
+}
+/** Production and preview are the deploy-blocking targets; development is local-only. */
+const DEPLOY_TARGETS = ['production', 'preview'];
+export function buildEnvMatrix(envVars, requiredKeys, optionalKeys = []) {
+    const rows = [];
+    const seen = new Set();
+    const missingCritical = [];
+    for (const key of requiredKeys) {
+        seen.add(key);
+        const presence = presenceForKey(envVars, key);
+        rows.push({ key, required: true, presence });
+        const missing = DEPLOY_TARGETS.filter((t) => !presence[t]);
+        if (missing.length > 0)
+            missingCritical.push({ key, targets: missing });
+    }
+    for (const key of optionalKeys) {
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        rows.push({ key, required: false, presence: presenceForKey(envVars, key) });
+    }
+    return { rows, missingCritical };
+}
+const BLOB_LINK_SIGNALS = ['BLOB_STORE_ID', 'BLOB_WEBHOOK_PUBLIC_KEY', 'BLOB_READ_WRITE_TOKEN'];
+export function evaluateBlobLink(envVars) {
+    const linked = envVars.some((env) => BLOB_LINK_SIGNALS.includes(env.key) || env.key.startsWith('BLOB_'));
+    const tokenByTarget = presenceForKey(envVars, 'BLOB_READ_WRITE_TOKEN');
+    if (!linked) {
+        return { linked: false, tokenByTarget, missingTargets: [], status: 'none' };
+    }
+    const missingTargets = VERCEL_TARGETS.filter((t) => !tokenByTarget[t]);
+    const criticalMissing = DEPLOY_TARGETS.some((t) => !tokenByTarget[t]);
+    return {
+        linked: true,
+        tokenByTarget,
+        missingTargets,
+        status: criticalMissing ? 'partial' : 'ok',
+    };
+}
+//# sourceMappingURL=env-matrix.js.map

package/dist/vercel/env-matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-matrix.js","sourceRoot":"","sources":["../../src/vercel/env-matrix.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cli",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "CLI for Actuate CMS — migrations, codegen, imports, exports, and upgrades",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "typescript": "^5.7.0",
     "vitest": "^4.1.0",
-    "@actuate-media/cms-core": "0.53.0"
+    "@actuate-media/cms-core": "0.61.0"
   },
   "scripts": {
     "build": "tsc",

package/src/__tests__/db-sync.test.ts

@@ -3,7 +3,13 @@ import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 
-import { buildConsumerSchema, syncPrismaAssets } from '../commands/db-sync.js'
+import {
+  buildConsumerSchema,
+  checkSchemaDrift,
+  driftGuidance,
+  syncPrismaAssets,
+  type DriftRunner,
+} from '../commands/db-sync.js'
 
 const CORE_SCHEMA = `generator client {
   provider = "prisma-client"
@@ -164,4 +170,52 @@ describe('db:sync (WS-D D2 — post-upgrade schema sync)', () => {
       expect(second.migrationsAdded).toEqual([])
     })
   })
+
+  describe('checkSchemaDrift', () => {
+    const okRunner: DriftRunner = async () => ({ exitCode: 0, stdout: '', stderr: '' })
+    const driftRunner: DriftRunner = async () => ({
+      exitCode: 2,
+      stdout: 'ALTER TABLE "actuate_media_usages" RENAME COLUMN "fieldName" TO "fieldPath";',
+      stderr: '',
+    })
+
+    it('skips when no database URL is configured', async () => {
+      const result = await checkSchemaDrift('prisma/schema.prisma', {}, okRunner)
+      expect(result.status).toBe('skipped')
+    })
+
+    it('reports no-drift on exit code 0', async () => {
+      const result = await checkSchemaDrift(
+        'prisma/schema.prisma',
+        { DATABASE_URL: 'postgres://x' },
+        okRunner,
+      )
+      expect(result.status).toBe('no-drift')
+    })
+
+    it('reports drift (with reconciling SQL) on exit code 2', async () => {
+      const result = await checkSchemaDrift(
+        'prisma/schema.prisma',
+        { DATABASE_URL: 'postgres://x' },
+        driftRunner,
+      )
+      expect(result.status).toBe('drift')
+      expect(result.detail).toContain('RENAME COLUMN')
+      expect(driftGuidance(result).join('\n')).toContain('prisma migrate dev --name')
+    })
+
+    it('prefers DIRECT_DATABASE_URL for the diff connection', async () => {
+      let usedUrl = ''
+      const spyRunner: DriftRunner = async ({ url }) => {
+        usedUrl = url
+        return { exitCode: 0, stdout: '', stderr: '' }
+      }
+      await checkSchemaDrift(
+        'prisma/schema.prisma',
+        { DATABASE_URL: 'postgres://pooled', DIRECT_DATABASE_URL: 'postgres://direct' },
+        spyRunner,
+      )
+      expect(usedUrl).toBe('postgres://direct')
+    })
+  })
 })

package/src/__tests__/deployment-diagnostics.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest'
 import {
   buildDeploymentManifest,
   createDiagnosticReport,
+  detectBlobLinkState,
   REQUIRED_CMS_MODELS,
   REQUIRED_ENV_VARS,
 } from '../deployment/diagnostics.js'
@@ -127,6 +128,56 @@ describe('deployment diagnostics', () => {
     )
   })
 
+  it('fails (not warns) when a Blob store is linked but the read-write token is missing', () => {
+    const report = createDiagnosticReport({
+      schemaModels: new Set(REQUIRED_CMS_MODELS),
+      schemaContent: '',
+      env: {
+        DATABASE_URL: 'postgresql://example',
+        CMS_SECRET: 'secret',
+        CMS_ENCRYPTION_KEY: 'a'.repeat(64),
+        NEXT_PUBLIC_SITE_URL: 'https://example.com',
+        BLOB_STORE_ID: 'store_abc123',
+        BLOB_WEBHOOK_PUBLIC_KEY: 'pk_abc',
+        // BLOB_READ_WRITE_TOKEN deliberately absent — the partial-link failure.
+      },
+      packageManager: 'pnpm',
+      schemaPath: 'prisma/schema.prisma',
+    })
+
+    expect(report.status).toBe('fail')
+    expect(report.checks).toEqual(
+      expect.arrayContaining([expect.objectContaining({ id: 'blob-storage', status: 'fail' })]),
+    )
+  })
+
+  it('passes the blob check when no Blob storage is configured', () => {
+    const report = createDiagnosticReport({
+      schemaModels: new Set(REQUIRED_CMS_MODELS),
+      schemaContent: '',
+      env: {
+        DATABASE_URL: 'postgresql://example',
+        CMS_SECRET: 'secret',
+        CMS_ENCRYPTION_KEY: 'a'.repeat(64),
+        NEXT_PUBLIC_SITE_URL: 'https://example.com',
+      },
+      packageManager: 'pnpm',
+      schemaPath: 'prisma/schema.prisma',
+    })
+
+    expect(report.checks).toEqual(
+      expect.arrayContaining([expect.objectContaining({ id: 'blob-storage', status: 'pass' })]),
+    )
+  })
+
+  it('classifies blob link state from env and config signals', () => {
+    expect(detectBlobLinkState({ BLOB_READ_WRITE_TOKEN: 'vercel_blob_rw_x' })).toBe('ok')
+    expect(detectBlobLinkState({ BLOB_READ_WRITE_TOKEN: 'not-a-real-token' })).toBe('token-format')
+    expect(detectBlobLinkState({ BLOB_STORE_ID: 'store_x' })).toBe('partial')
+    expect(detectBlobLinkState({}, "storage: { provider: 'vercel-blob' }")).toBe('partial')
+    expect(detectBlobLinkState({})).toBe('none')
+  })
+
   it('exposes machine-readable deployment metadata', () => {
     const manifest = buildDeploymentManifest()
 

package/src/__tests__/form-seed.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from 'vitest'
+
+// seed.js transitively imports cms-core helpers at module scope via mocks
+// elsewhere; keep the same stub so importing DEMO_FORMS stays side-effect-free.
+vi.mock('@actuate-media/cms-core', () => ({
+  extractPlainText: vi.fn(),
+  hashContent: vi.fn(),
+  sanitizeHtml: vi.fn(),
+  createInitialAdmin: vi.fn(),
+}))
+
+import { validateFormSeedData, validateFormSeeds } from '../utils/form-seed.js'
+import { DEMO_FORMS } from '../commands/seed.js'
+
+const validForm = () => ({
+  name: 'Contact',
+  slug: 'contact',
+  status: 'active',
+  fields: [{ id: 'f1', key: 'email', label: 'Email', type: 'email', required: true, sortOrder: 0 }],
+})
+
+describe('validateFormSeedData', () => {
+  it('accepts the canonical form shape', () => {
+    expect(validateFormSeedData(validForm())).toEqual([])
+  })
+
+  it('every DEMO_FORMS entry passes its own validation', () => {
+    for (const form of DEMO_FORMS) {
+      expect(validateFormSeedData(form, form.slug)).toEqual([])
+    }
+  })
+
+  it('explains the data.status vs document status split when status is missing', () => {
+    const { status: _status, ...form } = validForm()
+    const errors = validateFormSeedData(form)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('data.status to "active"')
+    expect(errors[0]).toContain('document envelope status')
+  })
+
+  it('catches a document-envelope status (PUBLISHED) used as the form status', () => {
+    const errors = validateFormSeedData({ ...validForm(), status: 'PUBLISHED' })
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('looks like a document envelope status')
+    expect(errors[0]).toContain('"active" | "draft" | "archived"')
+  })
+
+  it('rejects unknown statuses with the allowed list', () => {
+    const errors = validateFormSeedData({ ...validForm(), status: 'live' })
+    expect(errors[0]).toContain('invalid data.status "live"')
+  })
+
+  it('requires slug, name, and a non-empty fields array', () => {
+    const errors = validateFormSeedData({ status: 'active' })
+    expect(errors.some((e) => e.includes('"slug"'))).toBe(true)
+    expect(errors.some((e) => e.includes('"name"'))).toBe(true)
+    expect(errors.some((e) => e.includes('"fields"'))).toBe(true)
+  })
+
+  it('points "name"-keyed fields (the old demo shape) at key/label', () => {
+    const errors = validateFormSeedData({
+      ...validForm(),
+      fields: [{ name: 'email', type: 'email' }],
+    })
+    expect(errors.some((e) => e.includes('Rename name → key'))).toBe(true)
+    expect(errors.some((e) => e.includes('"label"'))).toBe(true)
+  })
+
+  it('rejects unknown field types', () => {
+    const errors = validateFormSeedData({
+      ...validForm(),
+      fields: [{ key: 'x', label: 'X', type: 'dropdown' }],
+    })
+    expect(errors[0]).toContain('invalid type "dropdown"')
+  })
+})
+
+describe('validateFormSeeds', () => {
+  it('only validates forms-collection documents and labels errors by slug', () => {
+    const errors = validateFormSeeds([
+      { collection: 'pages', data: { title: 'Home' } },
+      { collection: 'forms', data: { ...validForm(), slug: 'contact', status: 'PUBLISHED' } },
+    ])
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('forms "contact"')
+  })
+
+  it('returns no errors for a payload without forms', () => {
+    expect(validateFormSeeds([{ collection: 'pages', data: {} }])).toEqual([])
+  })
+})

package/src/__tests__/seed.test.ts

@@ -130,6 +130,103 @@ describe('seed document creation', () => {
   })
 })
 
+describe('seed document upsert', () => {
+  function makeDb(existing: { id: string; status: string; publishedAt: Date | null } | null) {
+    const tx = {
+      document: {
+        create: vi.fn().mockResolvedValue({ id: 'doc-new' }),
+        update: vi.fn().mockResolvedValue({ id: existing?.id ?? 'doc-new' }),
+      },
+      version: { create: vi.fn() },
+    }
+    const db = {
+      document: { findFirst: vi.fn().mockResolvedValue(existing) },
+      $transaction: vi.fn(async (fn: any) => fn(tx)),
+    }
+    return { db, tx }
+  }
+
+  const doc = {
+    collection: 'pages',
+    status: 'PUBLISHED',
+    data: { title: 'Home v2', slug: 'home' },
+  }
+
+  it('updates an existing document matched by collection + slug', async () => {
+    const publishedAt = new Date('2026-01-01T00:00:00Z')
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'PUBLISHED', publishedAt })
+
+    const result = await createSeedDocument(db, 'admin-1', doc, { upsert: true })
+
+    expect(result).toBe('updated')
+    expect(db.document.findFirst).toHaveBeenCalledWith({
+      where: { collection: 'pages', slug: 'home', deletedAt: null },
+      select: { id: true, status: true, publishedAt: true },
+    })
+    expect(tx.document.create).not.toHaveBeenCalled()
+    expect(tx.document.update).toHaveBeenCalledWith({
+      where: { id: 'doc-1' },
+      data: expect.objectContaining({
+        title: 'Home v2',
+        status: 'PUBLISHED',
+        // Re-publishing an already-published doc keeps the original timestamp.
+        publishedAt,
+        updatedById: 'admin-1',
+      }),
+    })
+    expect(tx.version.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({ documentId: 'doc-1', changeType: 'UPDATE' }),
+    })
+  })
+
+  it('stamps publishedAt on the transition into PUBLISHED', async () => {
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'DRAFT', publishedAt: null })
+
+    await createSeedDocument(db, 'admin-1', doc, { upsert: true })
+
+    expect(tx.document.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ publishedAt: expect.any(Date) }),
+      }),
+    )
+  })
+
+  it('creates when no document matches', async () => {
+    const { db, tx } = makeDb(null)
+
+    const result = await createSeedDocument(db, 'admin-1', doc, { upsert: true })
+
+    expect(result).toBe('created')
+    expect(tx.document.create).toHaveBeenCalled()
+    expect(tx.document.update).not.toHaveBeenCalled()
+  })
+
+  it('always creates slugless documents (no upsert key)', async () => {
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'DRAFT', publishedAt: null })
+
+    const result = await createSeedDocument(
+      db,
+      'admin-1',
+      { collection: 'pages', status: 'DRAFT', data: { title: 'No slug' } },
+      { upsert: true },
+    )
+
+    expect(result).toBe('created')
+    expect(db.document.findFirst).not.toHaveBeenCalled()
+    expect(tx.document.create).toHaveBeenCalled()
+  })
+
+  it('does not look up existing documents without the upsert flag', async () => {
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'DRAFT', publishedAt: null })
+
+    const result = await createSeedDocument(db, 'admin-1', doc)
+
+    expect(result).toBe('created')
+    expect(db.document.findFirst).not.toHaveBeenCalled()
+    expect(tx.document.create).toHaveBeenCalled()
+  })
+})
+
 describe('demo navigations', () => {
   // The scaffold site layout fetches menus by the `main` and `footer` slugs, so
   // the demo seed must provide exactly those — guard against slug drift.

package/src/__tests__/vercel-env-matrix.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+
+import type { VercelEnvVar } from '../vercel/client.js'
+import { buildEnvMatrix, evaluateBlobLink, presenceForKey } from '../vercel/env-matrix.js'
+
+function env(key: string, target: VercelEnvVar['target']): VercelEnvVar {
+  return { key, target }
+}
+
+describe('presenceForKey', () => {
+  it('aggregates targets across multiple entries for the same key', () => {
+    const vars = [env('DATABASE_URL', ['production']), env('DATABASE_URL', ['preview'])]
+    expect(presenceForKey(vars, 'DATABASE_URL')).toEqual({
+      production: true,
+      preview: true,
+      development: false,
+    })
+  })
+})
+
+describe('buildEnvMatrix', () => {
+  it('flags required vars missing on production or preview as critical', () => {
+    const vars = [
+      env('DATABASE_URL', ['production', 'preview', 'development']),
+      env('CMS_SECRET', ['production']),
+    ]
+    const matrix = buildEnvMatrix(vars, ['DATABASE_URL', 'CMS_SECRET'], ['CRON_SECRET'])
+
+    expect(matrix.missingCritical).toEqual([{ key: 'CMS_SECRET', targets: ['preview'] }])
+    expect(matrix.rows.find((r) => r.key === 'CRON_SECRET')).toMatchObject({ required: false })
+  })
+})
+
+describe('evaluateBlobLink', () => {
+  it('reports none when no blob vars exist', () => {
+    expect(evaluateBlobLink([env('DATABASE_URL', ['production'])]).status).toBe('none')
+  })
+
+  it('reports partial when linked but token missing on production/preview', () => {
+    const report = evaluateBlobLink([
+      env('BLOB_STORE_ID', ['production', 'preview', 'development']),
+    ])
+    expect(report.linked).toBe(true)
+    expect(report.status).toBe('partial')
+    expect(report.missingTargets).toContain('production')
+  })
+
+  it('reports ok when token covers production and preview (dev optional)', () => {
+    const report = evaluateBlobLink([
+      env('BLOB_STORE_ID', ['production', 'preview']),
+      env('BLOB_READ_WRITE_TOKEN', ['production', 'preview']),
+    ])
+    expect(report.status).toBe('ok')
+    expect(report.missingTargets).toEqual(['development'])
+  })
+})

package/src/commands/db-sync.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander'
 import { access, cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
+import { spawn } from 'node:child_process'
 import { dirname, join, resolve } from 'node:path'
 import { createRequire } from 'node:module'
 import ora from 'ora'
@@ -96,6 +97,99 @@ async function listMigrationDirs(dir: string): Promise<string[]> {
 interface DbSyncOptions {
   schema: string
   force?: boolean
+  checkDrift?: boolean
+}
+
+export interface DriftDiffResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+export type DriftRunner = (args: { schemaPath: string; url: string }) => Promise<DriftDiffResult>
+
+export interface DriftCheckResult {
+  status: 'no-drift' | 'drift' | 'skipped' | 'error'
+  detail?: string
+}
+
+const defaultDriftRunner: DriftRunner = ({ schemaPath, url }) =>
+  new Promise((resolvePromise) => {
+    // `--exit-code` makes prisma return 2 when the database differs from the
+    // datamodel, 0 when in sync. `--script` prints the reconciling SQL.
+    const child = spawn(
+      'npx',
+      [
+        'prisma',
+        'migrate',
+        'diff',
+        '--from-url',
+        url,
+        '--to-schema-datamodel',
+        schemaPath,
+        '--script',
+        '--exit-code',
+      ],
+      { shell: process.platform === 'win32' },
+    )
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk) => {
+      stdout += String(chunk)
+    })
+    child.stderr?.on('data', (chunk) => {
+      stderr += String(chunk)
+    })
+    child.on('error', (err) => {
+      resolvePromise({ exitCode: 1, stdout, stderr: stderr || String(err) })
+    })
+    child.on('close', (code) => {
+      resolvePromise({ exitCode: code ?? 1, stdout, stderr })
+    })
+  })
+
+/**
+ * Detect whether the live database differs from the canonical schema. Pure of
+ * I/O via the injectable `runner` so the decision logic is unit-testable. A
+ * non-pooled `DIRECT_DATABASE_URL` is preferred (migrations use it); falls back
+ * to `DATABASE_URL`. Skips gracefully when neither is set.
+ */
+export async function checkSchemaDrift(
+  schemaPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+  runner: DriftRunner = defaultDriftRunner,
+): Promise<DriftCheckResult> {
+  const url = env.DIRECT_DATABASE_URL || env.DATABASE_URL
+  if (!url) {
+    return {
+      status: 'skipped',
+      detail: 'Set DATABASE_URL (or DIRECT_DATABASE_URL) to let db:sync detect schema drift.',
+    }
+  }
+  const result = await runner({ schemaPath, url })
+  if (result.exitCode === 0) return { status: 'no-drift' }
+  if (result.exitCode === 2) return { status: 'drift', detail: result.stdout.trim() }
+  return { status: 'error', detail: (result.stderr || result.stdout).trim() }
+}
+
+/** Human-readable next steps for a drift verdict (pure, for testing + reuse). */
+export function driftGuidance(result: DriftCheckResult): string[] {
+  switch (result.status) {
+    case 'drift':
+      return [
+        'Database schema differs from the canonical Actuate schema.',
+        'Apply the migrations shipped by db:sync (includes column renames):',
+        '  npx prisma migrate deploy',
+        'If drift remains afterward, generate a reconciling migration:',
+        '  npx prisma migrate dev --name actuate-schema-sync',
+      ]
+    case 'error':
+      return ['Could not check schema drift (is the database reachable?).']
+    case 'skipped':
+      return [result.detail ?? 'Drift check skipped.']
+    case 'no-drift':
+      return ['Database schema matches the canonical Actuate schema.']
+  }
 }
 
 export interface DbSyncResult {
@@ -215,6 +309,27 @@ async function runDbSync(options: DbSyncOptions): Promise<void> {
   if (result.schemaWritten || result.migrationsAdded.length > 0) {
     logger.info('Next: run `npx prisma migrate deploy` then `npx prisma generate`.')
   }
+
+  // Drift detection: compare the live DB against the canonical schema so a
+  // mismatch (e.g. a renamed column not yet migrated) surfaces an exact command
+  // rather than a silent runtime failure. Opt-out with --no-check-drift.
+  if (options.checkDrift !== false && !result.skippedReason) {
+    const driftSpinner = ora('Checking database for schema drift…').start()
+    const drift = await checkSchemaDrift(consumerSchemaPath)
+    if (drift.status === 'drift') {
+      driftSpinner.warn('Schema drift detected.')
+      if (drift.detail) {
+        logger.info('Reconciling SQL (review before applying):')
+        console.log(drift.detail)
+      }
+      for (const line of driftGuidance(drift)) logger.info(line)
+      process.exitCode = 1
+    } else if (drift.status === 'no-drift') {
+      driftSpinner.succeed('No schema drift detected.')
+    } else {
+      driftSpinner.info(driftGuidance(drift)[0] ?? 'Drift check skipped.')
+    }
+  }
 }
 
 export function registerDbSyncCommand(program: Command): void {
@@ -223,5 +338,6 @@ export function registerDbSyncCommand(program: Command): void {
     .description('Sync the canonical Prisma schema + migrations from the installed cms-core')
     .option('--schema <path>', 'Path to schema.prisma', 'prisma/schema.prisma')
     .option('--force', 'Overwrite schema.prisma even if it lacks the AUTO-SYNCED marker')
+    .option('--no-check-drift', 'Skip the post-sync database drift check')
     .action(runDbSync)
 }