@orion-studios/payload-studio 0.6.0-beta.9 → 0.7.0

package/README.md

@@ -22,8 +22,10 @@ Prefer explicit subpath imports.
 import { configureAdmin, type StudioSection } from '@orion-studios/payload-studio/admin'
 import { createPayloadClient, createPageQueries, createSiteQueries } from '@orion-studios/payload-studio/nextjs'
 import { defaultPageLayoutBlocks } from '@orion-studios/payload-studio/blocks'
-import { pageStudioModuleManifest } from '@orion-studios/payload-studio/studio-pages'
+import { createStudioPagesCollection, pageStudioModuleManifest } from '@orion-studios/payload-studio/studio-pages'
 import { withImageUploadOptimization } from '@orion-studios/payload-studio/studio'
+import { validateEmail, formatPhoneUS } from '@orion-studios/payload-studio/forms'
+import { createFormSubmissionHandler } from '@orion-studios/payload-studio/forms/server'
 ```
 
 The root `@orion-studios/payload-studio` namespace export remains available for backward compatibility, but new integrations should treat subpath imports as the public contract.
@@ -32,6 +34,7 @@ The root `@orion-studios/payload-studio` namespace export remains available for
 
 ```bash
 npm install @orion-studios/payload-studio
+npx payload-studio-init   # scaffolds app scripts, lib wrappers, and the form submission route
 ```
 
 ```ts
