@canonical/summon-application 0.29.0-experimental.0

package/src/application/react/templates/src/sitemap/renderer.ts

@@ -0,0 +1,40 @@
+/**
+ * Sitemap renderer for the `/sitemap.xml` route.
+ *
+ * Builds a `SitemapRenderer` from the route getters (`getSitemapItems`) and the
+ * site's canonical base URL. Each server entrypoint dispatches `GET /sitemap.xml`
+ * to this factory; every other path falls through to the JSX app renderer. The
+ * sitemap and app renderers know nothing about each other — the server picks
+ * between them. Set `BASE_URL` (e.g. `https://example.com`) in production so
+ * relative `loc` values resolve to absolute, crawlable URLs.
+ */
+import { SitemapRenderer } from "@canonical/react-ssr/renderer";
+import getSitemapItems from "./getSitemapItems.js";
+
+/** True only for an absolute URL — the sitemap base must be one (relative `loc`
+ * values are resolved against it). Guards against an empty or relative
+ * `BASE_URL` (e.g. the `"/"` some tooling injects), which is not a valid base. */
+function isAbsoluteUrl(value: string): boolean {
+  return URL.canParse(value);
+}
+
+/** Canonical base URL for the sitemap. Prefer an absolute `BASE_URL`; otherwise
+ * fall back to localhost on the active `PORT` (so local preview / e2e `<loc>`
+ * URLs point at the running server rather than a stale hard-coded port). */
+const fromEnv = process.env.BASE_URL;
+const baseUrl =
+  fromEnv && isAbsoluteUrl(fromEnv)
+    ? fromEnv
+    : `http://localhost:${process.env.PORT ?? 5174}`;
+
+/**
+ * Per-request factory mirroring the JSX app's `createRenderer` contract, so the
+ * server entrypoints select between them uniformly. A fresh `SitemapRenderer`
+ * is created per request: it mutates `statusCode` / `statusReady` while
+ * rendering, so a shared instance could interfere across concurrent
+ * `/sitemap.xml` requests. The constructor only stores the getters + config, so
+ * the allocation is cheap (the data fetch happens later, in `renderTo*`).
+ */
+export default function createSitemapRenderer() {
+  return new SitemapRenderer([getSitemapItems], { baseUrl });
+}

package/src/application/react/templates/src/styles/app.css

@@ -0,0 +1,16 @@
+.app-shell {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding-inline: var(--grid-gap, 1.5rem);
+  padding-block: var(--container-gap-loose, 1.5rem);
+}
+
+.shell-header {
+  padding-block-end: var(--container-gap-default, 1rem);
+}
+
+.shell-header nav {
+  grid-column: 1 / -1;
+  display: flex;
+  gap: var(--container-gap-default, 1rem);
+}

package/src/application/react/templates/src/styles/index.css.ejs

@@ -0,0 +1,5 @@
+@import url("@canonical/styles");
+<% if (forms) { -%>
+@import url("@canonical/react-ds-global-form/dist/esm/index.css");
+<% } -%>
+@import url("./app.css");

package/src/application/react/templates/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/application/react/templates/test/e2e/serverHarness.ts

