@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/create/generatorToVerbSpec.ts

@@ -0,0 +1,111 @@
+/**
+ * The generator→grammar adapter: map a summon {@link PromptDefinition} onto the
+ * one grammar's {@link ParamSpec}, mirroring the v1 cli-core
+ * `convertGenerator.promptToParameter`.
+ *
+ *   text        → { kind: "string" }   (+ positional; `complete: files` for paths)
+ *   confirm     → { kind: "boolean" }
+ *   select      → { kind: "enum", values: choices.map(value) }
+ *   multiselect → { kind: "string[]", complete: values }
+ *
+ * `name→name`, `message→doc`, `default→default`, `positional→positional`;
+ * `required = default === undefined && !when`. A prompt's `validate` and a
+ * `select`'s choice set have NO ParamSpec slot: they are enforced by summon's
+ * `validateAnswers` inside `execute`, so a flag/MCP-arg run rejects the same bad
+ * input a wizard would. A `when` condition is honoured by `collectAnswers` at
+ * prompt time. `generate` is reached through the verb's `run` → `execute`.
+ *
+ * This adapter runs over STATIC prompt mirrors (see `create.verb.ts`), never the
+ * live generators — importing a generator runs a top-level `await loadTemplate`,
+ * which must stay behind `create`'s lazy dispatch (R9). A parity test loads the
+ * real generators and asserts the mirrors match.
+ */
+
+import type { PromptDefinition } from "@canonical/summon-core";
+import type { ParamSpec } from "../../kernel/spec/types.js";
+
+/** A path-like text prompt gets file completion. */
+const looksLikePath = (name: string): boolean => /(path|dir)$/i.test(name);
+
+/**
+ * Derive a declarative param `doc` from a generator prompt's `message`.
+ *
+ * A prompt `message` is a wizard QUESTION (`Include styles?`, `Package name:`),
+ * but a {@link ParamSpec.doc} is help text shown in CLI `--help` and the MCP
+ * arg schema, where every other param reads as a declarative statement. We
+ * DERIVE the doc rather than editing the mirrors' `message` — the generator
+ * parity test couples `message` to the live generators, so the question must
+ * stay verbatim for the interactive wizard while the flag/MCP doc reads well.
+ * Strip the trailing `?`/`:` and end with a period.
+ */
+export function declarativeDoc(message: string): string {
+  const trimmed = message
+    .trim()
+    .replace(/\s*[?:]+$/, "")
+    .trim();
+  if (trimmed === "") return trimmed;
+  return /[.!]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+
+/**
+ * Convert one generator prompt to a grammar param.
+ *
+ * @param prompt - The generator's prompt definition.
+ * @returns The equivalent {@link ParamSpec}.
+ */
+export function promptToParam(prompt: PromptDefinition): ParamSpec {
+  const required = prompt.default === undefined && !prompt.when;
+  const positional = prompt.positional === true;
+
+  switch (prompt.type) {
+    case "confirm":
+      return {
+        kind: "boolean",
+        name: prompt.name,
+        doc: declarativeDoc(prompt.message),
+        required,
+        positional,
+        ...(prompt.default !== undefined
+          ? { default: prompt.default as boolean }
+          : {}),
+      };
+    case "select":
+      return {
+        kind: "enum",
+        name: prompt.name,
+        doc: declarativeDoc(prompt.message),
+        values: (prompt.choices ?? []).map((choice) => choice.value),
+        required,
+        positional,
+        ...(prompt.default !== undefined
+          ? { default: String(prompt.default) }
+          : {}),
+      };
+    case "multiselect":
+      return {
+        kind: "string[]",
+        name: prompt.name,
+        doc: declarativeDoc(prompt.message),
+        required,
+        positional,
+        complete: { kind: "values" },
+      };
+    default:
+      return {
+        kind: "string",
+        name: prompt.name,
+        doc: declarativeDoc(prompt.message),
+        required,
+        positional,
+        ...(prompt.default !== undefined ? { default: prompt.default } : {}),
+        ...(looksLikePath(prompt.name) ? { complete: { kind: "files" } } : {}),
+      };
+  }
+}
+
+/** Map a generator's whole prompt list to grammar params, in order. */
+export function generatorToParams(
+  prompts: readonly PromptDefinition[],
+): ParamSpec[] {
+  return prompts.map(promptToParam);
+}

package/src/capabilities/create/index.ts

@@ -0,0 +1,25 @@
+/**
+ * The `create` capability barrel — component / package / application scaffolds.
+ *
+ * Importing this pulls only the verb specs (static params + formatters); every
+ * generator load and the summon-core runtime stay behind each verb's lazy
+ * `run` dispatch, so the command tree builds without touching summon-core.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import {
+  createApplicationVerb,
+  createComponentVerb,
+  createPackageVerb,
+} from "./create.verb.js";
+
+/** The `create` capability module. */
+export const createModule: CapabilityModule = {
+  name: "create",
+  verbs: [
+    asVerb(createComponentVerb),
+    asVerb(createPackageVerb),
+    asVerb(createApplicationVerb),
+  ],
+};

package/src/capabilities/create/pathJail.ts

@@ -0,0 +1,73 @@
+/**
+ * SEC-2 path jail: an independent guard that a `create` output path stays inside
+ * the workspace, run BEFORE any effect. It rejects an absolute path, a `..`
+ * escape, and — via `realpath` on the nearest existing ancestor — a symlink that
+ * points out of the tree. This is defence in depth: the generators' own
+ * `validateComponentPath` already rejects absolute/`..`, but the jail is the
+ * kernel-level backstop that also catches symlink escapes and covers every
+ * create noun uniformly.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+
+/** Walk up from `p` to the nearest ancestor that exists on disk. */
+function nearestExisting(p: string): string {
+  let current = p;
+  while (!existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return current; // filesystem root
+    current = parent;
+  }
+  return current;
+}
+
+/** Whether `rel` (a `path.relative` result) points at or above its base. */
+const escapes = (rel: string): boolean =>
+  rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+
+/**
+ * Reject a create output path that would escape the workspace root (`cwd`).
+ *
+ * @param field - The param name being jailed (for the error message).
+ * @param value - The path value (skipped when absent — the generator's own safe
+ *   default is used instead).
+ * @param cwd - The workspace root the path must stay within.
+ * @throws PragmaError INVALID_INPUT when the path escapes the workspace.
+ * @note Impure — reads the filesystem (`existsSync`/`realpathSync`).
+ */
+export function assertInsideWorkspace(
+  field: string,
+  value: unknown,
+  cwd: string,
+): void {
+  if (typeof value !== "string" || value === "") return;
+
+  if (path.isAbsolute(value)) {
+    throw PragmaError.invalidInput(field, value, {
+      recovery: { message: "Use a path relative to the current directory." },
+    });
+  }
+
+  const root = path.resolve(cwd);
+  const resolved = path.resolve(root, value);
+  if (escapes(path.relative(root, resolved))) {
+    throw PragmaError.invalidInput(field, value, {
+      recovery: { message: "The path must stay inside the workspace." },
+    });
+  }
+
+  // Symlink escape: the nearest existing ancestor, resolved through symlinks,
+  // must still sit within the resolved workspace root.
+  const realRoot = realpathSync(root);
+  const realAncestor = realpathSync(nearestExisting(resolved));
+  if (
+    realAncestor !== realRoot &&
+    escapes(path.relative(realRoot, realAncestor))
+  ) {
+    throw PragmaError.invalidInput(field, value, {
+      recovery: { message: "The path resolves outside the workspace." },
+    });
+  }
+}

package/src/capabilities/create/pickGenerator.ts

@@ -0,0 +1,63 @@
+/**
+ * Select the summon generator for a `create` invocation.
+ *
+ * This module statically imports the summon generator packages' `generators`
+ * maps — and importing them runs a top-level `await loadTemplate` that reads
+ * every template file from disk. So this module MUST stay behind `create`'s
+ * lazy `import()` (R9): the fast paths (`buildProgram` / `__complete` / `--help`
+ * / reads) never load it, and `create --yes` never loads React either (the
+ * generators pull summon-core, whose Ink UI is dynamic-only).
+ */
+
+import { generators as applicationGenerators } from "@canonical/summon-application";
+import { generators as componentGenerators } from "@canonical/summon-component";
+import type { GeneratorDefinition } from "@canonical/summon-core";
+import { generators as packageGenerators } from "@canonical/summon-package";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import type { CreateKind } from "./types.js";
+
+/** The component frameworks that collapse to one `create component` verb. */
+export const FRAMEWORKS = ["react", "svelte", "lit"] as const;
+
+/**
+ * The generators' `generate` is invariant in its (specific) answer type, so the
+ * strongly-typed maps are erased to the base definition via `unknown`. This is
+ * runtime-safe: `execute` calls `generate(answers)` with the resolved answers,
+ * which carry the fields the specific generator reads.
+ */
+type GeneratorMap = Record<string, GeneratorDefinition | undefined>;
+const componentMap = componentGenerators as unknown as GeneratorMap;
+const packageMap = packageGenerators as unknown as GeneratorMap;
+const applicationMap = applicationGenerators as unknown as GeneratorMap;
+
+/**
+ * Pick the generator for a `create <kind>` run.
+ *
+ * @param kind - The create noun.
+ * @param params - The coerced params (used for `--framework` on `component`).
+ * @returns The selected generator definition.
+ * @throws PragmaError INVALID_INPUT for an unknown component framework.
+ */
+export function pickGenerator(
+  kind: CreateKind,
+  params: Readonly<Record<string, unknown>>,
+): GeneratorDefinition {
+  if (kind === "component") {
+    const framework = String(params.framework ?? "react");
+    const generator = componentMap[`component/${framework}`];
+    if (!generator) {
+      throw PragmaError.invalidInput("framework", framework, {
+        validOptions: [...FRAMEWORKS],
+      });
+    }
+    return generator;
+  }
+  const generator =
+    kind === "package"
+      ? packageMap.package
+      : applicationMap["application/react"];
+  if (!generator) {
+    throw PragmaError.internalError(`missing ${kind} generator`);
+  }
+  return generator;
+}

package/src/capabilities/create/templates.embedded.generated.ts

@@ -0,0 +1,53 @@
+// AUTO-GENERATED by scripts/build.ts — do not edit by hand.
+// Regenerate: `bun run scripts/build.ts`. Inlines the summon generators' .ejs
+// templates as strings so `pragma create` works from the standalone --compile
+// binary (the .ejs files are absent from the binary's virtual filesystem).
+/** Directory-qualified template path → file contents. */
+export const TEMPLATES: Record<string, string> = {
+  "application/.storybook/main.ts.ejs": "import { createConfig } from \"@canonical/storybook-config\";\n\nexport default createConfig(\"react\", {\n  staticDirs: [\"../src/assets\", \"../public\"],\n<% if (relay) { -%>\n  // Wraps stories that declare `parameters.relay` in a relay-test-utils mock\n  // environment, so components using Relay hooks render without a server.\n  extraAddons: [\"@canonical/storybook-addon-relay\"],\n<% } -%>\n});\n",
+  "application/README.md.ejs": "# <%= name %>\n\nA React application with server-side rendering and routing, generated by\n`@canonical/summon`. It is built on Canonical's shared design system, router, and\nSSR packages, and ships SSR on two runtimes (Bun and Node), file-based routing, a\ncomponent library wired to design tokens, and Storybook.\n\n## Quick start\n\n```bash\nbun install\nbun run dev:bun      # SSR dev server with HMR, on http://localhost:5174\n```\n\nEdit anything under `src/` and the page hot-reloads. To check the production\nbuild before shipping, run `bun run preview:bun` instead.\n\n## Running the app\n\nThe server scripts form a **2×3 matrix** — two modes (development and preview)\nacross three targets (a client-only SPA, SSR on Bun, SSR on Node/Express):\n\n|                  | `dev` — transform, HMR | `preview` — compiled, production-faithful |\n| ---------------- | ---------------------- | ----------------------------------------- |\n| **SPA** (no SSR) | `bun run dev`          | `bun run preview`                         |\n| **SSR · Bun**    | `bun run dev:bun`      | `bun run preview:bun`                     |\n| **SSR · Node**   | `bun run dev:express`  | `bun run preview:express`                 |\n\nThe naming is systematic: the bare name is the **SPA**, the `:bun` / `:express`\nsuffix selects the **SSR runtime**, and the `dev` / `preview` prefix selects the\n**mode**. Reach for `dev:*` while building — it is the fast inner loop, with HMR\nand no build step — and for `preview:*` when verifying that the production bundle\nbehaves before a deploy: `preview:*` builds the client and runs a compiled\nrenderer over the built assets, the same artifact that deploys.\n\n```bash\nbun run storybook    # component workshop\n```\n<% if (relay) { -%>\n\nRelay's compiler artifacts are committed, not rebuilt on the fly:\n\n```bash\nbun run relay          # regenerate src/relay/__generated__ after schema/query edits\nbun run relay:watch    # the same, re-running on change — pair with dev:*\n```\n<% } -%>\n\n## Adding routes\n\n`summon` scaffolds the building blocks of the app so new features follow the\nestablished structure rather than diverging from it.\n\n```bash\nsummon domain billing            # a new feature domain (routes + pages)\nsummon route billing/invoices    # a route within a domain\nsummon wrapper sidebar           # a layout wrapper\n```\n\n## Testing\n\n```bash\nbun run test          # unit + component tests (Vitest, jsdom)\nbun run test:coverage # the same, with a coverage report\nbun run test:e2e      # boots all six matrix servers and asserts each serves\n```\n\n`test:e2e` is an end-to-end test *of the build*: it runs each of the six server\nscripts — including the production builds that `preview:*` performs — and asserts\nthat every server returns a rendered document and serves its client assets with\nthe correct content type.\n\n## Project structure\n\n```\nsrc/\n├── client/         Client entry (hydration)\n├── server/         Server entry, compiled renderer, dev servers, sitemap\n├── domains/        Feature domains (each owns its routes and pages)\n├── lib/            Shared components\n<% if (relay) { -%>\n├── relay/          Relay environment factory, executable mock schema,\n│                   and generated artifacts (__generated__/)\n<% } -%>\n├── styles/         Application CSS\n├── assets/         Assets imported in code (bundled and hashed by Vite)\n└── routes.tsx      Root route map\npublic/             Files served verbatim at a fixed URL (favicon, robots.txt)\ntest/e2e/           The 2×3 server-matrix end-to-end suite\n```\n\nDomains are the unit of feature organisation: each owns its routes and pages, so\nadding a feature is adding a domain rather than threading changes through shared\nfiles. This app ships both `src/assets/` (assets imported in code) and `public/`\n(files served by fixed URL); either may be removed if the app uses only one.\n<% if (relay) { -%>\n\n## Data layer (Relay)\n\nThe `catalog` domain demonstrates the app's [Relay](https://relay.dev) data\nlayer: `ProductList` fetches a page of products with `useLazyLoadQuery`, and\neach `ProductCard` reads its own colocated `useFragment` — the component owns\nits field selection, the parent query just spreads it.\n\n**By default the app needs no backend.** `createEnvironment`\n(`src/relay/environment.ts`) resolves every GraphQL operation in-process\nagainst an executable mock schema (`src/relay/schema.ts`, built from the SDL\nin `src/relay/schema.graphql`) backed by a small deterministic catalog. Set\n`VITE_GRAPHQL_URL` (or pass `graphqlUrl` to `createEnvironment`) to switch the\nenvironment to posting operations to a real GraphQL endpoint instead — no code\nchanges needed.\n\n**Generated artifacts are committed.** The Vite plugin runs with\n`codegen: false`, so `src/relay/__generated__/` is not rebuilt on the fly:\nafter editing a `graphql` tag or the schema, run `bun run relay` (or keep\n`bun run relay:watch` running) to regenerate the artifacts, and commit them.\n\n**SSR ships no data yet.** `useLazyLoadQuery` fetches (and suspends) while\nrendering, and the server cannot serialize the fetched store for the client\nyet, so the catalog page wraps its query subtree in `ClientOnly`\n(`src/lib/ClientOnly/`): the server streams the fallback and the browser\nfetches after hydration.\n\n<% if (standalone) { -%>\n**Patched dependencies.** `patches/` carries three package patches applied via\n`patchedDependencies` in `package.json` (a bun feature — with another package\nmanager, apply the equivalent mechanism): `react-relay@21.0.1` needs a\ncjs-module-lexer export hint so named imports survive Node SSR,\n`relay-runtime@21.0.1` needs real runtime bindings for type-only names its\ncompiler artifacts import as values (`ConcreteRequest`, `ReaderFragment`,\n`FragmentRefs`), and `relay-runtime-network@0.1.0` ships a broken `imports`\nmap. The last patch is temporary until the fixed upstream release lands\n([advl/lit-relay#32](https://github.com/advl/lit-relay/pull/32)); drop it and\nits `patchedDependencies` entry once a fixed version is published.\n<% } else { -%>\n**Patched dependencies.** This app was scaffolded inside a bun workspace, so\ndependency patching is owned by the workspace root — bun resolves\n`patchedDependencies` paths from the root, which is why the scaffold emitted\nno app-local `patches/` directory or `patchedDependencies` block. The root's\n`patches/` must carry the `react-relay@21.0.1`, `relay-runtime@21.0.1` and\n`relay-runtime-network@0.1.0` patches (named imports under Node SSR, runtime\nbindings for type-only artifact imports, and a broken `imports` map,\nrespectively).\n<% } -%>\n\n**Not yet on npm.** `@canonical/storybook-addon-relay` and the fixed\n`relay-runtime-network` release have not been published yet, so a fresh\ninstall of this app will not fully resolve until they land on npm.\n<% } -%>\n",
+  "application/biome.json.ejs": "{\n  \"extends\": [\"@canonical/biome-config\"],\n  \"files\": {\n    \"includes\": [\"src\", \"*.json\", \"vite.config.ts\"<% if (relay) { %>, \"!src/relay/__generated__\"<% } %>]\n  }\n}\n",
+  "application/index.html.ejs": "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <meta name=\"description\" content=\"<%= name %> — a React application built with the Canonical design system, router, and SSR packages.\" />\n    <link rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://assets.ubuntu.com/v1/be7e4cc6-COF-favicon-32x32.png\">\n    <title><%= name %></title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/src/client/entry.tsx\"></script>\n  </body>\n</html>\n",
+  "application/package.json.ejs": "{\n  \"name\": \"<%= name %>\",\n  \"private\": true,\n  \"version\": \"0.0.0\",\n  \"type\": \"module\",\n  \"license\": \"GPL-3.0-only\",\n  \"imports\": {\n    \"#lib/*\": \"./src/lib/*\",\n    \"#domains/*\": \"./src/domains/*\",\n<% if (relay) { -%>\n    \"#relay/*\": \"./src/relay/*\",\n<% } -%>\n    \"#styles/*\": \"./src/styles/*\"\n  },\n  \"scripts\": {\n    \"dev\": \"vite\",\n    \"dev:express\": \"node --import tsx src/server/server.express.ts\",\n    \"dev:bun\": \"bun src/server/server.bun.ts\",\n    \"preview\": \"bun run build:client && vite preview --outDir dist/client\",\n    \"preview:bun\": \"bun run build:client && bun run build:server && bun src/server/preview.bun.ts\",\n    \"preview:express\": \"bun run build:client && bun run build:server && node --import tsx src/server/preview.express.ts\",\n    \"build\": \"bun run build:client\",\n    \"build:all\": \"bun run build:client && bun run build:storybook\",\n    \"build:client\": \"vite build --ssrManifest --outDir dist/client\",\n    \"build:server\": \"vite build --mode server\",\n    \"build:storybook\": \"storybook build\",\n    \"check\": \"bun run check:biome && bun run check:ts\",\n    \"check:fix\": \"bun run check:biome:fix && bun run check:ts\",\n    \"check:biome\": \"biome check\",\n    \"check:biome:fix\": \"biome check --write\",\n    \"check:ts\": \"tsc --noEmit\",\n<% if (relay) { -%>\n    \"relay\": \"relay-compiler\",\n    \"relay:watch\": \"relay-compiler --watch\",\n<% } -%>\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"test:coverage\": \"vitest run --coverage\",\n    \"test:e2e\": \"vitest run --config vitest.e2e.config.ts\",\n    \"storybook\": \"storybook dev -p 6010 --no-open --host 0.0.0.0\"\n  },\n  \"dependencies\": {\n    \"@canonical/react-ds-global\": \"<%= pragmaVersion %>\",\n<% if (forms) { -%>\n    \"@canonical/react-ds-global-form\": \"<%= pragmaVersion %>\",\n<% } -%>\n    \"@canonical/react-head\": \"<%= pragmaVersion %>\",\n    \"@canonical/react-hooks\": \"<%= pragmaVersion %>\",\n    \"@canonical/react-ssr\": \"<%= pragmaVersion %>\",\n    \"@canonical/router-core\": \"<%= pragmaVersion %>\",\n    \"@canonical/router-react\": \"<%= pragmaVersion %>\",\n<% if (relay) { -%>\n    \"@canonical/storybook-addon-relay\": \"<%= pragmaVersion %>\",\n<% } -%>\n    \"@canonical/storybook-config\": \"<%= pragmaVersion %>\",\n    \"@canonical/styles\": \"<%= pragmaVersion %>\",\n    \"express\": \"^5.2.1\",\n<% if (relay) { -%>\n    \"graphql\": \"^16.11.0\",\n<% } -%>\n    \"react\": \"^19.2.4\",\n    \"react-dom\": \"^19.2.4\"<% if (relay) { %>,\n    \"react-relay\": \"^21.0.1\",\n    \"relay-runtime\": \"^21.0.1\",\n    \"relay-runtime-network\": \"^0.1.0\"<% } %>\n  },\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"2.4.9\",\n    \"@canonical/biome-config\": \"<%= pragmaVersion %>\",\n    \"@canonical/typescript-config-react\": \"<%= pragmaVersion %>\",\n    \"@storybook/react-vite\": \"^10.3.1\",\n    \"@testing-library/jest-dom\": \"^6.9.1\",\n    \"@testing-library/react\": \"^16.3.2\",\n    \"@types/express\": \"^5.0.6\",\n    \"@types/node\": \"^24.12.0\",\n    \"@types/react\": \"^19.2.14\",\n    \"@types/react-dom\": \"^19.2.3\",\n<% if (relay) { -%>\n    \"@types/react-relay\": \"^18.2.1\",\n    \"@types/relay-runtime\": \"^20.1.1\",\n    \"@types/relay-test-utils\": \"^19.0.0\",\n<% } -%>\n    \"@vitejs/plugin-react\": \"^6.0.0\",\n    \"@vitest/coverage-v8\": \"^4.0.18\",\n    \"browserslist\": \"^4.28.1\",\n    \"bun-types\": \"^1.3.9\",\n    \"jsdom\": \"^28.1.0\",\n    \"lightningcss\": \"^1.32.0\",\n<% if (relay) { -%>\n    \"relay-compiler\": \"^21.0.1\",\n    \"relay-test-utils\": \"^21.0.1\",\n<% } -%>\n    \"storybook\": \"^10.3.1\",\n    \"tsx\": \"^4.19.0\",\n    \"typescript\": \"^5.9.3\",\n    \"vite\": \"^8.0.1\",\n<% if (relay) { -%>\n    \"vite-plugin-relay-lite\": \"^0.12.0\",\n<% } -%>\n    \"vitest\": \"^4.0.18\"\n  }<% if (relay && standalone) { %>,\n  \"patchedDependencies\": {\n    \"react-relay@21.0.1\": \"patches/react-relay@21.0.1.patch\",\n    \"relay-runtime@21.0.1\": \"patches/relay-runtime@21.0.1.patch\",\n    \"relay-runtime-network@0.1.0\": \"patches/relay-runtime-network@0.1.0.patch\"\n  }<% } %>\n}\n",
+  "application/src/client/entry.tsx.ejs": "import { HeadProvider } from \"@canonical/react-head\";\nimport { createBrowserRouter } from \"@canonical/router-core\";\nimport { Outlet, RouterProvider } from \"@canonical/router-react\";\nimport { hydrateRoot } from \"react-dom/client\";\n<% if (relay) { -%>\nimport { RelayEnvironmentProvider } from \"react-relay\";\nimport { createEnvironment } from \"#relay/environment.js\";\n<% } -%>\nimport { appRoutes, middleware, notFoundRoute } from \"../routes.js\";\nimport \"#styles/index.css\";\n\nconst router = createBrowserRouter(appRoutes, {\n  middleware: [...middleware],\n  notFound: notFoundRoute,\n});\n<% if (relay) { -%>\n\n// One Relay environment (network + normalized store) for the whole browser\n// session — module scope, so client-side navigations share the cache.\nconst relayEnvironment = createEnvironment();\n<% } -%>\n\nconst root = document.getElementById(\"root\");\nif (!root) {\n  throw new Error('Root element \"#root\" not found');\n}\n\n<% if (relay) { -%>\nhydrateRoot(\n  root,\n  <HeadProvider>\n    <RelayEnvironmentProvider environment={relayEnvironment}>\n      <RouterProvider router={router}>\n        <Outlet fallback={<p>Loading…</p>} />\n      </RouterProvider>\n    </RelayEnvironmentProvider>\n  </HeadProvider>,\n);\n<% } else { -%>\nhydrateRoot(\n  root,\n  <HeadProvider>\n    <RouterProvider router={router}>\n      <Outlet fallback={<p>Loading…</p>} />\n    </RouterProvider>\n  </HeadProvider>,\n);\n<% } -%>\n",
+  "application/src/lib/Navigation/Navigation.tsx.ejs": "import { Link } from \"@canonical/router-react\";\nimport type { ReactElement } from \"react\";\nimport ThemeSelector from \"../ThemeSelector/index.js\";\n\nexport default function Navigation(): ReactElement {\n  return (\n    <nav aria-label=\"Main\">\n      <Link to=\"home\">Home</Link>\n      <Link params={{ slug: \"router-core\" }} to=\"guide\">\n        Guide\n      </Link>\n<% if (relay) { -%>\n      <Link to=\"catalog\">Catalog</Link>\n<% } -%>\n<% if (forms) { -%>\n      <Link to=\"contact\">Contact</Link>\n<% } -%>\n      <Link search={{ auth: \"1\" }} to=\"account\">\n        Demo sign-in\n      </Link>\n      <ThemeSelector />\n    </nav>\n  );\n}\n",
+  "application/src/lib/index.ts.ejs": "<% if (relay) { -%>\nexport { default as ClientOnly } from \"./ClientOnly/index.js\";\n<% } -%>\nexport { ExampleComponent } from \"./ExampleComponent/index.js\";\nexport { default as LazyComponent } from \"./LazyComponent/index.js\";\nexport { default as Navigation } from \"./Navigation/index.js\";\nexport { default as ThemeSelector } from \"./ThemeSelector/index.js\";\n",
+  "application/src/routes.tsx.ejs": "import {\n  type AnyRoute,\n  group,\n  type NavigationContext,\n  type RouteMiddleware,\n  type RouteParamValues,\n  redirect,\n  route,\n  wrapper,\n} from \"@canonical/router-core\";\nimport type { ReactElement, ReactNode } from \"react\";\nimport accountRoutes from \"#domains/account/routes.js\";\n<% if (relay) { -%>\nimport catalogRoutes from \"#domains/catalog/routes.js\";\n<% } -%>\n<% if (forms) { -%>\nimport contactRoutes from \"#domains/contact/routes.js\";\n<% } -%>\nimport marketingRoutes from \"#domains/marketing/routes.js\";\nimport Navigation from \"#lib/Navigation/index.js\";\n\nconst protectedPaths = new Set([\"/account\"]);\n\nfunction hasDemoAuth(search: unknown): boolean {\n  const authValue = (search as Record<string, unknown>)?.auth;\n\n  return authValue === \"1\";\n}\n\nexport function getAuthRedirectHref(input: string | URL): string | null {\n  // Absolute URLs are used as-is; relative paths resolve against a dummy base.\n  const url =\n    input instanceof URL ? input : new URL(input, \"https://router.local\");\n\n  if (\n    !protectedPaths.has(url.pathname) ||\n    hasDemoAuth({ auth: url.searchParams.get(\"auth\") })\n  ) {\n    return null;\n  }\n\n  return `/login?from=${encodeURIComponent(url.pathname)}`;\n}\n\nexport function withAuth(loginPath: string): RouteMiddleware {\n  return ((currentRoute: AnyRoute) => {\n    if (!protectedPaths.has(currentRoute.url)) {\n      return currentRoute;\n    }\n\n    const currentPrefetch = currentRoute.prefetch;\n\n    return {\n      ...currentRoute,\n      prefetch: (\n        params: unknown,\n        search: unknown,\n        context: NavigationContext,\n      ) => {\n        if (!hasDemoAuth(search)) {\n          const from = currentRoute.render(\n            (params ?? {}) as RouteParamValues | Record<string, never>,\n          );\n\n          redirect(`${loginPath}?from=${encodeURIComponent(from)}`, 302);\n        }\n\n        if (currentPrefetch) {\n          return currentPrefetch(params, search, context);\n        }\n      },\n    };\n  }) as RouteMiddleware;\n}\n\nconst publicLayout = wrapper<ReactElement>({\n  id: \"public-layout\",\n  component: ({ children }: { children: ReactNode }) => (\n    <div className=\"subgrid app-shell\">\n      <header className=\"subgrid shell-header\">\n        <Navigation />\n      </header>\n      <main className=\"subgrid\">{children}</main>\n    </div>\n  ),\n});\n\nconst notFoundRoute = route({\n  url: \"/not-found\",\n  content: () => (\n    <section>\n      <h1>Page not found</h1>\n      <p>The page you are looking for does not exist.</p>\n    </section>\n  ),\n});\n\nconst [guide, home] = group(publicLayout, [\n  marketingRoutes.guide,\n  marketingRoutes.home,\n] as const);\n\nconst [account, login] = group(publicLayout, [\n  accountRoutes.account,\n  accountRoutes.login,\n] as const);\n\n<% if (forms) { -%>\nconst [contact] = group(publicLayout, [contactRoutes.contact] as const);\n\n<% } -%>\n<% if (relay) { -%>\nconst [catalog] = group(publicLayout, [catalogRoutes.catalog] as const);\n\n<% } -%>\nconst appRoutes = {\n  guide,\n  home,\n  account,\n  login,\n<% if (forms) { -%>\n  contact,\n<% } -%>\n<% if (relay) { -%>\n  catalog,\n<% } -%>\n} as const;\n\nexport type AppRoutes = typeof appRoutes;\n\ndeclare module \"@canonical/router-react\" {\n  interface RouterRegister {\n    routes: AppRoutes;\n  }\n}\n\nexport const middleware = [withAuth(\"/login\")] as const;\n\nexport { appRoutes, notFoundRoute };\n",
+  "application/src/server/entry.tsx.ejs": "import { HeadProvider } from \"@canonical/react-head\";\nimport type { ServerEntrypointProps } from \"@canonical/react-ssr/renderer\";\nimport { createStaticRouter } from \"@canonical/router-core\";\nimport { Outlet, RouterProvider } from \"@canonical/router-react\";\n<% if (relay) { -%>\nimport { RelayEnvironmentProvider } from \"react-relay\";\nimport { createEnvironment } from \"#relay/environment.js\";\n<% } -%>\nimport { appRoutes, middleware, notFoundRoute } from \"../routes.js\";\nimport \"#styles/app.css\";\n\ninterface InitialData extends Record<string, unknown> {\n  readonly url?: string;\n  /** Colour-scheme preference resolved from the request cookie, if any. */\n  readonly theme?: \"light\" | \"dark\";\n}\n\nexport default function EntryServer(props: ServerEntrypointProps<InitialData>) {\n  const initialData = props.initialData ?? {};\n  const url = initialData.url ?? \"/\";\n  const router = createStaticRouter(appRoutes, url, {\n    middleware: [...middleware],\n    notFound: notFoundRoute,\n  });\n<% if (relay) { -%>\n\n  // A fresh Relay environment per server render, so no store state leaks\n  // between requests. Nothing fetches through it yet: components that issue\n  // queries are wrapped in `ClientOnly` (see CatalogPage) until data\n  // serialization/hydration is supported; the provider is here so any\n  // component touching Relay context renders without branching on runtime.\n  const relayEnvironment = createEnvironment();\n<% } -%>\n\n  // Paint the cookie-resolved theme on <html> for a flash-free first render —\n  // the same element `usePreferredTheme` toggles on the client, and one React\n  // does not hydrate (only `#root` is), so there is no mismatch to reconcile.\n<% if (relay) { -%>\n  return (\n    <html lang={props.lang} className={initialData.theme}>\n      <head>\n        {props.otherHeadElements}\n        {props.scriptElements}\n        {props.linkElements}\n      </head>\n      <body>\n        <div id=\"root\">\n          <HeadProvider>\n            <RelayEnvironmentProvider environment={relayEnvironment}>\n              <RouterProvider router={router}>\n                <Outlet fallback={<p>Loading…</p>} />\n              </RouterProvider>\n            </RelayEnvironmentProvider>\n          </HeadProvider>\n        </div>\n      </body>\n    </html>\n  );\n<% } else { -%>\n  return (\n    <html lang={props.lang} className={initialData.theme}>\n      <head>\n        {props.otherHeadElements}\n        {props.scriptElements}\n        {props.linkElements}\n      </head>\n      <body>\n        <div id=\"root\">\n          <HeadProvider>\n            <RouterProvider router={router}>\n              <Outlet fallback={<p>Loading…</p>} />\n            </RouterProvider>\n          </HeadProvider>\n        </div>\n      </body>\n    </html>\n  );\n<% } -%>\n}\n\nexport type { InitialData };\n",
+  "application/src/sitemap/getSitemapItems.ts.ejs": "import type { SitemapItem } from \"@canonical/react-ssr/renderer\";\n\n/**\n * Returns sitemap entries for all known routes.\n *\n * Update this list as you add domains and routes. For dynamic content\n * (blog posts, product pages), fetch entries from your data source.\n *\n * @example\n * const posts = await fetchPosts();\n * return [\n *   ...staticEntries,\n *   ...posts.map((post) => ({\n *     loc: `/blog/${post.slug}`,\n *     lastmod: post.updatedAt,\n *     changefreq: \"weekly\" as const,\n *     priority: 0.7,\n *   })),\n * ];\n */\nexport default async function getSitemapItems(): Promise<SitemapItem[]> {\n  return [\n    { loc: \"/\", changefreq: \"weekly\", priority: 1.0 },\n    { loc: \"/guides/router-core\", changefreq: \"monthly\", priority: 0.8 },\n<% if (relay) { -%>\n    { loc: \"/catalog\", changefreq: \"weekly\", priority: 0.7 },\n<% } -%>\n<% if (forms) { -%>\n    { loc: \"/contact\", changefreq: \"monthly\", priority: 0.7 },\n<% } -%>\n    { loc: \"/account\", changefreq: \"monthly\", priority: 0.5 },\n    { loc: \"/login\", changefreq: \"yearly\", priority: 0.3 },\n  ];\n}\n",
+  "application/src/styles/index.css.ejs": "@import url(\"@canonical/styles\");\n<% if (forms) { -%>\n@import url(\"@canonical/react-ds-global-form/dist/esm/index.css\");\n<% } -%>\n@import url(\"./app.css\");\n",
+  "application/tsconfig.json.ejs": "{\n  \"extends\": \"@canonical/typescript-config-react\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"src\",\n    \"skipLibCheck\": true,\n    \"types\": [\n      \"bun-types\",\n      \"node\",\n      \"react\",\n      \"react-dom\",\n      \"vitest/globals\",\n      \"@testing-library/jest-dom\"\n    ],\n    \"noEmit\": true,\n    \"paths\": {\n      \"#lib/*\": [\"./lib/*\"],\n      \"#domains/*\": [\"./domains/*\"],\n<% if (relay) { -%>\n      \"#relay/*\": [\"./relay/*\"],\n<% } -%>\n      \"#styles/*\": [\"./styles/*\"]\n    }\n  },\n  \"include\": [\n    \"src/**/*.ts\",\n    \"src/**/*.tsx\",\n    \".storybook/*.ts\",\n    \".storybook/*.tsx\",\n    \"vite.config.ts\",\n    \"vitest.setup.ts\",\n    \"vitest.config.ts\",\n    \"vitest.e2e.config.ts\",\n    \"test/**/*.ts\"\n  ]\n}\n",
+  "application/vite.config.ts.ejs": "import react from \"@vitejs/plugin-react\";\nimport browserslist from \"browserslist\";\nimport { browserslistToTargets } from \"lightningcss\";\nimport { defineConfig } from \"vite\";\n<% if (relay) { -%>\nimport relay from \"vite-plugin-relay-lite\";\n<% } -%>\n\n// Path aliases (#lib, #domains, #styles) are declared as Node subpath imports\n// in package.json \"imports\" and resolved natively by Vite — no resolver plugin.\nconst PORT = Number(process.env.PORT) || undefined;\n\n// `build:server` runs `vite build --mode server` to compile the two server\n// renderers in a single pass. Each is a separate, individually-instantiated\n// Lego brick, so they are named Rollup inputs — the build emits\n// `dist/server/renderer.js` (the JSX app) + `dist/server/sitemap.js` (the XML\n// sitemap), which the preview servers import directly. Every other command\n// (`dev`, `build:client`, `preview`) uses the default mode and the SPA client\n// build (`--ssrManifest --outDir dist/client`).\nexport default defineConfig(({ mode }) => ({\n<% if (relay) { -%>\n  // Relay's `graphql\\`...\\`` tags must be rewritten into imports of the\n  // compiler-generated artifacts. `@vitejs/plugin-react` v6 is OXC-based (no\n  // Babel), so the classic `babel-plugin-relay` route would need the\n  // `@rolldown/plugin-babel` escape hatch; `vite-plugin-relay-lite` does the\n  // same rewrite with its own parser and no Babel, and works on Vite 8 /\n  // rolldown despite its peer range stopping at Vite 7 (bun installs it with\n  // only a peer-version warning). Footgun: its tag scanner matches the word\n  // \"graphql\" followed by a backtick even inside comments, so never\n  // backtick-quote a graphql file name in a comment. `codegen: false` because\n  // artifacts are committed and regenerated explicitly via the `relay` /\n  // `relay:watch` scripts.\n  plugins: [relay({ codegen: false }), react()],\n<% } else { -%>\n  plugins: [react()],\n<% } -%>\n  // Honour the PORT env var for `dev` (SPA) and `preview` so all server scripts\n  // — including the SSR ones, which already read PORT — respond to it uniformly.\n  server: { port: PORT },\n  preview: { port: PORT },\n  // CSS delivery is the app's job, not the libraries': @canonical/* packages\n  // deliberately ship modern, uncompiled per-component CSS and take no stance\n  // on browser support. Lightning CSS (already bundled with Vite 8) compiles\n  // that CSS down to this app's declared browser floor — the browserslist\n  // query in .browserslistrc, which is the one knob to turn when support\n  // requirements change. Not everything can be downleveled: math functions\n  // like `mod()` (used by the typography baseline grid) have no polyfillable\n  // form, so that feature's effective Chromium ≥ 125 floor is unchanged.\n  css: {\n    transformer: \"lightningcss\",\n    lightningcss: { targets: browserslistToTargets(browserslist()) },\n  },\n  build: {\n    // Minify CSS with Lightning CSS too (instead of the esbuild default), so\n    // a single tool owns both downleveling and minification — in the client\n    // build and the server build alike.\n    cssMinify: \"lightningcss\",\n    ...(mode === \"server\"\n      ? {\n          ssr: true,\n          outDir: \"dist/server\",\n          rollupOptions: {\n            input: {\n              renderer: \"src/server/renderer.tsx\",\n              sitemap: \"src/sitemap/renderer.ts\",\n            },\n          },\n        }\n      : undefined),\n  },\n  ssr: {\n    // Bundle @canonical/* for SSR rather than externalising them, for two\n    // reasons: (1) some packages declare only a \"module\" entry (no\n    // \"main\"/\"exports\"), which Vite's SSR (Node-style) resolver ignores —\n    // externalising them fails with ERR_RESOLVE_PACKAGE_ENTRY_FAIL; (2) their\n    // built output imports CSS as a side effect (e.g. `import \"./x.css\"`),\n    // which Node cannot load (ERR_UNKNOWN_FILE_EXTENSION) but Vite's SSR\n    // transform no-ops. The regex covers the whole scope so any current or\n    // future @canonical dependency is handled.\n<% if (relay) { -%>\n    //\n    // The Relay packages (react-relay, relay-runtime, relay-runtime-network,\n    // graphql) stay externalised like react itself. Three packaging defects\n    // made that possible and are fixed via `patchedDependencies` (app-local\n    // patches/ for a standalone app; the workspace root's patches/ when the\n    // app lives inside a bun workspace): react-relay's CJS exports are member\n    // expressions cjs-module-lexer cannot detect (breaking named imports\n    // under Node SSR and Vite's dev module runner), relay-runtime lacks\n    // runtime bindings for type-only names its compiler artifacts import as\n    // values (ConcreteRequest, ReaderFragment, FragmentRefs), and\n    // relay-runtime-network@0.1.0 ships an `imports` map pointing at its\n    // unpublished src/ directory.\n<% } -%>\n    noExternal: [/^@canonical\\//],\n  },\n}));\n",
+  "application/vitest.setup.ts.ejs": "import * as matchers from \"@testing-library/jest-dom/matchers\";\nimport { cleanup } from \"@testing-library/react\";\n<% if (relay) { -%>\nimport { afterEach, expect, vi } from \"vitest\";\n<% } else { -%>\nimport { afterEach, expect } from \"vitest\";\n<% } -%>\n\nexpect.extend(matchers as unknown as Parameters<typeof expect.extend>[0]);\n<% if (relay) { -%>\n\n// relay-test-utils' `createMockEnvironment` wraps environment methods in\n// `jest.fn` mocks whenever NODE_ENV === \"test\", reaching for a global `jest`\n// object. Vitest sets NODE_ENV=test but exposes `vi` instead, so alias it —\n// `vi.fn` is API-compatible with the `jest.fn` surface relay-test-utils uses\n// (`.mock`, `.mockClear`).\n(globalThis as { jest?: typeof vi }).jest = vi;\n<% } -%>\n\nafterEach(() => {\n  cleanup();\n});\n",
+  "component/lit/component.ts.ejs": "import { html, LitElement } from \"lit\";\nimport { customElement } from \"lit/decorators.js\";\n<% if (withStyles) { -%>\nimport styles from \"./styles.css\";\n<% } -%>\nimport type { <%= name %>Props } from \"./types.js\";\n\nconst componentCssClassName = \"ds <%= kebabName %>\";\n\n/**\n * <%= name %> web component.\n *\n * @implements ds:global.component.<%= kebabName %>\n */\n@customElement(\"ds-<%= kebabName %>\")\nexport default class <%= name %> extends LitElement implements <%= name %>Props {\n<% if (withStyles) { -%>\n  static styles = styles;\n\n<% } -%>\n  render() {\n    return html`\n      <div class=\"${componentCssClassName}\">\n        <slot></slot>\n      </div>\n    `;\n  }\n}\n",
+  "component/lit/index.ts.ejs": "export { default as <%= name %> } from \"./<%= name %>.js\";\nexport type { <%= name %>Props } from \"./types.js\";\n",
+  "component/lit/stories.ts.ejs": "import type { Meta, StoryObj } from \"@storybook/web-components-vite\";\nimport { html } from \"lit\";\n\nimport \"./<%= name %>.js\";\nimport type <%= name %> from \"./<%= name %>.js\";\n\nconst meta = {\n  title: \"Web Components/<%= name %>\",\n  tags: [\"autodocs\"],\n} satisfies Meta<<%= name %>>;\n\nexport default meta;\ntype Story = StoryObj<<%= name %>>;\n\nexport const Default: Story = {\n  render: () => html`<ds-<%= kebabName %>>Hello, <%= name %>!</ds-<%= kebabName %>>`,\n};\n",
+  "component/lit/styles.css.ejs": "/*\n * Lit Layout Primer\n * Delete this comment block when you're done implementing.\n *\n * Styles live in a shadow DOM, isolated from the page by default.\n *\n * Two layers:\n *\n *   1) :host — the outer shell, how this component presents to its parent layout.\n *      display, width, height                          (always apply)\n *      grid-column, grid-row, align-self, justify-self (parent must be grid/flex)\n *\n *   2) .ds.<%= kebabName %> — the inner shell, how this component arranges its shadow children.\n *      display: grid/flex, gap, grid-template-columns, align-items, justify-content\n *\n * Subgrid pattern — use when the parent defines grid tracks you want to inherit:\n *\n *   In the parent component:\n *   .ds.parent { display: grid; grid-template-columns: repeat(4, 1fr); }\n *\n *   In this component:\n *   :host                { display: grid; grid-column: span 2; }\n *   .ds.<%= kebabName %> { display: grid; grid-template-columns: subgrid; }\n *\n *   In this example, the parent establishes a 4-column grid.\n *   This component claims 2 of those columns and inherits their widths via subgrid.\n *\n * Keep in mind:\n *   - Custom elements are display: inline by default — always set display on :host.\n *   - Flex/grid rules only affect direct children of the container, not deeper descendants.\n *   - External CSS cannot pierce the shadow boundary — expose CSS custom properties for theming.\n */\n\n:host {\n  /*\n   * Host controls the outer layout role.\n   * Declare component CSS variables here when needed.\n   * Variables must be on :host to be accessible inside the shadow tree.\n   *\n   * Example:\n   * --<%= kebabName %>-color-background: var(--color-background-default);\n   * --<%= kebabName %>-color-text: var(--color-text-default);\n   */\n  display: inline-flex;\n}\n\n.ds.<%= kebabName %> {\n  /* Inner layout and visual styles go here. */\n}\n",
+  "component/lit/tests.ts.ejs": "import { afterEach, beforeEach, describe, expect, it } from \"vitest\";\nimport \"./<%= name %>.js\";\nimport type <%= name %> from \"./<%= name %>.js\";\n\ndescribe(\"<%= name %> component\", () => {\n  let elem: <%= name %>;\n\n  beforeEach(() => {\n    elem = document.createElement(\"ds-<%= kebabName %>\") as <%= name %>;\n    document.body.appendChild(elem);\n  });\n\n  afterEach(() => {\n    elem.remove();\n  });\n\n  it(\"should render component\", async () => {\n    await customElements.whenDefined(\"ds-<%= kebabName %>\");\n\n    const container = elem.shadowRoot?.querySelector(\".ds.<%= kebabName %>\");\n    expect(container).toBeTruthy();\n  });\n\n  it(\"should have correct tag name\", () => {\n    expect(elem.tagName.toLowerCase()).toBe(\"ds-<%= kebabName %>\");\n  });\n});\n",
+  "component/lit/types.ts.ejs": "/**\n * Props for the <%= name %> component.\n */\nexport interface <%= name %>Props {\n  // Define props specific to <%= name %> here\n}\n",
+  "component/react/component.tsx.ejs": "import type React from \"react\";\nimport type { <%= name %>Props } from \"./types.js\";\n<% if (withStyles) { -%>\nimport \"./styles.css\";\n<% } -%>\n\nconst componentCssClassName = \"ds <%= kebabName %>\";\n\n/**\n * <%= name %> component\n */\nconst <%= name %> = ({\n\tclassName,\n\tchildren,\n\t...props\n}: <%= name %>Props): React.ReactElement => {\n\treturn (\n\t\t<div\n\t\t\tclassName={[componentCssClassName, className].filter(Boolean).join(\" \")}\n\t\t\t{...props}\n\t\t>\n\t\t\t{children}\n\t\t</div>\n\t);\n};\n\nexport default <%= name %>;\n",
+  "component/react/index.ts.ejs": "export { default as <%= name %> } from \"./<%= name %>.js\";\nexport type * from \"./types.js\";\n",
+  "component/react/ssr.test.tsx.ejs": "import { describe, expect, it } from \"vitest\";\nimport { renderToString } from \"react-dom/server\";\nimport <%= name %> from \"./<%= name %>.js\";\n\ndescribe(\"<%= name %> SSR\", () => {\n\tit(\"renders without hydration errors\", () => {\n\t\tconst html = renderToString(<<%= name %>>Test content</<%= name %>>);\n\t\texpect(html).toContain(\"Test content\");\n\t\texpect(html).toContain(\"ds <%= kebabName %>\");\n\t});\n});\n",
+  "component/react/stories.tsx.ejs": "import type { Meta, StoryObj } from \"@storybook/react-vite\";\nimport <%= name %> from \"./<%= name %>.js\";\n\nconst meta: Meta<typeof <%= name %>> = {\n\ttitle: \"Components/<%= name %>\",\n\tcomponent: <%= name %>,\n\ttags: [\"autodocs\"],\n};\n\nexport default meta;\ntype Story = StoryObj<typeof <%= name %>>;\n\nexport const Default: Story = {\n\targs: {\n\t\tchildren: \"Hello, <%= name %>!\",\n\t},\n};\n\nexport const WithCustomClass: Story = {\n\targs: {\n\t\tchildren: \"Custom styled\",\n\t\tclassName: \"custom-class\",\n\t},\n};\n",
+  "component/react/test.tsx.ejs": "import { describe, expect, it } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport <%= name %> from \"./<%= name %>.js\";\n\ndescribe(\"<%= name %>\", () => {\n\tit(\"renders children\", () => {\n\t\trender(<<%= name %>>Test content</<%= name %>>);\n\t\texpect(screen.getByText(\"Test content\")).toBeInTheDocument();\n\t});\n\n\tit(\"applies custom className\", () => {\n\t\trender(<<%= name %> className=\"custom-class\">Content</<%= name %>>);\n\t\tconst element = screen.getByText(\"Content\");\n\t\texpect(element.className).toContain(\"ds <%= kebabName %>\");\n\t\texpect(element.className).toContain(\"custom-class\");\n\t});\n\n\tit(\"passes through additional props\", () => {\n\t\trender(<<%= name %> data-testid=\"test-component\">Content</<%= name %>>);\n\t\texpect(screen.getByTestId(\"test-component\")).toBeInTheDocument();\n\t});\n});\n",
+  "component/react/types.ts.ejs": "import type { HTMLAttributes, ReactNode } from \"react\";\n\nexport interface <%= name %>Props extends HTMLAttributes<HTMLDivElement> {\n\t/** Content to render inside the component */\n\tchildren?: ReactNode;\n}\n",
+  "component/shared/styles.css.ejs": ".ds.<%= kebabName %> {\n\t/* Component styles */\n}\n",
+  "component/svelte/component.svelte.ejs": "<script lang=\"ts\">\n\timport type { <%= name %>Props } from \"./types.js\";\n<% if (withStyles) { -%>\n\timport \"./styles.css\";\n<% } -%>\n\n\tconst componentCssClassName = \"ds <%= kebabName %>\";\n\n\tlet {\n\t\tclass: className,\n\t\tchildren,\n\t\t...rest\n\t}: <%= name %>Props = $props();\n</script>\n\n<div\n\tclass={[componentCssClassName, className]}\n\t{...rest}\n>\n\t{@render children?.()}\n</div>\n",
+  "component/svelte/index.ts.ejs": "export { default as <%= name %> } from \"./<%= name %>.svelte\";\nexport type { <%= name %>Props } from \"./types.js\";\n",
+  "component/svelte/ssr.test.ts.ejs": "import { render } from \"@canonical/svelte-ssr-test\";\nimport type { RenderResult } from \"@canonical/svelte-ssr-test\";\nimport { createRawSnippet } from \"svelte\";\nimport type { ComponentProps } from \"svelte\";\nimport { describe, expect, it } from \"vitest\";\nimport Component from \"./<%= name %>.svelte\";\n\ndescribe(\"<%= name %> SSR\", () => {\n\tconst baseProps = {\n\t\tchildren: createRawSnippet(() => ({\n\t\t\trender: () => `<span><%= name %></span>`,\n\t\t})),\n\t} satisfies ComponentProps<typeof Component>;\n\n\tdescribe(\"basics\", () => {\n\t\tit(\"doesn't throw\", () => {\n\t\t\texpect(() => {\n\t\t\t\trender(Component, { props: { ...baseProps } });\n\t\t\t}).not.toThrow();\n\t\t});\n\n\t\tit(\"renders\", () => {\n\t\t\tconst page = render(Component, { props: { ...baseProps } });\n\t\t\texpect(componentLocator(page)).toBeInstanceOf(page.window.HTMLDivElement);\n\t\t});\n\t});\n\n\tdescribe(\"attributes\", () => {\n\t\tit.each([\n\t\t\t[\"id\", \"test-id\"],\n\t\t\t[\"aria-label\", \"test-aria-label\"],\n\t\t])(\"applies %s\", (attribute, expected) => {\n\t\t\tconst page = render(Component, {\n\t\t\t\tprops: { ...baseProps, [attribute]: expected },\n\t\t\t});\n\t\t\texpect(componentLocator(page).getAttribute(attribute)).toBe(expected);\n\t\t});\n\n\t\tit(\"applies classes\", () => {\n\t\t\tconst page = render(Component, {\n\t\t\t\tprops: { class: \"test-class\", ...baseProps },\n\t\t\t});\n\t\t\texpect(componentLocator(page).classList).toContain(\"test-class\");\n<% if (withStyles) { _%>\n\t\t\texpect(componentLocator(page).classList).toContain(\"ds\");\n\t\t\texpect(componentLocator(page).classList).toContain(\"<%= kebabName %>\");<% } %>\n\t\t});\n\n\t\tit(\"applies style\", () => {\n\t\t\tconst page = render(Component, {\n\t\t\t\tprops: { style: \"color: orange;\", ...baseProps },\n\t\t\t});\n\t\t\texpect(componentLocator(page).style.color).toBe(\"orange\");\n\t\t});\n\t});\n});\n\n// Note: Prefer role/semantics-oriented ways of selecting elements (e.g., by role, label, etc.) not only for component roots but for all elements to enhance accessibility and maintainability.\n// To select the component's root element, use one of the available [Queries](https://testing-library.com/docs/queries/about/#priority).\nfunction componentLocator(page: RenderResult): HTMLElement {\n\t// 1. SEMANTIC ROLES (PREFERRED) - These the most closely resemble how assistive technologies interact with your component\n\t// return page.getByRole(\"link\", { name: \"Learn more\" });\n\n\t// 2. LABELS - To test the association between labels and form controls\n\t// return page.getByLabelText(\"Email address\");\n\n\t// 3. PLACEHOLDER TEXT - Useful for input fields with placeholders\n\t// return page.getByPlaceholderText(\"Enter your email\");\n\n\t// 4. TEXT CONTENT - Good for testing the presence of unique texts and selecting non-interactive elements\n\t// return page.getByText(\"<%= name %>\");\n\n\t// 5. DISPLAY VALUE - For selecting form elements by their current value\n\t// return page.getByDisplayValue(\"test value\");\n\n\t// 6. ALT TEXT - For images and visual elements\n\t// return page.getByAltText(\"Company logo\");\n\n\t// 7. TITLE ATTRIBUTE - For elements with title tooltips\n\t// return page.getByTitle(\"Close dialog\");\n\n\t// 8. TEST IDS (LAST RESORT) - When semantic options aren't available\n\t// return page.getByTestId(\"<%= kebabName %>\");\n}\n",
+  "component/svelte/stories.svelte.ejs": "<script lang=\"ts\" module>\n\timport { defineMeta } from \"@storybook/addon-svelte-csf\";\n\timport <%= name %> from \"./<%= name %>.svelte\";\n\n\tconst { Story } = defineMeta({\n\t\ttitle: \"Components/<%= name %>\",\n\t\tcomponent: <%= name %>,\n\t\ttags: [\"autodocs\"],\n\t});\n</script>\n\n<Story name=\"Default\">\n\tHello, <%= name %>!\n</Story>\n\n<Story\n  name=\"WithCustomClass\"\n  args={{\n    class: \"custom-class\",\n    id: \"custom-id\",\n    style: \"background-color: tomato;\",\n  }}\n>\n\tCustom styled\n</Story>\n",
+  "component/svelte/stories.ts.ejs": "import type { Meta, StoryObj } from \"@storybook/svelte\";\nimport <%= name %> from \"./<%= name %>.svelte\";\n\nconst meta: Meta<typeof <%= name %>> = {\n\ttitle: \"Components/<%= name %>\",\n\tcomponent: <%= name %>,\n\ttags: [\"autodocs\"],\n};\n\nexport default meta;\ntype Story = StoryObj<typeof <%= name %>>;\n\nexport const Default: Story = {};\n\nexport const WithCustomClass: Story = {\n\targs: {\n\t\tclass: \"custom-class\",\n\t},\n};\n",
+  "component/svelte/test.ts.ejs": "import type { Locator } from \"@vitest/browser/context\";\nimport { createRawSnippet } from \"svelte\";\nimport type { ComponentProps } from \"svelte\";\nimport { describe, expect, it } from \"vitest\";\nimport { render } from \"vitest-browser-svelte\";\nimport type { RenderResult } from \"vitest-browser-svelte\";\nimport Component from \"./<%= name %>.svelte\";\n\ndescribe(\"<%= name %> component\", () => {\n\tconst baseProps = {\n\t\tchildren: createRawSnippet(() => ({\n\t\t\trender: () => `<span><%= name %></span>`,\n\t\t})),\n\t} satisfies ComponentProps<typeof Component>;\n\n\tit(\"renders\", async () => {\n\t\tconst page = render(Component, { ...baseProps });\n\t\tawait expect.element(componentLocator(page)).toBeInTheDocument();\n\t\tawait expect.element(page.getByText(\"<%= name %>\")).toBeVisible();\n\t});\n\n\tdescribe(\"attributes\", () => {\n\t\tit.each([\n\t\t\t[\"id\", \"test-id\"],\n\t\t\t[\"aria-label\", \"test-aria-label\"],\n\t\t])(\"applies %s\", async (attribute, expected) => {\n\t\t\tconst page = render(Component, { ...baseProps, [attribute]: expected });\n\t\t\tawait expect\n\t\t\t\t.element(componentLocator(page))\n\t\t\t\t.toHaveAttribute(attribute, expected);\n\t\t});\n\n\t\tit(\"applies classes\", async () => {\n\t\t\tconst page = render(Component, { ...baseProps, class: \"test-class\" });\n\t\t\tawait expect.element(componentLocator(page)).toHaveClass(\"test-class\");\n<% if (withStyles) { _%>\n\t\t\tawait expect.element(componentLocator(page)).toHaveClass(\"ds\");\n\t\t\tawait expect\n\t\t\t\t.element(componentLocator(page))\n\t\t\t\t.toHaveClass(\"<%= kebabName %>\");<% } %>\n\t\t});\n\n\t\tit(\"applies style\", async () => {\n\t\t\tconst page = render(Component, {\n\t\t\t\t...baseProps,\n\t\t\t\tstyle: \"color: orange;\",\n\t\t\t});\n\t\t\tawait expect\n\t\t\t\t.element(componentLocator(page))\n\t\t\t\t.toHaveStyle({ color: \"orange\" });\n\t\t});\n\t});\n});\n\n// Note: Prefer role/semantics-oriented ways of selecting elements (e.g., by role, label, etc.) not only for component roots but for all elements to enhance accessibility and maintainability.\n// To select the component's root element, use one of the available [Locators](https://vitest.dev/guide/browser/locators.html).\nfunction componentLocator(page: RenderResult<typeof Component>): Locator {\n\t// 1. SEMANTIC ROLES (PREFERRED) - These the most closely resemble how assistive technologies interact with your component\n\t// return page.getByRole(\"link\", { name: \"Learn more\" });\n\n\t// 2. LABELS - To test the association between labels and form controls\n\t// return page.getByLabel(\"Email address\");\n\n\t// 3. PLACEHOLDER TEXT - Useful for input fields with placeholders\n\t// return page.getByPlaceholder(\"Enter your email\");\n\n\t// 4. TEXT CONTENT - Good for testing the presence of unique texts and selecting non-interactive elements\n\t// return page.getByText(\"<%= name %>\");\n\n\t// 5. ALT TEXT - For images and visual elements\n\t// return page.getByAltText(\"Company logo\");\n\n\t// 6. TITLE ATTRIBUTE - For elements with title tooltips\n\t// return page.getByTitle(\"Close dialog\");\n\n\t// 7. TEST IDS (LAST RESORT) - When semantic options aren't available\n\t// return page.getByTestId(\"<%= kebabName %>\");\n}\n",
+  "component/svelte/types.ts.ejs": "import type { Snippet } from \"svelte\";\nimport type { SvelteHTMLElements } from \"svelte/elements\";\n\n/*\n\tFor components that render specific HTML elements with extended prop sets,\n\tmake sure to change `\"div\"` to the appropriate HTML element type.\n*/\ntype BaseProps = SvelteHTMLElements[\"div\"];\n\nexport interface <%= name %>Props extends BaseProps {\n\t/** Content to render inside the component */\n\tchildren?: Snippet;\n\t// Define additional props specific to <%= name %> here\n}\n\n/*\n\t...or consider using appropriate interfaces directly exported from `svelte/elements`.\n\n\tFor example:\n\t- `HTMLButtonAttributes` (provides `disabled`, `type`, etc.)\n\t- `HTMLAnchorAttributes` (provides `href`, `target`, etc.)\n\t- `HTMLInputAttributes` (provides `type`, `checked`, `value`, etc.)\n\t- `HTMLFormAttributes` (provides `action`, `method`, etc.)\n\n\t```typescript\n\timport type { HTMLButtonAttributes } from \"svelte/elements\";\n\n\texport interface MyButtonProps extends HTMLButtonAttributes {\n\t\t// Your custom props here\n\t}\n\t```\n\n\tSee Svelte documentation on typing wrapper components:\n\thttps://svelte.dev/docs/svelte/typescript#Typing-wrapper-components\n*/\n",
+  "package/PULL_REQUEST_TEMPLATE.md.ejs": "## Summary\n\n[What this PR does and why]\n\n## QA\n\n- [Add QA steps]\n\n### Checklist\n\n- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format\n- [ ] Code follows the [code standards](https://github.com/canonical/web-code-standards)\n- [ ] `check`, `test` pass locally\n",
+  "package/README.md.ejs": "# <%= name %>\n\n<%= description || 'TODO: Add description' %>\n\n## Installation\n\n```bash\nbun add <%= name %>\n```\n\n## Usage\n\n```typescript\nimport { } from \"<%= name %>\";\n```\n\n## Development\n\n```bash\n# Run checks\nbun run check\n\n# Run tests\nbun run test\n```\n\n## License\n\n<%= license %>\n",
+  "package/biome.json.ejs": "{\n  \"extends\": [\"@canonical/biome-config\"],\n  \"files\": {\n    \"includes\": [\"src\", \"*.json\"]\n  }\n}\n",
+  "package/cli.ts.ejs": "#!/usr/bin/env bun\n/**\n * <%= name %> CLI\n *\n * <%= description || 'TODO: Add description' %>\n */\n\nconsole.log(\"Hello from <%= shortName %>!\");\n",
+  "package/index.css.ejs": "/**\n * <%= name %>\n *\n * <%= description || 'TODO: Add description' %>\n */\n",
+  "package/index.ts.ejs": "/**\n * <%= name %>\n *\n * <%= description || 'TODO: Add description' %>\n */\n\nexport {};\n",
+  "package/package.json.ejs": "{\n  \"name\": \"<%= name %>\",\n  \"description\": \"<%= description %>\",\n  \"version\": \"<%= version %>\",\n  \"type\": \"module\",\n<% if (type === 'tool-ts') { -%>\n  \"module\": \"src/index.ts\",\n  \"types\": \"src/index.ts\",\n<% } else if (type === 'css') { -%>\n  \"module\": \"src/index.css\",\n<% } else { -%>\n  \"module\": \"dist/esm/index.js\",\n  \"types\": \"dist/types/index.d.ts\",\n<% } -%>\n<% if (withCli && type !== 'css') { -%>\n  \"bin\": {\n    \"<%= shortName %>\": \"src/cli.ts\"\n  },\n<% } -%>\n  \"files\": [\n<% if (type === 'tool-ts' || type === 'css') { -%>\n    \"src\"\n<% } else { -%>\n    \"dist\"\n<% } -%>\n  ],\n  \"author\": {\n    \"email\": \"webteam@canonical.com\",\n    \"name\": \"Canonical Webteam\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/canonical/pragma\"\n  },\n  \"license\": \"<%= license %>\",\n  \"bugs\": {\n    \"url\": \"https://github.com/canonical/pragma/issues\"\n  },\n  \"homepage\": \"https://github.com/canonical/pragma#readme\",\n  \"scripts\": {\n<% if (type === 'tool-ts' || type === 'css') { -%>\n    \"build\": \"echo 'No build needed'\",\n<% } else { -%>\n    \"build\": \"tsc -p tsconfig.build.json\",\n<% } -%>\n<% if (withStorybook) { -%>\n    \"build:all\": \"bun run build && bun run build:storybook\",\n    \"build:storybook\": \"storybook build\",\n<% } else { -%>\n    \"build:all\": \"bun run build\",\n<% } -%>\n<% if (type === 'css') { -%>\n    \"check\": \"bun run check:biome && bun run check:webarchitect\",\n    \"check:fix\": \"bun run check:biome:fix\",\n<% } else { -%>\n    \"check\": \"bun run check:biome && bun run check:ts && bun run check:webarchitect\",\n    \"check:fix\": \"bun run check:biome:fix && bun run check:ts\",\n<% } -%>\n    \"check:biome\": \"biome check\",\n    \"check:biome:fix\": \"biome check --write\",\n<% if (type !== 'css') { -%>\n    \"check:ts\": \"tsc --noEmit\",\n<% } -%>\n    \"check:webarchitect\": \"webarchitect <%= ruleset %>\",\n<% if (withStorybook) { -%>\n    \"storybook\": \"storybook dev -p 6006 --no-open --host 0.0.0.0\",\n<% } -%>\n<% if (type === 'css') { -%>\n    \"test\": \"echo 'No tests for CSS package'\"\n<% } else { -%>\n    \"test\": \"vitest run\"\n<% } -%>\n  },\n<% if (type !== 'css') { -%>\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"2.4.6\",\n    \"@canonical/biome-config\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% if (withReact) { -%>\n    \"@canonical/typescript-config-react\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% } else { -%>\n    \"@canonical/typescript-config\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% } -%>\n<% if (withStorybook) { -%>\n    \"@chromatic-com/storybook\": \"^5.0.0\",\n<% } -%>\n<% if (withReact) { -%>\n    \"@types/react\": \"^19.0.0\",\n    \"@types/react-dom\": \"^19.0.0\",\n<% } -%>\n    \"bun-types\": \"^1.0.0\",\n<% if (withStorybook) { -%>\n    \"storybook\": \"^10.1.11\",\n<% } -%>\n    \"typescript\": \"^5.9.3\",\n    \"vitest\": \"^3.2.4\"\n  },\n  \"dependencies\": {\n<% if (withStorybook) { -%>\n    \"@canonical/storybook-config\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% } -%>\n<% if (withReact) { -%>\n    \"react\": \"^19.0.0\",\n    \"react-dom\": \"^19.0.0\"\n<% } -%>\n  }\n<% } else { -%>\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"2.4.6\",\n    \"@canonical/biome-config\": \"^<%= monorepoVersion || '0.1.0' %>\"\n  }\n<% } -%>\n}\n",
+  "package/storybook-main.ts.ejs": "import { createConfig } from \"@canonical/storybook-config\";\n\nexport default createConfig(\"react\", {\n  staticDirs: [\"../src/assets\", \"../public\"],\n});\n",
+  "package/storybook-preview.ts.ejs": "import { withThemeByClassName } from \"@storybook/addon-themes\";\nimport type { Preview, ReactRenderer } from \"@storybook/react-vite\";\n\nimport \"index.css\";\nimport \"@canonical/styles-debug/baseline-grid\";\n\nconst preview: Preview = {\n  tags: [\"autodocs\"],\n  decorators: [\n    withThemeByClassName<ReactRenderer>({\n      themes: {\n        light: \"is-light\",\n        dark: \"dark\",\n        paper: \"is-paper\",\n      },\n      defaultTheme: \"light\",\n    }),\n  ],\n  parameters: {\n    docs: {\n      codePanel: true,\n    },\n  },\n};\n\nexport default preview;\n",
+  "package/tsconfig-react.json.ejs": "{\n  \"extends\": \"@canonical/typescript-config-react\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"src\",\n    \"types\": [\"bun-types\"]\n  },\n  \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\"]\n}\n",
+  "package/tsconfig.json.ejs": "{\n  \"extends\": \"@canonical/typescript-config\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"src\",\n    \"types\": [\"bun-types\"]\n  },\n  \"include\": [\"src/**/*.ts\"]\n}\n",
+};

package/src/capabilities/create/types.ts

@@ -0,0 +1,8 @@
+/**
+ * Create-capability types with NO summon-core / generator import, so a module
+ * that only needs `CreateKind` (e.g. `create.verb`) does not drag
+ * `pickGenerator` — and its heavy generator imports — into the static graph.
+ */
+
+/** The three `create` nouns (path capped at two segments). */
+export type CreateKind = "component" | "package" | "application";

package/src/capabilities/doctor/checks/checkConfigFile.ts

@@ -0,0 +1,41 @@
+import { readConfig } from "../../../kernel/config/readConfig.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Check which config layer is active for the working directory.
+ *
+ * Passes when a project `pragma.config.ts` is found up the tree, or — pragma is
+ * global-first — when only the global XDG config exists. Fails only when
+ * neither layer is configured.
+ *
+ * @param rt - The per-invocation runtime (for `cwd`).
+ * @returns A CheckResult indicating the active layer, or fail with a remedy.
+ * @note Impure — reads the config layers from disk.
+ */
+export async function checkConfigFile(rt: PragmaRuntime): Promise<CheckResult> {
+  const layers = await readConfig(rt.cwd);
+
+  if (layers.project.exists) {
+    return {
+      name: "pragma config",
+      status: "pass",
+      detail: `project config active (${layers.project.path})`,
+    };
+  }
+
+  if (layers.global.exists) {
+    return {
+      name: "pragma config",
+      status: "pass",
+      detail: `no project config — global config active (${layers.global.path})`,
+    };
+  }
+
+  return {
+    name: "pragma config",
+    status: "fail",
+    detail: "not found",
+    remedy: "pragma config set tier <path>",
+  };
+}

package/src/capabilities/doctor/checks/checkKeStore.ts

@@ -0,0 +1,39 @@
+import { entityTotal } from "../../../kernel/completion/entitySource.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Check that the ke store boots, reporting the entity total and boot time.
+ *
+ * This is the ONE check that touches the store — it boots the shared lazy store
+ * inside a try/catch, so doctor stays storeless-by-default at the dispatch level
+ * (the verb declares `needsStore: false`; only this check pays the boot, only
+ * when reached). On success it reads the entity total from the session's
+ * storeless index rather than a fresh triple COUNT — cheaper, and the store is
+ * already booted.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns A CheckResult: pass with the entity total, or fail with a remedy.
+ * @note Impure — boots the store.
+ */
+export async function checkKeStore(rt: PragmaRuntime): Promise<CheckResult> {
+  const start = performance.now();
+  try {
+    const session = await rt.store.get();
+    const total = entityTotal(session.index);
+    const elapsed = Math.round(performance.now() - start);
+    return {
+      name: "ke store",
+      status: "pass",
+      detail: `${total.toLocaleString()} entities in ${elapsed}ms`,
+    };
+  } catch {
+    return {
+      name: "ke store",
+      status: "fail",
+      detail: "failed to boot",
+      remedy:
+        "Ensure design-system packages are installed and run `pragma sources update`.",
+    };
+  }
+}