@canonical/summon-application 0.29.0-experimental.0

package/src/route/insertRoute.ts

@@ -0,0 +1,236 @@
+import ts from "typescript";
+
+/**
+ * Peel `as const` / type assertions / parentheses off an initializer to reach
+ * the underlying object literal (e.g. `{ ... } as const`), if any.
+ */
+function unwrapObjectLiteral(
+  expr: ts.Expression,
+): ts.ObjectLiteralExpression | undefined {
+  let node: ts.Expression = expr;
+  while (
+    ts.isAsExpression(node) ||
+    ts.isParenthesizedExpression(node) ||
+    ts.isTypeAssertionExpression(node) ||
+    ts.isSatisfiesExpression(node)
+  ) {
+    node = node.expression;
+  }
+  return ts.isObjectLiteralExpression(node) ? node : undefined;
+}
+
+export interface RouteInsertion {
+  /** Imported page component, e.g. "InvoicesPage". */
+  readonly pageName: string;
+  /** Import specifier, e.g. "./InvoicesPage.js". */
+  readonly importPath: string;
+  /** Route key in the routes object, e.g. "invoices". */
+  readonly routeKey: string;
+  /** Route URL, e.g. "/billing/invoices". */
+  readonly url: string;
+}
+
+/**
+ * Insert a route into a domain `routes.ts` source.
+ *
+ * Uses the TypeScript compiler API only to *locate* the insertion points (the
+ * last import declaration and the `routes` object literal), then splices text
+ * at those offsets. Locating with the AST is robust to formatting; editing by
+ * string keeps the rest of the file byte-for-byte unchanged (no full re-print,
+ * so it doesn't fight the formatter).
+ *
+ * Idempotent: if `routeKey` already exists in the routes object, the source is
+ * returned unchanged. Throws if the `routes` object literal cannot be found.
+ */
+export function insertRoute(source: string, ins: RouteInsertion): string {
+  const sf = ts.createSourceFile(
+    "routes.ts",
+    source,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+  );
+
+  // Locate the `routes` object literal and the last import declaration.
+  let routesObject: ts.ObjectLiteralExpression | undefined;
+  let lastImportEnd: number | undefined;
+
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt)) {
+      lastImportEnd = stmt.end;
+      continue;
+    }
+    if (ts.isVariableStatement(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (
+          ts.isIdentifier(decl.name) &&
+          decl.name.text === "routes" &&
+          decl.initializer
+        ) {
+          const obj = unwrapObjectLiteral(decl.initializer);
+          if (obj) routesObject = obj;
+        }
+      }
+    }
+  }
+
+  if (!routesObject) {
+    throw new Error(
+      "insertRoute: could not find a `const routes = { ... }` object literal",
+    );
+  }
+
+  // Idempotency: skip if the key is already present.
+  const exists = routesObject.properties.some(
+    (p) =>
+      p.name &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === ins.routeKey,
+  );
+  if (exists) return source;
+
+  // Indentation of the existing properties (fall back to two spaces).
+  const indent = detectIndent(source, routesObject) ?? "  ";
+
+  const importLine = `import ${ins.pageName} from "${ins.importPath}";\n`;
+  const entry =
+    `${indent}${ins.routeKey}: route({\n` +
+    `${indent}${indent}url: "${ins.url}",\n` +
+    `${indent}${indent}content: ${ins.pageName},\n` +
+    `${indent}}),\n`;
+
+  // Insert after the last existing property, or — for an empty object — just
+  // inside the braces. Use AST node bounds, never a brace text-scan (which can
+  // match a nested `route({ ... })` brace on a single-line object).
+  const props = routesObject.properties;
+  let out: string;
+  if (props.length > 0) {
+    const last = props[props.length - 1];
+    // Find the insertion point: just after the last property, including its
+    // trailing comma if it has one (so the existing comma stays attached to the
+    // existing property). If there's no trailing comma, add one.
+    let at = last.end;
+    let prefix = ",\n";
+    if (source[at] === ",") {
+      at += 1; // step past the existing comma
+      prefix = "\n";
+    }
+    out = `${source.slice(0, at)}${prefix}${entry.replace(/\n$/, "")}${source.slice(at)}`;
+  } else {
+    // Empty object: insert between the braces.
+    const openBrace =
+      routesObject.getStart(sf) +
+      source.slice(routesObject.getStart(sf)).indexOf("{") +
+      1;
+    out = `${source.slice(0, openBrace)}\n${entry}${source.slice(openBrace)}`;
+  }
+
+  // Insert the import after the last existing import (offsets in the original
+  // source are still valid because the route entry was added later in the file).
+  if (lastImportEnd !== undefined) {
+    out =
+      out.slice(0, lastImportEnd) +
+      `\n${importLine.trimEnd()}` +
+      out.slice(lastImportEnd);
+  } else {
+    out = importLine + out;
+  }
+
+  return out;
+}
+
+/**
+ * Inverse of {@link insertRoute}: remove the route entry and its import.
+ *
+ * Used as the route generator's undo. Rather than restoring a stored copy of
+ * the file, it deletes exactly the lines that {@link insertRoute} added — the
+ * `routeKey` property in the `routes` object and the `import <pageName> ...`
+ * line. Idempotent: returns the source unchanged if neither is present, and
+ * leaves any other content (including manual edits) intact.
+ */
+export function removeRoute(
+  source: string,
+  ins: Pick<RouteInsertion, "pageName" | "routeKey">,
+): string {
+  const sf = ts.createSourceFile(
+    "routes.ts",
+    source,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+  );
+
+  let result = source;
+
+  // 1. Remove the route entry (the property whose name === routeKey).
+  for (const stmt of sf.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      if (
+        !ts.isIdentifier(decl.name) ||
+        decl.name.text !== "routes" ||
+        !decl.initializer
+      ) {
+        continue;
+      }
+      const obj = unwrapObjectLiteral(decl.initializer);
+      if (!obj) continue;
+      const prop = obj.properties.find(
+        (p) =>
+          p.name &&
+          (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+          p.name.text === ins.routeKey,
+      );
+      if (prop) {
+        result = removeFullLines(result, prop.getStart(sf), prop.end);
+      }
+    }
+  }
+
+  // 2. Remove the import line for the page component.
+  // Re-parse because offsets shifted after the entry removal.
+  const sf2 = ts.createSourceFile(
+    "routes.ts",
+    result,
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  for (const stmt of sf2.statements) {
+    if (
+      ts.isImportDeclaration(stmt) &&
+      stmt.importClause?.name?.text === ins.pageName &&
+      // Only remove a pure default import (`import Page from "..."`), which is
+      // exactly what insertRoute creates. If a user merged named bindings into
+      // it (`import Page, { x } from "..."`), leave it — removing the whole line
+      // would discard their bindings.
+      !stmt.importClause.namedBindings
+    ) {
+      result = removeFullLines(result, stmt.getStart(sf2), stmt.end);
+      break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove the whole-line span covering [start, end), including the node's
+ * leading indentation and its trailing newline, so no blank line is left behind.
+ */
+function removeFullLines(source: string, start: number, end: number): string {
+  const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+  let lineEnd = source.indexOf("\n", end);
+  if (lineEnd === -1) lineEnd = source.length;
+  else lineEnd += 1; // include the newline
+  return source.slice(0, lineStart) + source.slice(lineEnd);
+}
+
+/** Detect the indentation used by the first property of the object literal. */
+function detectIndent(
+  source: string,
+  obj: ts.ObjectLiteralExpression,
+): string | undefined {
+  const first = obj.properties[0];
+  if (!first) return undefined;
+  const lineStart = source.lastIndexOf("\n", first.getStart()) + 1;
+  const ws = source.slice(lineStart, first.getStart());
+  return /^\s+$/.test(ws) ? ws : undefined;
+}

package/src/shared/casing.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a command path argument: trim, remove leading/trailing slashes,
+ * convert backslashes to forward slashes.
+ *
+ * This is generator-specific — it normalizes CLI input like
+ * `" /billing/invoices/ "` → `"billing/invoices"`.
+ */
+export function normalizeCommandPath(value: string): string {
+  return value
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+}

package/src/shared/versions.ts

@@ -0,0 +1,48 @@
+import { createRequire } from "node:module";
+import type { Task } from "@canonical/task";
+import { info } from "@canonical/task";
+
+/**
+ * Version range for the pragma workspace packages a generated app depends on
+ * directly — react-ds-global(-form), react-head, react-hooks, react-ssr,
+ * router-core, router-react, styles, storybook-config, biome-config,
+ * typescript-config-react. These share one lerna-managed release line.
+ *
+ * Scope notes:
+ * - Third-party deps (react, express, vite…) keep their own ranges.
+ * - `@canonical/design-tokens` is versioned SEPARATELY and is NOT pinned here —
+ *   it reaches the app transitively via `@canonical/styles`, which owns its range.
+ *
+ * A single hand-maintained constant — NOT read from a package.json at runtime,
+ * because the generator ships as a compiled binary where such a read would
+ * resolve to "unknown". Bump in lockstep with the lerna release.
+ *
+ * Open question: inject this at binary-build time once the compile pipeline
+ * supports it, so it cannot drift from the release. See README "Open questions".
+ */
+export const PRAGMA_WORKSPACE_VERSION = "^0.27.1-experimental.0";
+
+const require = createRequire(import.meta.url);
+
+function readVersion(packageName: string): string {
+  try {
+    const pkg = require(`${packageName}/package.json`);
+
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+const coreVersion = readVersion("@canonical/summon-core");
+const appVersion = readVersion("@canonical/summon-application");
+
+/**
+ * Print a version table for the current generator run.
+ */
+export function printVersions(generatorName: string): Task<void> {
+  return info(
+    `@canonical/summon-core         ${coreVersion}\n` +
+      `@canonical/summon-application  ${appVersion}  (${generatorName})`,
+  );
+}

package/src/wrapper/index.ts

@@ -0,0 +1,100 @@
+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 { toKebabCase, toPascalCase } from "@canonical/utils";
+import { normalizeCommandPath } from "../shared/casing.js";
+
+interface WrapperAnswers {
+  readonly wrapperName: string;
+}
+
+const prompts: PromptDefinition[] = [
+  {
+    name: "wrapperName",
+    type: "text",
+    message: "Wrapper name (for example settings):",
+    default: "example",
+    positional: true,
+    group: "Wrapper",
+  },
+];
+
+function buildLayout(wrapperName: string): string {
+  const layoutName = `${toPascalCase(wrapperName)}Layout`;
+  const className = `${toKebabCase(wrapperName)}-layout`;
+
+  return `import type { ReactNode, ReactElement } from "react";
+
+export default function ${layoutName}({
+  children,
+}: { children: ReactNode }): ReactElement {
+  return <div className="${className}">{children}</div>;
+}
+`;
+}
+
+function buildBarrel(wrapperName: string): string {
+  const layoutName = `${toPascalCase(wrapperName)}Layout`;
+
+  return `export { default } from "./${layoutName}.js";
+`;
+}
+
+export const generator: GeneratorDefinition<WrapperAnswers> = {
+  meta: {
+    name: "wrapper",
+    displayName: "@canonical/summon-application:wrapper",
+    description: "Create a layout wrapper component",
+    version: "0.1.0",
+    help: `Creates a layout wrapper component under src/lib/.
+
+Given a name like "settings", creates:
+  - src/lib/SettingsLayout/SettingsLayout.tsx
+  - src/lib/SettingsLayout/index.ts (barrel export)`,
+    examples: [
+      "summon wrapper settings",
+      "summon wrapper sidebar",
+      "summon wrapper --dry-run dashboard",
+    ],
+  },
+
+  prompts,
+
+  generate: (answers) => {
+    const name = normalizeCommandPath(answers.wrapperName);
+    const layoutName = `${toPascalCase(name)}Layout`;
+    const layoutDir = path.join("src", "lib", layoutName);
+
+    const scaffold = sequence_([
+      info(`Creating wrapper "${layoutName}"...`),
+      mkdir(layoutDir),
+      writeFile(path.join(layoutDir, `${layoutName}.tsx`), buildLayout(name)),
+      writeFile(path.join(layoutDir, "index.ts"), buildBarrel(name)),
+      info(`Wrapper "${layoutName}" created at ${layoutDir}.`),
+    ]);
+
+    // Refuse to run when the layout already exists — mkdir/writeFile undos are
+    // destructive, so overwriting then `--undo` could delete a pre-existing one.
+    return flatMap(exists(layoutDir), (present) =>
+      present
+        ? fail({
+            code: "WRAPPER_EXISTS",
+            message: `Wrapper "${layoutDir}" already exists. Choose a different name or remove it first.`,
+          })
+        : scaffold,
+    );
+  },
+};
+
+export default generator;