@actuate-media/cli 0.8.0 → 0.10.0

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/commands/seed.ts

@@ -7,6 +7,7 @@ import { pathToFileURL } from 'node:url'
 import ora from 'ora'
 import { logger } from '../utils/logger.js'
 import { connectProjectDatabase } from '../utils/database.js'
+import { validateFormSeeds } from '../utils/form-seed.js'
 
 async function confirm(question: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
@@ -119,37 +120,101 @@ const DEMO_POSTS = [
   },
 ]
 
-const DEMO_FORMS = [
+// Canonical form seed shape: the form definition lives in document `data`
+// with its own lifecycle `status: 'active'` (gates the public endpoints) and
+// `fields` keyed by { id, key, label, type, required, sortOrder }. See
+// `validateFormSeeds` — these are validated by the same rules as user seeds.
+export const DEMO_FORMS = [
   {
+    name: 'Contact Form',
     title: 'Contact Form',
     slug: 'contact-form',
+    status: 'active',
     fields: [
-      { name: 'name', type: 'text', required: true },
-      { name: 'email', type: 'email', required: true },
-      { name: 'message', type: 'textarea', required: true },
+      {
+        id: 'contact-name',
+        key: 'name',
+        label: 'Name',
+        type: 'text',
+        required: true,
+        sortOrder: 0,
+      },
+      {
+        id: 'contact-email',
+        key: 'email',
+        label: 'Email',
+        type: 'email',
+        required: true,
+        sortOrder: 1,
+      },
+      {
+        id: 'contact-message',
+        key: 'message',
+        label: 'Message',
+        type: 'textarea',
+        required: true,
+        sortOrder: 2,
+      },
     ],
-    submitLabel: 'Send Message',
     successMessage: "Thanks for reaching out! We'll get back to you soon.",
   },
   {
+    name: 'Newsletter Signup',
     title: 'Newsletter Signup',
     slug: 'newsletter',
+    status: 'active',
     fields: [
-      { name: 'email', type: 'email', required: true },
-      { name: 'firstName', type: 'text', required: false },
+      {
+        id: 'newsletter-email',
+        key: 'email',
+        label: 'Email',
+        type: 'email',
+        required: true,
+        sortOrder: 0,
+      },
+      {
+        id: 'newsletter-first-name',
+        key: 'firstName',
+        label: 'First name',
+        type: 'text',
+        required: false,
+        sortOrder: 1,
+      },
     ],
-    submitLabel: 'Subscribe',
     successMessage: "You're subscribed! Check your inbox for confirmation.",
   },
   {
+    name: 'Feedback Form',
     title: 'Feedback Form',
     slug: 'feedback',
+    status: 'active',
     fields: [
-      { name: 'name', type: 'text', required: false },
-      { name: 'rating', type: 'select', options: ['1', '2', '3', '4', '5'], required: true },
-      { name: 'comments', type: 'textarea', required: false },
+      {
+        id: 'feedback-name',
+        key: 'name',
+        label: 'Name',
+        type: 'text',
+        required: false,
+        sortOrder: 0,
+      },
+      {
+        id: 'feedback-rating',
+        key: 'rating',
+        label: 'Rating',
+        type: 'select',
+        required: true,
+        sortOrder: 1,
+        options: ['1', '2', '3', '4', '5'].map((v) => ({ label: v, value: v })),
+      },
+      {
+        id: 'feedback-comments',
+        key: 'comments',
+        label: 'Comments',
+        type: 'textarea',
+        required: false,
+        sortOrder: 2,
+      },
     ],
-    submitLabel: 'Submit Feedback',
     successMessage: 'Thank you for your feedback!',
   },
 ]
@@ -188,6 +253,7 @@ interface SeedOptions {
   demo?: boolean
   file?: string
   reset?: boolean
+  upsert?: boolean
 }
 
 export interface NormalizedSeedDocument {
@@ -324,7 +390,7 @@ async function runSeed(options: SeedOptions): Promise<void> {
     }
 
     if (file) {
-      await seedFromFile(db, file)
+      await seedFromFile(db, file, { upsert: options.upsert })
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
@@ -380,19 +446,63 @@ export async function createSeedDocument(
   db: any,
   userId: string,
   doc: NormalizedSeedDocument,
-): Promise<void> {
+  options: { upsert?: boolean } = {},
+): Promise<'created' | 'updated'> {
   const { extractPlainText, hashContent, sanitizeHtml } = await import('@actuate-media/cms-core')
   const data = sanitizeSeedData(doc.data, sanitizeHtml) as Record<string, unknown>
   const serialized = JSON.stringify(data)
   const plainText = extractPlainText(serialized)
   const contentHash = await hashContent(serialized)
+  const slug = typeof data.slug === 'string' ? data.slug : null
+  const title = typeof data.title === 'string' ? data.title : null
+
+  // Upsert key: collection + slug. Slugless documents can't be re-identified,
+  // so they always insert (same as a plain seed run).
+  const existing =
+    options.upsert && slug
+      ? await db.document.findFirst({
+          where: { collection: doc.collection, slug, deletedAt: null },
+          select: { id: true, status: true, publishedAt: true },
+        })
+      : null
+
+  if (existing) {
+    await db.$transaction(async (tx: any) => {
+      await tx.document.update({
+        where: { id: existing.id },
+        data: {
+          title,
+          data,
+          status: doc.status,
+          // Stamp publishedAt only on the transition into PUBLISHED.
+          publishedAt:
+            doc.status === 'PUBLISHED'
+              ? (existing.publishedAt ?? new Date())
+              : existing.publishedAt,
+          updatedById: userId,
+          plainText,
+          contentHash,
+        },
+      })
+
+      await tx.version.create({
+        data: {
+          documentId: existing.id,
+          data,
+          changedById: userId,
+          changeType: 'UPDATE',
+        },
+      })
+    })
+    return 'updated'
+  }
 
   await db.$transaction(async (tx: any) => {
     const created = await tx.document.create({
       data: {
         collection: doc.collection,
-        title: typeof data.title === 'string' ? data.title : null,
-        slug: typeof data.slug === 'string' ? data.slug : null,
+        title,
+        slug,
         data,
         status: doc.status,
         publishedAt: doc.status === 'PUBLISHED' ? new Date() : null,
@@ -412,6 +522,7 @@ export async function createSeedDocument(
       },
     })
   })
+  return 'created'
 }
 
 async function seedDemoData(db: any): Promise<void> {
@@ -486,7 +597,11 @@ async function seedDemoData(db: any): Promise<void> {
   logger.info(`  Users:        ${usersCreated} (+ existing admin)`)
 }
 
-async function seedFromFile(db: any, filePath: string): Promise<void> {
+async function seedFromFile(
+  db: any,
+  filePath: string,
+  options: { upsert?: boolean } = {},
+): Promise<void> {
   if (!existsSync(filePath)) {
     logger.error(`File not found: ${filePath}`)
     process.exit(1)
@@ -511,13 +626,32 @@ async function seedFromFile(db: any, filePath: string): Promise<void> {
   const userId = adminUser.id
 
   const normalized = normalizeSeedPayload(seedData)
+
+  // Forms have a stricter shape than generic documents (data.status gates the
+  // public endpoints; fields need key/label/type). Fail loudly BEFORE writing
+  // anything — a malformed form seed used to insert fine and then 404 on
+  // /api/cms/public/forms/:slug with no hint why.
+  const formErrors = validateFormSeeds(normalized.documents)
+  if (formErrors.length > 0) {
+    spinner.fail('Form seed validation failed — nothing was written:')
+    for (const error of formErrors) {
+      logger.error(`  ${error}`)
+    }
+    logger.info(
+      '  Expected shape: { "forms": [{ "status": "PUBLISHED", "data": { "name", "slug", "status": "active", "fields": [{ "key", "label", "type", … }] } }] }',
+    )
+    process.exit(1)
+  }
+
   const { updateGlobal } = await import('@actuate-media/cms-core')
   const ctx = { userId, role: 'ADMIN', db }
 
-  let documentCount = 0
+  let createdCount = 0
+  let updatedCount = 0
   for (const doc of normalized.documents) {
-    await createSeedDocument(db, userId, doc)
-    documentCount++
+    const result = await createSeedDocument(db, userId, doc, options)
+    if (result === 'updated') updatedCount++
+    else createdCount++
   }
 
   let globalCount = 0
@@ -526,7 +660,11 @@ async function seedFromFile(db: any, filePath: string): Promise<void> {
     globalCount++
   }
 
-  spinner.succeed(`Seeded ${documentCount} documents and ${globalCount} globals from ${filePath}.`)
+  spinner.succeed(
+    options.upsert
+      ? `Seeded from ${filePath}: ${createdCount} created, ${updatedCount} updated, ${globalCount} globals.`
+      : `Seeded ${createdCount} documents and ${globalCount} globals from ${filePath}.`,
+  )
 }
 
 export function registerSeedCommand(program: Command): void {
@@ -536,6 +674,10 @@ export function registerSeedCommand(program: Command): void {
     .option('--demo', 'Seed demo content (pages, posts, forms, users)')
     .option('--file <path>', 'Seed from a JSON, JavaScript, or TypeScript file')
     .option('--reset', 'Clear existing data before seeding')
+    .option(
+      '--upsert',
+      'Update existing documents matched by collection + slug instead of inserting duplicates',
+    )
     .action(runSeed)
 
   program
@@ -543,5 +685,9 @@ export function registerSeedCommand(program: Command): void {
     .description('Populate the database from actuate.seed.json or a custom seed file')
     .option('--file <path>', 'Seed from a JSON, JavaScript, or TypeScript file')
     .option('--reset', 'Clear existing data before seeding')
+    .option(
+      '--upsert',
+      'Update existing documents matched by collection + slug instead of inserting duplicates',
+    )
     .action(runSeed)
 }

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