@@ -0,0 +1,153 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { createServer } from "node:net";
+
+/**
+ * A spawned dev/preview server under test.
+ */
+export interface RunningServer {
+  /** Base URL, e.g. `http://localhost:54123`. */
+  base: string;
+  /** Stop the server and its whole process group. */
+  stop: () => Promise<void>;
+}
+
+/** Reserve a free TCP port by opening an ephemeral listener and reading it back. */
+export function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on("error", reject);
+    srv.listen(0, () => {
+      const address = srv.address();
+      if (address && typeof address === "object") {
+        const { port } = address;
+        srv.close(() => resolve(port));
+      } else {
+        srv.close(() => reject(new Error("could not determine a free port")));
+      }
+    });
+  });
+}
+
+/**
+ * Resolve once the server answers an HTTP request on `localhost:<port>`, or
+ * reject after `timeoutMs`. Probing over HTTP against `localhost` (rather than a
+ * raw TCP connect to a fixed IP) confirms the server is actually serving and
+ * works whether it bound IPv4 (`0.0.0.0`, the SSR servers) or IPv6 (`[::1]`,
+ * Vite's default) — `fetch`/`localhost` resolves both families.
+ */
+async function waitForServer(
+  base: string,
+  port: number,
+  timeoutMs: number,
+  startedAt: number,
+): Promise<void> {
+  const deadline = startedAt + timeoutMs;
+  for (;;) {
+    try {
+      // Any HTTP response (even a 404/500) means the server is up.
+      await fetch(`${base}/`, { signal: AbortSignal.timeout(1000) });
+      return;
+    } catch {
+      if (Date.now() > deadline) {
+        throw new Error(
+          `server did not respond on ${port} within ${timeoutMs}ms`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, 150));
+    }
+  }
+}
+
+/**
+ * Spawn an `npm`/`bun` script in `cwd` on a fresh OS-assigned port, wait until
+ * it is accepting connections, and return a handle that tears down the whole
+ * process group.
+ *
+ * Flakiness is designed out, not retried away:
+ * - **OS-assigned port** (`getFreePort` + `PORT` env) → no collisions across the
+ *   six matrix servers.
+ * - **Poll until the port accepts a connection** (not a fixed sleep) → no
+ *   readiness race; tolerates Vite's first-boot dep-optimization and the
+ *   `preview:*` build via a generous timeout.
+ * - **Detached spawn + process-group kill** in `stop()` → no zombie servers
+ *   leaking ports into the next test.
+ */
+export async function startServer(
+  script: string,
+  cwd: string,
+  { timeoutMs = 180_000 }: { timeoutMs?: number } = {},
+): Promise<RunningServer> {
+  const port = await getFreePort();
+  const base = `http://localhost:${port}`;
+  // Capture stderr so a boot crash surfaces the real cause instead of an opaque
+  // readiness timeout.
+  const child: ChildProcess = spawn("bun", ["run", script], {
+    cwd,
+    env: { ...process.env, PORT: String(port) },
+    detached: true,
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+
+  let stderrTail = "";
+  child.stderr?.on("data", (chunk: Buffer) => {
+    stderrTail = (stderrTail + chunk.toString()).slice(-4000);
+  });
+
+  // Reject readiness immediately if the child exits before it starts serving.
+  // Guarded so the exit fired by stop()'s SIGKILL (after readiness) is ignored.
+  let ready = false;
+  const exited = new Promise<never>((_, reject) => {
+    child.once("exit", (code) => {
+      if (ready) return;
+      reject(
+        new Error(
+          `\`${script}\` exited early (code ${code}) before serving.\n${stderrTail}`,
+        ),
+      );
+    });
+  });
+
+  const stop = (): Promise<void> =>
+    new Promise((resolve) => {
+      const { pid } = child;
+      if (pid == null || child.exitCode != null) {
+        resolve();
+        return;
+      }
+      child.once("exit", () => resolve());
+      try {
+        if (process.platform === "win32") {
+          // `process.kill(-pid)` (process-group kill) is POSIX-only and throws
+          // on Windows, which would leave the server holding its port. Use
+          // `taskkill /T` to terminate the child and its descendants instead.
+          spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            stdio: "ignore",
+          });
+        } else {
+          // Negative PID → kill the whole process group (the script and the
+          // server it spawns), so nothing is left holding the port.
+          process.kill(-pid, "SIGKILL");
+        }
+      } catch {
+        resolve();
+      }
+    });
+
+  try {
+    // Whichever settles first: the server responds, or the child dies.
+    await Promise.race([
+      waitForServer(base, port, timeoutMs, Date.now()),
+      exited,
+    ]);
+    ready = true;
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+
+  // Surface (and swallow) the now-irrelevant rejection so it isn't unhandled.
+  exited.catch(() => {});
+
+  return { base, stop };
+}

package/src/application/react/templates/test/e2e/servers.e2e.ts

@@ -0,0 +1,99 @@
+// @vitest-environment node
+
+/**
+ * End-to-end test of the build: boot each of the 2×3 server scripts and assert
+ * it serves correctly over HTTP. The defects this guards against live at the
+ * HTTP/content-type layer (assets served as text/html; a 500 page), so
+ * fetch-level assertions catch them — no browser needed.
+ *
+ * Each cell runs its real package.json script — including the build that
+ * `preview:*` performs — so the test mirrors the actual user experience. The
+ * `dev*` cells boot in a second or two (tight readiness budget); the
+ * `preview*` cells build the client + compile the renderer first, so they get a
+ * larger budget. Kept out of the default `test` run via the `*.e2e.ts` name;
+ * invoke with `bun run test:e2e`.
+ */
+import { describe, expect, it } from "vitest";
+import { startServer } from "./serverHarness.js";
+
+const CWD = process.cwd();
+
+// Readiness budgets: dev* boots straight away; preview* builds the client +
+// renderer before serving, so it needs a larger budget.
+const DEV_READY_MS = 20_000;
+const PREVIEW_READY_MS = 90_000;
+const TEST_TIMEOUT_MS = PREVIEW_READY_MS + 30_000;
+
+interface Cell {
+  /** package.json script to run. */
+  script: string;
+  /** Readiness budget for this cell's boot (and build, for preview*). */
+  timeoutMs: number;
+  /**
+   * Whether this cell server-renders. The plain `dev`/`preview` cells are the
+   * Vite SPA path (no SSR), so they have no `/sitemap.xml` route; the four
+   * `*:bun`/`*:express` cells render it from the sitemap renderer.
+   */
+  ssr: boolean;
+}
+
+const MATRIX: Cell[] = [
+  { script: "dev", timeoutMs: DEV_READY_MS, ssr: false },
+  { script: "dev:bun", timeoutMs: DEV_READY_MS, ssr: true },
+  { script: "dev:express", timeoutMs: DEV_READY_MS, ssr: true },
+  { script: "preview", timeoutMs: PREVIEW_READY_MS, ssr: false },
+  { script: "preview:bun", timeoutMs: PREVIEW_READY_MS, ssr: true },
+  { script: "preview:express", timeoutMs: PREVIEW_READY_MS, ssr: true },
+];
+
+/** A JS/TS module or CSS-as-JS asset must never come back as the HTML page. */
+const JS_CONTENT_TYPE = /javascript/;
+
+describe("server matrix (2×3) serves correctly", () => {
+  for (const cell of MATRIX) {
+    it(
+      `${cell.script} serves an HTML page and JS assets (not HTML)`,
+      async () => {
+        const server = await startServer(cell.script, CWD, {
+          timeoutMs: cell.timeoutMs,
+        });
+        try {
+          // 1. The document renders.
+          const page = await fetch(`${server.base}/`);
+          expect(page.status).toBe(200);
+          expect(page.headers.get("content-type")).toMatch(/text\/html/);
+          const html = await page.text();
+          expect(html).toContain('id="root"');
+
+          // 2. The HTML references at least one client script.
+          const scriptSrc = html.match(/<script[^>]+src="([^"]+)"/)?.[1];
+          expect(
+            scriptSrc,
+            "page should reference a client script",
+          ).toBeTruthy();
+
+          // 3. That script is served as JavaScript — never the HTML page.
+          //    (This is the exact defect: assets returned with a text/html MIME.)
+          const asset = await fetch(new URL(scriptSrc as string, server.base));
+          expect(asset.status).toBe(200);
+          expect(asset.headers.get("content-type")).toMatch(JS_CONTENT_TYPE);
+
+          // 4. SSR cells render /sitemap.xml as XML from the sitemap renderer —
+          //    the second renderer, picked by path, never the HTML app. (The SPA
+          //    dev/preview cells have no SSR route, so they are exempt.)
+          if (cell.ssr) {
+            const sitemap = await fetch(`${server.base}/sitemap.xml`);
+            expect(sitemap.status).toBe(200);
+            expect(sitemap.headers.get("content-type")).toMatch(/xml/);
+            const xml = await sitemap.text();
+            expect(xml).toContain("<urlset");
+            expect(xml).toContain("<loc>");
+          }
+        } finally {
+          await server.stop();
+        }
+      },
+      TEST_TIMEOUT_MS,
+    );
+  }
+});

