@actuate-media/cli 0.7.0 → 0.8.0

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.8.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.55.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__/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)
 }

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/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.',
+        )
+      }
+    })
+}