@forumone/create-throughline 0.4.0 → 1.0.0-next.2

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

@@ -0,0 +1,33 @@
+import { describeAnonymousAccess } from '@forumone/throughline/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',
+  },
+  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',
+    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,92 +1,28 @@
-import type { InngestFunction } from 'inngest'
 import { serve } from 'inngest/next'
 import { getPayload } from 'payload'
-import config from '@/payload.config'
-import { createInngestClient } from '@forumone/throughline-core'
-import {
-  createAuditEventEchoFunction,
-  createExecuteScheduledPublishesFunction,
-  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 {
-  getIntegrationContext,
-  getIntegrationRegistry,
-} from '@forumone/throughline-integrations'
+import config, { suite } from '@/payload.config'
+import { inngest } from '@/lib/inngest'
+import { inngestJobs } from '@forumone/throughline/jobs/inngest'
+import { createTerminalFailureHandler } from '@forumone/throughline/jobs'
 
-const inngest = createInngestClient({ id: '{{projectName}}' })
 const payload = await getPayload({ config })
 
-const emailFunctions = getEmailFunctions(payload) ?? []
-const formsFunctions = getFormsFunctions(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 }
-}
+Every job the Throughline suite runs, as `throughline()` in payload.config.ts
+listed them: publish revalidation, scheduled publishing and its backstop,
+approval expiry, the audit echo, the healthcheck, the approval emails and each
+integration's jobs. Each keeps the function id it has always had, so a run in
+flight survives an upgrade.
 
-const scheduledCollections = [{ slug: 'pages' }]
+A job that runs out of retries is logged, recorded in the `job-failures`
+collection, and posted to ERROR_WEBHOOK_URL if that is set: given once, here,
+and handed to every job.
 
-/*
-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.
+Add this site's own functions to the list beside them.
 */
-const integrationRegistry = getIntegrationRegistry<InngestFunction.Any>(payload)
-const integrationContext = getIntegrationContext(payload)
-const integrationFunctions =
-  integrationRegistry && integrationContext
-    ? integrationRegistry
-        .list()
-        .flatMap((integration) => integration.createFunctions(integrationContext))
-    : []
+const jobs = inngestJobs(inngest, { onFailure: createTerminalFailureHandler({ payload }), payload })
 
 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: scheduledCollections,
-      publish: publishScheduled,
-      schedule: '17 3 * * *',
-      overdueByMs: 60 * 60 * 1000,
-    }),
-    createExpireStaleApprovalsFunction({ inngest, payload }),
-    createAuditEventEchoFunction({ inngest }),
-    createHealthcheckFunction({
-      inngest,
-      payload,
-      checks: [createPayloadReachableCheck()],
-    }),
-    ...emailFunctions,
-    ...formsFunctions,
-    ...integrationFunctions,
-  ],
+  functions: [...jobs.functions(suite.jobs)],
 })

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/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/cache-tags'
+
+export const cacheTags = createCacheTags()

package/dist/templates/base/apps/web/src/lib/inngest.ts.template

@@ -0,0 +1,7 @@
+import { createInngestClient } from '@forumone/throughline/jobs/inngest'
+
+/*
+The one Inngest client: payload.config.ts sends events through it, and the
+endpoint at app/api/inngest serves this site's jobs with it.
+*/
+export const inngest = createInngestClient({ id: '{{projectName}}' })

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

@@ -4,41 +4,133 @@ import { buildConfig } from 'payload'
 import type { Access, CollectionConfig } from 'payload'
 import { postgresAdapter } from '@payloadcms/db-postgres'
 import { lexicalEditor } from '@payloadcms/richtext-lexical'
-import {
-  auditPlugin,
-  createInngestClient,
-  createMcpToolCollector,
-} from '@forumone/throughline-core'
+import { assertEnvironment, mcpApiKeyAccess, throughline } from '@forumone/throughline'
+import { inngestJobs } from '@forumone/throughline/jobs/inngest'
 import { mcpPlugin } from '@payloadcms/plugin-mcp'
-import { componentsPlugin } from '@forumone/throughline-components'
-import { publishingPlugin } from '@forumone/throughline-publishing'
-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 { approvalsEnv } from '@forumone/throughline/approvals'
+import { emailEnv } from '@forumone/throughline/email'
+import { createPayloadReachableCheck } from '@forumone/throughline/integrations'
+import { createTagRevalidationHooks } from '@forumone/throughline/publishing'
+import { cacheTags } from './lib/cache-tags'
+import { inngest } from './lib/inngest'
 import { databaseConnectionString } from './lib/database'
