@actuate-media/cli 0.7.0 → 0.8.0

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',

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   registerDoctorCommand,
   registerVerifyCommand,
 } from './commands/doctor.js'
+import { registerVercelBlobLinkCommand } from './commands/vercel-blob-link.js'
 
 const program = new Command()
 
@@ -40,5 +41,6 @@ registerInitCommand(program)
 registerDoctorCommand(program)
 registerDeployCheckCommand(program)
 registerVerifyCommand(program)
+registerVercelBlobLinkCommand(program)
 
 program.parse()

package/src/vercel/client.ts

@@ -0,0 +1,112 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Minimal Vercel REST client for the CLI. Scope is deliberately small: read a
+ * project's environment variables so we can validate Blob wiring and print a
+ * per-environment readiness matrix. No write operations.
+ *
+ * Auth: a Vercel access token via `--token`, `VERCEL_TOKEN`, or
+ * `VERCEL_API_TOKEN`. Project/team identity from `.vercel/project.json` (written
+ * by `vercel link`) or explicit overrides. The client is fetch-injectable so the
+ * evaluation logic can be unit-tested without network access.
+ */
+
+const DEFAULT_BASE_URL = 'https://api.vercel.com'
+
+export const VERCEL_TARGETS = ['production', 'preview', 'development'] as const
+export type VercelTarget = (typeof VERCEL_TARGETS)[number]
+
+export interface VercelLink {
+  projectId: string
+  orgId?: string
+}
+
+export interface VercelEnvVar {
+  key: string
+  /** Targets this var applies to, e.g. ['production', 'preview']. */
+  target: VercelTarget[]
+  type?: string
+}
+
+export class VercelApiError extends Error {
+  readonly status: number
+
+  constructor(message: string, status: number) {
+    super(message)
+    this.name = 'VercelApiError'
+    this.status = status
+  }
+}
+
+/** Read `.vercel/project.json` (written by `vercel link`). Returns null if absent. */
+export async function readVercelLink(cwd: string): Promise<VercelLink | null> {
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'project.json'), 'utf-8')
+    const parsed = JSON.parse(raw) as { projectId?: string; orgId?: string }
+    if (!parsed.projectId) return null
+    return { projectId: parsed.projectId, orgId: parsed.orgId }
+  } catch {
+    return null
+  }
+}
+
+/** Resolve a Vercel token from an explicit flag or the standard env vars. */
+export function resolveVercelToken(explicit?: string): string | undefined {
+  return explicit ?? process.env.VERCEL_TOKEN ?? process.env.VERCEL_API_TOKEN ?? undefined
+}
+
+export interface VercelClientOptions {
+  token: string
+  /** Team / org id, appended as `teamId` when the project belongs to a team. */
+  teamId?: string
+  fetchImpl?: typeof fetch
+  baseUrl?: string
+}
+
+export interface VercelClient {
+  listProjectEnv(projectId: string): Promise<VercelEnvVar[]>
+}
+
+export function createVercelClient(options: VercelClientOptions): VercelClient {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL
+
+  async function request<T>(path: string): Promise<T> {
+    const url = new URL(path, baseUrl)
+    if (options.teamId) url.searchParams.set('teamId', options.teamId)
+
+    const response = await fetchImpl(url.toString(), {
+      headers: { Authorization: `Bearer ${options.token}` },
+    })
+
+    if (!response.ok) {
+      let detail = ''
+      try {
+        const body = (await response.json()) as { error?: { message?: string } }
+        detail = body?.error?.message ? `: ${body.error.message}` : ''
+      } catch {
+        // non-JSON error body — status alone is enough context
+      }
+      throw new VercelApiError(
+        `Vercel API request failed (HTTP ${response.status})${detail}`,
+        response.status,
+      )
+    }
+
+    return (await response.json()) as T
+  }
+
+  return {
+    async listProjectEnv(projectId: string): Promise<VercelEnvVar[]> {
+      const data = await request<{ envs?: VercelEnvVar[] }>(
+        `/v9/projects/${encodeURIComponent(projectId)}/env`,
+      )
+      return (data.envs ?? []).map((env) => ({
+        key: env.key,
+        target: Array.isArray(env.target) ? env.target : [],
+        type: env.type,
+      }))
+    },
+  }
+}

package/src/vercel/env-matrix.ts

@@ -0,0 +1,101 @@
+import { VERCEL_TARGETS, 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>
+
+function emptyPresence(): TargetPresence {
+  return { production: false, preview: false, development: false }
+}
+
+/** Which targets a given env var key is defined for. */
+export function presenceForKey(envVars: VercelEnvVar[], key: string): TargetPresence {
+  const presence = emptyPresence()
+  for (const env of envVars) {
+    if (env.key !== key) continue
+    for (const target of env.target) {
+      if ((VERCEL_TARGETS as readonly string[]).includes(target)) {
+        presence[target as VercelTarget] = true
+      }
+    }
+  }
+  return presence
+}
+
+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[] }[]
+}
+
+/** Production and preview are the deploy-blocking targets; development is local-only. */
+const DEPLOY_TARGETS: VercelTarget[] = ['production', 'preview']
+
+export function buildEnvMatrix(
+  envVars: VercelEnvVar[],
+  requiredKeys: readonly string[],
+  optionalKeys: readonly string[] = [],
+): EnvMatrix {
+  const rows: EnvMatrixRow[] = []
+  const seen = new Set<string>()
+  const missingCritical: { key: string; targets: VercelTarget[] }[] = []
+
+  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 }
+}
+
+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
+}
+
+const BLOB_LINK_SIGNALS = ['BLOB_STORE_ID', 'BLOB_WEBHOOK_PUBLIC_KEY', 'BLOB_READ_WRITE_TOKEN']
+
+export function evaluateBlobLink(envVars: VercelEnvVar[]): BlobLinkReport {
+  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',
+  }
+}