@forumone/create-throughline 0.3.0 → 0.4.0

package/dist/templates/base/apps/web/scripts/write-migration-snapshot.ts

@@ -0,0 +1,119 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+
+/*
+Writes the `.json` schema snapshot beside a hand-written migration.
+
+    pnpm migrate:snapshot                 # the newest migration
+    pnpm migrate:snapshot 20260812_154500_add_jobs
+    pnpm migrate:snapshot --force         # replace an existing snapshot
+
+`migrate:create` diffs the config against the snapshot beside the **most
+recent** migration, and writes a fresh one only when it generates the SQL
+itself. A migration written by hand therefore leaves the generator one step
+behind, and every run after it re-proposes a change that already shipped.
+
+This closes the gap the way `createMigration` does, minus the diff: it asks the
+adapter for the schema the config describes and serialises it. The adapter
+builds that schema from the config alone, so this needs **no database**.
+
+## When it would be a lie
+
+The snapshot says: *the database, once this migration has run, matches the
+config.* Run it only after the hand-written migration is complete. A snapshot
+claiming a config change the migration only half implements makes the next
+generated migration quietly omit the missing half.
+
+Overwriting needs `--force`, because the common mistake is running this instead
+of writing the migration: the snapshot is rewritten to match a config that moved
+on, and the change becomes invisible to the generator — the schema drifts with
+no migration anywhere that would apply it.
+
+The config is loaded, so the environment it validates must be present. Values
+that only need to parse — secrets, keys — can be placeholders on this run.
+*/
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const MIGRATIONS = path.resolve(here, '../src/migrations')
+
+// `pnpm run x -- --flag` forwards the `--` itself, which `parseArgs` would read
+// as "positionals from here".
+const argv = process.argv.slice(2).filter((arg) => arg !== '--')
+
+const { positionals, values } = parseArgs({
+  args: argv,
+  allowPositionals: true,
+  options: { force: { type: 'boolean', default: false } },
+})
+
+const migrations = (await readdir(MIGRATIONS).catch(() => [] as string[]))
+  .filter((name) => name.endsWith('.ts') && name !== 'index.ts')
+  .map((name) => name.slice(0, -'.ts'.length))
+  .sort()
+
+if (migrations.length === 0) {
+  console.error(`No migrations in ${MIGRATIONS}.`)
+  process.exit(1)
+}
+
+const target = positionals[0]?.replace(/\.(json|ts)$/, '') ?? migrations.at(-1)!
+
+if (!migrations.includes(target)) {
+  console.error(
+    `No migration named ${target}.\n\nMigrations in src/migrations:\n` +
+      migrations.map((name) => `  ${name}`).join('\n') +
+      '\n',
+  )
+  process.exit(1)
+}
+
+const destination = path.join(MIGRATIONS, `${target}.json`)
+const existing = await readFile(destination, 'utf8').then(
+  () => true,
+  () => false,
+)
+
+if (existing && !values.force) {
+  console.error(
+    `${target}.json already exists, and describes the schema as of that migration.\n` +
+      'Rewriting it to match a config that has since changed hides the change from\n' +
+      '`migrate:create`. If replacing it is genuinely what you want, pass --force.\n',
+  )
+  process.exit(1)
+}
+
+if (target !== migrations.at(-1)) {
+  console.warn(
+    `Warning: ${target} is not the newest migration. Only the newest snapshot is\n` +
+      'read by migrate:create, so this describes a state nothing will diff against.\n',
+  )
+}
+
+// No database, and nothing that runs on startup (seeds, syncs, cron
+// registration) from a script whose whole job is to serialise a schema.
+const payload = await getPayload({ config, disableDBConnect: true, disableOnInit: true })
+
+const db = payload.db as typeof payload.db & {
+  requireDrizzleKit: () => { generateDrizzleJson: (schema: unknown) => Promise<unknown> }
+  schema: unknown
+}
+
+const { generateDrizzleJson } = db.requireDrizzleKit()
+const snapshot = await generateDrizzleJson(db.schema)
+
+// Byte for byte what `createMigration` writes, with no trailing newline, so a
+// hand-written migration's snapshot is indistinguishable from a generated one.
+await writeFile(destination, JSON.stringify(snapshot, null, 2))
+
+console.log(
+  `Wrote src/migrations/${target}.json\n\n` +
+    'Commit it beside the migration. Confirm the generator is unblocked with:\n\n' +
+    '    pnpm migrate:create check --skip-empty\n\n' +
+    'which exits without writing anything when there is no diff.\n',
+)
+
+process.exit(0)

