@forumone/create-throughline 0.3.1 → 0.5.0

package/dist/templates/base/apps/web/package.json.template

@@ -9,7 +9,19 @@
     "start": "next start",
     "clean": "rm -rf .next .turbo",
     "typecheck": "tsc --noEmit",
-    "payload": "payload"
+    "payload": "throughline-payload",
+    "payload:reap": "throughline-payload --reap",
+    "generate:types": "throughline-payload generate:types",
+    "generate:importmap": "throughline-payload generate:importmap",
+    "migrate": "PAYLOAD_MIGRATING=1 throughline-payload migrate",
+    "migrate:create": "throughline-payload migrate:create",
+    "migrate:status": "throughline-payload migrate:status",
+    "migrate:snapshot": "tsx scripts/write-migration-snapshot.ts",
+    "check:migrations": "tsx scripts/check-migrations.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:smoke": "playwright test",
+    "test:smoke:install": "playwright install --with-deps chromium"
   },
   "dependencies": {
     "@forumone/throughline-approvals": "^{{version_approvals}}",
@@ -23,21 +35,25 @@
     "@forumone/throughline-workflows": "^{{version_workflows}}",
     {{#if useReferenceDs}}"@forumone/throughline-design-contract": "^{{version_design_contract}}",
     "{{designSystemName}}": "workspace:*",
-    {{/if}}"@payloadcms/db-postgres": "^3.83.0",
-    "@payloadcms/next": "^3.83.0",
-    "@payloadcms/plugin-form-builder": "3.83.0",
-    "@payloadcms/richtext-lexical": "^3.83.0",
+    {{/if}}"@payloadcms/db-postgres": "^3.89.0",
+    "@payloadcms/next": "^3.89.0",
+    "@payloadcms/plugin-form-builder": "^3.89.0",
+    "@payloadcms/plugin-mcp": "^3.89.0",
+    "@payloadcms/richtext-lexical": "^3.89.0",
     "graphql": "^16.8.1",
     "inngest": "^4.2.0",
     "next": "^16.2.4",
-    "payload": "^3.83.0",
+    "payload": "^3.89.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "@types/node": "^20.17.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
-    "typescript": "^5.6.0"
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
   }
 }

package/dist/templates/base/apps/web/playwright.config.ts

@@ -0,0 +1,63 @@
+import { defineConfig, devices } from '@playwright/test'
+import { site } from './e2e/site'
+
+/*
+The smoke pack: a real server answering real requests.
+
+The vitest suite (the `*.test.ts` files under `src`) checks values — access rules, field
+validations — and connects to nothing. What it cannot reach is anything true
+only of a *response*: that the admin serves a login screen, that an unknown
+path is a 404 rather than a 500, that the REST API refuses an anonymous read of
+`users` in practice and not only on paper. That is this.
+
+**Deliberately not a functional suite.** It runs against an empty, migrated
+database — CI's `verify` job creates one — so nothing here needs a document to
+exist. Anything that does belongs in a seeded environment.
+
+    pnpm --dir apps/web build && pnpm --dir apps/web test:smoke     # local build
+    E2E_BASE_URL=https://example.org pnpm --dir apps/web test:smoke # deployed
+
+With `E2E_BASE_URL` set the pack runs against that URL and starts no server.
+Every check is a GET, which is what makes pointing it at production defensible;
+adding one that writes would not be. Which routes it checks is in `e2e/site.ts`.
+*/
+
+/*
+`next start`, not `next dev`: headers, caching and rendering are properties of
+the built output, and a pack against `dev` would assert something nobody
+deploys. So this needs `.next/` — in CI the build step has made it; locally,
+run `pnpm build` first.
+
+Hoisted, and spread in only when there is no URL to point at: with
+`exactOptionalPropertyTypes` an explicit `webServer: undefined` is a type
+error, and omitting the key is the only way to say "start nothing".
+*/
+const webServer = {
+  command: `pnpm exec next start --port ${String(site.port)}`,
+  url: `http://127.0.0.1:${String(site.port)}${site.home}`,
+  reuseExistingServer: !process.env.CI,
+  timeout: 120_000,
+  stdout: 'pipe' as const,
+  stderr: 'pipe' as const,
+}
+
+export default defineConfig({
+  testDir: './e2e',
+  outputDir: './e2e/.results',
+
+  // A cold `next start` can lose the first request to a route while it warms.
+  // Nothing here is a visual comparison, so one retry cannot hide a real failure.
+  retries: process.env.CI ? 1 : 0,
+  forbidOnly: Boolean(process.env.CI),
+  reporter: process.env.CI ? [['github'], ['list']] : [['list']],
+  workers: 1,
+
+  use: {
+    baseURL: site.baseURL ?? `http://127.0.0.1:${String(site.port)}`,
+    trace: 'retain-on-failure',
+  },
+
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+
+  ...(site.baseURL ? {} : { webServer }),
+})

package/dist/templates/base/apps/web/scripts/check-migrations.ts

@@ -0,0 +1,147 @@
+import { readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/*
+Three checks on `src/migrations`, each about a failure nobody sees until the
+moment it has to work.
+
+    pnpm check:migrations
+
+With `push: false` a migration is the only way this schema ever changes, so the
+migration chain has to stay usable.
+
+## 1. A migration with no schema snapshot
+
+`migrate:create` does not diff the config against the database. It diffs it
+against the `.json` snapshot beside the **most recent** migration, and writes one
+only when it generated the SQL itself. So a migration written by hand leaves the
+generator a step behind, and every run after it re-proposes a change that
+already shipped — often as drizzle's interactive rename prompt, which cannot be
+answered non-interactively, so the command exits having written nothing.
+
+Every migration is checked, not only the newest: a gap in the middle is inert
+today and was a blocked generator on the day it merged, which is the day this
+needs to fail. Write one with `pnpm migrate:snapshot`.
+
+## 2. An orphaned snapshot
+
+A `.json` with no `.ts` beside it. Delete a migration and leave its snapshot,
+and that snapshot sorts last and becomes what the generator diffs against — a
+schema no database will ever be in.
+
+## 3. A drop that a CASCADE has already carried out
+
+Payload's generator can emit, in this order:
+
+    DROP TABLE "posts" CASCADE;
+    ALTER TABLE "search_rels" DROP CONSTRAINT "search_rels_posts_fk";
+
+The CASCADE already removed that constraint, so the second statement errors,
+and because a migration runs in a transaction it takes the whole migration — or
+the whole rollback — with it. What is flagged is a bare `DROP CONSTRAINT` or
+`DROP INDEX` that follows a cascading `DROP` in the same function. A bare drop
+with no CASCADE above it is dropping something that is still there, and
+demanding `IF EXISTS` of it would be the kind of blanket rule people learn to
+suppress.
+*/
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const MIGRATIONS = path.resolve(here, '../src/migrations')
+
+const BARE_DROP = /\bDROP\s+(CONSTRAINT|INDEX)\s+"/gi
+
+// A `DROP` that cascaded, kept inside one statement by `[^;]*`. Not the word
+// on its own, which also matches the `ON DELETE cascade` of every foreign key.
+const CASCADE = /\bDROP\b[^;]*\bCASCADE\b/i
+
+const stem = (name: string) => name.replace(/\.(json|ts)$/, '')
+
+const entries = await readdir(MIGRATIONS).catch((error: NodeJS.ErrnoException) => {
+  if (error.code === 'ENOENT') return [] as string[]
+  throw error
+})
+
+const files = entries.filter((name) => name.endsWith('.ts') && name !== 'index.ts').sort()
+
+if (files.length === 0) {
+  console.log('No migrations yet. Create the first with:\n\n' + '    pnpm migrate:create initial\n')
+  process.exit(0)
+}
+
+// Basenames on both sides, because that is what `createMigration` sorts: it
+// reads the directory, keeps the `.json`, sorts, and takes the last.
+const snapshots = new Set(entries.filter((name) => name.endsWith('.json')).map(stem))
+
+const missing = files.filter((file) => !snapshots.has(stem(file)))
+
+if (missing.length > 0) {
+  console.error(
+    `${missing.length} migration(s) with no schema snapshot:\n\n` +
+      missing.map((file) => `  ${file}\n  ${stem(file)}.json   <- missing`).join('\n\n') +
+      '\n\nmigrate:create diffs the config against the snapshot beside the most\n' +
+      'recent migration. Without one it diffs against a schema that is a step\n' +
+      'behind, and re-proposes a change that has already shipped. Write it with:\n\n' +
+      '    pnpm migrate:snapshot\n\n' +
+      'Run it only once the migration is complete: the snapshot claims the\n' +
+      'database matches the config.\n',
+  )
+  process.exit(1)
+}
+
+const migrationNames = new Set(files.map(stem))
+const orphans = [...snapshots].filter((name) => !migrationNames.has(name)).sort()
+
+if (orphans.length > 0) {
+  console.error(
+    `${orphans.length} schema snapshot(s) with no migration beside them:\n\n` +
+      orphans.map((name) => `  ${name}.json`).join('\n') +
+      '\n\nA snapshot sorting last is what migrate:create diffs against, so one\n' +
+      'left behind by a deleted migration describes a schema no database will\n' +
+      'reach. Delete it, or restore the migration it belongs to.\n',
+  )
+  process.exit(1)
+}
+
+const problems: Array<{ file: string; statement: string }> = []
+
+for (const file of files) {
+  const source = await readFile(path.join(MIGRATIONS, file), 'utf8')
+
+  for (const name of ['up', 'down'] as const) {
+    const start = source.indexOf(`export async function ${name}`)
+    if (start === -1) continue
+    const other = source.indexOf('export async function', start + 1)
+    const body = source.slice(start, other === -1 ? undefined : other)
+
+    for (const match of body.matchAll(BARE_DROP)) {
+      const at = match.index ?? 0
+      if (!CASCADE.test(body.slice(0, at))) continue
+
+      const absolute = start + at
+      const lineStart = source.lastIndexOf('\n', absolute) + 1
+      const lineEnd = source.indexOf('\n', absolute)
+      problems.push({
+        file,
+        statement: source.slice(lineStart, lineEnd === -1 ? undefined : lineEnd).trim(),
+      })
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(
+    `${problems.length} drop(s) after a CASCADE without IF EXISTS:\n\n` +
+      problems.map((p) => `  ${p.file}\n    ${p.statement}`).join('\n\n') +
+      '\n\nA preceding DROP ... CASCADE has already removed these, so the\n' +
+      'migration will abort. Add IF EXISTS:\n\n' +
+      '    DROP CONSTRAINT IF EXISTS "..."\n' +
+      '    DROP INDEX IF EXISTS "..."\n',
+  )
+  process.exit(1)
+}
+
+console.log(
+  `Checked ${files.length} migration(s): every drop is guarded, every migration has\n` +
+    `its schema snapshot, and the generator will diff against ${stem(files.at(-1)!)}.`,
+)

package/dist/templates/base/apps/web/scripts/lib/target.ts

@@ -0,0 +1,95 @@
+import { resolveDatabaseConnection } from '../../src/lib/database'
+
+/*
+Which database a script is about to write to, and an explicit confirmation of
+it. For seed, import and repair scripts:
+
+    const where = requireTarget(process.argv, overwriting, 'Replaces every page')
+
+A script reads its connection string from the environment like everything else,
+so a shell that happens to have production's connection string loaded points it
+at production and nothing asks. This prints the target before anything is
+written, and demands `--confirm <database>@<host>` when the run would overwrite.
+
+It is not authentication — anyone who can run the script can type the token. It
+is the difference between a mistake and a decision, and the print alone is worth
+it: a run aimed at the wrong host is visible before it writes rather than after.
+
+Sized to the risk: creating what is missing is recoverable by deleting it;
+replacing what an editor has worked on is not.
+*/
+
+export interface Target {
+  host: string
+  database: string
+  /** The environment variable the connection string came from, or `(none)`. */
+  source: string
+}
+
+/**
+ * The database the config will actually connect to — through the same resolver
+ * `payload.config.ts` uses, not by reading `DATABASE_URI` directly. A guard that
+ * reports a different database than the code connects to is not a weaker guard;
+ * it is a false one.
+ */
+export function target(): Target {
+  let connection = ''
+  let source = '(none)'
+  try {
+    const resolved = resolveDatabaseConnection()
+    connection = resolved.value
+    source = resolved.name
+  } catch {
+    // Nothing set at all: a target of "none", which every destructive run refuses.
+  }
+
+  try {
+    const parsed = new URL(connection)
+    return { host: parsed.hostname, database: parsed.pathname.replace(/^\//, ''), source }
+  } catch {
+    return { host: '(unparseable)', database: '', source }
+  }
+}
+
+/*
+The token that has to be typed back. Not the database name on its own: Neon
+names every branch's database `neondb`, so `--confirm neondb` would match
+production and a preview alike. The host distinguishes them, so the host is in
+the token — long enough that it cannot be typed from memory while thinking about
+a different environment.
+*/
+export const confirmToken = (where: Target): string => `${where.database}@${where.host}`
+
+/**
+ * Print the target, and exit unless a destructive run has named it back.
+ *
+ * @param argv        The script's arguments, for `--confirm <database>@<host>`.
+ * @param destructive Whether this run would overwrite existing documents.
+ * @param consequence One line naming what would be overwritten, shown in the refusal.
+ */
+export function requireTarget(argv: string[], destructive: boolean, consequence: string): Target {
+  const where = target()
+  console.log(
+    `\n  target   ${where.database || '(none)'} on ${where.host}\n  from     ${where.source}`,
+  )
+
+  if (!destructive) return where
+
+  const index = argv.indexOf('--confirm')
+  const confirmed = index === -1 ? undefined : argv[index + 1]
+  const expected = confirmToken(where)
+
+  if (where.database === '' || confirmed !== expected) {
+    console.error(
+      `\n  Refusing to write.\n\n` +
+        `  ${consequence}\n` +
+        `  in the database "${where.database}" on ${where.host},\n` +
+        `  read from ${where.source}.\n\n` +
+        `  Re-run with --confirm ${where.database ? expected : '<database>@<host>'}\n` +
+        `  if that is what you meant.\n`,
+    )
+    process.exit(2)
+  }
+
+  return where
+}

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/access/anonymousAccess.test.ts

@@ -0,0 +1,36 @@
+import { describeAnonymousAccess } from '@forumone/throughline-core/testing'
+import config from '../payload.config'
+
+/*
+What a reader with no account can read, as values — no database.
+
+Every query the public site makes runs with nobody signed in, so a collection's
+own `read` rule decides whether a page can see its content. Close one by
+mistake and nothing errors: the page renders empty. Open the wrong one and the
+audit log, the approval queue or the MCP keys are on the internet.
+
+Every collection in the config — yours and the ones the plugins bring — has to
+be in exactly one bucket below. **Adding a collection fails this test until you
+put it in one.** Say where the site reads it, or why it is private.
+*/
+describeAnonymousAccess(config, {
+  renderPath: {
+    // Anonymous reads see published pages only; signed-in users see drafts.
+    pages: 'the page routes, once the frontend renders them',
+    // formsPlugin opens form definitions so a page can render the fields.
+    forms: 'any page that embeds a form',
+  },
+  private: {
+    users: 'accounts',
+    'payload-mcp-api-keys': 'MCP keys are credentials; narrowed to admins in payload.config.ts',
+    'audit-events': 'who did what',
+    approvals: 'who signed off on what',
+    'form-submissions': 'what readers typed into a form',
+    integrations: 'connection settings and sync state',
+    'job-failures': 'background jobs that ran out of retries, with their errors',
+    'payload-kv': 'the key-value store Payload keeps',
+    'payload-locked-documents': 'who is editing what',
+    'payload-preferences': 'admin UI state',
+    'payload-migrations': 'the migration history',
+  },
+})

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

@@ -1,15 +1,19 @@
+import type { InngestFunction } from 'inngest'
 import { serve } from 'inngest/next'
 import { getPayload } from 'payload'
 import config from '@/payload.config'
+import { cacheTags } from '@/lib/cache-tags'
 import { createInngestClient } from '@forumone/throughline-core'
 import {
   createAuditEventEchoFunction,
   createExecuteScheduledPublishesFunction,
   createExpireStaleApprovalsFunction,
+  createHealthcheckFailureHandler,
   createHealthcheckFunction,
   createPayloadReachableCheck,
   createPublishAtScheduledTimeFunction,
   createRevalidateOnPublishFunction,
+  createTerminalFailureHandler,
   type ScheduledPublishRequest,
 } from '@forumone/throughline-workflows'
 import { getPublishingService } from '@forumone/throughline-publishing'
@@ -23,6 +27,13 @@ import {
 const inngest = createInngestClient({ id: '{{projectName}}' })
 const payload = await getPayload({ config })
 
+/*
+A workflow that runs out of retries is logged, recorded in the `job-failures`
+collection, and posted to ERROR_WEBHOOK_URL if that is set. Passed to every
+factory below: a factory without it fails silently into Inngest's dashboard.
+*/
+const onTerminalFailure = createTerminalFailureHandler({ payload })
+
 const emailFunctions = getEmailFunctions(payload) ?? []
 const formsFunctions = getFormsFunctions(payload) ?? []
 /*
@@ -42,7 +53,23 @@ async function publishScheduled({ collection, id, reasoning }: ScheduledPublishR
 
 const scheduledCollections = [{ slug: 'pages' }]
 
-const integrationRegistry = getIntegrationRegistry(payload)
+/*
+Where each publishable collection's documents are served, so a publish
+revalidates the right path. There are no defaults: a collection missing here
+has its cache tags dropped but no path revalidated, and the run logs a warning.
+Add an entry for every collection you give publishingPlugin.
+*/
+const urlBuilders = {
+  pages: (slug: string) => (slug === 'home' ? '/' : `/${slug}`),
+}
+
+/*
+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
@@ -54,13 +81,20 @@ const integrationFunctions =
 export const { GET, POST, PUT } = serve({
   client: inngest,
   functions: [
-    createRevalidateOnPublishFunction({ inngest, payload }),
+    createRevalidateOnPublishFunction({
+      inngest,
+      payload,
+      urlBuilders,
+      cacheTags,
+      onTerminalFailure,
+    }),
     // On time: sleeps until each document's scheduled time.
     createPublishAtScheduledTimeFunction({
       inngest,
       payload,
       collections: scheduledCollections,
       publish: publishScheduled,
+      onTerminalFailure,
     }),
     // The backstop, for a schedule whose wake-up event never arrived.
     createExecuteScheduledPublishesFunction({
@@ -70,13 +104,16 @@ export const { GET, POST, PUT } = serve({
       publish: publishScheduled,
       schedule: '17 3 * * *',
       overdueByMs: 60 * 60 * 1000,
+      onTerminalFailure,
     }),
-    createExpireStaleApprovalsFunction({ inngest, payload }),
-    createAuditEventEchoFunction({ inngest }),
+    createExpireStaleApprovalsFunction({ inngest, payload, onTerminalFailure }),
+    createAuditEventEchoFunction({ inngest, onTerminalFailure }),
     createHealthcheckFunction({
       inngest,
       payload,
       checks: [createPayloadReachableCheck()],
+      onFailure: createHealthcheckFailureHandler({ payload }),
+      onTerminalFailure,
     }),
     ...emailFunctions,
     ...formsFunctions,

package/dist/templates/base/apps/web/src/instrumentation.ts

@@ -0,0 +1,35 @@
+import type { Instrumentation } from 'next'
+import {
+  buildRequestErrorReport,
+  describeErrorReporting,
+  reportError,
+} from '@forumone/throughline-core/observability'
+
+/*
+Where a server-side error goes.
+
+`onRequestError` fires when Next captures an error in a Server Component
+render, a Route Handler, a Server Action or the proxy — the one place that sees
+all four. It does not see client-side errors; `error.tsx` and
+`global-error.tsx` are the boundaries for those.
+
+The report is logged first, always, and then posted to `ERROR_WEBHOOK_URL` if
+it is set — a log drain, an alerting endpoint, a Slack incoming webhook, a
+proxy in front of whichever tracker you choose. Request headers are copied
+from an allowlist: `cookie` carries the Payload session, and must never leave.
+
+The subpath import keeps the CMS out of this file. This hook runs when
+something has already gone wrong, and loading Payload here would put the whole
+CMS in the one path that has to work regardless.
+*/
+export const onRequestError: Instrumentation.onRequestError = async (error, request, context) => {
+  const report = buildRequestErrorReport(error, request, context)
+  console.error('[error]', JSON.stringify(report))
+  await reportError(report)
+}
+
+/** Once per server instance: say so if error reports are going nowhere. */
+export function register(): void {
+  const status = describeErrorReporting()
+  if (!status.startsWith('error reporting: on')) console.warn('[boot]', status)
+}

package/dist/templates/base/apps/web/src/lib/cache-tags.ts

@@ -0,0 +1,23 @@
+/*
+Next cache tags, named in one place.
+
+A tag has two ends: a reader that caches under it and a hook that drops it.
+Nothing checks that they match, so both build their tags from this object —
+`payload.config.ts` hands it to the revalidation hooks, the Inngest route hands
+it to `createRevalidateOnPublishFunction`, and frontend code that caches a read
+tags it from here too:
+
+    import { unstable_cache } from 'next/cache'
+    import { cacheTags } from '@/lib/cache-tags'
+
+    const getNavigation = unstable_cache(loadNavigation, ['navigation'], {
+      tags: [cacheTags.global('navigation')],
+    })
+
+Change the scheme here and every end moves with it. Imported from the
+package's `/cache-tags` subpath, which imports nothing, so frontend code that
+uses it does not pull in Payload.
+*/
+import { createCacheTags } from '@forumone/throughline-workflows/cache-tags'
+
+export const cacheTags = createCacheTags()