@forumone/create-throughline 0.3.1 → 0.5.0

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,34 +1,102 @@
 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 {
+  assertEnvironment,
   auditPlugin,
-  createApiKeysCollection,
   createInngestClient,
+  createMcpToolCollector,
+  mcpApiKeyAccess,
 } from '@forumone/throughline-core'
+import { mcpPlugin } from '@payloadcms/plugin-mcp'
 import { componentsPlugin } from '@forumone/throughline-components'
 import { publishingPlugin } from '@forumone/throughline-publishing'
 import {
+  approvalsEnv,
   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 { emailEnv, emailPlugin } from '@forumone/throughline-email'
+import { formsEnv, formsPlugin } from '@forumone/throughline-forms'
+import { createTagRevalidationHooks } from '@forumone/throughline-workflows'
+import { cacheTags } from './lib/cache-tags'
+import { jobFailuresPlugin } from '@forumone/throughline-core/observability'
+import { databaseConnectionString } from './lib/database'
 {{#if useReferenceDs}}import type { Manifest } from '@forumone/throughline-design-contract'
 import designSystemManifest from '{{designSystemName}}/manifest' with { type: 'json' }
 {{/if}}
 
+/*
+Every variable this site needs, checked once and reported together, before any
+plugin runs. Without it each plugin throws on the first thing it finds, in
+registration order, inside `next build`'s "Failed to collect page data" — one
+missing variable per deploy, reading like a build failure.
+
+The plugins' lists are their own declarations of what they refuse to start
+without, so a requirement a plugin adds arrives here with the upgrade. Only the
+site's own variables are written out. A value passed to a plugin as an option
+rather than read from the environment takes that plugin's list out of this call.
+
+Anything that loads this file — `next build`, `payload generate:types`,
+`payload migrate` — needs these set. Where only parsing matters (CI's typecheck
+and type generation), placeholders of the right length do; see
+.github/workflows/ci.yml.
+*/
+assertEnvironment(
+  approvalsEnv,
+  emailEnv,
+  formsEnv,
+  {
+    name: 'PAYLOAD_SECRET',
+    minLength: 32,
+    why: 'Signs Payload sessions and auth tokens. Generate with `openssl rand -base64 48`.',
+  },
+  {
+    name: 'NEXT_PUBLIC_SERVER_URL',
+    why:
+      'The origin approval links are built against, e.g. http://localhost:3000. On a ' +
+      'Vercel preview, set it to https://$VERCEL_URL.',
+  },
+  // Accepts several names (see lib/database.ts), so it is a check, not a name.
+  () => databaseConnectionString(),
+)
+
 const __filename = fileURLToPath(import.meta.url)
 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()
+
+/*
+Drops a Next cache tag when content changes, named by the same scheme your
+cached reads use (see lib/cache-tags.ts). Give every collection and global that
+a cached read renders a pair of these: afterChange and afterDelete on a
+collection, afterChange on a global. Draft saves and autosave drop nothing.
+*/
+const revalidation = createTagRevalidationHooks({ cacheTags })
+
+// 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',
@@ -52,13 +120,27 @@ const Users: CollectionConfig = {
   ],
 }
 
+// The public site reads with nobody signed in, so a collection it renders needs
+// a read rule that says yes to that. Without one, Payload's default refuses —
+// and the page renders empty rather than erroring. Anonymous readers get a
+// query, so they see published documents only; anybody signed in sees drafts
+// too, which the admin and live preview need. `src/access/anonymousAccess.test.ts`
+// holds every collection to the bucket it is listed in.
+const publishedOrSignedIn: Access = ({ req: { user } }) =>
+  user ? true : { _status: { equals: 'published' } }
+
 // Example Pages collection. Replace this with your real content model;
 // keep the `policy` group on collections that should require approval —
 // the approvals plugin reads that field shape.
 const Pages: CollectionConfig = {
   slug: 'pages',
   admin: { useAsTitle: 'title' },
+  access: { read: publishedOrSignedIn },
   versions: { drafts: true },
+  hooks: {
+    afterChange: [revalidation.afterCollectionChange()],
+    afterDelete: [revalidation.afterCollectionDelete()],
+  },
   fields: [
     { name: 'title', type: 'text', required: true },
     { name: 'slug', type: 'text', required: true, unique: true },
@@ -93,23 +175,43 @@ 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 }),
 
+    // Where a workflow that ran out of retries, or a failing healthcheck, leaves
+    // a row — see the failure handlers in app/api/inngest/route.ts. Not the
+    // audit log: that records who did what through an MCP tool.
+    jobFailuresPlugin({}),
+
     componentsPlugin({
       {{#if useReferenceDs}}manifest: { type: 'object', manifest: designSystemManifest as unknown as Manifest },
       {{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({
@@ -119,6 +221,7 @@ export default buildConfig({
       approvalResolver: {
         getActiveApproval: async () => null, // TODO: wire to approvals plugin
       },
+      mcpTools,
     }),
 
     approvalsPlugin({
@@ -135,9 +238,10 @@ export default buildConfig({
           return []
         },
       },
+      mcpTools,
     }),
 
-    auditQueryPlugin({}),
+    auditQueryPlugin({ mcpTools }),
 
     emailPlugin({
       inngest,
@@ -161,19 +265,32 @@ export default buildConfig({
 
     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.
+      // ipHashSecret: read from FORMS_IP_HASH_SECRET, checked above.
+      // 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 that runs
+    // every tool as the person it is bound to, so who may mint, read and
+    // revoke one is an admin's call: `mcpApiKeyAccess` narrows the key
+    // collection to `isAdmin`, and refuses a key principal outright.
+    mcpPlugin({
+      mcp: { tools: mcpTools.tools },
+      overrideApiKeyCollection: mcpApiKeyAccess(isAdmin),
+    }),
   ],
 })

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

@@ -0,0 +1,57 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+/*
+The cheap tier: vitest in node, with no database and no browser.
+
+Everything here is an invariant over values — the access rules, field
+validations, hooks as functions — and `payload.config.ts` is imported, never
+connected. That is what lets these run on every pull request, in CI's `fast`
+job, which has no database. Anything that needs one belongs in `verify`, and
+anything true only of a real response belongs in the smoke pack (`e2e/`).
+
+`environment: 'node'`, deliberately: nothing in `apps/web` renders here. The
+components live in the design system, whose own suite runs them.
+*/
+export default defineConfig({
+  /*
+  The two aliases `tsconfig.json` declares. Next resolves them from that file
+  and vitest does not, so a module importing `@/lib/…` or `@payload-config`
+  cannot be loaded here unless they are repeated.
+  */
+  resolve: {
+    alias: {
+      '@payload-config': path.join(here, 'src/payload.config.ts'),
+      '@': path.join(here, 'src'),
+    },
+  },
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    /*
+    Enough for `payload.config.ts` to load, and nothing more.
+
+    The plugins check their secrets when the config is built, so importing it
+    needs every value present. None is a credential: the secrets are padded
+    placeholders, the address is under `.invalid`, which RFC 2606 reserves so
+    it can never resolve, and the connection string names a database nobody
+    has. That is safe because the config *parses* the string and never
+    connects — the same fact CI's `fast` job relies on.
+
+    Set here rather than left to the shell, so `pnpm test` needs no setup and a
+    `DATABASE_URI` somebody exported for a migration cannot reach a test.
+    */
+    env: {
+      DATABASE_URI: 'postgres://test:test@localhost:5432/does-not-exist',
+      PAYLOAD_SECRET: 'test-only-not-a-real-secret-000000000000',
+      APPROVAL_TOKEN_SECRET: 'test-only-not-a-real-secret-000000000000',
+      FORMS_IP_HASH_SECRET: 'test-only-not-a-real-secret-000000000000',
+      RESEND_API_KEY: 're_test_only_not_a_real_key',
+      EMAIL_FROM_ADDRESS: 'test-only@example.invalid',
+      NEXT_PUBLIC_SERVER_URL: 'http://localhost:3000',
+    },
+  },
+})

package/dist/templates/base/claude/hooks/gate.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Stop hook: run the cheap half of CI's gate — typecheck and lint — when a
+# session ends with pending changes under apps/ or design-system/.
+#
+# Why a hook and not only CI: these failures are cheap to fix in the session
+# that caused them and expensive later. A session that touched nothing exits in
+# milliseconds, which is what keeps this cheap enough to leave switched on.
+#
+# Deliberately not here: tests, manifest validation, the generated-files check
+# and the build. They take minutes or need a database; they are CI's job. See
+# CLAUDE.md for the whole gate.
+#
+# This reports. It never blocks and never edits, so it cannot wedge a session on
+# a failure it cannot resolve. Exit is always 0. Set THROUGHLINE_SKIP_GATE=1 to
+# silence it, for instance in headless sessions that run their own gate.
+
+set -uo pipefail
+
+[[ -z "${THROUGHLINE_SKIP_GATE:-}" ]] || exit 0
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[[ -n "$ROOT" ]] || exit 0
+
+if [[ -z "$(git -C "$ROOT" status --porcelain -- apps design-system 2>/dev/null)" ]]; then
+  exit 0
+fi
+
+cd "$ROOT" || exit 0
+
+OUTPUT="$(pnpm typecheck 2>&1 && pnpm lint 2>&1)"
+STATUS=$?
+
+if [[ $STATUS -eq 0 ]]; then
+  MESSAGE="Gate clean: typecheck + lint. Tests, validate, check-generated and the build are CI's job — see CLAUDE.md."
+else
+  # The failing rule or type error is at the end, and a systemMessage is read
+  # in a terminal, not scrolled.
+  MESSAGE="Gate FAILED (typecheck/lint) — CI will fail on this:
+
+$(printf '%s' "$OUTPUT" | tail -25)"
+fi
+
+node -e 'process.stdout.write(JSON.stringify({ systemMessage: process.argv[1], suppressOutput: true }))' "$MESSAGE"
+exit 0

package/dist/templates/base/claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "GATE=\"$(git rev-parse --show-toplevel 2>/dev/null)/.claude/hooks/gate.sh\"; [ -f \"$GATE\" ] && exec bash \"$GATE\" || exit 0",
+            "timeout": 180,
+            "statusMessage": "Running the gate (typecheck + lint)…"
+          }
+        ]
+      }
+    ]
+  }
+}

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"