@canonical/summon-application 0.29.0-experimental.0

package/src/index.test.ts

@@ -0,0 +1,398 @@
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { dryRun, sequence_ } from "@canonical/task";
+import { describe, expect, it } from "vitest";
+import { generators } from "./index.js";
+
+/**
+ * The route generator requires an existing domain (it adds to one). In a
+ * dry-run the virtual filesystem is empty, so we first run the domain generator
+ * in the same sequence to "create" src/domains/<domain>/routes.ts, then add the
+ * route — mirroring real usage (`summon domain` then `summon route`).
+ */
+function dryRunRoute(domain: string, route: string) {
+  return dryRun(
+    sequence_([
+      generators.domain.generate({ domainName: domain }),
+      generators.route.generate({ routePath: `${domain}/${route}` }),
+    ]),
+  );
+}
+
+describe("application/react generator", () => {
+  it("produces effects for all expected files", () => {
+    const result = dryRun(
+      generators["application/react"].generate({
+        appPath: "my-app",
+        ssr: true,
+        router: true,
+        forms: false,
+        runInstall: false,
+      }),
+    );
+
+    // template() produces WriteFile, copyFile() produces CopyFile
+    const filePaths = result.effects
+      .filter((e) => e._tag === "WriteFile" || e._tag === "CopyFile")
+      .map(
+        (e) =>
+          (e as { path?: string; dest?: string }).path ??
+          (e as { dest?: string }).dest,
+      );
+
+    // EJS templates (interpolated)
+    expect(filePaths).toContain("my-app/package.json");
+    expect(filePaths).toContain("my-app/README.md");
+
+    // Static copies
+    expect(filePaths).toContain("my-app/tsconfig.json");
+    expect(filePaths).toContain("my-app/vite.config.ts");
+    expect(filePaths).toContain("my-app/biome.json");
+    expect(filePaths).toContain("my-app/index.html");
+    expect(filePaths).toContain("my-app/.gitignore");
+    expect(filePaths).toContain("my-app/src/client/entry.tsx");
+    expect(filePaths).toContain("my-app/src/server/entry.tsx");
+    expect(filePaths).toContain("my-app/src/server/renderer.tsx");
+    expect(filePaths).toContain("my-app/src/server/server.express.ts");
+    expect(filePaths).toContain("my-app/src/server/server.bun.ts");
+    expect(filePaths).toContain("my-app/src/server/preview.express.ts");
+    expect(filePaths).toContain("my-app/src/server/preview.bun.ts");
+    expect(filePaths).toContain("my-app/public/robots.txt");
+    expect(filePaths).toContain("my-app/src/sitemap/renderer.ts");
+    expect(filePaths).toContain("my-app/src/sitemap/getSitemapItems.ts");
+    expect(filePaths).toContain("my-app/vitest.e2e.config.ts");
+    expect(filePaths).toContain("my-app/test/e2e/serverHarness.ts");
+    expect(filePaths).toContain("my-app/test/e2e/servers.e2e.ts");
+    expect(filePaths).toContain("my-app/src/domains/marketing/HomePage.tsx");
+    expect(filePaths).toContain("my-app/src/domains/marketing/routes.ts");
+    expect(filePaths).toContain("my-app/src/routes.tsx");
+    expect(filePaths).toContain("my-app/src/lib/Navigation/Navigation.tsx");
+    expect(filePaths).toContain("my-app/src/lib/Navigation/index.ts");
+    expect(filePaths).toContain("my-app/src/lib/index.ts");
+    expect(filePaths).toContain("my-app/src/vite-env.d.ts");
+    expect(filePaths).toContain("my-app/src/styles/index.css");
+    expect(filePaths).toContain("my-app/src/styles/app.css");
+    expect(filePaths).toContain("my-app/.storybook/main.ts");
+    expect(filePaths).toContain("my-app/.storybook/preview.ts");
+    expect(filePaths).toContain("my-app/.storybook/decorators/withRouter.tsx");
+    expect(filePaths).toContain("my-app/.storybook/decorators/index.ts");
+
+    // Account domain
+    expect(filePaths).toContain("my-app/src/domains/account/AccountPage.tsx");
+    expect(filePaths).toContain("my-app/src/domains/account/LoginPage.tsx");
+    expect(filePaths).toContain("my-app/src/domains/account/routes.ts");
+
+    // Contact domain NOT included when forms=false
+    expect(filePaths).not.toContain(
+      "my-app/src/domains/contact/ContactPage.tsx",
+    );
+    expect(filePaths).not.toContain("my-app/src/domains/contact/routes.ts");
+  });
+
+  it("scaffolds every file present in the templates directory", () => {
+    // Authoritative manifest-completeness guard: enumerate the templates dir on
+    // disk and assert each file is emitted by the generator. The manifest is a
+    // hand-maintained allow-list, so a new template file added without a matching
+    // copy()/template() entry would silently never reach generated apps — this
+    // test fails loudly when that happens.
+    const templatesDir = fileURLToPath(
+      new URL("./application/react/templates", import.meta.url),
+    );
+    const onDisk = readdirSync(templatesDir, { recursive: true })
+      .map((entry) => String(entry).split(path.sep).join("/"))
+      .filter((rel) => statSync(path.join(templatesDir, rel)).isFile())
+      // `.ejs` templates are emitted at the interpolated dest (suffix stripped).
+      .map((rel) =>
+        rel.endsWith(".ejs") ? rel.slice(0, -".ejs".length) : rel,
+      );
+
+    // Generate with all features on so conditionally-included templates emit.
+    const result = dryRun(
+      generators["application/react"].generate({
+        appPath: "my-app",
+        ssr: true,
+        router: true,
+        forms: true,
+        runInstall: false,
+      }),
+    );
+    const emitted = new Set(
+      result.effects
+        .filter((e) => e._tag === "WriteFile" || e._tag === "CopyFile")
+        .map(
+          (e) =>
+            (e as { path?: string; dest?: string }).path ??
+            (e as { dest?: string }).dest,
+        ),
+    );
+
+    const missing = onDisk.filter((rel) => !emitted.has(`my-app/${rel}`));
+    expect(
+      missing,
+      `templates not wired into the manifest: ${missing}`,
+    ).toEqual([]);
+  });
+
+  it("includes contact domain when forms=true", () => {
+    const result = dryRun(
+      generators["application/react"].generate({
+        appPath: "my-app",
+        ssr: true,
+        router: true,
+        forms: true,
+        runInstall: false,
+      }),
+    );
+
+    const filePaths = result.effects
+      .filter((e) => e._tag === "WriteFile" || e._tag === "CopyFile")
+      .map(
+        (e) =>
+          (e as { path?: string; dest?: string }).path ??
+          (e as { dest?: string }).dest,
+      );
+
+    expect(filePaths).toContain("my-app/src/domains/contact/ContactPage.tsx");
+    expect(filePaths).toContain("my-app/src/domains/contact/routes.ts");
+
+    // routes.tsx is generated as an EJS template (WriteFile effect exists)
+    // Note: readFile is mocked in dry-run so we can't inspect rendered content,
+    // but we verify the template is wired up and the contact files are generated.
+    const routesEffect = result.effects.find(
+      (e) =>
+        e._tag === "WriteFile" &&
+        (e as { path: string }).path === "my-app/src/routes.tsx",
+    );
+    expect(routesEffect).toBeDefined();
+  });
+
+  it("excludes contact domain files when forms=false", () => {
+    const result = dryRun(
+      generators["application/react"].generate({
+        appPath: "my-app",
+        ssr: true,
+        router: true,
+        forms: false,
+        runInstall: false,
+      }),
+    );
+
+    const filePaths = result.effects
+      .filter((e) => e._tag === "WriteFile" || e._tag === "CopyFile")
+      .map(
+        (e) =>
+          (e as { path?: string; dest?: string }).path ??
+          (e as { dest?: string }).dest,
+      );
+
+    expect(filePaths).not.toContain(
+      "my-app/src/domains/contact/ContactPage.tsx",
+    );
+    expect(filePaths).not.toContain("my-app/src/domains/contact/routes.ts");
+  });
+
+  it("uses the appPath in file paths", () => {
+    const result = dryRun(
+      generators["application/react"].generate({
+        appPath: "custom-app",
+        ssr: true,
+        router: true,
+        forms: false,
+        runInstall: false,
+      }),
+    );
+
+    const filePaths = result.effects
+      .filter((e) => e._tag === "WriteFile" || e._tag === "CopyFile")
+      .map(
+        (e) =>
+          (e as { path?: string; dest?: string }).path ??
+          (e as { dest?: string }).dest,
+      );
+
+    expect(filePaths).toContain("custom-app/package.json");
+    expect(filePaths).toContain("custom-app/src/client/entry.tsx");
+  });
+
+  it("throws when --ssr is false", () => {
+    expect(() =>
+      dryRun(
+        generators["application/react"].generate({
+          appPath: "my-app",
+          ssr: false,
+          router: true,
+          forms: false,
+          runInstall: false,
+        }),
+      ),
+    ).toThrow();
+  });
+
+  it("throws when --router is false", () => {
+    expect(() =>
+      dryRun(
+        generators["application/react"].generate({
+          appPath: "my-app",
+          ssr: true,
+          router: false,
+          forms: false,
+          runInstall: false,
+        }),
+      ),
+    ).toThrow();
+  });
+});
+
+describe("domain generator", () => {
+  it("creates MainPage.tsx and routes.ts in src/domains/{name}/", () => {
+    const result = dryRun(
+      generators.domain.generate({ domainName: "billing" }),
+    );
+
+    const writeEffects = result.effects.filter((e) => e._tag === "WriteFile");
+    const paths = writeEffects.map((e) => (e as { path: string }).path);
+
+    expect(paths).toContain("src/domains/billing/MainPage.tsx");
+    expect(paths).toContain("src/domains/billing/routes.ts");
+  });
+
+  it("creates a MakeDir effect for the domain directory", () => {
+    const result = dryRun(
+      generators.domain.generate({ domainName: "billing" }),
+    );
+
+    const mkdirEffects = result.effects.filter((e) => e._tag === "MakeDir");
+    const paths = mkdirEffects.map((e) => (e as { path: string }).path);
+
+    expect(paths).toContain("src/domains/billing");
+  });
+});
+
+describe("route generator", () => {
+  it("creates {Name}Page.tsx and transforms routes.ts", () => {
+    const result = dryRunRoute("account", "settings");
+
+    const writePaths = result.effects
+      .filter((e) => e._tag === "WriteFile")
+      .map((e) => (e as { path: string }).path);
+    expect(writePaths).toContain("src/domains/account/SettingsPage.tsx");
+
+    // The route is wired into routes.ts via a TransformFile (AST insert), not
+    // an AppendFile of a TODO comment. The transform content is covered by
+    // insertRoute.test.ts.
+    const transformPaths = result.effects
+      .filter((e) => e._tag === "TransformFile")
+      .map((e) => (e as { path: string }).path);
+    expect(transformPaths).toContain("src/domains/account/routes.ts");
+  });
+
+  it("includes correct content in the page component", () => {
+    const result = dryRunRoute("account", "settings");
+
+    const page = result.effects.find(
+      (e) =>
+        e._tag === "WriteFile" &&
+        (e as { path: string }).path === "src/domains/account/SettingsPage.tsx",
+    ) as { content: string } | undefined;
+
+    expect(page).toBeDefined();
+    expect(page?.content).toContain("export default function SettingsPage()");
+    expect(page?.content).toContain('useHead({ title: "Settings" })');
+  });
+
+  it("wires the route via a reversible TransformFile (no TODO append)", () => {
+    const result = dryRunRoute("account", "settings");
+
+    // No AppendFile TODO stub any more.
+    expect(result.effects.some((e) => e._tag === "AppendFile")).toBe(false);
+
+    const transform = result.effects.find(
+      (e) =>
+        e._tag === "TransformFile" &&
+        (e as { path: string }).path === "src/domains/account/routes.ts",
+    ) as { transform: (s: string) => string; undo?: unknown } | undefined;
+
+    expect(transform).toBeDefined();
+    // It carries an undo (the inverse removeRoute transform).
+    expect(transform?.undo).toBeDefined();
+
+    // The forward transform actually inserts the import + route entry.
+    const base = `import { route } from "@canonical/router-core";
+import MainPage from "./MainPage.js";
+
+const routes = {
+  account: route({ url: "/account", content: MainPage }),
+} as const;
+
+export default routes;
+`;
+    const out = transform?.transform(base) ?? "";
+    expect(out).toContain('import SettingsPage from "./SettingsPage.js";');
+    expect(out).toContain("settings: route({");
+    expect(out).toContain('url: "/account/settings",');
+    expect(out).toContain("content: SettingsPage,");
+  });
+
+  it("throws on single-segment path", () => {
+    expect(() =>
+      dryRun(generators.route.generate({ routePath: "settings" })),
+    ).toThrow();
+  });
+
+  it("fails when the target domain does not exist", () => {
+    // No domain created first → the guard rejects before writing anything.
+    expect(() =>
+      dryRun(generators.route.generate({ routePath: "missing/page" })),
+    ).toThrow(/not found|Create it first/);
+  });
+});
+
+describe("wrapper generator", () => {
+  it("creates {Name}Layout.tsx and index.ts in src/lib/{Name}Layout/", () => {
+    const result = dryRun(
+      generators.wrapper.generate({ wrapperName: "settings" }),
+    );
+
+    const writeEffects = result.effects.filter((e) => e._tag === "WriteFile");
+    const paths = writeEffects.map((e) => (e as { path: string }).path);
+
+    expect(paths).toContain("src/lib/SettingsLayout/SettingsLayout.tsx");
+    expect(paths).toContain("src/lib/SettingsLayout/index.ts");
+  });
+
+  it("generates correct layout content", () => {
+    const result = dryRun(
+      generators.wrapper.generate({ wrapperName: "settings" }),
+    );
+
+    const writeEffects = result.effects.filter((e) => e._tag === "WriteFile");
+    const layout = writeEffects.find(
+      (e) =>
+        (e as { path: string }).path ===
+        "src/lib/SettingsLayout/SettingsLayout.tsx",
+    ) as { content: string } | undefined;
+
+    expect(layout).toBeDefined();
+    expect(layout?.content).toContain(
+      "export default function SettingsLayout(",
+    );
+    expect(layout?.content).toContain('className="settings-layout"');
+  });
+
+  it("generates correct barrel export", () => {
+    const result = dryRun(
+      generators.wrapper.generate({ wrapperName: "settings" }),
+    );
+
+    const writeEffects = result.effects.filter((e) => e._tag === "WriteFile");
+    const barrel = writeEffects.find(
+      (e) => (e as { path: string }).path === "src/lib/SettingsLayout/index.ts",
+    ) as { content: string } | undefined;
+
+    expect(barrel).toBeDefined();
+    expect(barrel?.content).toContain(
+      'export { default } from "./SettingsLayout.js"',
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,14 @@
+import type { AnyGenerator } from "@canonical/summon-core";
+import { generator as applicationReactGenerator } from "./application/react/index.js";
+import { generator as domainGenerator } from "./domain/index.js";
+import { generator as routeGenerator } from "./route/index.js";
+import { generator as wrapperGenerator } from "./wrapper/index.js";
+
+export const generators = {
+  "application/react": applicationReactGenerator,
+  domain: domainGenerator,
+  route: routeGenerator,
+  wrapper: wrapperGenerator,
+} as const satisfies Record<string, AnyGenerator>;
+
+export default generators;

package/src/route/index.ts

@@ -0,0 +1,154 @@
+import * as path from "node:path";
+import type {
+  GeneratorDefinition,
+  PromptDefinition,
+} from "@canonical/summon-core";
+import {
+  exists,
+  fail,
+  flatMap,
+  info,
+  sequence_,
+  transformFile,
+  writeFile,
+} from "@canonical/task";
+import { toCamelCase, toPascalCase, toTitleCase } from "@canonical/utils";
+import { normalizeCommandPath } from "../shared/casing.js";
+import { insertRoute, removeRoute } from "./insertRoute.js";
+
+interface RouteAnswers {
+  readonly routePath: string;
+}
+
+const prompts: PromptDefinition[] = [
+  {
+    name: "routePath",
+    type: "text",
+    message: "Route path (for example account/settings):",
+    default: "example/page",
+    positional: true,
+    group: "Route",
+  },
+];
+
+function buildPage(routeName: string): string {
+  const pageName = `${toPascalCase(routeName)}Page`;
+  const title = toTitleCase(routeName);
+  const slugId = toCamelCase(routeName);
+
+  return `import { useHead } from "@canonical/react-head";
+import type { ReactElement } from "react";
+
+export default function ${pageName}(): ReactElement {
+  useHead({ title: "${title}" });
+
+  return (
+    <section aria-labelledby="${slugId}-title">
+      <h1 id="${slugId}-title">${title}</h1>
+    </section>
+  );
+}
+`;
+}
+
+export const generator: GeneratorDefinition<RouteAnswers> = {
+  meta: {
+    name: "route",
+    displayName: "@canonical/summon-application:route",
+    description: "Add a route page to an existing domain",
+    version: "0.1.0",
+    help: `Creates a page component inside an existing domain directory.
+
+Given a path like "account/settings":
+  - Domain = first segment ("account")
+  - Route  = last segment ("settings")
+
+Creates:
+  - src/domains/<domain>/<RouteName>Page.tsx
+  - Inserts the import + route entry into src/domains/<domain>/routes.ts
+
+Refuses to overwrite an existing page file.
+
+Create the domain first with: summon domain <name>
+
+Note on --undo: undo removes the route entry and import it added. It assumes the
+route was newly created — running --undo after an insert that was a no-op (the
+route key already existed) would remove a route you already had.`,
+    examples: [
+      "summon route account/settings",
+      "summon route billing/invoices",
+      "summon route --dry-run user/profile",
+    ],
+  },
+
+  prompts,
+
+  generate: (answers) => {
+    const normalized = normalizeCommandPath(answers.routePath);
+    const segments = normalized.split("/");
+
+    if (segments.length < 2) {
+      throw new Error(
+        `Route path must include a domain and route name (e.g. "account/settings"), got "${normalized}"`,
+      );
+    }
+
+    const domainName = segments[0];
+    const routeName = segments[segments.length - 1];
+    const pageName = `${toPascalCase(routeName)}Page`;
+    const domainDir = path.join("src", "domains", domainName);
+    const pageFile = path.join(domainDir, `${pageName}.tsx`);
+    const routesFile = path.join(domainDir, "routes.ts");
+    const url = `/${normalized}`;
+    const routeKey = toCamelCase(routeName);
+
+    const scaffold = sequence_([
+      info(`Adding route "${routeName}" to domain "${domainName}"...`),
+      // No mkdir: this generator targets an *existing* domain (guarded below).
+      // mkdir's default undo is DeleteDirectory, which on `--undo` could remove
+      // a pre-existing domain folder.
+      writeFile(pageFile, buildPage(routeName)),
+      // Insert the import + route entry into the domain's routes object via a
+      // pure AST-located transform (no manual edit needed afterwards). Undo
+      // removes exactly the lines we added, rather than restoring a snapshot.
+      transformFile(
+        routesFile,
+        (source) =>
+          insertRoute(source, {
+            pageName,
+            importPath: `./${pageName}.js`,
+            routeKey,
+            url,
+          }),
+        {
+          undo: transformFile(routesFile, (source) =>
+            removeRoute(source, { pageName, routeKey }),
+          ),
+        },
+      ),
+      info(`Route "${routeName}" wired into ${routesFile}.`),
+    ]);
+
+    // Guard before touching anything:
+    // - the domain must exist (this generator adds to an existing domain);
+    // - the page must NOT exist (its write's undo is a delete, so overwriting a
+    //   hand-authored page then `--undo` would destroy the original).
+    return flatMap(exists(routesFile), (domainPresent) =>
+      !domainPresent
+        ? fail({
+            code: "ROUTE_DOMAIN_MISSING",
+            message: `Domain "${domainName}" not found (${routesFile} missing). Create it first with: summon domain ${domainName}`,
+          })
+        : flatMap(exists(pageFile), (pagePresent) =>
+            pagePresent
+              ? fail({
+                  code: "ROUTE_PAGE_EXISTS",
+                  message: `Page "${pageFile}" already exists. Choose a different route name or remove the file first.`,
+                })
+              : scaffold,
+          ),
+    );
+  },
+};
+
+export default generator;

package/src/route/insertRoute.test.ts

@@ -0,0 +1,98 @@
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+import { insertRoute, removeRoute } from "./insertRoute.js";
+
+const BASE = `import { route } from "@canonical/router-core";
+import MainPage from "./MainPage.js";
+
+const routes = {
+  billing: route({
+    url: "/billing",
+    content: MainPage,
+  }),
+} as const;
+
+export default routes;
+`;
+
+const INS = {
+  pageName: "InvoicesPage",
+  importPath: "./InvoicesPage.js",
+  routeKey: "invoices",
+  url: "/billing/invoices",
+} as const;
+
+describe("insertRoute", () => {
+  it("adds the import and the route entry", () => {
+    const out = insertRoute(BASE, INS);
+    expect(out).toContain('import InvoicesPage from "./InvoicesPage.js";');
+    expect(out).toContain("invoices: route({");
+    expect(out).toContain('url: "/billing/invoices",');
+    expect(out).toContain("content: InvoicesPage,");
+    // existing entry untouched
+    expect(out).toContain("billing: route({");
+  });
+
+  it("is idempotent — re-inserting the same route is a no-op", () => {
+    const once = insertRoute(BASE, INS);
+    expect(insertRoute(once, INS)).toBe(once);
+  });
+
+  it("throws when there is no routes object literal", () => {
+    expect(() => insertRoute("export const x = 1;\n", INS)).toThrow(/routes/);
+  });
+
+  // Bug fixes from the adversarial review: the entry must be spliced using the
+  // object literal's own AST bounds (not a brace text-scan), and a separating
+  // comma added when the previous property lacks one — so non-canonical routes
+  // shapes still produce parseable output.
+  it.each([
+    [
+      "single-line object",
+      `const routes = { billing: route({ url: "/billing", content: MainPage }) } as const;\n`,
+    ],
+    [
+      "no trailing comma",
+      `const routes = {\n  billing: route({ url: "/billing", content: MainPage })\n} as const;\n`,
+    ],
+    ["empty object", "const routes = {} as const;\n"],
+  ])("produces parseable output for a %s", (_label, src) => {
+    const out = insertRoute(src, INS);
+    const sf = ts.createSourceFile("r.ts", out, ts.ScriptTarget.Latest, true);
+    // @ts-expect-error parseDiagnostics is internal but reliable for this check
+    expect(sf.parseDiagnostics).toHaveLength(0);
+    expect(out).toContain("invoices: route({");
+  });
+});
+
+describe("removeRoute", () => {
+  it("is the exact inverse of insertRoute (round-trip)", () => {
+    const added = insertRoute(BASE, INS);
+    expect(removeRoute(added, INS)).toBe(BASE);
+  });
+
+  it("is idempotent — removing an absent route is a no-op", () => {
+    expect(removeRoute(BASE, INS)).toBe(BASE);
+  });
+
+  it("leaves other routes and imports intact", () => {
+    const added = insertRoute(BASE, INS);
+    const back = removeRoute(added, INS);
+    expect(back).toContain("billing: route({");
+    expect(back).toContain('import MainPage from "./MainPage.js";');
+    expect(back).not.toContain("InvoicesPage");
+  });
+
+  it("does NOT delete a merged import that has named bindings", () => {
+    // A user may have merged named bindings into the generated import. removing
+    // the whole line would discard them, so removeRoute leaves it alone.
+    const merged = insertRoute(BASE, INS).replace(
+      'import InvoicesPage from "./InvoicesPage.js";',
+      'import InvoicesPage, { helper } from "./InvoicesPage.js";',
+    );
+    const back = removeRoute(merged, INS);
+    expect(back).toContain("{ helper }");
+    // the route entry is still removed
+    expect(back).not.toContain("invoices: route({");
+  });
+});