@forumone/create-throughline 0.3.1 → 0.5.0

package/dist/templates/base/github/workflows/ci.yml

@@ -0,0 +1,143 @@
+name: CI
+
+# Two tiers.
+#
+#   fast    every pull request and every push to main. No database: every gate
+#           here needs the config to parse, not to connect.
+#   verify  pushes to main, and on demand. A Postgres service, the migrations,
+#           a production build — `next build` boots Payload to collect page
+#           data, so it needs a migrated database — and the Playwright smoke
+#           pack against `next start` on that build.
+#
+# A green `fast` is what a pull request is reviewed on; `verify` is what says
+# main still builds and migrates. Add a path filter to run `verify` on pull
+# requests that touch the config, the migrations or the dependencies, once this
+# project has enough of all three to make it worth the minutes.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# What payload.config.ts and the plugins check at load, as placeholders. The
+# config parses the connection string and never connects in `fast`; secrets only
+# have to be long enough to pass the plugins' own checks. Never a real value.
+env:
+  DATABASE_URI: postgres://ci:ci@localhost:5432/ci
+  PAYLOAD_SECRET: ci-placeholder-not-a-secret-000000000000
+  APPROVAL_TOKEN_SECRET: ci-placeholder-not-a-secret-000000000000
+  FORMS_IP_HASH_SECRET: ci-placeholder-not-a-secret-000000000000
+  RESEND_API_KEY: re_ci_placeholder
+  EMAIL_FROM_ADDRESS: ci@example.com
+  NEXT_PUBLIC_SERVER_URL: http://localhost:3000
+
+jobs:
+  fast:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      # First, because a lockfile missing an entry passes every other gate
+      # locally and fails here.
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Check singletons resolve once
+        run: pnpm check:instances
+
+      - name: Check every package that ships code has tests
+        run: pnpm check:tested
+
+      - name: Check the migration chain
+        run: pnpm check:migrations
+
+      # Builds the design system's manifest and lints it against the contract:
+      # an unknown token, a composition rule naming a missing component, an
+      # example pointing at a story that does not exist.
+      - name: Validate the design-system manifest
+        run: pnpm validate
+
+      - name: Check generated Payload artifacts are current
+        run: bash .github/scripts/check-generated.sh
+
+      - name: Test
+        run: pnpm test
+
+      # Non-blocking: a new advisory is news, not necessarily a defect, and
+      # blocking every open pull request the morning a CVE is published is how
+      # a gate gets removed rather than fixed. Read it.
+      - name: Audit production dependencies
+        run: pnpm check:audit
+        continue-on-error: true
+
+  verify:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: ci
+          POSTGRES_PASSWORD: ci
+          POSTGRES_DB: ci
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      # A fresh database, migrated exactly as a deploy would migrate it. A
+      # migration that does not apply cleanly from empty fails here rather than
+      # on the first environment somebody creates.
+      - name: Migrate
+        run: pnpm --dir apps/web migrate
+
+      - name: Build
+        run: pnpm build
+
+      # The smoke pack (apps/web/e2e): `next start` on the build above, against
+      # the empty database migrated above, asserting only what answers without
+      # content — the front door, a 404, the admin sign-in screen, and the REST
+      # API refusing an anonymous read of private collections. Here and not in
+      # `fast`, because the server needs a database to answer at all.
+      - name: Install Chromium for the smoke pack
+        run: pnpm --dir apps/web test:smoke:install
+
+      - name: Smoke test
+        run: pnpm --dir apps/web test:smoke

package/dist/templates/base/gitignore

@@ -13,3 +13,12 @@ dist/
 .vscode/
 
 coverage/
+
+# Written by throughline-payload (@forumone/throughline-core): the process
+# group of each in-flight Payload CLI run, so the next run can reap one whose
+# runner was killed before it could clean up.
+.payload-cli-pids
+
+# Playwright: traces and screenshots from a failed smoke run
+e2e/.results/
+playwright-report/

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

@@ -7,14 +7,20 @@
     "dev": "{{#if useReferenceDs}}pnpm --filter \"./design-system\" build && {{/if}}turbo run dev",
     "storybook": "turbo run storybook",
     "build-storybook": "turbo run build-storybook",
-    "validate": "turbo run validate",
+    "validate": "turbo run validate --filter=./design-system",
     "lint": "turbo run lint",
     "typecheck": "turbo run typecheck",
     "test": "turbo run test",
+    "check:instances": "tsx scripts/check-single-instance.ts",
+    "check:tested": "tsx scripts/check-tested-packages.ts",
+    "check:audit": "tsx scripts/check-audit.ts",
+    "check:migrations": "pnpm --dir apps/web run check:migrations",
+    "payload:reap": "pnpm --dir apps/web run payload:reap",
     "format": "prettier --write ."
   },
   "devDependencies": {
     "prettier": "^3.4.0",
+    "tsx": "^4.21.0",
     "turbo": "^2.3.0",
     "typescript": "^5.6.0"
   },