@@ -70,6 +73,8 @@ const adminConfig = configureAdmin({
 - `@orion-studios/payload-studio/admin-app/client`
 - `@orion-studios/payload-studio/admin-app/styles.css`
 - `@orion-studios/payload-studio/blocks`
+- `@orion-studios/payload-studio/forms`
+- `@orion-studios/payload-studio/forms/server`
 - `@orion-studios/payload-studio/nextjs`
 - `@orion-studios/payload-studio/studio`
 - `@orion-studios/payload-studio/studio-pages`

package/bin/init.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+/**
+ * Scaffolds the app-side files required by the Studio Website Setup Guide.
+ *
+ * Usage (from the consuming app root):
+ *   npx payload-studio-init
+ *
+ * Existing files are never overwritten — safe to re-run after upgrades.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const cwd = process.cwd()
+
+const hasSrcDir = fs.existsSync(path.join(cwd, 'src'))
+const srcRoot = hasSrcDir ? 'src' : '.'
+
+const FILES = [
+  {
+    file: 'scripts/clean-next-cache.cjs',
+    contents: `#!/usr/bin/env node
+
+// Clears stale Next.js build caches before dev/build runs.
+// Pass --all to remove the entire .next directory instead of just the cache.
+
+const fs = require('fs')
+const path = require('path')
+
+const all = process.argv.includes('--all')
+const target = path.join(process.cwd(), '.next', all ? '' : 'cache')
+
+try {
+  fs.rmSync(target, { recursive: true, force: true })
+  console.log('[clean-next-cache] removed ' + path.relative(process.cwd(), target || '.next'))
+} catch (error) {
+  console.warn('[clean-next-cache] skipped: ' + error.message)
+}
+`,
+  },
+  {
+    file: 'scripts/schema-sync.ts',
+    contents: `/**
+ * Pushes the current Payload schema to the database.
+ *
+ * Run via: npm run schema:sync
+ * The PAYLOAD_SCHEMA_PUSH=true env flag is set by the npm script — schema push
+ * stays opt-in only, per the Studio contract.
+ */
+
+import config from '../${srcRoot}/payload.config'
+import { getPayload } from 'payload'
+
+async function run() {
+  if (process.env.PAYLOAD_SCHEMA_PUSH !== 'true') {
+    console.error('Refusing to run: set PAYLOAD_SCHEMA_PUSH=true (use \`npm run schema:sync\`).')
+    process.exit(1)
+  }
+
+  const payload = await getPayload({ config })
+  console.log('[schema-sync] schema synchronized')
+  if (typeof payload.db?.destroy === 'function') {
+    await payload.db.destroy()
+  }
+  process.exit(0)
+}
+
+run().catch((error) => {
+  console.error('[schema-sync] failed:', error)
+  process.exit(1)
+})
+`,
+  },
+  {
+    file: 'scripts/seed.ts',
+    contents: `/**
+ * Seeds the CMS with the canonical default pages from src/lib/site-page-layouts.
+ * Existing pages are left untouched — safe to re-run.
+ *
+ * Run via: npm run seed
+ */
+
+import config from '../${srcRoot}/payload.config'
+import { getPayload } from 'payload'
+import { sitePageLayouts } from '../${srcRoot}/lib/site-page-layouts'
+
+async function run() {
+  const payload = await getPayload({ config })
+
+  for (const page of sitePageLayouts) {
+    const existing = await payload.find({
+      collection: 'pages',
+      limit: 1,
+      where: { slug: { equals: page.slug } },
+    })
+
+    if (existing.docs.length > 0) {
+      console.log('[seed] skip existing page: ' + page.slug)
+      continue
+    }
+
+    await payload.create({
+      collection: 'pages',
+      data: {
+        _status: 'published',
+        layout: page.layout,
+        slug: page.slug,
+        title: page.title,
+      },
+    })
+    console.log('[seed] created page: ' + page.slug)
+  }
+
+  if (typeof payload.db?.destroy === 'function') {
+    await payload.db.destroy()
+  }
+  process.exit(0)
+}
+
+run().catch((error) => {
+  console.error('[seed] failed:', error)
+  process.exit(1)
+})
+`,
+  },
+  {
+    file: 'scripts/sync-page-layouts.ts',
+    contents: `/**
+ * Syncs the canonical default layouts from src/lib/site-page-layouts into the
+ * CMS for pages that have NOT been edited in the Studio builder yet
+ * (no studioDocument). Builder-authored pages are never overwritten.
+ *
+ * Run via: npm run pages:sync-layouts
+ */
+
+import config from '../${srcRoot}/payload.config'
+import { getPayload } from 'payload'
+import { sitePageLayouts } from '../${srcRoot}/lib/site-page-layouts'
+
+async function run() {
+  const payload = await getPayload({ config })
+
+  for (const page of sitePageLayouts) {
+    const existing = await payload.find({
+      collection: 'pages',
+      draft: true,
+      limit: 1,
+      where: { slug: { equals: page.slug } },
+    })
+
+    const doc = existing.docs[0] as { id: number | string; studioDocument?: unknown } | undefined
+
+    if (!doc) {
+      await payload.create({
+        collection: 'pages',
+        data: {
+          _status: 'published',
+          layout: page.layout,
+          slug: page.slug,
+          title: page.title,
+        },
+      })
+      console.log('[sync-layouts] created page: ' + page.slug)
+      continue
+    }
+
+    if (doc.studioDocument) {
+      console.log('[sync-layouts] skip builder-owned page: ' + page.slug)
+      continue
+    }
+
+    await payload.update({
+      collection: 'pages',
+      id: doc.id,
+      data: { layout: page.layout },
+    })
+    console.log('[sync-layouts] updated layout for page: ' + page.slug)
+  }
+
+  if (typeof payload.db?.destroy === 'function') {
+    await payload.db.destroy()
+  }
+  process.exit(0)
+}
+
+run().catch((error) => {
+  console.error('[sync-layouts] failed:', error)
+  process.exit(1)
+})
+`,
+  },
+  {
+    file: `${srcRoot}/lib/payload.ts`,
+    contents: `import config from '@/payload.config'
+import { createPayloadClient, WEBSITE_CONTENT_TAG } from '@orion-studios/payload-studio/nextjs'
+
+export const getPayloadClient = createPayloadClient(config)
+export { WEBSITE_CONTENT_TAG }
+`,
+  },
+  {
+    file: `${srcRoot}/lib/pages.ts`,
+    contents: `import { createPageQueries } from '@orion-studios/payload-studio/nextjs'
+import { getPayloadClient, WEBSITE_CONTENT_TAG } from '@/lib/payload'
+
+export const { getPageBySegments, listPublishedPagePaths, pathToSegments } = createPageQueries(
+  getPayloadClient,
+  { contentTag: WEBSITE_CONTENT_TAG },
+)
+`,
+  },
+  {
+    file: `${srcRoot}/lib/site.ts`,
+    contents: `import { createSiteQueries } from '@orion-studios/payload-studio/nextjs'
+import { getPayloadClient, WEBSITE_CONTENT_TAG } from '@/lib/payload'
+
+export const { getSiteSettings, getHeader, getFooter, getSocialMedia } = createSiteQueries(
+  getPayloadClient,
+  { contentTag: WEBSITE_CONTENT_TAG },
+)
+`,
+  },
+  {
+    file: `${srcRoot}/lib/site-page-layouts.ts`,
+    contents: `/**
+ * Canonical default page layouts.
+ *
+ * This module is the single layout source used by runtime fallback, the seed
+ * script, and the sync script, per the Studio Website Setup Guide.
+ */
+
+export type SitePageLayout = {
+  slug: string
+  title: string
+  layout: Array<Record<string, unknown>>
+}
+
+export const sitePageLayouts: SitePageLayout[] = [
+  {
+    slug: 'home',
+    title: 'Home',
+    layout: [],
+  },
+]
+`,
+  },
+  {
+    file: `${srcRoot}/app/api/form-submissions/[slug]/route.ts`,
+    contents: `import { createFormSubmissionHandler } from '@orion-studios/payload-studio/forms/server'
+import { getPayloadClient } from '@/lib/payload'
+
+/**
+ * Public form submission boundary. Anonymous users must never write directly
+ * to the submissions collection — this route is the only entry point.
+ * Origin check, honeypot, minimum fill time, rate limiting, and server-side
+ * re-validation are handled by the shared package handler.
+ */
+export const POST = createFormSubmissionHandler({
+  getPayloadClient,
+})
+`,
+  },
+]
+
+const REQUIRED_SCRIPTS = {
+  dev: 'node scripts/clean-next-cache.cjs && npm run generate:importmap && next dev --webpack',
+  build:
+    'node scripts/clean-next-cache.cjs --all && npm run generate:importmap && next build --webpack',
+  lint: 'eslint .',
+  typecheck: 'tsc --noEmit',
+  verify: 'npm run payload:types && npm run lint && npm run typecheck',
+  payload: "NODE_OPTIONS='--import tsx' payload",
+  'payload:types': "NODE_OPTIONS='--import tsx' payload generate:types",
+  'generate:importmap': "NODE_OPTIONS='--import tsx' payload generate:importmap",
+  'schema:sync': 'PAYLOAD_SCHEMA_PUSH=true tsx scripts/schema-sync.ts',
+  seed: 'tsx scripts/seed.ts',
+  'pages:sync-layouts': 'tsx scripts/sync-page-layouts.ts',
+}
+
+try {
+  console.log('Payload Studio app scaffolding\n')
+
+  let created = 0
+  let skipped = 0
+
+  for (const entry of FILES) {
+    const target = path.join(cwd, entry.file)
+
+    if (fs.existsSync(target)) {
+      console.log('  skip (exists)  ' + entry.file)
+      skipped += 1
+      continue
+    }
+
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.writeFileSync(target, entry.contents)
+    console.log('  created        ' + entry.file)
+    created += 1
+  }
+
+  console.log('\n' + created + ' file(s) created, ' + skipped + ' skipped (already present).')
+
+  // Report which required package.json scripts are missing, without mutating.
+  const pkgPath = path.join(cwd, 'package.json')
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+    const scripts = pkg.scripts || {}
+    const missing = Object.entries(REQUIRED_SCRIPTS).filter(([name]) => !scripts[name])
+
+    if (missing.length > 0) {
+      console.log('\nAdd the following to package.json "scripts":\n')
+      for (const [name, command] of missing) {
+        console.log('  "' + name + '": "' + command.replace(/"/g, '\\"') + '",')
+      }
+    } else {
+      console.log('\nAll required package.json scripts are present.')
+    }
+  }
+
+  console.log('\nNext steps:')
+  console.log('  1. Wire payload.config.ts with configureAdmin(...) and createStudioPagesCollection(...)')
+  console.log('  2. npm run payload:types')
+  console.log('  3. npm run generate:importmap')
+  console.log('  4. See docs/studio-website-setup-guide.md for the full contract.')
+} catch (error) {
+  console.error('Scaffolding failed:', error)
+  process.exit(1)
+}