@actuate-media/cli 0.6.0 → 0.8.0

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)
 }

package/src/commands/doctor.ts

@@ -6,8 +6,19 @@ import {
   buildDeploymentManifest,
   createDiagnosticReport,
   detectPackageManager,
+  VERCEL_MATRIX_OPTIONAL,
+  VERCEL_MATRIX_REQUIRED,
   type DiagnosticReport,
 } from '../deployment/diagnostics.js'
+import {
+  createVercelClient,
+  readVercelLink,
+  resolveVercelToken,
+  VercelApiError,
+  VERCEL_TARGETS,
+} from '../vercel/client.js'
+import { buildEnvMatrix, type EnvMatrix } from '../vercel/env-matrix.js'
+import { logger } from '../utils/logger.js'
 
 async function fileExists(path: string): Promise<boolean> {
   try {
@@ -108,23 +119,120 @@ export function registerDoctorCommand(program: Command): void {
     })
 }
 
+function printEnvMatrix(matrix: EnvMatrix): void {
+  const cell = (present: boolean): string => (present ? chalk.green(' Y ') : chalk.red(' . '))
+  const keyWidth = Math.max(24, ...matrix.rows.map((r) => `${r.key} (optional)`.length + 1))
+
+  console.log()
+  console.log(chalk.bold('Environment variable matrix (Vercel)'))
+  console.log(chalk.dim('─────────────────────────────────'))
+  console.log(`${'Variable'.padEnd(keyWidth)} Prod Prev Dev`)
+  for (const row of matrix.rows) {
+    const labelPlain = row.required ? row.key : `${row.key} (optional)`
+    const label = row.required ? row.key : chalk.dim(labelPlain)
+    console.log(
+      `${label}${' '.repeat(Math.max(1, keyWidth - labelPlain.length))}` +
+        `${cell(row.presence.production)} ${cell(row.presence.preview)} ${cell(row.presence.development)}`,
+    )
+  }
+  console.log(chalk.dim('─────────────────────────────────'))
+  console.log(chalk.dim('Y = set for that environment, . = missing'))
+}
+
+async function runVercelMatrix(opts: {
+  token?: string
+  project?: string
+  org?: string
+  json?: boolean
+}): Promise<{ ok: boolean; matrix?: EnvMatrix }> {
+  const token = resolveVercelToken(opts.token)
+  if (!token) {
+    logger.error('No Vercel token found. Pass --token or set VERCEL_TOKEN to use --vercel.')
+    return { ok: false }
+  }
+
+  const link = opts.project
+    ? { projectId: opts.project, orgId: opts.org }
+    : await readVercelLink(process.cwd())
+  if (!link?.projectId) {
+    logger.error('No linked Vercel project. Run `vercel link` or pass --project <id>.')
+    return { ok: false }
+  }
+
+  const client = createVercelClient({ token, teamId: link.orgId ?? opts.org })
+  try {
+    const envVars = await client.listProjectEnv(link.projectId)
+    const matrix = buildEnvMatrix(envVars, VERCEL_MATRIX_REQUIRED, VERCEL_MATRIX_OPTIONAL)
+    if (!opts.json) {
+      printEnvMatrix(matrix)
+      if (matrix.missingCritical.length > 0) {
+        for (const m of matrix.missingCritical) {
+          logger.error(`${m.key} missing on: ${m.targets.join(', ')}`)
+        }
+        logger.info(
+          `Add the missing variables in the Vercel dashboard (include Development for local \`vercel env pull\`). Targets checked: ${VERCEL_TARGETS.join(', ')}.`,
+        )
+      }
+    }
+    return { ok: matrix.missingCritical.length === 0, matrix }
+  } catch (error) {
+    const message =
+      error instanceof VercelApiError
+        ? error.message
+        : error instanceof Error
+          ? error.message
+          : String(error)
+    logger.error(`Could not read project environment from Vercel: ${message}`)
+    return { ok: false }
+  }
+}
+
 export function registerDeployCheckCommand(program: Command): void {
   program
     .command('deploy:check')
     .description('Check production deployment readiness for Actuate CMS')
     .option('--schema <path>', 'Path to schema.prisma', 'prisma/schema.prisma')
     .option('--config <path>', 'Path to actuate.config.ts', 'actuate.config.ts')
+    .option('--vercel', 'Read the linked Vercel project and print a per-environment matrix')
+    .option('--token <token>', 'Vercel access token (with --vercel; defaults to $VERCEL_TOKEN)')
+    .option('--project <id>', 'Vercel project id (with --vercel; defaults to .vercel/project.json)')
+    .option('--org <id>', 'Vercel team/org id (with --vercel)')
     .option('--json', 'Print machine-readable JSON')
-    .action(async (opts: { schema: string; config: string; json?: boolean }) => {
-      const report = await buildReport(opts.schema, opts.config, 'deploy')
-      if (opts.json) {
-        console.log(JSON.stringify({ ...report, manifest: buildDeploymentManifest() }, null, 2))
-      } else {
-        printReport('Actuate Deploy Check', report)
-        console.log(chalk.dim('Run `actuate verify --full` after deployment succeeds.'))
-      }
-      if (report.status === 'fail') process.exitCode = 1
-    })
+    .action(
+      async (opts: {
+        schema: string
+        config: string
+        vercel?: boolean
+        token?: string
+        project?: string
+        org?: string
+        json?: boolean
+      }) => {
+        const report = await buildReport(opts.schema, opts.config, 'deploy')
+        const vercelResult = opts.vercel ? await runVercelMatrix(opts) : null
+
+        if (opts.json) {
+          console.log(
+            JSON.stringify(
+              {
+                ...report,
+                manifest: buildDeploymentManifest(),
+                ...(vercelResult ? { vercelMatrix: vercelResult.matrix ?? null } : {}),
+              },
+              null,
+              2,
+            ),
+          )
+        } else {
+          printReport('Actuate Deploy Check', report)
+          console.log(chalk.dim('Run `actuate verify --full` after deployment succeeds.'))
+        }
+
+        if (report.status === 'fail' || (vercelResult && !vercelResult.ok)) {
+          process.exitCode = 1
+        }
+      },
+    )
 }
 
 export function registerVerifyCommand(program: Command): void {

package/src/commands/migrate-sections.ts

@@ -0,0 +1,73 @@
+import { Command } from 'commander'
+import ora from 'ora'
+import { logger } from '../utils/logger.js'
+import { connectProjectDatabase } from '../utils/database.js'
+
+interface MigrateSectionsOptions {
+  dryRun?: boolean
+  batchSize?: string
+}
+
+/**
+ * `actuate migrate:sections` — backfill canonical `data.sections` for legacy
+ * page-builder documents (ADR 0002). Idempotent: safe to re-run.
+ */
+async function runMigrateSections(options: MigrateSectionsOptions): Promise<void> {
+  const dryRun = options.dryRun ?? false
+  const batchSize = options.batchSize ? Number.parseInt(options.batchSize, 10) : undefined
+  if (batchSize !== undefined && (!Number.isFinite(batchSize) || batchSize <= 0)) {
+    logger.error('--batch-size must be a positive integer.')
+    process.exit(1)
+  }
+
+  let connection: { db: any; disconnect: () => Promise<void> } | null = null
+  const spinner = ora(
+    dryRun ? 'Scanning page-builder documents (dry run)…' : 'Backfilling page sections…',
+  ).start()
+
+  try {
+    connection = await connectProjectDatabase()
+    const db = connection.db
+
+    const { migratePageBuilderSections } = await import('@actuate-media/cms-core')
+
+    // Run as the system admin so per-collection update access is satisfied.
+    const admin = await db.user.findFirst({ where: { role: 'ADMIN' } })
+    if (!admin) {
+      spinner.fail('No ADMIN user found. Create an admin (setup wizard or seed) first.')
+      process.exit(1)
+    }
+
+    const ctx = { userId: admin.id, role: 'ADMIN', db }
+    const result = await migratePageBuilderSections(ctx, { dryRun, batchSize })
+
+    spinner.succeed(
+      dryRun
+        ? `Dry run complete — ${result.migrated} document(s) would be migrated.`
+        : `Migrated ${result.migrated} document(s).`,
+    )
+    logger.info(`  Scanned:  ${result.scanned}`)
+    logger.info(`  Migrated: ${result.migrated}`)
+    logger.info(`  Skipped:  ${result.skipped}`)
+    if (result.migratedIds.length > 0) {
+      logger.info(`  IDs:      ${result.migratedIds.join(', ')}`)
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    spinner.fail(`Section migration failed: ${message}`)
+    process.exit(1)
+  } finally {
+    await connection?.disconnect()
+  }
+}
+
+export function registerMigrateSectionsCommand(program: Command): void {
+  program
+    .command('migrate:sections')
+    .description(
+      'Backfill canonical page sections for legacy page-builder documents (ADR 0002). Idempotent.',
+    )
+    .option('--dry-run', 'Report what would change without writing')
+    .option('--batch-size <n>', 'Documents to scan per DB page (default 100)')
+    .action(runMigrateSections)
+}

package/src/commands/seed.ts

@@ -1,12 +1,12 @@
 import { Command } from 'commander'
 import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { createRequire } from 'node:module'
 import path from 'node:path'
 import { createInterface } from 'node:readline/promises'
 import { pathToFileURL } from 'node:url'
 import ora from 'ora'
 import { logger } from '../utils/logger.js'
+import { connectProjectDatabase } from '../utils/database.js'
 
 async function confirm(question: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
@@ -300,7 +300,7 @@ async function runSeed(options: SeedOptions): Promise<void> {
   let seededDb: { db: any; disconnect: () => Promise<void> } | null = null
 
   try {
-    seededDb = await getSeedDatabase()
+    seededDb = await connectProjectDatabase()
     const db = seededDb.db
 
     if (options.reset) {
@@ -335,60 +335,6 @@ async function runSeed(options: SeedOptions): Promise<void> {
   }
 }
 
-async function getSeedDatabase(): Promise<{ db: any; disconnect: () => Promise<void> }> {
-  const { getDB, initDB, isDBInitialized } = await import('@actuate-media/cms-core')
-
-  if (isDBInitialized()) {
-    return { db: getDB<any>(), disconnect: async () => {} }
-  }
-
-  const db = await createProjectPrismaClient()
-  initDB(db)
-  return {
-    db,
-    disconnect: async () => {
-      if (typeof db.$disconnect === 'function') {
-        await db.$disconnect()
-      }
-    },
-  }
-}
-
-async function createProjectPrismaClient(): Promise<any> {
-  if (!process.env.DATABASE_URL) {
-    throw new Error('DATABASE_URL is required to run seed/populate.')
-  }
-
-  const requireFromProject = createRequire(path.join(process.cwd(), 'package.json'))
-  const generatedClient = path.resolve('generated', 'prisma', 'client.ts')
-
-  if (existsSync(generatedClient)) {
-    const [{ tsImport }, adapterModule, pgModule] = await Promise.all([
-      import('tsx/esm/api'),
-      import(pathToFileURL(requireFromProject.resolve('@prisma/adapter-pg')).href),
-      import(pathToFileURL(requireFromProject.resolve('pg')).href),
-    ])
-    const { PrismaClient } = (await tsImport(
-      pathToFileURL(generatedClient).href,
-      import.meta.url,
-    )) as {
-      PrismaClient: new (options?: unknown) => any
-    }
-    const { PrismaPg } = adapterModule as { PrismaPg: new (pool: unknown) => unknown }
-    const pg = (pgModule as { default?: typeof pgModule }).default ?? pgModule
-    const pool = new (pg as any).Pool({ connectionString: process.env.DATABASE_URL })
-    const adapter = new PrismaPg(pool)
-    return new PrismaClient({ adapter } as any)
-  }
-
-  const clientModule = (await import(
-    pathToFileURL(requireFromProject.resolve('@prisma/client')).href
-  )) as {
-    PrismaClient: new () => any
-  }
-  return new clientModule.PrismaClient()
-}
-
 export async function ensureSeedAdmin(db: any): Promise<{ id: string }> {
   const existing = await db.user.findFirst({ where: { role: 'ADMIN' } })
   if (existing) return existing

package/src/commands/vercel-blob-link.ts

@@ -0,0 +1,115 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import {
+  createVercelClient,
+  readVercelLink,
+  resolveVercelToken,
+  VercelApiError,
+  VERCEL_TARGETS,
+  type VercelTarget,
+} from '../vercel/client.js'
+import { evaluateBlobLink } from '../vercel/env-matrix.js'
+import { logger } from '../utils/logger.js'
+
+interface BlobLinkOptions {
+  token?: string
+  project?: string
+  org?: string
+  json?: boolean
+}
+
+function mark(present: boolean): string {
+  return present ? chalk.green('PASS') : chalk.red('FAIL')
+}
+
+export function registerVercelBlobLinkCommand(program: Command): void {
+  program
+    .command('vercel:blob-link')
+    .description('Validate the Vercel Blob store connection for the linked project')
+    .option('--token <token>', 'Vercel access token (defaults to $VERCEL_TOKEN)')
+    .option('--project <id>', 'Vercel project id (defaults to .vercel/project.json)')
+    .option('--org <id>', 'Vercel team/org id (defaults to .vercel/project.json)')
+    .option('--json', 'Print machine-readable JSON')
+    .action(async (opts: BlobLinkOptions) => {
+      const token = resolveVercelToken(opts.token)
+      if (!token) {
+        logger.error(
+          'No Vercel token found. Pass --token or set VERCEL_TOKEN (create one at https://vercel.com/account/tokens).',
+        )
+        process.exitCode = 1
+        return
+      }
+
+      const link = opts.project
+        ? { projectId: opts.project, orgId: opts.org }
+        : await readVercelLink(process.cwd())
+      if (!link?.projectId) {
+        logger.error(
+          'No linked Vercel project found. Run `vercel link` first, or pass --project <id> (and --org <id> for team projects).',
+        )
+        process.exitCode = 1
+        return
+      }
+
+      const client = createVercelClient({ token, teamId: link.orgId ?? opts.org })
+
+      let envVars
+      try {
+        envVars = await client.listProjectEnv(link.projectId)
+      } catch (error) {
+        const message =
+          error instanceof VercelApiError
+            ? error.message
+            : error instanceof Error
+              ? error.message
+              : String(error)
+        logger.error(`Could not read project environment variables from Vercel: ${message}`)
+        process.exitCode = 1
+        return
+      }
+
+      const report = evaluateBlobLink(envVars)
+
+      if (opts.json) {
+        console.log(JSON.stringify({ projectId: link.projectId, ...report }, null, 2))
+      } else {
+        console.log()
+        console.log(chalk.bold('Vercel Blob connection'))
+        console.log(chalk.dim('─────────────────────────────────'))
+        if (!report.linked) {
+          console.log('No Vercel Blob store is connected to this project.')
+        } else {
+          console.log('BLOB_READ_WRITE_TOKEN by environment:')
+          for (const target of VERCEL_TARGETS) {
+            console.log(`  ${mark(report.tokenByTarget[target])} ${target}`)
+          }
+        }
+        console.log(chalk.dim('─────────────────────────────────'))
+      }
+
+      if (report.status === 'partial') {
+        if (!opts.json) {
+          logger.error(
+            'A Blob store is connected but BLOB_READ_WRITE_TOKEN is missing for Production/Preview. Uploads will fail.',
+          )
+          logger.info(
+            'Reconnect the Blob store and provision the token to all environments (include Development for local `vercel env pull`), then re-run this command.',
+          )
+        }
+        process.exitCode = 1
+        return
+      }
+
+      const devOnlyMissing =
+        report.linked && report.missingTargets.includes('development' as VercelTarget)
+      if (devOnlyMissing && !opts.json) {
+        logger.warn(
+          'BLOB_READ_WRITE_TOKEN is not set for Development — `vercel env pull` will not provide a local token. Include Development when connecting the store.',
+        )
+      } else if (report.status === 'ok' && !opts.json) {
+        logger.success(
+          'Blob store is connected and BLOB_READ_WRITE_TOKEN is provisioned for Production and Preview.',
+        )
+      }
+    })
+}

package/src/deployment/diagnostics.ts

@@ -38,6 +38,24 @@ export const REQUIRED_ENV_VARS = [
   'NEXT_PUBLIC_SITE_URL',
 ] as const
 
+/** Vars the per-environment Vercel matrix treats as deploy-blocking. */
+export const VERCEL_MATRIX_REQUIRED = [
+  'DATABASE_URL',
+  'DIRECT_DATABASE_URL',
+  'CMS_SECRET',
+  'CMS_ENCRYPTION_KEY',
+  'NEXT_PUBLIC_SITE_URL',
+  'CRON_SECRET',
+] as const
+
+/** Vars the matrix surfaces as advisory (feature-gated, not deploy-blocking). */
+export const VERCEL_MATRIX_OPTIONAL = [
+  'BLOB_READ_WRITE_TOKEN',
+  'UPSTASH_REDIS_REST_URL',
+  'UPSTASH_REDIS_REST_TOKEN',
+  'RESEND_API_KEY',
+] as const
+
 export interface DiagnosticInput {
   schemaModels: Set<string>
   schemaContent?: string
@@ -56,6 +74,32 @@ export function missingEnvVars(env: Record<string, string | undefined>): string[
   return REQUIRED_ENV_VARS.filter((name) => !env[name])
 }
 
+export type BlobLinkState = 'ok' | 'partial' | 'token-format' | 'none'
+
+/**
+ * Classify the local Vercel Blob wiring. A "partial" link is the failure mode
+ * Opal hit: a Blob store is connected (so `BLOB_STORE_ID` / the webhook key are
+ * present, or the config selects vercel-blob storage) but `BLOB_READ_WRITE_TOKEN`
+ * was never provisioned — uploads then fail at runtime even though the store is
+ * "connected" in the dashboard. We treat that as a hard failure, not a warning.
+ */
+export function detectBlobLinkState(
+  env: Record<string, string | undefined>,
+  configContent?: string,
+): BlobLinkState {
+  const token = env.BLOB_READ_WRITE_TOKEN
+  if (token) {
+    return token.startsWith('vercel_blob_') ? 'ok' : 'token-format'
+  }
+
+  const hasPartialSignals =
+    Boolean(env.BLOB_STORE_ID) ||
+    Boolean(env.BLOB_WEBHOOK_PUBLIC_KEY) ||
+    (configContent ? /vercel-blob|platform-vercel|vercelBlob/i.test(configContent) : false)
+
+  return hasPartialSignals ? 'partial' : 'none'
+}
+
 export function detectPackageManager(lockfiles: Set<string>): string {
   if (lockfiles.has('pnpm-lock.yaml')) return 'pnpm'
   if (lockfiles.has('yarn.lock')) return 'yarn'
@@ -123,6 +167,31 @@ export function createDiagnosticReport(input: DiagnosticInput): DiagnosticReport
     docs: 'https://actuatecms.dev/docs/environment-variables',
   })
 
+  const blobState = detectBlobLinkState(input.env, input.configContent)
+  checks.push({
+    id: 'blob-storage',
+    label: 'Vercel Blob storage',
+    status: blobState === 'partial' ? 'fail' : blobState === 'token-format' ? 'warn' : 'pass',
+    message:
+      blobState === 'partial'
+        ? 'A Vercel Blob store is linked (BLOB_STORE_ID / webhook key or vercel-blob storage configured) but BLOB_READ_WRITE_TOKEN is missing. Media uploads will fail.'
+        : blobState === 'token-format'
+          ? 'BLOB_READ_WRITE_TOKEN does not start with `vercel_blob_` — verify it is a real Vercel Blob read-write token.'
+          : blobState === 'ok'
+            ? 'BLOB_READ_WRITE_TOKEN is configured.'
+            : 'No Vercel Blob storage configured (skipped).',
+    fix:
+      blobState === 'partial'
+        ? 'Finish the Blob connection so BLOB_READ_WRITE_TOKEN is provisioned to every environment (including Development for local `vercel env pull`), then `vercel env pull`. Validate with `actuate vercel:blob-link`.'
+        : blobState === 'token-format'
+          ? 'Re-copy the read-write token from the Vercel Blob store (Storage tab) and re-pull your environment.'
+          : undefined,
+    docs:
+      blobState === 'partial' || blobState === 'token-format'
+        ? 'https://actuatecms.dev/docs/deployment'
+        : undefined,
+  })
+
   checks.push({
     id: 'package-manager',
     label: 'Package manager',
@@ -163,6 +232,7 @@ export function buildDeploymentManifest() {
       'DIRECT_DATABASE_URL',
       'CMS_ADMIN_EMAIL',
       'CMS_ADMIN_PASSWORD',
+      'CRON_SECRET',
       'BLOB_READ_WRITE_TOKEN',
       'UPSTASH_REDIS_REST_URL',
       'UPSTASH_REDIS_REST_TOKEN',