@clubedge/create-clubedge-app 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.5.0
+
+- Default to Starter `v0.5.0`, which adds optional modules, Better Auth, and template schema 3.
+- Add `--auth`, `--storage`, and `--cache`, and offer to customize them interactively. Options whose requirements are not met (Supabase Storage without Supabase Auth) are refused with an explanation.
+- Read template schema 3 modules: unselected options' packages, files, provider dependencies, environment variables, and lockfile entries are removed, and selected variants replace the default files.
+- Process `clubedge:if` blocks in the Starter's documentation, environment examples, and sources, so a project only describes what it contains.
+- Support Mermaid (`%%`) markers and single-line `clubedge:only` conditions, and leave no blank lines at file edges after removing blocks.
+- Record the selected modules in the generated `package.json` and `README.md`. The smoke test skips the sign-up check for projects without authentication.
+
+## 0.4.0
+
+- Default to Starter `v0.4.0`, which adds the TanStack Start app and template schema 2.
+- Add `--framework next|tanstack-start`, and ask which framework to use when the Starter offers several. Next.js stays the default.
+- Read template schema 2, which describes each framework's app, environment example, and Dockerfile. The selected app is moved to `apps/web`, the others are left out, and `pnpm-lock.yaml` is kept in step so frozen installs work.
+- Record the chosen framework in the generated `package.json` and `README.md`.
+- Test generated projects for both frameworks in CI and in the release smoke test.
+
 ## 0.3.0
 
 - Default to Starter `v0.3.0`, which adds the `clubedge.template.json` template manifest.

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 
-Create a Next.js application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
+Create a Next.js or TanStack Start application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
 
 The CLI downloads a tested Starter release, names the generated project, creates `apps/web/.env.local` from the example, initializes Git, and installs dependencies. The Starter remains the source of truth for the generated architecture.
 
@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.3.0
+create-clubedge-app v0.5.0
         |
         v
-Clubedge Starter v0.3.0
-commit 60f1691920c91a5cf83e480a3ce98c3ddefdef55
+Clubedge Starter v0.5.0
+commit d9375c2c3b520323ff0255ef8ec65da19251c3c1
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.3.0` | `clubedge-starter@v0.3.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.5.0` | `clubedge-starter@v0.5.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.3.0` tag is expected to resolve to commit
-`60f1691920c91a5cf83e480a3ce98c3ddefdef55`. The CLI verifies this before
+The `v0.5.0` tag is expected to resolve to commit
+`d9375c2c3b520323ff0255ef8ec65da19251c3c1`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.3.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.5.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
@@ -68,11 +68,47 @@ When no destination is provided, the CLI asks where to create the project:
 pnpm dlx @clubedge/create-clubedge-app
 ```
 
+### Choosing a framework
+
+The Starter ships the same application for two React frameworks. Next.js is the default; pick TanStack Start with `--framework`, or choose interactively when the Starter offers more than one:
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
+```
+
+| `--framework`    | App                         | Production output             |
+| ---------------- | --------------------------- | ----------------------------- |
+| `next`           | Next.js App Router          | Next.js standalone build      |
+| `tanstack-start` | TanStack Start with Vite    | Nitro `.output` server bundle |
+
+Either way, the app lives in `apps/web` and uses the same shared packages, so the project layout, root scripts, and Docker commands are identical.
+
+### Choosing services
+
+Authentication, file storage, and caching are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries.
+
+| Flag        | Options                                    | Default    |
+| ----------- | ------------------------------------------ | ---------- |
+| `--auth`    | `supabase`, `better-auth`, `none`          | `supabase` |
+| `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
+| `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
+
+```sh
+# Only the monorepo, UI, database, and tooling
+pnpm dlx @clubedge/create-clubedge-app my-app --auth none --storage none --cache memory
+```
+
+Interactive runs ask whether to customize these after the framework question. The options come from the Starter's manifest, so `--help` lists the ones the bundled Starter offers.
+
 ## Options
 
 ```text
 Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