package/src/application/react/templates/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "extends": "@canonical/typescript-config-react",
+  "compilerOptions": {
+    "baseUrl": "src",
+    "skipLibCheck": true,
+    "types": [
+      "bun-types",
+      "node",
+      "react",
+      "react-dom",
+      "vitest/globals",
+      "@testing-library/jest-dom"
+    ],
+    "noEmit": true,
+    "paths": {
+      "#lib/*": ["./lib/*"],
+      "#domains/*": ["./domains/*"],
+      "#styles/*": ["./styles/*"]
+    }
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    ".storybook/*.ts",
+    ".storybook/*.tsx",
+    "vite.config.ts",
+    "vitest.setup.ts",
+    "vitest.config.ts",
+    "vitest.e2e.config.ts",
+    "test/**/*.ts"
+  ]
+}

package/src/application/react/templates/vite.config.ts

@@ -0,0 +1,45 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// Path aliases (#lib, #domains, #styles) are declared as Node subpath imports
+// in package.json "imports" and resolved natively by Vite — no resolver plugin.
+const PORT = Number(process.env.PORT) || undefined;
+
+// `build:server` runs `vite build --mode server` to compile the two server
+// renderers in a single pass. Each is a separate, individually-instantiated
+// Lego brick, so they are named Rollup inputs — the build emits
+// `dist/server/renderer.js` (the JSX app) + `dist/server/sitemap.js` (the XML
+// sitemap), which the preview servers import directly. Every other command
+// (`dev`, `build:client`, `preview`) uses the default mode and the SPA client
+// build (`--ssrManifest --outDir dist/client`).
+export default defineConfig(({ mode }) => ({
+  plugins: [react()],
+  // Honour the PORT env var for `dev` (SPA) and `preview` so all server scripts
+  // — including the SSR ones, which already read PORT — respond to it uniformly.
+  server: { port: PORT },
+  preview: { port: PORT },
+  build:
+    mode === "server"
+      ? {
+          ssr: true,
+          outDir: "dist/server",
+          rollupOptions: {
+            input: {
+              renderer: "src/server/renderer.tsx",
+              sitemap: "src/sitemap/renderer.ts",
+            },
+          },
+        }
+      : undefined,
+  ssr: {
+    // Bundle @canonical/* for SSR rather than externalising them, for two
+    // reasons: (1) some packages declare only a "module" entry (no
+    // "main"/"exports"), which Vite's SSR (Node-style) resolver ignores —
+    // externalising them fails with ERR_RESOLVE_PACKAGE_ENTRY_FAIL; (2) their
+    // built output imports CSS as a side effect (e.g. `import "./x.css"`),
+    // which Node cannot load (ERR_UNKNOWN_FILE_EXTENSION) but Vite's SSR
+    // transform no-ops. The regex covers the whole scope so any current or
+    // future @canonical dependency is handled.
+    noExternal: [/^@canonical\//],
+  },
+}));

package/src/application/react/templates/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig, mergeConfig } from "vitest/config";
+import viteConfig from "./vite.config.js";
+
+// `vite.config` is a config function (it branches on `--mode server` for the
+// SSR build); resolve it for the default test run before merging.
+export default mergeConfig(
+  viteConfig({ command: "serve", mode: "test" }),
+  defineConfig({
+    test: {
+      // Browser-like environment for component tests
+      environment: "jsdom",
+      // Vitest globals (describe/it/expect) without imports
+      globals: true,
+      // Extend matchers and clean up the DOM between tests
+      setupFiles: ["./vitest.setup.ts"],
+      // Repo convention: test files are named *.tests.ts(x)
+      include: ["src/**/*.tests.ts", "src/**/*.tests.tsx"],
+      coverage: {
+        provider: "v8",
+        // Thresholds start at 0 — coverage is reported but does not gate.
+        // Ratchet these up as the app grows.
+        thresholds: {
+          statements: 0,
+          branches: 0,
+          functions: 0,
+          lines: 0,
+        },
+      },
+    },
+  }),
+);

