@forumone/create-throughline 0.3.1 → 0.4.0

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,165 @@
+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> = {
+  'apps/web':
+    'Freshly scaffolded: the config and routes are generated wiring. Delete this entry with your first test here — an access rule, a hook or a field validation is the place to start.',
+{{#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"],

package/dist/templates/with-reference-ds/design-system/scripts/build-manifest.ts

@@ -10,42 +10,77 @@ import { getTokenList } from '../src/tokens/index.ts'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const packageRoot = resolve(__dirname, '..')
-const componentsDir = resolve(packageRoot, 'src/components')
 const outputDir = resolve(packageRoot, 'dist')
 const outputFile = resolve(outputDir, 'manifest.json')
 
-async function readPackageVersion(): Promise<string> {
+/**
+ * Every directory, relative to the package, whose subdirectories are
+ * components. A design system that splits components across layers (atoms and
+ * molecules, or a Gesso-style `02-layouts` / `03-components`) lists each one.
+ */
+const CONTRACT_LAYERS = ['src/components']
+
+/**
+ * The manifest names the design system from its own `package.json`. This file
+ * is vendored into every scaffolded project, and a hard-coded name made each of
+ * them publish a manifest claiming to be the reference design system.
+ */
+async function readPackage(): Promise<{ name: string; version: string; description?: string }> {
   const raw = await readFile(resolve(packageRoot, 'package.json'), 'utf8')
-  const parsed = JSON.parse(raw) as { version?: string }
-  return parsed.version ?? '0.0.0'
+  const parsed = JSON.parse(raw) as { name?: string; version?: string; description?: string }
+  if (!parsed.name) throw new Error('package.json has no "name"; the manifest needs one.')
+  return {
+    name: parsed.name,
+    version: parsed.version ?? '0.0.0',
+    ...(parsed.description ? { description: parsed.description } : {}),
+  }
 }
 
 async function collectContracts(): Promise<Record<string, ComponentContract>> {
   const components: Record<string, ComponentContract> = {}
 
-  let entries: string[]
-  try {
-    entries = await readdir(componentsDir)
-  } catch {
-    return components
-  }
+  for (const layer of CONTRACT_LAYERS) {
+    let entries: string[]
+    try {
+      entries = await readdir(resolve(packageRoot, layer))
+    } catch {
+      continue
+    }
 
-  for (const name of entries) {
-    const dir = resolve(componentsDir, name)
-    const dirStat = await stat(dir).catch(() => null)
-    if (!dirStat?.isDirectory()) continue
+    for (const name of entries.sort()) {
+      // Underscore-prefixed directories are private implementation details.
+      if (name.startsWith('_') || name.startsWith('.')) continue
 
-    const contractPath = join(dir, `${name}.contract.ts`)
-    const contractStat = await stat(contractPath).catch(() => null)
-    if (!contractStat?.isFile()) continue
+      const dir = resolve(packageRoot, layer, name)
+      const dirStat = await stat(dir).catch(() => null)
+      if (!dirStat?.isDirectory()) continue
 
-    const module = (await import(pathToFileURL(contractPath).href)) as {
-      contract?: ComponentContract
-    }
-    if (!module.contract) {
-      throw new Error(`${name}.contract.ts does not export "contract"`)
+      /*
+      A component with no contract is refused, not skipped. Skipped, it is
+      absent from the manifest — and every other gate reads the manifest or the
+      contract, so nothing would notice that the CMS cannot offer it.
+      */
+      const contractPath = join(dir, `${name}.contract.ts`)
+      const contractStat = await stat(contractPath).catch(() => null)
+      if (!contractStat?.isFile()) {
+        throw new Error(
+          `${layer}/${name} has no ${name}.contract.ts, so the CMS cannot offer it. ` +
+            `Write one beside the component. If the directory is not a component, ` +
+            `prefix it with an underscore.`,
+        )
+      }
+
+      const module = (await import(pathToFileURL(contractPath).href)) as {
+        contract?: ComponentContract
+      }
+      if (!module.contract) {
+        throw new Error(`${name}.contract.ts does not export "contract"`)
+      }
+      if (components[name]) {
+        throw new Error(`Duplicate component contract for "${name}"`)
+      }
+      components[name] = module.contract
     }
-    components[name] = module.contract
   }
 
   return components
@@ -56,12 +91,7 @@ async function main() {
 
   const manifest = {
     contractVersion: CONTRACT_VERSION,
-    designSystem: {
-      name: '@forumone/throughline-reference-ds',
-      version: await readPackageVersion(),
-      description:
-        'A brand-neutral reference design system demonstrating contract compliance for Throughline.',
-    },
+    designSystem: await readPackage(),
     tokens: getTokenList(),
     components,
     build: {

package/dist/templates/with-reference-ds/design-system/scripts/validate.ts

@@ -32,6 +32,24 @@ async function collectStoryIds(): Promise<Set<string> | undefined> {
   return ids
 }
 
+/*
+Lint rules this design system treats as failures, though the shared linter
+reports them as warnings.
+
+`design-contract` sets both to `warning` because it serves every project, and a
+project migrating an existing design system onto the contract should not be
+blocked by prose. A design system written against the contract from the start is
+never mid-migration, so it starts strict. Relax a rule here, deliberately, if
+yours is.
+
+Both are promoted because of who reads them. `intent` and `antiExamples` are the
+two fields the composing agent reasons about hardest: `intent` is how it chooses
+between components that could both fit, and `antiExamples` is how it rules one
+out. A component with neither still renders, and still gets composed into the
+wrong place, silently.
+*/
+const REQUIRED_RULES = new Set(['antiExamples.empty', 'intent.brevity'])
+
 async function main() {
   const raw = await readJson<unknown>(manifestPath)
   const loaded = loadManifest(raw)
@@ -39,7 +57,14 @@ async function main() {
   const availableStoryIds = await collectStoryIds()
   const lintOptions = availableStoryIds ? { availableStoryIds } : {}
 
-  const issues = lintManifest(loaded.raw, lintOptions)
+  /*
+  Severity is rewritten, not just re-bucketed: `formatLintIssues` groups by the
+  field itself, so a promoted rule left as a warning would print under
+  "Warnings" immediately before the command exits 1.
+  */
+  const issues = lintManifest(loaded.raw, lintOptions).map((issue) =>
+    REQUIRED_RULES.has(issue.rule) ? { ...issue, severity: 'error' as const } : issue,
+  )
   const errors = issues.filter((i) => i.severity === 'error')
   const warnings = issues.filter((i) => i.severity === 'warning')
 

package/dist/versions.json

@@ -9,6 +9,6 @@
   "@forumone/throughline-integrations": "0.8.5",
   "@forumone/throughline-plugin-contract": "0.4.1",
   "@forumone/throughline-publishing": "0.10.0",
-  "@forumone/throughline-reference-ds": "0.3.5",
+  "@forumone/throughline-reference-ds": "0.3.6",
   "@forumone/throughline-workflows": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumone/create-throughline",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffolder for new Throughline projects (Payload CMS + MCP servers + Inngest workflows).",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "^0.8.0",
+    "@clack/prompts": "^0.11.0",
     "picocolors": "^1.1.0"
   },
   "devDependencies": {