package/dist/templates/base/scripts/check-audit.ts

@@ -0,0 +1,117 @@
+import { execFileSync } from 'node:child_process'
+
+/*
+`pnpm audit` over the production tree, with an allowlist that cannot rot.
+
+    pnpm check:audit
+
+**Why not `pnpm audit --prod --audit-level=high` on its own.** A Payload + Next
+production tree is rarely clean: there are usually high advisories in it that no
+request the site serves can reach. A gate that is red on every run is a gate
+people stop reading.
+
+**Why not `pnpm.auditConfig.ignoreGhsas`.** It filters, and that is all it does.
+A list of ids in `package.json` carries no reason, and nothing notices when one
+stops applying — the dependency is dropped or patched, and the entry sits there
+suppressing a finding it no longer describes.
+
+So this asserts the allowlist in both directions. An advisory that is not on the
+list is reported. An entry that no longer appears in the audit is *also*
+reported, as something to delete. That second half is why this is a script.
+
+It is non-blocking in CI. A new advisory is news, not necessarily a defect, and
+blocking every open pull request the morning a CVE is published is how a gate
+gets removed rather than fixed.
+*/
+
+interface Allowed {
+  ghsa: string
+  module: string
+  /** Which path it is on, and why that path cannot reach a request. */
+  why: string
+}
+
+/**
+ * High and critical advisories in the production tree that are accepted.
+ *
+ * "Not exploitable" is not a reason. Say which dependency path it arrives on
+ * and what would have to be true for a request to reach it.
+ */
+const ALLOWED: Allowed[] = []
+
+interface Advisory {
+  severity: string
+  module_name: string
+  title: string
+  github_advisory_id?: string
+}
+
+function audit(): Advisory[] {
+  let stdout: string
+  try {
+    // Exits non-zero whenever it finds anything at or above the level, so the
+    // throw is the normal case and the output is on it.
+    stdout = execFileSync('pnpm', ['audit', '--prod', '--audit-level=high', '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+  } catch (error) {
+    stdout = (error as { stdout?: string }).stdout ?? ''
+  }
+
+  if (stdout.trim() === '') return []
+  const parsed = JSON.parse(stdout) as { advisories?: Record<string, Advisory> }
+  // One advisory reached through several dependency paths is reported once
+  // per path; it is one finding.
+  const unique = new Map<string, Advisory>()
+  for (const advisory of Object.values(parsed.advisories ?? {})) {
+    if (advisory.severity !== 'high' && advisory.severity !== 'critical') continue
+    unique.set(advisory.github_advisory_id ?? `${advisory.module_name}:${advisory.title}`, advisory)
+  }
+  return [...unique.values()]
+}
+
+function main(): void {
+  const found = audit()
+  const seen = new Set(found.map((a) => a.github_advisory_id).filter(Boolean) as string[])
+  const allowed = new Map(ALLOWED.map((entry) => [entry.ghsa, entry]))
+
+  const unexpected = found.filter(
+    (a) => !a.github_advisory_id || !allowed.has(a.github_advisory_id),
+  )
+  const stale = ALLOWED.filter((entry) => !seen.has(entry.ghsa))
+
+  for (const advisory of found) {
+    if (advisory.github_advisory_id && allowed.has(advisory.github_advisory_id)) {
+      console.log(`  = ${advisory.module_name.padEnd(18)} ${advisory.github_advisory_id}  accepted`)
+    }
+  }
+
+  if (unexpected.length > 0) {
+    console.log(`\n${unexpected.length} advisory/advisories not on the allowlist:\n`)
+    for (const advisory of unexpected) {
+      console.log(`  ! ${advisory.severity.padEnd(8)} ${advisory.module_name}`)
+      console.log(`      ${advisory.github_advisory_id ?? '(no GHSA id)'} — ${advisory.title}`)
+    }
+    console.log(
+      '\nEither upgrade past it, or add it to ALLOWED in scripts/check-audit.ts with the\n' +
+        'dependency path it arrives on and why no request can reach it.',
+    )
+  }
+
+  if (stale.length > 0) {
+    console.log(
+      `\n${stale.length} allowlist entry/entries no longer apply and should be deleted:\n`,
+    )
+    for (const entry of stale) console.log(`  - ${entry.ghsa}  (${entry.module})`)
+  }
+
+  if (unexpected.length === 0 && stale.length === 0) {
+    console.log(`\nNothing new. ${found.length} known advisory/advisories, each with a reason.`)
+    return
+  }
+
+  process.exitCode = 1
+}
+
+main()

package/dist/templates/base/scripts/check-single-instance.ts

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process'
+
+/*
+One copy of each package that carries React context or is a singleton.
+
+    pnpm check:instances
+
+**The failure this exists for.** pnpm keys a package's identity on its version
+*and* its resolved peers. When two workspace packages resolve a peer differently
+— one on `@types/node@^20`, another on `^24`, say — pnpm installs the same
+version of `@payloadcms/ui` twice, in two directories. Two directories are two
+module instances, two instances are two React contexts, and a component that
+reads the context the provider did not populate gets `undefined`. In the admin
+that is an intermittent 500 on one view while every other view works.
+
+**Nothing else can see it.** `pnpm install` succeeds, typecheck, lint and every
+unit test pass, because the two copies are byte-identical: the problem exists
+only at module-resolution time, and only matters at render time. So this asserts
+what no other gate can — that each package below resolves to exactly one
+instance across the workspace. A version range is not the thing to check; the
+instance is.
+
+When it fails, compare the peers of the packages that pull in each copy and pin
+the offender in `pnpm.overrides` in the root `package.json`.
+*/
+
+/**
+ * Packages where a second copy is a bug rather than waste: each holds React
+ * context or is a singleton by construction, so two copies fail at runtime.
+ */
+const SINGLETONS = ['@payloadcms/ui', 'payload', 'react', 'react-dom']
+
+/**
+ * Copies that are real but cannot reach a bundle, by version, with the reason.
+ * An entry here is a claim that nothing you ship imports that copy.
+ */
+const ACCEPTED: Record<string, string[]> = {}
+
+interface Instance {
+  version: string
+  path: string
+}
+
+/** Every resolved copy of `name`, by reading pnpm's own resolution. */
+function instances(name: string): Instance[] {
+  const stdout = execFileSync(
+    'pnpm',
+    ['ls', name, '--recursive', '--depth', 'Infinity', '--json'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 },
+  )
+
+  const found = new Map<string, Instance>()
+  const visit = (deps: Record<string, unknown> | undefined): void => {
+    for (const [depName, raw] of Object.entries(deps ?? {})) {
+      const info = raw as {
+        version?: string
+        path?: string
+        dependencies?: Record<string, unknown>
+      }
+      if (!info || typeof info !== 'object') continue
+      if (depName === name && info.path) {
+        found.set(info.path, { version: info.version ?? '?', path: info.path })
+      }
+      visit(info.dependencies)
+    }
+  }
+
+  for (const pkg of JSON.parse(stdout) as Record<string, unknown>[]) {
+    visit(pkg['dependencies'] as Record<string, unknown> | undefined)
+    visit(pkg['devDependencies'] as Record<string, unknown> | undefined)
+  }
+  return [...found.values()]
+}
+
+function main(): void {
+  let failed = false
+
+  for (const name of SINGLETONS) {
+    const all = instances(name)
+    const accepted = ACCEPTED[name] ?? []
+    const live = all.filter((i) => !accepted.includes(i.version))
+
+    if (live.length <= 1) {
+      const note = all.length > live.length ? `  (+${all.length - live.length} accepted)` : ''
+      console.log(`  = ${name.padEnd(20)} one instance${note}`)
+      continue
+    }
+
+    failed = true
+    console.log(`\n  ! ${name} resolves to ${live.length} instances:\n`)
+    for (const instance of live) console.log(`      ${instance.version}  ${instance.path}`)
+  }
+
+  if (!failed) {
+    console.log('\nEvery singleton resolves once.')
+    return
+  }
+
+  console.log(
+    [
+      '',
+      'Two copies of the same version are still two modules, and two modules holding',
+      'React context is a runtime failure no type or test can see.',
+      '',
+      'The usual cause is a peer that differs between workspace packages, which changes',
+      "pnpm's identity hash for the dependency. Compare the peers and pin the offender",
+      'in `pnpm.overrides`.',
+    ].join('\n'),
+  )
+  process.exitCode = 1
+}
+
+main()

package/dist/templates/base/scripts/check-tested-packages.ts

@@ -0,0 +1,163 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+/*
+Every workspace package that ships code has at least one test.
+
+    pnpm check:tested
+
+Deliberately not a coverage percentage. A number invites a target, and a target
+invites tests written to move it. What this asserts is the one bit a coverage
+report hides: a package with source and **no test file at all**, which looks
+exactly like a package whose tests pass. Defects in a code generator, a
+serialiser or a set of access rules then surface downstream, one at a time, long
+after the package that caused them.
+*/
+
+/**
+ * Packages with source files and no tests, keyed by their path from the repo
+ * root, with the reason.
+ *
+ * This is the whole exception list. An entry is a claim that the package holds
+ * no behaviour worth asserting, not that testing it is inconvenient. An entry
+ * whose package has since gained a test fails the check, so each one is removed
+ * by the same change that makes it untrue.
+ */
+const ACCEPTED: Record<string, string> = {
+{{#if useReferenceDs}}{{else}}  'design-system':
+    'Placeholder until the design system is written. Delete this entry with its first component.',
+{{/if}}}
+
+/** Directories that never hold source worth testing. */
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.turbo',
+  'storybook-static',
+  'coverage',
+  '__snapshots__',
+])
+
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']
+
+const isTest = (name: string): boolean => /\.(test|spec)\.[cm]?[jt]sx?$/.test(name)
+
+const isSource = (name: string): boolean =>
+  SOURCE_EXTENSIONS.some((extension) => name.endsWith(extension)) &&
+  !isTest(name) &&
+  !name.endsWith('.d.ts')
+
+interface Counts {
+  source: number
+  tests: number
+}
+
+/**
+ * Source and test files under a package's own `src`. `src` rather than the
+ * package root, so a package cannot pass on the strength of its own build
+ * tooling. A package with no `src` ships no code and is not asked.
+ */
+function countUnder(packagePath: string): Counts | undefined {
+  const src = join(packagePath, 'src')
+  if (!existsSync(src)) return undefined
+
+  const counts: Counts = { source: 0, tests: 0 }
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (IGNORED_DIRS.has(entry.name)) continue
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) walk(full)
+      else if (isTest(entry.name)) counts.tests += 1
+      else if (isSource(entry.name)) counts.source += 1
+    }
+  }
+  walk(src)
+  return counts
+}
+
+interface WorkspacePackage {
+  name: string
+  path: string
+}
+
+function workspacePackages(): WorkspacePackage[] {
+  const stdout = execFileSync('pnpm', ['ls', '--recursive', '--depth', '-1', '--json'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  return (JSON.parse(stdout) as WorkspacePackage[]).filter((pkg) => Boolean(pkg.name && pkg.path))
+}
+
+function main(): void {
+  const root = process.cwd()
+  const untested: string[] = []
+  const staleExceptions: string[] = []
+  let checked = 0
+
+  for (const pkg of workspacePackages()) {
+    const counts = countUnder(pkg.path)
+    if (!counts || counts.source === 0) continue
+
+    checked += 1
+    const where = relative(root, pkg.path) || '.'
+    const accepted = ACCEPTED[where]
+
+    if (counts.tests > 0) {
+      // An exception that has stopped applying reads, in review, as though
+      // somebody decided this package needs no tests.
+      if (accepted) staleExceptions.push(where)
+      console.log(
+        `  = ${where.padEnd(32)} ${String(counts.tests).padStart(3)} test files  ` +
+          `${String(counts.source).padStart(4)} source`,
+      )
+      continue
+    }
+
+    if (accepted) {
+      console.log(`  - ${where.padEnd(32)} no tests, accepted`)
+      continue
+    }
+
+    untested.push(where)
+    console.log(`  ! ${where.padEnd(32)}   0 test files  ${String(counts.source).padStart(4)} source`)
+  }
+
+  if (staleExceptions.length > 0) {
+    console.log(
+      [
+        '',
+        `${staleExceptions.length} package(s) are on the accepted list and now have tests:`,
+        '',
+        ...staleExceptions.map((where) => `      ${where}`),
+        '',
+        'Delete the entry from ACCEPTED in scripts/check-tested-packages.ts.',
+      ].join('\n'),
+    )
+    process.exitCode = 1
+  }
+
+  if (untested.length === 0) {
+    if (!process.exitCode) console.log(`\nAll ${checked} packages that ship code have tests.`)
+    return
+  }
+
+  console.log(
+    [
+      '',
+      `${untested.length} package(s) ship code with no test file:`,
+      '',
+      ...untested.map((where) => `      ${where}`),
+      '',
+      'One test is the bar, not a coverage number. If the package genuinely holds no',
+      'runtime behaviour, add it to ACCEPTED in scripts/check-tested-packages.ts with',
+      'the reason.',
+    ].join('\n'),
+  )
+  process.exitCode = 1
+}
+
+main()

package/dist/templates/base/turbo.json

@@ -5,7 +5,22 @@
     "build": {
       "dependsOn": ["^build"],
       "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
-      "env": ["NODE_ENV"]
+      "env": [
+        "NODE_ENV",
+        "DATABASE_URI",
+        "DATABASE_URL",
+        "DATABASE_URL_UNPOOLED",
+        "POSTGRES_URL",
+        "POSTGRES_URL_NON_POOLING",
+        "PAYLOAD_SECRET",
+        "APPROVAL_TOKEN_SECRET",
+        "FORMS_IP_HASH_SECRET",
+        "RESEND_API_KEY",
+        "EMAIL_*",
+        "INNGEST_*",
+        "BLOB_READ_WRITE_TOKEN",
+        "NEXT_PUBLIC_*"
+      ]
     },
     "build-storybook": {
       "dependsOn": ["^build"],