+--framework <id>        App framework: next (default) or tanstack-start
+--auth <id>             Authentication: supabase (default), better-auth, or none
+--storage <id>          File storage: s3 (default), supabase, or none
+--cache <id>            Cache and rate limits: redis (default) or memory
 --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
 --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
 --dry-run               Show what would be created without writing anything
@@ -85,20 +121,20 @@ Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
 The target directory must be empty or not exist. The CLI never deletes or overwrites existing files, and if scaffolding fails it removes whatever it wrote, so a failed run leaves nothing behind.
 
-Every generated project records its CLI version, Starter repository, Starter ref, and Starter commit in `package.json` and `README.md`.
+Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
 ```sh
 # Preview the files and edits without writing anything
 pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
 
 # Non-interactive, for scripts and CI
-pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git
+pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstack-start
 
 # Try an unreleased Starter change
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.3.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.5.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -109,7 +145,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter
 
 Each CLI release bundles one Starter release. When the release is built, `scripts/bundle-template.mjs` clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (`template/` and `template.lock.json`). Running the CLI then needs no GitHub access for the default Starter.
 
-The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
+The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to `apps/web` (renaming its package to `@clubedge/web`), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from `pnpm-lock.yaml` so `pnpm install --frozen-lockfile` keeps working. Schema 3 adds `modules`: for each option, the workspace packages it uses, the files it owns, the variant files that replace defaults, and the options it requires. Files listed under `conditional` contain `clubedge:if <condition>` / `clubedge:end` blocks (in `#`, `//`, `<!-- -->`, or JSX comments) that the CLI keeps or drops for the selection, always removing the markers; `clubedge:if starter-repository` marks sections for Starter maintainers only. The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
 
 The CLI first builds a plan (the files to copy and the edits to make), which `--dry-run` prints, and then applies it. The source is organized the same way:
 
@@ -143,7 +179,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.3.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.5.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/dist/cli/args.js

@@ -1,4 +1,6 @@
 import { parseArgs } from "node:util";
+/** Module flags the CLI accepts. Which options exist is up to the Starter's manifest. */
+export const MODULE_FLAGS = ["auth", "storage", "cache"];
 export class UsageError extends Error {
     name = "UsageError";
 }
