@canonical/summon-application 0.29.0-experimental.0

package/README.md

@@ -0,0 +1,264 @@
+# @canonical/summon-application
+
+Summon generators for scaffolding application structure: full applications, domains, routes, and wrappers. Produces code aligned with the [boilerplate reference app](../../../apps/react/boilerplate-vite/).
+
+## Generators
+
+### `summon application/react <name>`
+
+Scaffolds a complete React application with SSR, routing, Storybook, and two starter domains.
+
+```bash
+summon application/react my-app
+summon application/react --forms my-app
+```
+
+Produces:
+
+```
+my-app/
+├── .storybook/
+│   ├── main.ts
+│   ├── preview.ts
+│   └── decorators/
+│       ├── withRouter.tsx    # Hash-based router decorator
+│       └── index.ts
+├── src/
+│   ├── client/entry.tsx      # Client hydration
+│   ├── server/
+│   │   ├── entry.tsx         # SSR render
+│   │   ├── server.express.ts # Express dev server
+│   │   ├── server.bun.ts     # Bun dev server
+│   │   └── sitemap.ts
+│   ├── domains/
+│   │   ├── marketing/        # HomePage, GuidePage, routes
+│   │   ├── account/          # AccountPage, LoginPage, routes
+│   │   └── contact/          # ContactPage, routes (--forms only)
+│   ├── lib/
+│   │   ├── Navigation/
+│   │   ├── ThemeSelector/
+│   │   ├── ExampleComponent/
+│   │   └── LazyComponent/
+│   ├── styles/
+│   ├── routes.tsx
+│   └── vite-env.d.ts
+├── biome.json
+├── index.html
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+The `--forms` flag adds the contact domain with form components and wires `contactRoutes` into `routes.tsx`.
+
+### `summon domain <name>`
+
+Creates a domain folder under `src/domains/` with a `MainPage` and a `routes.ts` barrel.
+
+```bash
+summon domain billing
+```
+
+Produces:
+
+```
+src/domains/billing/
+├── MainPage.tsx    # Page component with useHead()
+└── routes.ts       # Route barrel with example route entry
+```
+
+After generating, import the domain routes in `src/routes.tsx` and wire them with `group()`:
+
+```tsx
+import billingRoutes from "#domains/billing/routes.js";
+
+const [billing] = group(publicLayout, [billingRoutes.billing] as const);
+```
+
+### `summon route <domain>/<name>`
+
+Adds a page component to an existing domain and appends the import to its `routes.ts`.
+
+```bash
+summon route billing/invoices
+```
+
+Produces:
+
+```
+src/domains/billing/
+├── InvoicesPage.tsx   # New page component
+└── routes.ts          # Import + TODO comment appended
+```
+
+The generator appends the import and a comment with the route entry. Add the route to the `routes` object manually:
+
+```ts
+invoices: route({ url: "/billing/invoices", content: InvoicesPage }),
+```
+
+Create the domain first with `summon domain <name>`.
+
+### `summon wrapper <name>`
+
+Creates a layout wrapper component under `src/lib/`.
+
+```bash
+summon wrapper sidebar
+```
+
+Produces:
+
+```
+src/lib/SidebarLayout/
+├── SidebarLayout.tsx   # Layout component with children prop
+└── index.ts            # Barrel export
+```
+
+Use the layout component in a `wrapper()` call in `routes.tsx`:
+
+```tsx
+import SidebarLayout from "#lib/SidebarLayout/index.js";
+
+const sidebarWrapper = wrapper({
+  id: "sidebar",
+  component: ({ children }) => <SidebarLayout>{children}</SidebarLayout>,
+});
+```
+
+## Conventions
+
+The generators enforce the conventions established by the boilerplate:
+
+### File structure
+
+```
+src/
+├── client/                 # Client entry point (hydration)
+├── server/                 # Server entry points (Express, Bun)
+├── domains/                # Feature domains
+│   ├── marketing/
+│   │   ├── HomePage.tsx
+│   │   ├── GuidePage.tsx
+│   │   └── routes.ts
+│   ├── account/
+│   │   ├── AccountPage.tsx
+│   │   ├── LoginPage.tsx
+│   │   └── routes.ts
+│   └── contact/            # When --forms is enabled
+│       ├── ContactPage.tsx
+│       └── routes.ts
+├── lib/                    # Shared components
+│   ├── Navigation/
+│   └── SidebarLayout/
+├── styles/                 # CSS
+└── routes.tsx              # Root route map, middleware, type registration
+```
+
+### Naming
+
+| Concept | Pattern | Example |
+|---------|---------|---------|
+| Page component | `{Name}Page.tsx` | `SettingsPage.tsx` |
+| Layout component | `{Name}Layout.tsx` | `SidebarLayout.tsx` |
+| Domain routes | `routes.ts` (not `.tsx`) | `src/domains/billing/routes.ts` |
+| Root routes | `routes.tsx` | `src/routes.tsx` |
+| Component folders | PascalCase | `src/lib/SidebarLayout/` |
+
+### Route definitions
+
+Routes are flat objects using `route()` from `@canonical/router-core`:
+
+```ts
+const routes = {
+  invoices: route({
+    url: "/billing/invoices",
+    content: InvoicesPage,
+  }),
+} as const;
+
+export default routes;
+```
+
+- `content` receives the component directly (not a wrapper function)
+- Pages use `useHead()` from `@canonical/react-head` for title and meta
+- No `fetch()` / `prefetch()` unless needed for cache warming
+- No `.error` — use React error boundaries
+- Route files are `.ts` (no JSX in route definitions)
+
+### Storybook decorators
+
+The generated application includes a `withRouter` decorator for stories that need a router context:
+
+```tsx
+import withRouter from "../decorators/withRouter.js";
+
+const meta = {
+  decorators: [withRouter()],
+} satisfies Meta;
+```
+
+Pass custom routes when the story depends on specific route shapes:
+
+```tsx
+import { appRoutes } from "../../routes.js";
+
+const meta = {
+  decorators: [withRouter({ routes: appRoutes })],
+} satisfies Meta;
+```
+
+The decorator uses `createHashRouter` from `@canonical/router-core`, which stores routes in `window.location.hash` — suitable for Storybook and static environments where no server handles URL paths.
+
+### Wrappers
+
+Wrapper components are standard React components with a `children` prop. They become routable wrappers via `wrapper()` + `group()` in `routes.tsx`:
+
+```tsx
+const layout = wrapper({
+  id: "sidebar",
+  component: ({ children }) => <SidebarLayout>{children}</SidebarLayout>,
+});
+
+const [invoices, payments] = group(layout, [
+  billingRoutes.invoices,
+  billingRoutes.payments,
+] as const);
+```
+
+### Type registration
+
+Register routes once in `routes.tsx` for global type inference:
+
+```tsx
+declare module "@canonical/router-react" {
+  interface RouterRegister {
+    routes: typeof appRoutes;
+  }
+}
+```
+
+This enables typed `<Link to="invoices">`, `router.navigate("invoices")`, and `router.buildPath("invoices")`.
+
+## Open questions
+
+Design decisions about the generated output that are not yet settled:
+
+- **Pinned pragma version is a hand-maintained constant.** Generated apps pin the pragma
+  workspace packages (`react-ds-global`, `router-core`, `styles`, …) at the range in
+  `PRAGMA_WORKSPACE_VERSION` (`src/shared/versions.ts`), which must be bumped in lockstep
+  with each lerna release. It is a literal constant, not read from a package.json at runtime,
+  because the generator ships as a compiled binary where such a read resolves to `"unknown"`.
+  **Open:** inject the version at binary-build time (a build-step `define`/codegen) so it
+  cannot drift from the release — deferred until the compile pipeline supports it, to avoid
+  adding build tooling prematurely. Note `@canonical/design-tokens` is versioned separately
+  and is *not* covered by this constant (it arrives transitively via `@canonical/styles`).
+
+- **Two static-asset folders (`src/assets/` + `public/`).** The generated app ships both,
+  and `.storybook/main.ts` lists `staticDirs: ["../src/assets", "../public"]` to match the
+  `@canonical/react-ds-global` convention. The two serve different roles under Vite —
+  `src/assets/` for assets *imported in code* (hashed/optimized, dropped if unused), `public/`
+  for files referenced by fixed URL (favicon, `robots.txt`, served as-is, unhashed). **Open:**
+  whether a scaffolded app genuinely needs both by default, or whether one (likely just
+  `public/` for a favicon) is enough and `src/assets/` should be added only when the app
+  actually imports an asset. Currently both ship with `.gitkeep` placeholders.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@canonical/summon-application",
+  "description": "Summon generators for application scaffolding: domain, route, and wrapper",
+  "version": "0.29.0-experimental.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "author": {
+    "email": "webteam@canonical.com",
+    "name": "Canonical Webteam"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/canonical/pragma"
+  },
+  "license": "GPL-3.0",
+  "scripts": {
+    "build": "echo 'No build needed - runs directly from TypeScript'",
+    "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
+    "check:webarchitect": "webarchitect tool-ts",
+    "check:fix": "bun run check:biome:fix && bun run check:ts",
+    "check:biome": "biome check",
+    "check:biome:fix": "biome check --write",
+    "check:ts": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@canonical/summon-core": "^0.29.0-experimental.0",
+    "@canonical/task": "^0.29.0-experimental.0",
+    "@canonical/utils": "^0.29.0-experimental.0",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@canonical/biome-config": "^0.28.0",
+    "@canonical/webarchitect": "^0.29.0-experimental.0",
+    "@types/node": "^24.12.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/application/react/index.ts

@@ -0,0 +1,294 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  GeneratorDefinition,
+  PromptDefinition,
+} from "@canonical/summon-core";
+import { template, withHelpers } from "@canonical/summon-core";
+import {
+  copyFile,
+  exec,
+  exists,
+  flatMap,
+  info,
+  sequence_,
+  warn,
+  when,
+} from "@canonical/task";
+import { PRAGMA_WORKSPACE_VERSION } from "../../shared/versions.js";
+
+interface ApplicationReactAnswers {
+  readonly appPath: string;
+  readonly ssr: boolean;
+  readonly router: boolean;
+  readonly forms: boolean;
+  readonly runInstall: boolean;
+}
+
+const prompts: PromptDefinition[] = [
+  {
+    name: "appPath",
+    type: "text",
+    message: "Application directory name:",
+    default: "my-app",
+    positional: true,
+    group: "Application",
+  },
+  {
+    name: "ssr",
+    type: "confirm",
+    message: "Include SSR?",
+    default: true,
+    group: "Application",
+  },
+  {
+    name: "router",
+    type: "confirm",
+    message: "Include router?",
+    default: true,
+    group: "Application",
+  },
+  {
+    name: "forms",
+    type: "confirm",
+    message: "Include form components?",
+    default: true,
+    group: "Application",
+  },
+  {
+    name: "runInstall",
+    type: "confirm",
+    message: "Run bun install?",
+    default: true,
+    group: "Application",
+  },
+];
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(__dirname, "templates");
+
+/** Resolve a path inside the templates directory. */
+const src = (templatePath: string) => path.join(templatesDir, templatePath);
+
+export const generator: GeneratorDefinition<ApplicationReactAnswers> = {
+  meta: {
+    name: "application/react",
+    displayName: "@canonical/summon-application:application/react",
+    description: "Scaffold a complete React application with SSR and routing",
+    version: "0.1.0",
+    help: `Creates a full React application with:
+  - Vite build + dev server
+  - Server-side rendering (Express + Bun dev servers)
+  - Routing with @canonical/router-core
+  - Head management with @canonical/react-head
+  - Two domains (marketing + account) with pages
+  - Contact domain with form components (when --forms is enabled)
+  - Navigation, ThemeSelector, ExampleComponent
+  - Storybook with router decorator
+  - Biome + TypeScript configuration
+
+Requires both --ssr and --router flags.`,
+    examples: [
+      "summon application/react my-app",
+      "summon application/react --forms my-app",
+      "summon application/react --ssr --router --forms my-app",
+    ],
+  },
+
+  prompts,
+
+  generate: (answers) => {
+    if (!answers.ssr || !answers.router) {
+      throw new Error(
+        "The application/react generator requires both --ssr and --router. " +
+          "Standalone SPA mode is not supported.",
+      );
+    }
+
+    // The app path is a directory path, not a route path — keep it as given
+    // (absolute or relative), only trimming surrounding whitespace and any
+    // trailing slash.
+    const appPath =
+      (answers.appPath || "my-app").trim().replace(/\/+$/, "") || "my-app";
+
+    // The package name is the final path segment. For "." / "" / "/" (scaffold
+    // into the current dir) basename gives "."/"" — resolve against the real
+    // directory so the name is the actual folder name. Then slugify to an
+    // npm-safe form (lowercase, safe chars).
+    const rawName = path.basename(path.resolve(appPath));
+    const name = rawName
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^[._-]+|[._-]+$/g, "");
+
+    if (!name) {
+      throw new Error(
+        `Could not derive a valid application name from path "${appPath}". ` +
+          "Pass an explicit directory name (lowercase letters/digits).",
+      );
+    }
+
+    const vars = withHelpers({
+      name,
+      forms: answers.forms,
+      pragmaVersion: PRAGMA_WORKSPACE_VERSION,
+    });
+    const dest = (...segments: string[]) => path.join(appPath, ...segments);
+    const copy = (filePath: string) => copyFile(src(filePath), dest(filePath));
+
+    return sequence_([
+      // Warn (don't block) if the destination already exists — scaffolding
+      // will overwrite files in place.
+      flatMap(exists(appPath), (present) =>
+        when(
+          present,
+          warn(
+            `"${appPath}" already exists — existing files may be overwritten.`,
+          ),
+        ),
+      ),
+      info(`Scaffolding React application in "${appPath}"...`),
+
+      // EJS templates (files needing interpolation)
+      template({
+        source: src("package.json.ejs"),
+        dest: dest("package.json"),
+        vars,
+      }),
+      template({ source: src("README.md.ejs"), dest: dest("README.md"), vars }),
+      template({
+        source: src("biome.json.ejs"),
+        dest: dest("biome.json"),
+        vars,
+      }),
+
+      // Root config
+      copy("tsconfig.json"),
+      copy("vite.config.ts"),
+      copy("vitest.config.ts"),
+      copy("vitest.setup.ts"),
+      copy("vitest.e2e.config.ts"),
+      // index.html (EJS — <title> uses the app name)
+      template({
+        source: src("index.html.ejs"),
+        dest: dest("index.html"),
+        vars,
+      }),
+      copy(".gitignore"),
+
+      // E2e tests (the 2×3 server matrix + its spawn/teardown harness)
+      copy("test/e2e/serverHarness.ts"),
+      copy("test/e2e/servers.e2e.ts"),
+
+      // Styles
+      // styles (EJS — form stylesheet imported only when --forms)
+      template({
+        source: src("src/styles/index.css.ejs"),
+        dest: dest("src/styles/index.css"),
+        vars,
+      }),
+      copy("src/styles/app.css"),
+
+      // Client
+      copy("src/client/entry.tsx"),
+
+      // Server — dev (Vite + HMR) and preview (compiled) servers each route
+      // between the app + sitemap renderers; the renderers stay routing-agnostic.
+      copy("src/server/entry.tsx"),
+      copy("src/server/renderer.tsx"),
+      copy("src/server/server.express.ts"),
+      copy("src/server/server.bun.ts"),
+      copy("src/server/preview.express.ts"),
+      copy("src/server/preview.bun.ts"),
+
+      // Sitemap (rendered route at /sitemap.xml)
+      copy("src/sitemap/renderer.ts"),
+      // sitemap getters (EJS — /contact entry only when --forms)
+      template({
+        source: src("src/sitemap/getSitemapItems.ts.ejs"),
+        dest: dest("src/sitemap/getSitemapItems.ts"),
+        vars,
+      }),
+
+      // Domain: marketing
+      copy("src/domains/marketing/HomePage.tsx"),
+      copy("src/domains/marketing/GuidePage.tsx"),
+      copy("src/domains/marketing/routes.ts"),
+
+      // Domain: account
+      copy("src/domains/account/AccountPage.tsx"),
+      copy("src/domains/account/LoginPage.tsx"),
+      copy("src/domains/account/routes.ts"),
+
+      // Domain: contact (when --forms is enabled)
+      when(answers.forms, copy("src/domains/contact/ContactPage.tsx")),
+      when(answers.forms, copy("src/domains/contact/routes.ts")),
+
+      // Routes (EJS — conditionally includes contact domain)
+      template({
+        source: src("src/routes.tsx.ejs"),
+        dest: dest("src/routes.tsx"),
+        vars,
+      }),
+
+      // Lib: Navigation (EJS — contact link only when --forms)
+      template({
+        source: src("src/lib/Navigation/Navigation.tsx.ejs"),
+        dest: dest("src/lib/Navigation/Navigation.tsx"),
+        vars,
+      }),
+      copy("src/lib/Navigation/index.ts"),
+
+      // Lib: ThemeSelector
+      copy("src/lib/ThemeSelector/ThemeSelector.tsx"),
+      copy("src/lib/ThemeSelector/index.ts"),
+
+      // Lib: ExampleComponent
+      copy("src/lib/ExampleComponent/ExampleComponent.tsx"),
+      copy("src/lib/ExampleComponent/ExampleComponent.stories.tsx"),
+      copy("src/lib/ExampleComponent/ExampleComponent.tests.tsx"),
+      copy("src/lib/ExampleComponent/index.ts"),
+      copy("src/lib/ExampleComponent/types.ts"),
+      copy("src/lib/ExampleComponent/styles.css"),
+
+      // Lib: LazyComponent
+      copy("src/lib/LazyComponent/LazyComponent.tsx"),
+      copy("src/lib/LazyComponent/LazyComponent.stories.tsx"),
+      copy("src/lib/LazyComponent/index.ts"),
+
+      // Lib barrel
+      copy("src/lib/index.ts"),
+
+      // Vite types
+      copy("src/vite-env.d.ts"),
+
+      // Storybook
+      copy(".storybook/main.ts"),
+      copy(".storybook/preview.ts"),
+      copy(".storybook/decorators/withRouter.tsx"),
+      copy(".storybook/decorators/index.ts"),
+
+      // Static asset dirs (kept by placeholder; both wired into Storybook staticDirs)
+      copy("src/assets/.gitkeep"),
+      copy("public/.gitkeep"),
+      copy("public/robots.txt"),
+
+      // Install dependencies
+      when(
+        answers.runInstall,
+        sequence_([
+          info("Installing dependencies..."),
+          exec("bun", ["install"], appPath),
+        ]),
+      ),
+
+      info(
+        answers.runInstall
+          ? `Application "${appPath}" created. Run \`cd ${appPath} && bun run dev\` to start.`
+          : `Application "${appPath}" created. Run \`cd ${appPath} && bun install && bun run dev\` to start.`,
+      ),
+    ]);
+  },
+};
+
+export default generator;