package/src/application/react/templates/vitest.e2e.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config";
+
+// E2e build/server tests: boot each package.json server script and assert it
+// serves over HTTP. Separate from the default unit suite (vitest.config.ts) —
+// node environment, serial (servers bind ports), and a long timeout because
+// `preview:*` builds the client + compiles the renderer before serving.
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["test/**/*.e2e.ts"],
+    // Servers bind real ports and the preview build is heavy — run serially.
+    // fileParallelism:false pins maxWorkers to 1, so cells never run concurrently.
+    fileParallelism: false,
+    testTimeout: 300_000,
+    hookTimeout: 300_000,
+  },
+});

package/src/application/react/templates/vitest.setup.ts

@@ -0,0 +1,9 @@
+import * as matchers from "@testing-library/jest-dom/matchers";
+import { cleanup } from "@testing-library/react";
+import { afterEach, expect } from "vitest";
+
+expect.extend(matchers as unknown as Parameters<typeof expect.extend>[0]);
+
+afterEach(() => {
+  cleanup();
+});

package/src/domain/index.ts

@@ -0,0 +1,119 @@
+import * as path from "node:path";
+import type {
+  GeneratorDefinition,
+  PromptDefinition,
+} from "@canonical/summon-core";
+import {
+  exists,
+  fail,
+  flatMap,
+  info,
+  mkdir,
+  sequence_,
+  writeFile,
+} from "@canonical/task";
+import { toCamelCase, toTitleCase } from "@canonical/utils";
+import { normalizeCommandPath } from "../shared/casing.js";
+import { printVersions } from "../shared/versions.js";
+
+interface DomainAnswers {
+  readonly domainName: string;
+}
+
+const prompts: PromptDefinition[] = [
+  {
+    name: "domainName",
+    type: "text",
+    message: "Domain name (for example billing):",
+    default: "example",
+    positional: true,
+    group: "Domain",
+  },
+];
+
+function buildMainPage(domainName: string): string {
+  const title = toTitleCase(domainName);
+
+  return `import { useHead } from "@canonical/react-head";
+import type { ReactElement } from "react";
+
+export default function MainPage(): ReactElement {
+  useHead({ title: "${title}" });
+
+  return (
+    <section aria-labelledby="main-title">
+      <h1 id="main-title">${title}</h1>
+      <p>This is the main page for the ${domainName} domain.</p>
+    </section>
+  );
+}
+`;
+}
+
+function buildRoutesFile(domainName: string): string {
+  const routeUrl = `/${normalizeCommandPath(domainName)}`;
+
+  return `import { route } from "@canonical/router-core";
+import MainPage from "./MainPage.js";
+
+const routes = {
+  ${toCamelCase(domainName)}: route({
+    url: "${routeUrl}",
+    content: MainPage,
+  }),
+} as const;
+
+export default routes;
+`;
+}
+
+export const generator: GeneratorDefinition<DomainAnswers> = {
+  meta: {
+    name: "domain",
+    displayName: "@canonical/summon-application:domain",
+    description: "Create a domain folder with routes and a MainPage",
+    version: "0.1.0",
+    help: `Creates a domain directory under src/domains/ with:
+  - MainPage.tsx — example page component with useHead()
+  - routes.ts — route barrel exporting the domain's routes
+
+Add more routes with: summon route <domain>/<route-name>`,
+    examples: [
+      "summon domain billing",
+      "summon domain user-settings",
+      "summon domain --dry-run billing",
+    ],
+  },
+
+  prompts,
+
+  generate: (answers) => {
+    const name = normalizeCommandPath(answers.domainName);
+    const domainDir = path.join("src", "domains", name);
+
+    const scaffold = sequence_([
+      printVersions("domain"),
+      info(`Creating domain "${name}"...`),
+      mkdir(domainDir),
+      writeFile(path.join(domainDir, "MainPage.tsx"), buildMainPage(name)),
+      writeFile(path.join(domainDir, "routes.ts"), buildRoutesFile(name)),
+      info(
+        `Domain "${name}" created. Import its routes in src/routes.tsx and wire them with group().`,
+      ),
+    ]);
+
+    // Refuse to run when the domain already exists — mkdir/writeFile undos are
+    // destructive (DeleteDirectory / DeleteFile), so overwriting then `--undo`
+    // could delete a pre-existing domain.
+    return flatMap(exists(domainDir), (present) =>
+      present
+        ? fail({
+            code: "DOMAIN_EXISTS",
+            message: `Domain "${domainDir}" already exists. Choose a different name or remove it first.`,
+          })
+        : scaffold,
+    );
+  },
+};
+
+export default generator;