-{{#if useReferenceDs}}import type { Manifest } from '@forumone/throughline-design-contract'
+{{#if useReferenceDs}}import type { Manifest } from '@forumone/throughline-design-system/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,
+  {
+    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}}' })
+/*
+The Throughline suite, in one call. It registers every plugin in the order they
+need, gives each the one MCP tool collector, sends their events through the jobs
+adapter, and lists the jobs these options call for, which app/api/inngest
+serves. One value for each thing two plugins must agree on: the approvals
+collection's slug reaches approvals, the emails and the expiry job alike.
+
+A plugin is on when its key is here. Delete a key to turn one off.
+*/
+export const suite = throughline({
+  jobs: inngestJobs(inngest),
+  // The collections publishing gates, "Your work" lists and scheduling publishes.
+  collections: ['pages'],
+
+  {{#if useReferenceDs}}components: {
+    manifest: { type: 'object', manifest: designSystemManifest as unknown as Manifest },
+    matching: { strategy: 'tfidf' },
+  },
+  {{else}}components: {
+    // TODO: point at your design system manifest
+    manifest: { type: 'url', url: 'https://your-design-system.example.com/manifest.json' },
+    matching: { strategy: 'tfidf' },
+  },
+  {{/if}}publishing: {
+    /*
+    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 in `collections`.
+    */
+    urls: { pages: (slug: string) => (slug === 'home' ? '/' : `/${slug}`) },
+    revalidation: { cacheTags },
+    // Scheduled publishes go through the publishing pipeline, as an editor's
+    // would. The backstop catches a schedule whose wake-up event never arrived.
+    scheduling: { backstop: { schedule: '17 3 * * *', overdueByMs: 60 * 60 * 1000 } },
+  },
+
+  approvals: {
+    groups: [
+      { slug: 'editorial', name: 'Editorial' },
+      { slug: 'legal', name: 'Legal' },
+      { slug: 'communications', name: 'Communications' },
+      { slug: 'senior', name: 'Senior leadership' },
+    ],
+    groupResolver: {
+      // TODO: replace with your actual user/group lookup (DB query, SSO, etc.)
+      async resolveUsers(_groupSlugs) {
+        return []
+      },
+    },
+  },
+
+  auditQuery: {},
+
+  // Approval links are signed with APPROVAL_TOKEN_SECRET and point at
+  // NEXT_PUBLIC_SERVER_URL, both checked above.
+  email: {
+    // TODO: replace with your real user lookups
+    resolveApprover: async (_userId) => null,
+    resolveRequester: async (_userId) => null,
+    tokens: { brandName: '{{projectName}}' },
+  },
+
+  integrations: {},
+
+  // A failing check is recorded in `job-failures` and posted to ERROR_WEBHOOK_URL.
+  healthcheck: { checks: [createPayloadReachableCheck()] },
+})
 
 /*
-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.
+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 mcpTools = createMcpToolCollector()
+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
@@ -60,7 +152,7 @@ const Users: CollectionConfig = {
       type: 'select',
       hasMany: true,
       defaultValue: ['admin'],
-      options: ['admin', 'editor', 'approver', 'form-admin'],
+      options: ['admin', 'editor', 'approver'],
     },
     {
       name: 'groups',
@@ -71,13 +163,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 },
@@ -131,106 +237,15 @@ export default buildConfig({
     outputFile: path.resolve(__dirname, 'payload-types.ts'),
   },
   plugins: [
-    // 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({
-      {{#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({
-      collections: [{ slug: 'pages' }],
-      inngest,
-      // Lazy-resolve approvals at call time so plugin order doesn't matter.
-      approvalResolver: {
-        getActiveApproval: async () => null, // TODO: wire to approvals plugin
-      },
-      mcpTools,
-    }),
-
-    approvalsPlugin({
-      inngest,
-      groups: [
-        { slug: 'editorial', name: 'Editorial' },
-        { slug: 'legal', name: 'Legal' },
-        { slug: 'communications', name: 'Communications' },
-        { slug: 'senior', name: 'Senior leadership' },
-      ],
-      groupResolver: {
-        // TODO: replace with your actual user/group lookup (DB query, SSO, etc.)
-        async resolveUsers(_groupSlugs) {
-          return []
-        },
-      },
-      mcpTools,
-    }),
-
-    auditQueryPlugin({ mcpTools }),
-
-    emailPlugin({
-      inngest,
-      // TODO: replace with your real user lookups
-      resolveApprover: async (_userId) => null,
-      resolveRequester: async (_userId) => null,
-      // 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}}' },
-    }),
+    suite.plugin,
 
-    formsPlugin({
-      inngest,
-      ipHashSecret: process.env.FORMS_IP_HASH_SECRET!,
-      // 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: 'forms@example.com',
-          label: 'Placeholder',
-          description: 'Replace before launch: example.com accepts no mail.',
-        },
-      ],
-      mcpTools,
-    }),
-
-    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.
+    // After the suite, whose plugins fill the tools it serves. 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: (collection) => ({
-        ...collection,
-        access: {
-          ...collection.access,
-          read: isAdmin,
-          create: isAdmin,
-          update: isAdmin,
-          delete: isAdmin,
-        },
-      }),
+      mcp: { tools: suite.mcpTools },
+      overrideApiKeyCollection: mcpApiKeyAccess(isAdmin),
     }),
   ],
 })

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

@@ -0,0 +1,56 @@
+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',
+      RESEND_API_KEY: 're_test_only_not_a_real_key',
+      EMAIL_FROM_ADDRESS: 'test-only@example.invalid',
+      NEXT_PUBLIC_SERVER_URL: 'http://localhost:3000',
+    },
+  },
+})