package/src/application/react/templates/.storybook/decorators/index.ts

@@ -0,0 +1 @@
+export { default as withRouter } from "./withRouter.js";

package/src/application/react/templates/.storybook/decorators/withRouter.tsx

@@ -0,0 +1,44 @@
+import { HeadProvider } from "@canonical/react-head";
+import { createHashRouter, type RouteMap, route } from "@canonical/router-core";
+import { Outlet, RouterProvider } from "@canonical/router-react";
+import type { ElementType } from "react";
+
+const defaultRoutes = {
+  story: route({
+    url: "/",
+    content: () => null,
+  }),
+} as const;
+
+interface WithRouterOptions {
+  readonly routes?: RouteMap;
+}
+
+/**
+ * Storybook decorator that wraps stories in a router context.
+ *
+ * Uses a hash router so visual tests can navigate without a real server.
+ * Pass custom routes to test components that depend on specific route shapes.
+ *
+ * @example
+ * ```ts
+ * decorators: [withRouter()]
+ * decorators: [withRouter({ routes: appRoutes })]
+ * ```
+ */
+const withRouter =
+  ({ routes = defaultRoutes }: WithRouterOptions = {}) =>
+  (Story: ElementType) => {
+    const router = createHashRouter(routes);
+
+    return (
+      <HeadProvider>
+        <RouterProvider router={router}>
+          <Story />
+          <Outlet />
+        </RouterProvider>
+      </HeadProvider>
+    );
+  };
+
+export default withRouter;

package/src/application/react/templates/.storybook/main.ts

@@ -0,0 +1,5 @@
+import { createConfig } from "@canonical/storybook-config";
+
+export default createConfig("react", {
+  staticDirs: ["../src/assets", "../public"],
+});

package/src/application/react/templates/.storybook/preview.ts

@@ -0,0 +1,10 @@
+import previewConfig from "@canonical/storybook-config/preview";
+import type { Preview } from "@storybook/react-vite";
+
+import "../src/styles/index.css";
+
+const preview: Preview = {
+  ...previewConfig,
+};
+
+export default preview;