@@ -11,6 +13,10 @@ export function parseCliArgs(argv) {
             allowNegative: true,
             strict: true,
             options: {
+                framework: { type: "string" },
+                auth: { type: "string" },
+                storage: { type: "string" },
+                cache: { type: "string" },
                 ref: { type: "string" },
                 "template-dir": { type: "string" },
                 install: { type: "boolean", default: true },
@@ -29,6 +35,18 @@ export function parseCliArgs(argv) {
     const { values, positionals } = parsed;
     if (positionals.length > 1)
         throw new UsageError("Only one project directory can be provided.");
+    if (values.framework !== undefined && !values.framework.trim()) {
+        throw new UsageError("--framework requires a framework id, such as next or tanstack-start.");
+    }
+    const modules = {};
+    for (const module of MODULE_FLAGS) {
+        const value = values[module];
+        if (value === undefined)
+            continue;
+        if (!value.trim())
+            throw new UsageError(`--${module} requires an option, such as none.`);
+        modules[module] = value.trim();
+    }
     if (values.ref !== undefined && !values.ref.trim()) {
         throw new UsageError("--ref requires a tag, branch, or commit.");
     }
@@ -37,6 +55,8 @@ export function parseCliArgs(argv) {
     }
     return {
         projectDirectory: positionals[0],
+        framework: values.framework?.trim(),
+        modules,
         ref: values.ref,
         templateDir: values["template-dir"],
         install: values.install,

package/dist/cli/ui.js

@@ -63,6 +63,10 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
 Options:
+  --framework <id>        App framework: next (default) or tanstack-start
+  --auth <id>             Authentication: supabase (default), better-auth, or none
+  --storage <id>          File storage: s3 (default), supabase, or none
+  --cache <id>            Cache and rate limits: redis (default) or memory
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
   --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
   --dry-run               Show what would be created without writing anything
@@ -74,6 +78,8 @@ Options:
 
 Examples:
   pnpm dlx @clubedge/create-clubedge-app my-app
+  pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
+  pnpm dlx @clubedge/create-clubedge-app my-app --auth none --storage none --cache memory
   pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
   pnpm dlx @clubedge/create-clubedge-app my-app --ref main
   pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter

package/dist/core/customize.js

@@ -9,6 +9,8 @@ export function customizeRootManifest(source, { packageName }, provenance, docke
         starterRepository: provenance.starterRepository,
         starterRef: provenance.starterRef,
         ...(provenance.starterCommit ? { starterCommit: provenance.starterCommit } : {}),
+        ...(provenance.framework ? { framework: provenance.framework } : {}),
+        ...(provenance.modules ? { modules: provenance.modules } : {}),
     };
     for (const script of ["docker:build", "docker:start"]) {
         if (typeof manifest.scripts?.[script] === "string") {
@@ -21,9 +23,13 @@ export function customizeReadme(source, { displayName }, provenance) {
     const commitLine = provenance.starterCommit
         ? `\n- Starter commit: \`${provenance.starterCommit}\``
         : "";
+    const frameworkLine = provenance.frameworkName ? `\n- Framework: ${provenance.frameworkName}` : "";
+    const modulesLine = provenance.moduleSummary?.length
+        ? `\n- Modules: ${provenance.moduleSummary.join(", ")}`
+        : "";
     const origin = `## Generated from\n\n` +
         `- Starter repository: \`${provenance.starterRepository}\`\n` +
-        `- Starter ref: \`${provenance.starterRef}\`${commitLine}\n` +
+        `- Starter ref: \`${provenance.starterRef}\`${commitLine}${frameworkLine}${modulesLine}\n` +
         `- CLI version: \`${provenance.cliVersion}\``;
     // Only the first heading is the project title; leave every other line as written.
     return source.replace(/^# .+$/m, `# ${displayName}\n\n${origin}`);
@@ -54,3 +60,163 @@ export function customizeLegacySource(source, { displayName }) {
         .replaceAll(">Clubedge<", `>${displayName}<`)
         .replaceAll("Starter workspace", "Application workspace");
 }
+/** Gives the selected framework's app the package name generated projects use. */
+export function customizeAppManifest(source, appPackage) {
+    const manifest = JSON.parse(source);
+    manifest.name = appPackage;
+    return json(manifest);
+}
+/**
+ * Keeps pnpm-lock.yaml in step with the selected framework so `pnpm install --frozen-lockfile`
+ * works. Importers are keyed by workspace path at two-space indentation; package entries that
+ * are no longer used are harmless, and pnpm prunes them on the next lockfile update.
+ */
+export function customizeLockfile(source, { remove, rename, removeDependencies = [] }) {
+    const output = [];
+    let inImporters = false;
+    let skippingImporter = false;
+    let skippingDependency = false;
+    // A dependency group header ("    dependencies:") is held until it gets an entry, so a group
+    // whose entries were all removed disappears instead of becoming an empty YAML value.
+    let pendingGroup = null;
+    for (const line of source.split("\n")) {
+        if (/^\S/.test(line)) {
+            inImporters = line === "importers:";
+            skippingImporter = skippingDependency = false;
+            pendingGroup = null;
+            output.push(line);
+            continue;
+        }
+        if (!inImporters) {
+            output.push(line);
+            continue;
+        }
+        // An importer key, with its value on the next lines or inline ("packages/core: {}").
+        const importer = /^ {2}([^\s:][^:]*):(?: |$)/.exec(line)?.[1];
+        if (importer !== undefined) {
+            skippingImporter = remove.includes(importer);
+            skippingDependency = false;
+            pendingGroup = null;
+            if (!skippingImporter)
+                output.push(importer === rename?.from ? `  ${rename.to}:` : line);
+            continue;
+        }
+        if (skippingImporter)
+            continue;
+        if (/^ {4}\S/.test(line)) {
+            skippingDependency = false;
+            pendingGroup = line;
+            continue;
+        }
+        const dependency = /^ {6}(['"]?)([^'":]+)\1:\s*$/.exec(line)?.[2];
+        if (dependency !== undefined) {
+            skippingDependency = removeDependencies.includes(dependency);
+            if (skippingDependency)
+                continue;
+            if (pendingGroup !== null) {
+                output.push(pendingGroup);
+                pendingGroup = null;
+            }
+            output.push(line);
+            continue;
+        }
+        if (skippingDependency && /^ {8}/.test(line))
+            continue;
+        if (pendingGroup !== null && line.trim() !== "") {
+            output.push(pendingGroup);
+            pendingGroup = null;
+        }
+        skippingDependency = false;
+        output.push(line);
+    }
+    return output.join("\n");
+}
+export class ConditionalError extends Error {
+    name = "ConditionalError";
+}
+// A marker line in any comment style the Starter uses: //, #, %% (Mermaid), <!-- -->, /* */,
+// or {/* */}.
+const MARKER = /^\s*(?:\/\/|#|%%|<!--|\{?\/\*)\s*clubedge:(if|end)\b\s*(.*?)\s*(?:-->|\*\/\}?)?\s*$/;
+// A single line kept only when its condition holds: "- Item <!-- clubedge:only auth=supabase -->".
+const LINE_MARKER = /\s*(?:\/\/|#|<!--|\{?\/\*)\s*clubedge:only\s+(.+?)\s*(?:-->|\*\/\}?)?\s*$/;
+function evaluateCondition(expression, selection, location) {
+    // Maintainer-only sections of the Starter repository never reach a generated project.
+    if (expression.trim() === "starter-repository")
+        return false;
+    return expression.split("&&").every((part) => {
+        const match = /^\s*([a-z][a-z0-9-]*)\s*(!?=)\s*([a-z0-9|-]+)\s*$/.exec(part);
+        if (!match)
+            throw new ConditionalError(`${location}: cannot read the condition "${expression}".`);
+        const [, key, operator, values] = match;
+        const selected = selection[key];
+        if (selected === undefined)
+            throw new ConditionalError(`${location}: unknown key "${key}".`);
+        const matches = values.split("|").includes(selected);
+        return operator === "=" ? matches : !matches;
+    });
+}
+/**
+ * Keeps or drops `clubedge:if <condition>` ... `clubedge:end` blocks for the selection and
+ * always removes the marker lines. Conditions look like `auth=none`, `storage!=none`,
+ * `auth=supabase|better-auth`, or several joined with `&&`. Blocks do not nest.
+ */
+export function applyConditionals(source, selection, path = "file") {
+    const output = [];
+    let open = null;
+    let removed = false;
+    source.split("\n").forEach((line, index) => {
+        const marker = MARKER.exec(line);
+        const location = `${path}:${index + 1}`;
+        if (marker?.[1] === "if") {
+            if (open)
+                throw new ConditionalError(`${location}: clubedge:if blocks cannot nest.`);
+            open = { keep: evaluateCondition(marker[2] ?? "", selection, location), line: index + 1 };
+            removed = removed || !open.keep;
+            return;
+        }
+        if (marker?.[1] === "end") {
+            if (!open)
+                throw new ConditionalError(`${location}: clubedge:end without clubedge:if.`);
+            open = null;
+            return;
+        }
+        if (open && !open.keep)
+            return;
+        const lineMarker = LINE_MARKER.exec(line);
+        if (lineMarker && line.trim() !== lineMarker[0].trim()) {
+            if (!evaluateCondition(lineMarker[1], selection, location)) {
+                removed = true;
+                return;
+            }
+            output.push(line.slice(0, lineMarker.index));
+            return;
+        }
+        output.push(line);
+    });
+    if (open)
+        throw new ConditionalError(`${path}:${open.line}: clubedge:if is never closed.`);
+    const text = output.join("\n");
+    if (!removed)
+        return text;
+    // A removed block can leave two blank lines in a row, or blank lines at the start or end of
+    // the file; formatted sources never have them.
+    const collapsed = text.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+    return source.endsWith("\n") ? collapsed.replace(/\n+$/, "\n") : collapsed;
+}
+/** Removes dependencies on workspace packages that were left out of the project. */
+export function removePackageDependencies(source, names) {
+    const manifest = JSON.parse(source);
+    let changed = false;
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const dependencies = manifest[field];
+        if (!dependencies || typeof dependencies !== "object")
+            continue;
+        for (const name of names) {
+            if (name in dependencies) {
+                delete dependencies[name];
+                changed = true;
+            }
+        }
+    }
+    return changed ? json(manifest) : source;
+}

package/dist/core/manifest.js

@@ -1,7 +1,14 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 export const MANIFEST_FILE = "clubedge.template.json";
-export const SUPPORTED_SCHEMA_VERSION = 1;
+export const SUPPORTED_SCHEMA_VERSION = 3;
+/** Schema 1 Starters ship a single Next.js app at the generated location. */
+function singleNextFramework(app, envExample) {
+    return {
+        defaultFramework: "next",
+        frameworks: { next: { name: "Next.js", app, envExample, dockerfile: "Dockerfile" } },
+    };
+}
 /** Starter releases before v0.3.0 have no manifest; this describes their layout. */
 export const legacyManifest = {
     schemaVersion: 1,
@@ -11,6 +18,9 @@ export const legacyManifest = {
     siteConfig: "apps/web/src/config/site.json",
     env: { example: ".env.example", target: "apps/web/.env.local" },
     dockerImage: "clubedge-starter",
+    ...singleNextFramework("apps/web", ".env.example"),
+    modules: {},
+    conditional: [],
     exclude: [],
 };
 export class ManifestError extends Error {
@@ -43,17 +53,134 @@ export function parseTemplateManifest(source) {
     if (data.exclude !== undefined && !isStringArray(data.exclude)) {
         throw new ManifestError(`${MANIFEST_FILE}: exclude must be an array of paths.`);
     }
+    const app = requireString(data, "app");
+    const envExample = requireString(env, "example", "env.");
     return {
         schemaVersion,
         name: requireString(data, "name"),
         packageManager: "pnpm",
-        app: requireString(data, "app"),
+        app,
+        ...(schemaVersion >= 2 ? { appPackage: requireString(data, "appPackage") } : {}),
         siteConfig: requireString(data, "siteConfig"),
-        env: { example: requireString(env, "example", "env."), target: requireString(env, "target", "env.") },
+        env: { example: envExample, target: requireString(env, "target", "env.") },
         dockerImage: requireString(data, "dockerImage"),
+        ...(schemaVersion >= 2 ? parseFrameworks(data) : singleNextFramework(app, envExample)),
+        modules: schemaVersion >= 3 ? parseModules(data.modules) : {},
+        conditional: schemaVersion >= 3 ? optionalStringArray(data, "conditional") : [],
         exclude: data.exclude ?? [],
     };
 }
+const ID = /^[a-z][a-z0-9-]*$/;
+function parseModules(value) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        throw new ManifestError(`${MANIFEST_FILE}: modules must be an object.`);
+    const modules = {};
+    for (const [id, entry] of Object.entries(value)) {
+        if (!ID.test(id) || id === "framework") {
+            throw new ManifestError(`${MANIFEST_FILE}: "${id}" is not a valid module id.`);
+        }
+        if (!isRecord(entry))
+            throw new ManifestError(`${MANIFEST_FILE}: modules.${id} must be an object.`);
+        const prefix = `modules.${id}.`;
+        const optionsValue = entry.options;
+        if (!isRecord(optionsValue) || Object.keys(optionsValue).length === 0) {
+            throw new ManifestError(`${MANIFEST_FILE}: ${prefix}options must describe at least one option.`);
+        }
+        const options = {};
+        for (const [optionId, option] of Object.entries(optionsValue)) {
+            const optionPrefix = `${prefix}options.${optionId}.`;
+            if (!ID.test(optionId)) {
+                throw new ManifestError(`${MANIFEST_FILE}: "${optionId}" is not a valid option id in ${prefix.slice(0, -1)}.`);
+            }
+            if (!isRecord(option))
+                throw new ManifestError(`${MANIFEST_FILE}: ${optionPrefix.slice(0, -1)} must be an object.`);
+            options[optionId] = {
+                name: requireString(option, "name", optionPrefix),
+                packages: optionalStringRecord(option, "packages", optionPrefix),
+                files: optionalStringArray(option, "files", optionPrefix),
+                replace: optionalStringRecord(option, "replace", optionPrefix),
+                requires: parseRequires(option.requires, optionPrefix),
+            };
+        }
+        const defaultOption = requireString(entry, "default", prefix);
+        if (!options[defaultOption]) {
+            throw new ManifestError(`${MANIFEST_FILE}: ${prefix}default "${defaultOption}" is not in its options.`);
+        }
+        modules[id] = { name: requireString(entry, "name", prefix), default: defaultOption, options };
+    }
+    // Requirements must name real modules and options, or a selection could never be valid.
+    for (const [id, module] of Object.entries(modules)) {
+        for (const [optionId, option] of Object.entries(module.options)) {
+            for (const [requiredModule, allowed] of Object.entries(option.requires)) {
+                const unknown = allowed.find((value) => !modules[requiredModule]?.options[value]);
+                if (unknown !== undefined) {
+                    throw new ManifestError(`${MANIFEST_FILE}: modules.${id}.options.${optionId}.requires names unknown option ${requiredModule}=${unknown}.`);
+                }
+            }
+        }
+    }
+    return modules;
+}
+function parseRequires(value, prefix) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        throw new ManifestError(`${MANIFEST_FILE}: ${prefix}requires must be an object.`);
+    const requires = {};
+    for (const [module, allowed] of Object.entries(value)) {
+        const list = typeof allowed === "string" ? [allowed] : allowed;
+        if (!isStringArray(list) || list.length === 0) {
+            throw new ManifestError(`${MANIFEST_FILE}: ${prefix}requires.${module} must name one or more options.`);
+        }
+        requires[module] = list;
+    }
+    return requires;
+}
+function optionalStringArray(record, key, prefix = "") {
+    const value = record[key];
+    if (value === undefined)
+        return [];
+    if (!isStringArray(value))
+        throw new ManifestError(`${MANIFEST_FILE}: ${prefix}${key} must be an array of paths.`);
+    return value;
+}
+function optionalStringRecord(record, key, prefix = "") {
+    const value = record[key];
+    if (value === undefined)
+        return {};
+    if (!isRecord(value) || !Object.values(value).every((item) => typeof item === "string" && item)) {
+        throw new ManifestError(`${MANIFEST_FILE}: ${prefix}${key} must map names to paths.`);
+    }
+    return value;
+}
+function parseFrameworks(data) {
+    const { frameworks } = data;
+    if (!isRecord(frameworks) || Object.keys(frameworks).length === 0) {
+        throw new ManifestError(`${MANIFEST_FILE}: frameworks must describe at least one framework.`);
+    }
+    const parsed = {};
+    for (const [id, entry] of Object.entries(frameworks)) {
+        if (!ID.test(id)) {
+            throw new ManifestError(`${MANIFEST_FILE}: "${id}" is not a valid framework id.`);
+        }
+        if (!isRecord(entry))
+            throw new ManifestError(`${MANIFEST_FILE}: frameworks.${id} must be an object.`);
+        const prefix = `frameworks.${id}.`;
+        parsed[id] = {
+            name: requireString(entry, "name", prefix),
+            app: requireString(entry, "app", prefix),
+            envExample: requireString(entry, "envExample", prefix),
+            dockerfile: requireString(entry, "dockerfile", prefix),
+        };
+    }
+    const defaultFramework = requireString(data, "defaultFramework");
+    if (!parsed[defaultFramework]) {
+        throw new ManifestError(`${MANIFEST_FILE}: defaultFramework "${defaultFramework}" is not in frameworks.`);
+    }
+    return { defaultFramework, frameworks: parsed };
+}
 export async function readTemplateManifest(templateRoot) {
     let source;
     try {