@forumone/create-throughline 0.3.0 → 0.4.0

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/utils/versions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The version of every Throughline package the scaffold depends on, keyed for
+ * the template renderer: `@forumone/throughline-design-contract` becomes
+ * `version_design_contract`, rendered as `"^{{version_design_contract}}"`.
+ *
+ * The ranges used to be typed into the templates by hand, and nothing moved
+ * them: they sat at `^0.2.0` — which for a 0.x version admits patches only —
+ * while the packages reached 0.9 and 0.10. A scaffolded site installed the
+ * earliest releases, against a `payload.config.ts` written for today's APIs.
+ *
+ * So the versions are read, never typed. A published scaffolder reads
+ * `versions.json`, which `copy-templates` writes beside `templates/` at build
+ * time; `publish-packages` builds after `changeset version`, so that file names
+ * exactly the set being published. Running from source (tests, `tsx`), there is
+ * no such file and the workspace's own `package.json` files are the answer.
+ */
+export declare function loadPackageVersions(templatesDir: string): Promise<Record<string, string>>;
+/** `{ '@forumone/throughline-core': '0.9.1', … }` from a `packages/` directory. */
+export declare function readWorkspaceVersions(packagesDir: string): Promise<Record<string, string>>;
+//# sourceMappingURL=versions.d.ts.map

package/dist/utils/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/utils/versions.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAO/F;AAED,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA0BhG"}

package/dist/utils/versions.js

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+const SCOPE_PREFIX = '@forumone/throughline-';
+/**
+ * The version of every Throughline package the scaffold depends on, keyed for
+ * the template renderer: `@forumone/throughline-design-contract` becomes
+ * `version_design_contract`, rendered as `"^{{version_design_contract}}"`.
+ *
+ * The ranges used to be typed into the templates by hand, and nothing moved
+ * them: they sat at `^0.2.0` — which for a 0.x version admits patches only —
+ * while the packages reached 0.9 and 0.10. A scaffolded site installed the
+ * earliest releases, against a `payload.config.ts` written for today's APIs.
+ *
+ * So the versions are read, never typed. A published scaffolder reads
+ * `versions.json`, which `copy-templates` writes beside `templates/` at build
+ * time; `publish-packages` builds after `changeset version`, so that file names
+ * exactly the set being published. Running from source (tests, `tsx`), there is
+ * no such file and the workspace's own `package.json` files are the answer.
+ */
+export async function loadPackageVersions(templatesDir) {
+    const baked = resolve(templatesDir, '..', 'versions.json');
+    if (existsSync(baked)) {
+        return templateKeys(JSON.parse(await readFile(baked, 'utf-8')));
+    }
+    // src/templates or dist/templates -> the package -> packages/
+    return templateKeys(await readWorkspaceVersions(resolve(templatesDir, '..', '..', '..')));
+}
+/** `{ '@forumone/throughline-core': '0.9.1', … }` from a `packages/` directory. */
+export async function readWorkspaceVersions(packagesDir) {
+    const versions = {};
+    const entries = await readdir(packagesDir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = join(packagesDir, entry.name, 'package.json');
+        if (!existsSync(manifest))
+            continue;
+        const { name, version, private: isPrivate, } = JSON.parse(await readFile(manifest, 'utf-8'));
+        if (!name?.startsWith(SCOPE_PREFIX) || !version || isPrivate)
+            continue;
+        versions[name] = version;
+    }
+    if (Object.keys(versions).length === 0) {
+        throw new Error(`create-throughline: no package versions found. Expected versions.json beside the ` +
+            `templates, or @forumone/throughline-* packages in ${packagesDir}.`);
+    }
+    return versions;
+}
+function templateKeys(versions) {
+    const keys = {};
+    for (const [name, version] of Object.entries(versions)) {
+        if (!name.startsWith(SCOPE_PREFIX))
+            continue;
+        keys[`version_${name.slice(SCOPE_PREFIX.length).replace(/-/g, '_')}`] = version;
+    }
+    return keys;
+}
+//# sourceMappingURL=versions.js.map

package/dist/utils/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/utils/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEzC,MAAM,YAAY,GAAG,wBAAwB,CAAA;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,YAAoB;IAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,EAAE,IAAI,EAAE,eAAe,CAAC,CAAA;IAC1D,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAA2B,CAAC,CAAA;IAC3F,CAAC;IACD,8DAA8D;IAC9D,OAAO,YAAY,CAAC,MAAM,qBAAqB,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,WAAmB;IAC7D,MAAM,QAAQ,GAA2B,EAAE,CAAA;IAC3C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IACnF,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAQ;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,CAAA;QAC9D,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,SAAQ;QACnC,MAAM,EACJ,IAAI,EACJ,OAAO,EACP,OAAO,EAAE,SAAS,GACnB,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAI/C,CAAA;QACD,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,IAAI,SAAS;YAAE,SAAQ;QACtE,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;IAC1B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,qDAAqD,WAAW,GAAG,CACtE,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,SAAS,YAAY,CAAC,QAAgC;IACpD,MAAM,IAAI,GAA2B,EAAE,CAAA;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;YAAE,SAAQ;QAC5C,IAAI,CAAC,WAAW,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAA;IACjF,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/versions.json

@@ -0,0 +1,14 @@
+{
+  "@forumone/throughline-approvals": "0.8.8",
+  "@forumone/throughline-audit": "0.5.4",
+  "@forumone/throughline-components": "0.5.7",
+  "@forumone/throughline-core": "0.9.1",
+  "@forumone/throughline-design-contract": "0.6.0",
+  "@forumone/throughline-email": "0.2.12",
+  "@forumone/throughline-forms": "0.6.4",
+  "@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.6",
+  "@forumone/throughline-workflows": "0.4.0"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumone/create-throughline",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Scaffolder for new Throughline projects (Payload CMS + MCP servers + Inngest workflows).",
   "type": "module",
   "bin": {
@@ -40,17 +40,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "^0.8.0",
+    "@clack/prompts": "^0.11.0",
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.17.0",
-    "eslint": "^9.15.0",
+    "eslint": "^10.11.0",
     "tsx": "^4.21.0",
     "typescript": "^5.6.0",
-    "vitest": "^2.1.0",
-    "@forumone/throughline-eslint-config": "0.0.0",
-    "@forumone/throughline-tsconfig": "0.0.0"
+    "vitest": "^4.1.10",
+    "@forumone/throughline-tsconfig": "0.0.0",
+    "@forumone/throughline-eslint-config": "0.0.0"
   },
   "engines": {
     "node": ">=20.9.0"