package/dist/templates/base/apps/web/src/app/api/inngest/route.ts.template

@@ -1,3 +1,4 @@
+import type { InngestFunction } from 'inngest'
 import { serve } from 'inngest/next'
 import { getPayload } from 'payload'
 import config from '@/payload.config'
@@ -8,8 +9,11 @@ import {
   createExpireStaleApprovalsFunction,
   createHealthcheckFunction,
   createPayloadReachableCheck,
+  createPublishAtScheduledTimeFunction,
   createRevalidateOnPublishFunction,
+  type ScheduledPublishRequest,
 } from '@forumone/throughline-workflows'
+import { getPublishingService } from '@forumone/throughline-publishing'
 import { getEmailFunctions } from '@forumone/throughline-email'
 import { getFormsFunctions } from '@forumone/throughline-forms'
 import {
@@ -22,7 +26,30 @@ const payload = await getPayload({ config })
 
 const emailFunctions = getEmailFunctions(payload) ?? []
 const formsFunctions = getFormsFunctions(payload) ?? []
-const integrationRegistry = getIntegrationRegistry(payload)
+/*
+Through the publishing service, in process — so a scheduled publish passes the
+same composition, accessibility and approval gates as an interactive one. Not
+`payload.update`, which skips all of them.
+*/
+async function publishScheduled({ collection, id, reasoning }: ScheduledPublishRequest) {
+  const outcome = await getPublishingService(payload).publish({
+    collection,
+    id,
+    actor: { apiKeyName: 'scheduled-publish', channel: 'mcp' },
+    meta: { reasoning },
+  })
+  return { published: outcome.published, reason: outcome.reason }
+}
+
+const scheduledCollections = [{ slug: 'pages' }]
+
+/*
+Typed with this app's own `InngestFunction.Any`. The registry is generic in what
+`createFunctions` returns and defaults to `unknown`, because the platform never
+touches those functions — and one `unknown` element leaves `serve()` unable to
+type the whole array below.
+*/
+const integrationRegistry = getIntegrationRegistry<InngestFunction.Any>(payload)
 const integrationContext = getIntegrationContext(payload)
 const integrationFunctions =
   integrationRegistry && integrationContext
@@ -35,12 +62,21 @@ export const { GET, POST, PUT } = serve({
   client: inngest,
   functions: [
     createRevalidateOnPublishFunction({ inngest, payload }),
+    // On time: sleeps until each document's scheduled time.
+    createPublishAtScheduledTimeFunction({
+      inngest,
+      payload,
+      collections: scheduledCollections,
+      publish: publishScheduled,
+    }),
+    // The backstop, for a schedule whose wake-up event never arrived.
     createExecuteScheduledPublishesFunction({
       inngest,
       payload,
-      collections: [{ slug: 'pages' }],
-      publishingServerUrl: process.env.NEXT_PUBLIC_SERVER_URL!,
-      publishingApiKey: process.env.PUBLISHING_SYSTEM_API_KEY!,
+      collections: scheduledCollections,
+      publish: publishScheduled,
+      schedule: '17 3 * * *',
+      overdueByMs: 60 * 60 * 1000,
     }),
     createExpireStaleApprovalsFunction({ inngest, payload }),
     createAuditEventEchoFunction({ inngest }),

package/dist/templates/base/apps/web/src/lib/database.ts

@@ -0,0 +1,158 @@
+/*
+Which connection string to connect with, and the name of the variable it came
+from.
+
+Three things make this more than `process.env.DATABASE_URI!`.
+
+**The Vercel–Neon integration does not set `DATABASE_URI`.** It injects
+`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `POSTGRES_URL`,
+`POSTGRES_URL_NON_POOLING` and friends. Left alone, the first deploy fails at
+page-data collection with a connection error that says nothing about a missing
+variable.
+
+**The app wants the pooler and a migration cannot use it.** Neon's pooled
+endpoint is PgBouncer in transaction mode: right for a serving function, whose
+connections are many and short, and unusable for DDL, where Drizzle relies on
+prepared statements and session state. `migrate` hangs or fails partway. The two
+hostnames differ only by a `-pooler` suffix on the endpoint id.
+
+**`DATABASE_URI` leads both lists, deliberately.** It is the variable you scope
+per environment — a Preview-scoped `DATABASE_URI` pointing at a preview branch —
+while the integration's variables are project-wide and resolve to production. A
+preview build that fell through to one of those while migrating would migrate
+production.
+
+If you deploy somewhere other than Vercel + Neon, set `DATABASE_URI` and the
+rest of the list is never consulted.
+*/
+const RUNTIME_CANDIDATES = [
+  'DATABASE_URI',
+  // Neon via the Vercel integration, pooled. Correct for a serving instance.
+  'DATABASE_URL',
+  'POSTGRES_URL',
+  // Direct, as a fallback: a project with no pooler still boots.
+  'DATABASE_URL_UNPOOLED',
+  'POSTGRES_URL_NON_POOLING',
+] as const
+
+/*
+The DDL path: an optional migration-only credential first, then direct endpoints
+ahead of pooled ones. The pooled pair is kept at the end rather than dropped, so
+a migration whose only reachable string is pooled meets the explanation in
+`describeProblem` instead of "no connection string".
+
+`MIGRATION_DATABASE_URL` lets the app run as a role that can read and write rows
+and no more, while migrations run as the schema owner. It is consulted only by
+the process that migrates — see `isMigrationProcess` — because a platform with
+no build-only variables would otherwise hand the DDL role straight back to the
+running app.
+*/
+const MIGRATION_CANDIDATES = [
+  'MIGRATION_DATABASE_URL',
+  'DATABASE_URI',
+  'DATABASE_URL_UNPOOLED',
+  'POSTGRES_URL_NON_POOLING',
+  'DATABASE_URL',
+  'POSTGRES_URL',
+] as const
+
+/**
+ * Whether this process is `payload migrate` rather than a server or a build.
+ *
+ * `PAYLOAD_MIGRATING=1` is set by the `migrate` script in package.json and by
+ * nothing else. `NEXT_RUNTIME` is defined in every server bundle Next emits, so
+ * no route or page can satisfy both conditions even if the first were set.
+ */
+export function isMigrationProcess(): boolean {
+  return process.env.PAYLOAD_MIGRATING === '1' && !process.env.NEXT_RUNTIME
+}
+
+let announced = false
+
+/*
+One line in the deploy log saying which variable a migration connected through.
+Without it, a migration that quietly fell through to the app's credential looks
+exactly like one that worked. The name, never the value: a build log is not a
+secret store.
+*/
+function announceMigrationCredential(name: string): void {
+  if (announced) return
+  announced = true
+  process.stderr.write(`payload migrate: connecting via ${name}\n`)
+}
+
+/*
+What is wrong with a connection string, in words, before Postgres says
+"password authentication failed" and leaves you guessing. A string wrapped in
+quotes or prefixed with `psql` fails as `getaddrinfo ENOTFOUND`; a masked or
+truncated password fails as an auth error. The checks below catch the shapes
+that can be seen without connecting. Nothing here ever prints the value.
+*/
+function describeProblem(name: string, value: string, migrating: boolean): string | undefined {
+  const raw = value.trim()
+
+  if (/^psql\s/i.test(raw)) {
+    return `${name} starts with "psql". Copy the connection string itself, not the command that uses it.`
+  }
+  if (/^["']|["']$/.test(raw)) {
+    return `${name} is wrapped in quotes. Most hosts store the value literally — paste it without them.`
+  }
+  if (!/^postgres(ql)?:\/\//i.test(raw)) {
+    return `${name} does not start with postgres:// or postgresql://.`
+  }
+
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    return `${name} is not a valid URL.`
+  }
+
+  if (!url.password) {
+    return `${name} has no password. Neon's console masks it until you reveal or copy it.`
+  }
+  if (/^[•*·]+$/.test(decodeURIComponent(url.password))) {
+    return `${name}'s password is a row of bullets — it was copied while the console still had it masked.`
+  }
+  if (migrating && url.hostname.includes('-pooler')) {
+    return (
+      `${name} points at Neon's pooled endpoint. Migrations need the direct one: PgBouncer in ` +
+      `transaction mode does not support the prepared statements Drizzle's DDL relies on. Use ` +
+      `the host without "-pooler".`
+    )
+  }
+
+  return undefined
+}
+
+/**
+ * The connection string, and the name of the variable it came from.
+ *
+ * The name matters: `DATABASE_URI` leads both lists, so one left in a shell or a
+ * pulled `.env` file wins without saying so, and every Neon branch's database is
+ * called `neondb` — the host and database name alone may not tell you which
+ * environment you are about to write to. See `scripts/lib/target.ts`.
+ */
+export function resolveDatabaseConnection(): { name: string; value: string } {
+  const migrating = isMigrationProcess()
+  const candidates: readonly string[] = migrating ? MIGRATION_CANDIDATES : RUNTIME_CANDIDATES
+
+  for (const name of candidates) {
+    const value = process.env[name]
+    if (value && value.trim() !== '') {
+      const problem = describeProblem(name, value, migrating)
+      if (problem) throw new Error(problem)
+      if (migrating) announceMigrationCredential(name)
+      return { name, value: value.trim() }
+    }
+  }
+
+  throw new Error(
+    `No database connection string. Set DATABASE_URI, or connect a Neon database in Vercel — ` +
+      `the integration provides ${candidates.slice(1).join(', ')}, and every one was empty.`,
+  )
+}
+
+export function databaseConnectionString(): string {
+  return resolveDatabaseConnection().value
+}

package/dist/templates/base/apps/web/src/payload.config.ts.template

@@ -1,21 +1,27 @@
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { buildConfig } from 'payload'
-import type { CollectionConfig } from 'payload'
+import type { Access, CollectionConfig } from 'payload'
 import { postgresAdapter } from '@payloadcms/db-postgres'
 import { lexicalEditor } from '@payloadcms/richtext-lexical'
 import {
   auditPlugin,
-  createApiKeysCollection,
   createInngestClient,
+  createMcpToolCollector,
 } from '@forumone/throughline-core'
+import { mcpPlugin } from '@payloadcms/plugin-mcp'
 import { componentsPlugin } from '@forumone/throughline-components'
 import { publishingPlugin } from '@forumone/throughline-publishing'
-import { approvalsPlugin } from '@forumone/throughline-approvals'
+import {
+  approvalsPlugin,
+  buildActionUrl,
+  generateActionToken,
+} from '@forumone/throughline-approvals'
 import { auditQueryPlugin } from '@forumone/throughline-audit'
 import { integrationsPlugin } from '@forumone/throughline-integrations'
 import { emailPlugin } from '@forumone/throughline-email'
 import { formsPlugin } from '@forumone/throughline-forms'
+import { databaseConnectionString } from './lib/database'
 {{#if useReferenceDs}}import type { Manifest } from '@forumone/throughline-design-contract'
 import designSystemManifest from '{{designSystemName}}/manifest' with { type: 'json' }
 {{/if}}
@@ -25,6 +31,23 @@ const __dirname = path.dirname(__filename)
 
 const inngest = createInngestClient({ id: '{{projectName}}' })
 
+/*
+Where every Throughline server puts its tools for `mcpPlugin`, which serves them
+all on one `/api/mcp`. Each plugin declares its tools as the config is built and
+binds the handlers at `onInit`; `mcpPlugin` reads this array at both moments.
+Hand over `mcpTools.tools` itself — a spread or `.slice()` would hand over
+something nobody fills.
+*/
+const mcpTools = createMcpToolCollector()
+
+// A person in `users` with the admin role. `req.user` can also be an MCP key
+// document, which has no roles and is never an admin, so the collection is
+// checked first — once payload-types.ts exists, TypeScript insists on it.
+const isAdmin: Access = ({ req: { user } }) =>
+  user?.collection === 'users' &&
+  Array.isArray(user.roles) &&
+  (user.roles as unknown[]).includes('admin')
+
 // Users collection — extend with your own fields and SSO/auth provider.
 const Users: CollectionConfig = {
   slug: 'users',
@@ -89,16 +112,30 @@ export default buildConfig({
   admin: { user: 'users' },
   editor: lexicalEditor(),
   db: postgresAdapter({
-    pool: { connectionString: process.env.DATABASE_URI! },
+    // See lib/database.ts: which variable wins, and why a migration refuses
+    // Neon's pooled endpoint.
+    pool: { connectionString: databaseConnectionString() },
+    migrationDir: path.resolve(__dirname, 'migrations'),
+    // Never push schema: migrations are the only way this database changes.
+    // The adapter pushes whenever NODE_ENV !== 'production', which is true of
+    // every script and dev server. One pointed at a shared database silently
+    // syncs its schema and records a `dev` migration, and the next
+    // `payload migrate` in CI then stops to ask about it — with no terminal to
+    // answer — and skips the migration it was meant to apply.
+    push: false,
   }),
-  collections: [Users, Pages, createApiKeysCollection()],
+  // MCP keys live in `payload-mcp-api-keys`, which `mcpPlugin` below brings.
+  collections: [Users, Pages],
   secret: process.env.PAYLOAD_SECRET!,
   typescript: {
     outputFile: path.resolve(__dirname, 'payload-types.ts'),
   },
   plugins: [
-    // Order matters: audit first (so other plugins can write to it),
-    // then content plugins, then notification/forms/integrations.
+    // Order matters twice. `auditPlugin` first: every other Throughline plugin
+    // requires the audit log at init. And every tool-bearing plugin before
+    // `mcpPlugin`, which reads the declared tools when the config is built — a
+    // plugin registered after it gets no per-key checkbox, and its tools are
+    // denied to every key with no error anywhere.
     auditPlugin({ inngest }),
 
     componentsPlugin({
@@ -106,6 +143,7 @@ export default buildConfig({
       {{else}}// TODO: point at your design system manifest
       manifest: { type: 'url', url: 'https://your-design-system.example.com/manifest.json' },
       {{/if}}matching: { strategy: 'tfidf' },
+      mcpTools,
     }),
 
     publishingPlugin({
@@ -115,6 +153,7 @@ export default buildConfig({
       approvalResolver: {
         getActiveApproval: async () => null, // TODO: wire to approvals plugin
       },
+      mcpTools,
     }),
 
     approvalsPlugin({
@@ -131,36 +170,67 @@ export default buildConfig({
           return []
         },
       },
+      mcpTools,
     }),
 
-    auditQueryPlugin({}),
+    auditQueryPlugin({ mcpTools }),
 
     emailPlugin({
       inngest,
       // TODO: replace with your real user lookups
       resolveApprover: async (_userId) => null,
       resolveRequester: async (_userId) => null,
-      // TODO: sign these URLs (HMAC) so an approval decision can't be forged.
-      buildActionUrl: async ({ approvalId, action, approverId }) =>
-        `${process.env.NEXT_PUBLIC_SERVER_URL}/api/approvals/decision?approval=${approvalId}&action=${action}&approver=${approverId}`,
+      // Signed, and pointed at the route approvalsPlugin serves
+      // (`/api/approvals/action`). The token binds one approval, one action
+      // and one approver, so a link cannot be edited into a different decision.
+      buildActionUrl: async ({ approvalId, action, approverId }) => {
+        const secret = process.env.APPROVAL_TOKEN_SECRET
+        if (!secret) throw new Error('APPROVAL_TOKEN_SECRET is required to sign approval links.')
+        const token = await generateActionToken(
+          { approvalId, action, approverId, issuedAt: Date.now() },
+          secret,
+        )
+        return buildActionUrl(process.env.NEXT_PUBLIC_SERVER_URL!, token)
+      },
       tokens: { brandName: '{{projectName}}' },
     }),
 
     formsPlugin({
       inngest,
       ipHashSecret: process.env.FORMS_IP_HASH_SECRET!,
-      // TODO: list every place a form is allowed to send to. The plugin
-      // refuses to deliver to destinations that aren't in this list.
+      // TODO: list every place a form is allowed to send to, and delete the
+      // placeholder. The plugin refuses to start with an empty list — the
+      // allowlist is the security perimeter — and refuses to deliver anywhere
+      // not on it. example.com is reserved and accepts no mail, so the
+      // placeholder routes nothing anywhere while it stands.
       allowedDestinations: [
-        // {
-        //   type: 'email',
-        //   value: 'team@example.com',
-        //   label: 'Main inbox',
-        //   description: 'General contact form destination',
-        // },
+        {
+          type: 'email',
+          value: 'forms@example.com',
+          label: 'Placeholder',
+          description: 'Replace before launch: example.com accepts no mail.',
+        },
       ],
+      mcpTools,
     }),
 
-    integrationsPlugin({ inngest }),
+    integrationsPlugin({ inngest, mcpTools }),
+
+    // Last of the tool-bearing chain. An MCP key is a credential: the plugin
+    // ships its collection with no access rules — "anybody signed in" — so it
+    // is narrowed to admins here.
+    mcpPlugin({
+      mcp: { tools: mcpTools.tools },
+      overrideApiKeyCollection: (collection) => ({
+        ...collection,
+        access: {
+          ...collection.access,
+          read: isAdmin,
+          create: isAdmin,
+          update: isAdmin,
+          delete: isAdmin,
+        },
+      }),
+    }),
   ],
 })

package/dist/templates/base/github/scripts/check-generated.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# payload-types.ts and importMap.js are committed but generated from
+# payload.config.ts. Regenerating and diffing is what stops them drifting from
+# the config:
+#
+#   - a stale importMap.js is a 500 on any admin screen that renders a component
+#     the map has never heard of — a plugin upgrade that swaps in a custom
+#     Publish button is enough
+#   - stale types make everything downstream compile against a schema that no
+#     longer exists
+#
+# Run from the repository root, with the environment payload.config.ts demands.
+# **No database is needed** — the config parses a connection string and never
+# reaches it — which is what lets this run on every pull request.
+
+set -euo pipefail
+
+TYPES='apps/web/src/payload-types.ts'
+MAP='apps/web/src/app/(payload)/admin/importMap.js'
+
+# `git status --porcelain` rather than `git diff`: a file that was never
+# committed is untracked, and `git diff` says nothing about it.
+pnpm --dir apps/web run generate:types
+if [ -n "$(git status --porcelain -- "$TYPES")" ]; then
+  git --no-pager diff -- "$TYPES" || true
+  echo "::error::payload-types.ts is stale or uncommitted — run 'pnpm --dir apps/web generate:types' and commit it."
+  exit 1
+fi
+
+# importMap.js is compared as a *set* of lines. Payload emits plugin entries in
+# an order that differs between macOS and Linux, so a byte comparison fails on a
+# file whose content is identical. Order does not matter to correctness; a
+# missing entry does, and that is what this catches.
+sort "$MAP" > "${RUNNER_TEMP:-/tmp}/importmap-committed"
+pnpm --dir apps/web run generate:importmap
+sort "$MAP" > "${RUNNER_TEMP:-/tmp}/importmap-regenerated"
+
+if ! diff -u "${RUNNER_TEMP:-/tmp}/importmap-committed" "${RUNNER_TEMP:-/tmp}/importmap-regenerated"; then
+  echo "::error::importMap.js is stale — run 'pnpm --dir apps/web generate:importmap' and commit it."
+  exit 1
+fi
+
+git checkout -- "$MAP"