@actuate-media/cli 0.7.0 → 0.10.0

package/src/utils/form-seed.ts

@@ -0,0 +1,137 @@
+/**
+ * Validation for `forms`-collection seed entries.
+ *
+ * The form definition lives in `document.data` and has its own lifecycle
+ * `data.status` (`active` | `draft` | `archived`) that gates the public
+ * endpoints — a separate axis from the *document envelope* status
+ * (`DRAFT` | `PUBLISHED`). Seeding a form with the wrong shape used to fail
+ * silently: the document row was created, but `/api/cms/public/forms/:slug`
+ * 404'd (not `active`) or rendered nothing (fields missing `key`/`label`).
+ * This validator turns those mistakes into actionable errors at seed time.
+ *
+ * Type-only imports keep cms-core a runtime peer dependency (the CLI loads it
+ * lazily); the literal lists below are typed against the cms-core contracts so
+ * a typo here fails the build.
+ */
+import type { FormFieldType, FormStatus } from '@actuate-media/cms-core'
+
+const VALID_FIELD_TYPES: readonly FormFieldType[] = [
+  'text',
+  'email',
+  'phone',
+  'textarea',
+  'select',
+  'multiselect',
+  'radio',
+  'checkbox',
+  'date',
+  'number',
+  'url',
+  'hidden',
+  'file',
+  'consent',
+  'richtext',
+  'divider',
+  'honeypot',
+]
+
+const VALID_FORM_STATUSES: readonly FormStatus[] = ['active', 'draft', 'archived']
+
+/** Document-envelope statuses people mistakenly put in `data.status`. */
+const ENVELOPE_STATUSES = new Set(['DRAFT', 'PUBLISHED', 'SCHEDULED', 'ARCHIVED'])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Validate one form's `data` payload. Returns human-readable errors —
+ * empty array means the form will work with the public endpoints
+ * (`GET /api/cms/public/forms/:slug` + `/submit`) and `<ActuateForm>`.
+ */
+export function validateFormSeedData(data: unknown, label = 'form'): string[] {
+  const errors: string[] = []
+  if (!isRecord(data)) {
+    return [`${label}: form data must be an object.`]
+  }
+
+  if (typeof data.slug !== 'string' || data.slug.trim() === '') {
+    errors.push(
+      `${label}: missing "slug" (string). The public endpoints look forms up by slug — e.g. /api/cms/public/forms/contact.`,
+    )
+  }
+
+  const name = data.name ?? data.title
+  if (typeof name !== 'string' || name.trim() === '') {
+    errors.push(`${label}: missing "name" (string) — shown in the admin Forms list and inbox.`)
+  }
+
+  const status = data.status
+  if (status === undefined || status === null) {
+    errors.push(
+      `${label}: missing "status". Set data.status to "active" to enable the public form endpoints. ` +
+        `Note: this is the FORM's lifecycle status inside data — separate from the document envelope status ` +
+        `(DRAFT/PUBLISHED) set next to data.`,
+    )
+  } else if (typeof status === 'string' && ENVELOPE_STATUSES.has(status)) {
+    errors.push(
+      `${label}: data.status "${status}" looks like a document envelope status. The form definition's ` +
+        `data.status must be one of ${VALID_FORM_STATUSES.map((s) => `"${s}"`).join(' | ')} — use "active" ` +
+        `to enable the public endpoints. Put DRAFT/PUBLISHED on the document's top-level "status" key instead.`,
+    )
+  } else if (!VALID_FORM_STATUSES.includes(status as FormStatus)) {
+    errors.push(
+      `${label}: invalid data.status ${JSON.stringify(status)} — must be one of ` +
+        `${VALID_FORM_STATUSES.map((s) => `"${s}"`).join(' | ')}.`,
+    )
+  }
+
+  const fields = data.fields
+  if (!Array.isArray(fields) || fields.length === 0) {
+    errors.push(
+      `${label}: missing "fields" (non-empty array). Each field needs at least { key, label, type }.`,
+    )
+    return errors
+  }
+
+  fields.forEach((field, i) => {
+    const fieldLabel = `${label}: fields[${i}]`
+    if (!isRecord(field)) {
+      errors.push(`${fieldLabel}: must be an object with at least { key, label, type }.`)
+      return
+    }
+    if (typeof field.key !== 'string' || field.key.trim() === '') {
+      errors.push(
+        typeof field.name === 'string'
+          ? `${fieldLabel}: uses "name" — the form schema calls this "key". Rename name → key (and add a human-readable "label").`
+          : `${fieldLabel}: missing "key" (string) — the submission payload is keyed by it.`,
+      )
+    }
+    if (typeof field.label !== 'string' || field.label.trim() === '') {
+      errors.push(`${fieldLabel}: missing "label" (string) — shown to visitors and in the inbox.`)
+    }
+    if (!VALID_FIELD_TYPES.includes(field.type as FormFieldType)) {
+      errors.push(
+        `${fieldLabel}: invalid type ${JSON.stringify(field.type)} — must be one of ${VALID_FIELD_TYPES.join(', ')}.`,
+      )
+    }
+  })
+
+  return errors
+}
+
+/**
+ * Validate every `forms`-collection document in a normalized seed payload.
+ * Returns all errors across all forms (so one run surfaces everything).
+ */
+export function validateFormSeeds(
+  documents: ReadonlyArray<{ collection: string; data: Record<string, unknown> }>,
+): string[] {
+  const errors: string[] = []
+  documents.forEach((doc, i) => {
+    if (doc.collection !== 'forms') return
+    const slug = typeof doc.data.slug === 'string' ? doc.data.slug : `#${i + 1}`
+    errors.push(...validateFormSeedData(doc.data, `forms "${slug}"`))
+  })
+  return errors
+}

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