@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/create/create.mcp.test.ts

@@ -0,0 +1,139 @@
+/**
+ * PROTECTED — MCP plan-first + confirm parity for `create`:
+ * a tool call WITHOUT `confirm` returns a plan (`planOnly`/`confirmRequired`)
+ * and writes nothing; WITH `confirm: true` it runs for real. The plan mirrors
+ * the CLI `--dry-run` preview (both filter out Prompt effects).
+ */
+
+import { existsSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { createComponentVerb } from "./create.verb.js";
+import { createModule } from "./index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const freshCwd = (): string =>
+  mkdtempSync(join(tmpdir(), "pragma-create-mcp-"));
+
+let cleanup: (() => Promise<void>) | undefined;
+afterEach(async () => {
+  await cleanup?.();
+  cleanup = undefined;
+});
+
+describe("create over MCP (PROTECTED)", () => {
+  it("exposes create_component as mutating but NON-destructive", async () => {
+    const dir = freshCwd();
+    const mcp = await projectMcp([createModule], dir);
+    cleanup = mcp.cleanup;
+    const tools = await mcp.listTools();
+    const component = tools.find((t) => t.name === "create_component");
+    expect(component).toBeDefined();
+    expect(component?.annotations).toMatchObject({
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: false,
+    });
+    // Explicit: create only writes NEW files. An unset destructiveHint on a
+    // non-read-only tool defaults to `true`, so it must be emitted as false —
+    // agents otherwise treat scaffolding as a destructive operation (D4).
+    expect(component?.annotations?.destructiveHint).toBe(false);
+  });
+
+  it("plan-first: no confirm → a plan, no files written", async () => {
+    const dir = freshCwd();
+    const prev = process.cwd();
+    process.chdir(dir);
+    try {
+      const mcp = await projectMcp([createModule], dir);
+      cleanup = mcp.cleanup;
+      const result = await mcp.callTool("create_component", {
+        framework: "react",
+        componentPath: "src/components/Button",
+      });
+      expect(result.ok).toBe(true);
+      expect(result.meta).toMatchObject({
+        planOnly: true,
+        confirmRequired: true,
+      });
+      const plan = (result.data as { plan: string[] }).plan;
+      expect(plan.some((line) => line.includes("Button.tsx"))).toBe(true);
+      expect(plan.some((line) => line.includes("Prompt"))).toBe(false);
+      expect(readdirSync(dir)).toEqual([]); // nothing written
+    } finally {
+      process.chdir(prev);
+    }
+  });
+
+  it("confirm: true → runs for real and writes files", async () => {
+    const dir = freshCwd();
+    const prev = process.cwd();
+    process.chdir(dir);
+    try {
+      const mcp = await projectMcp([createModule], dir);
+      cleanup = mcp.cleanup;
+      const result = await mcp.callTool("create_component", {
+        framework: "react",
+        componentPath: "src/components/Button",
+        withStyles: false,
+        withStories: false,
+        withSsrTests: false,
+        confirm: true,
+      });
+      expect(result.ok).toBe(true);
+      expect(existsSync(join(dir, "src/components/Button/Button.tsx"))).toBe(
+        true,
+      );
+    } finally {
+      process.chdir(prev);
+    }
+  });
+
+  it("the MCP plan matches the CLI --dry-run preview", async () => {
+    const dir = freshCwd();
+    const prev = process.cwd();
+    process.chdir(dir);
+    try {
+      const mcp = await projectMcp([createModule], dir);
+      cleanup = mcp.cleanup;
+      const mcpResult = await mcp.callTool("create_component", {
+        framework: "react",
+        componentPath: "src/components/Button",
+        withStyles: false,
+        withStories: false,
+        withSsrTests: false,
+      });
+      const mcpPlan = (mcpResult.data as { plan: string[] }).plan;
+
+      const cliOutcome = await executeVerb(
+        createComponentVerb as VerbSpec,
+        {
+          framework: "react",
+          componentPath: "src/components/Button",
+          withStyles: false,
+          withStories: false,
+          withSsrTests: false,
+        },
+        { dryRun: true, undo: false, yes: false },
+        bootRuntime(FLAGS, dir),
+      );
+      // Every planned effect line appears in the CLI dry-run preview too.
+      for (const line of mcpPlan) {
+        expect(cliOutcome.stdout ?? "").toContain(line);
+      }
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

package/src/capabilities/create/create.render.ts

@@ -0,0 +1,50 @@
+/**
+ * Formatters for `create` — plain / llm / json over a {@link GeneratorResult}.
+ *
+ * Deliberately free of any runtime summon-core (and any Ink) import: the
+ * `GeneratorResult` type is imported type-only (erased), and the effect
+ * inspection uses `@canonical/task`, which the kernel already loads. So a verb
+ * spec carrying these formatters never pulls summon-core onto the
+ * `buildProgram` / `--help` / `__complete` fast paths — and never pulls React.
+ */
+
+import type { GeneratorResult } from "@canonical/summon-core";
+import { type Effect, getAffectedFiles } from "@canonical/task";
+import type { Formatters } from "../../kernel/spec/types.js";
+
+/** The user-visible mutating effects, de-duplicated by path for MakeDir. */
+function created(effects: readonly Effect[]): string[] {
+  return getAffectedFiles([...effects]);
+}
+
+/** The generation's outcome formatters. */
+export const createFormatters: Formatters<GeneratorResult> = {
+  plain(result) {
+    const files = created(result.effects);
+    const header = `Created with ${result.generator.meta.name} v${result.generator.meta.version}.`;
+    if (files.length === 0) return header;
+    return [header, ...files.map((file) => `  + ${file}`)].join("\n");
+  },
+
+  llm(result) {
+    const files = created(result.effects);
+    const lines = [
+      `# create — ${result.generator.meta.name}`,
+      "",
+      `Generated ${files.length} path${files.length === 1 ? "" : "s"}:`,
+      ...files.map((file) => `- \`${file}\``),
+    ];
+    return lines.join("\n");
+  },
+
+  json(result) {
+    return JSON.stringify({
+      generator: {
+        name: result.generator.meta.name,
+        version: result.generator.meta.version,
+      },
+      answers: result.answers,
+      created: created(result.effects),
+    });
+  },
+};

package/src/capabilities/create/create.test.ts

@@ -0,0 +1,403 @@
+/**
+ * `create` behaviour: real generation + stamp, the SEC-2 path jail, the
+ * lazy-React discipline, and the generator→grammar adapter parity guard.
+ * The MCP plan-first/confirm parity lives in create.mcp.test.ts; the
+ * byte-equality goldens in byteEquality.test.ts.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  symlinkSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import {
+  executeVerb,
+  type MutationFlags,
+} from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { ParamSpec } from "../../kernel/spec/types.js";
+import {
+  createApplicationVerb,
+  createComponentVerb,
+  createPackageVerb,
+  isModuleNotFound,
+} from "./create.verb.js";
+import { generatorToParams } from "./generatorToVerbSpec.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const YES: MutationFlags = { dryRun: false, undo: false, yes: true };
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-create-"));
+
+/** Run a create verb inside `dir` (relative generator paths resolve there). */
+async function runIn(
+  dir: string,
+  params: Record<string, unknown>,
+  mutation: MutationFlags = YES,
+) {
+  const prev = process.cwd();
+  process.chdir(dir);
+  try {
+    return await executeVerb(
+      createComponentVerb,
+      params,
+      mutation,
+      bootRuntime(FLAGS, dir),
+    );
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+const walk = (dir: string, base = ""): string[] =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory()
+      ? walk(join(dir, e.name), join(base, e.name))
+      : [join(base, e.name)],
+  );
+
+describe("create — real generation + stamp", () => {
+  it("scaffolds a component and stamps generated files", async () => {
+    const dir = freshCwd();
+    const outcome = await runIn(dir, {
+      framework: "react",
+      componentPath: "src/components/Widget",
+      withStyles: true,
+      withStories: false,
+      withSsrTests: false,
+    });
+    expect(outcome.exitCode).toBe(0);
+    const main = join(dir, "src/components/Widget/Widget.tsx");
+    expect(existsSync(main)).toBe(true);
+    expect(readFileSync(main, "utf-8").split("\n")[0]).toBe(
+      "// Generated by @canonical/summon-component:react v0.1.0",
+    );
+  });
+
+  it("--dry-run writes nothing and previews effects (no Prompt lines)", async () => {
+    const dir = freshCwd();
+    const outcome = await runIn(
+      dir,
+      { framework: "react", componentPath: "src/components/Widget" },
+      { dryRun: true, undo: false, yes: false },
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("Widget.tsx");
+    expect(outcome.stdout).not.toContain("Prompt");
+    expect(walk(dir)).toEqual([]); // nothing written
+  });
+
+  it("--undo reverses a run", async () => {
+    const dir = freshCwd();
+    await runIn(dir, {
+      framework: "react",
+      componentPath: "src/components/Widget",
+      withStyles: false,
+      withStories: false,
+      withSsrTests: false,
+    });
+    const outcome = await runIn(
+      dir,
+      {
+        framework: "react",
+        componentPath: "src/components/Widget",
+        withStyles: false,
+        withStories: false,
+        withSsrTests: false,
+      },
+      { dryRun: false, undo: true, yes: true },
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toMatch(/Undid \d+ step/);
+  });
+
+  it("rejects an unknown framework with INVALID_INPUT", async () => {
+    const dir = freshCwd();
+    // coerceParam rejects the enum before run, so drive run directly via a bad
+    // framework param to exercise pickGenerator's own guard too.
+    const runtime = bootRuntime(FLAGS, dir);
+    await expect(
+      createComponentVerb.run({ framework: "vue" }, {
+        ...runtime,
+        interaction: { isTTY: false, transport: "cli", yes: true },
+      } as never),
+    ).rejects.toBeInstanceOf(PragmaError);
+  });
+});
+
+describe("SEC-2 path jail (PROTECTED)", () => {
+  const cases: Array<[string, string]> = [
+    ["a .. escape", "../evil/Widget"],
+    ["an absolute path", "/tmp/evil/Widget"],
+  ];
+  for (const [label, value] of cases) {
+    it(`rejects ${label} with a PragmaError before any effect`, async () => {
+      const dir = freshCwd();
+      // The jail throws in `run`, before any effect; the projector maps it to an
+      // exit code, but exercised directly here `executeVerb` propagates it.
+      await expect(
+        runIn(dir, { framework: "react", componentPath: value }),
+      ).rejects.toBeInstanceOf(PragmaError);
+      expect(walk(dir)).toEqual([]);
+    });
+  }
+
+  it("rejects a symlink that escapes the workspace (realpath)", async () => {
+    const root = freshCwd();
+    const outside = freshCwd();
+    // A symlink `link` inside the workspace pointing OUT of it.
+    symlinkSync(outside, join(root, "link"));
+    await expect(
+      runIn(root, { framework: "react", componentPath: "link/Widget" }),
+    ).rejects.toBeInstanceOf(PragmaError);
+    expect(existsSync(join(outside, "Widget"))).toBe(false);
+  });
+
+  it("accepts an in-workspace path", async () => {
+    const dir = freshCwd();
+    mkdirSync(join(dir, "packages"), { recursive: true });
+    const outcome = await runIn(dir, {
+      framework: "react",
+      componentPath: "packages/Widget",
+      withStyles: false,
+      withStories: false,
+      withSsrTests: false,
+    });
+    expect(outcome.exitCode).toBe(0);
+  });
+});
+
+describe("lazy-React discipline (PROTECTED)", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+
+  /** Walk the STATIC (relative-only) import graph from an entry .ts file. */
+  function staticGraph(entry: string, seen = new Set<string>()): Set<string> {
+    if (seen.has(entry) || !existsSync(entry)) return seen;
+    seen.add(entry);
+    const src = readFileSync(entry, "utf-8");
+    const re = /(?:\bfrom\s*|(?:^|\n)\s*import\s*)["']([^"']+)["']/g;
+    for (const m of src.matchAll(re)) {
+      const spec = m[1];
+      if (spec?.startsWith("."))
+        staticGraph(
+          resolve(dirname(entry), spec.replace(/\.js$/, ".ts")),
+          seen,
+        );
+    }
+    return seen;
+  }
+
+  it("the capability registry never statically reaches React/Ink or the generators", () => {
+    const graph = staticGraph(resolve(here, "../index.ts"));
+    // pickGenerator (which imports the heavy generators) is dynamic-only.
+    expect([...graph].some((f) => f.endsWith("create/pickGenerator.ts"))).toBe(
+      false,
+    );
+    const forbidden = [
+      "react",
+      "react-dom",
+      "ink",
+      "ink-select-input",
+      "ink-text-input",
+      "ink-spinner",
+      "@canonical/summon-component",
+      "@canonical/summon-package",
+      "@canonical/summon-application",
+    ];
+    for (const file of graph) {
+      const src = readFileSync(file, "utf-8");
+      for (const pkg of forbidden) {
+        const esc = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        expect(
+          new RegExp(`from\\s*["']${esc}["']`).test(src),
+          `${file} statically imports ${pkg}`,
+        ).toBe(false);
+      }
+    }
+  });
+
+  it("running create --yes never loads React or Ink", async () => {
+    const dir = freshCwd();
+    await runIn(dir, {
+      framework: "react",
+      componentPath: "src/components/Widget",
+      withStyles: false,
+      withStories: false,
+      withSsrTests: false,
+    });
+    const isReactPkg = (k: string) =>
+      /[\\/](react|react-dom|ink|ink-select-input|ink-text-input|ink-spinner)@\d/.test(
+        k,
+      ) ||
+      /[\\/]node_modules[\\/](react|react-dom|ink|ink-select-input|ink-text-input|ink-spinner)[\\/]/.test(
+        k,
+      );
+    const loaded = Object.keys(require.cache ?? {});
+    expect(loaded.filter(isReactPkg)).toEqual([]);
+  });
+});
+
+describe("generator→grammar adapter parity (PROTECTED)", () => {
+  // The static mirrors in create.verb.ts are AUTHORITATIVE for omitted CLI
+  // flags: dispatch.extractParams fills ParamSpec.default when a flag is absent,
+  // so a drifted mirror default silently overrides the generator's own default.
+  // These guards assert the EMITTED grammar (names, kinds, defaults, choices)
+  // still matches the real generators for all three create nouns — the
+  // byte-equality goldens can't catch this (they pass every param explicitly).
+
+  /** Drop `doc` (help text is intentionally paraphrased in the mirrors) so the
+   * comparison is purely behavioural: names, kinds, defaults, choices. */
+  const behavioural = (
+    params: readonly ParamSpec[],
+  ): Record<string, unknown>[] =>
+    params.map((p) => {
+      const clone: Record<string, unknown> = { ...p };
+      delete clone.doc;
+      return clone;
+    });
+
+  /** `runInstall` is a DELIBERATE divergence (package + application): the real
+   * generators default it `true`, but the CLI grammar has no `--no-` form, so
+   * the mirror makes install opt-in (`default:false`, enabled by `--run-install`).
+   * Apply that same override to the generator side before comparing. */
+  const applyRunInstallOverride = (params: readonly ParamSpec[]): ParamSpec[] =>
+    params.map((p) =>
+      p.name === "runInstall" ? ({ ...p, default: false } as ParamSpec) : p,
+    );
+
+  it("component: framework collapse + shared confirms match the react generator", async () => {
+    const { generators } = await import("@canonical/summon-component");
+    const real = generatorToParams(
+      (generators as Record<string, { prompts: unknown[] }>)["component/react"]
+        .prompts as never,
+    );
+    const verb = createComponentVerb.params;
+
+    // The verb SYNTHESIZES a `framework` enum (the 3 framework generators
+    // collapse to one verb): react|svelte|lit, default react — no generator
+    // prompt corresponds to it.
+    expect(verb.find((p) => p.name === "framework")).toMatchObject({
+      kind: "enum",
+      values: ["react", "svelte", "lit"],
+      default: "react",
+    });
+
+    // componentPath deliberately drops its ParamSpec default so the SELECTED
+    // framework's own prompt default applies (react vs svelte/lit differ).
+    const verbPath = verb.find((p) => p.name === "componentPath") as
+      | Record<string, unknown>
+      | undefined;
+    const realPath = real.find((p) => p.name === "componentPath") as
+      | Record<string, unknown>
+      | undefined;
+    expect(verbPath).toMatchObject({
+      kind: "string",
+      positional: true,
+      complete: { kind: "files" },
+    });
+    expect(verbPath?.default).toBeUndefined();
+    expect(realPath?.default).toBe("src/components/MyComponent");
+
+    // Every other prompt (the shared confirms) must match names, kinds, AND
+    // defaults exactly — the silent-drift surface.
+    const shared = (ps: readonly ParamSpec[]) =>
+      behavioural(
+        ps.filter((p) => p.name !== "framework" && p.name !== "componentPath"),
+      );
+    expect(shared(verb)).toEqual(shared(real));
+  });
+
+  it("package: mirror matches the package generator (defaults + type choices)", async () => {
+    const { generators } = await import("@canonical/summon-package");
+    const real = generatorToParams(
+      (generators as Record<string, { prompts: unknown[] }>).package
+        .prompts as never,
+    );
+    // The package verb's grammar IS generatorToParams(PACKAGE_MIRROR).
+    expect(behavioural(createPackageVerb.params)).toEqual(
+      behavioural(applyRunInstallOverride(real)),
+    );
+
+    // Guard the intentional runInstall override so it can't silently flip.
+    const realRunInstall = real.find((p) => p.name === "runInstall") as
+      | Record<string, unknown>
+      | undefined;
+    const mirrorRunInstall = createPackageVerb.params.find(
+      (p) => p.name === "runInstall",
+    ) as Record<string, unknown> | undefined;
+    expect(realRunInstall?.default).toBe(true);
+    expect(mirrorRunInstall?.default).toBe(false);
+
+    // The `--type` enum choices are load-bearing and must match exactly.
+    const realType = real.find((p) => p.name === "type");
+    expect(realType).toMatchObject({
+      kind: "enum",
+      values: ["tool-ts", "library", "css"],
+      default: "tool-ts",
+    });
+  });
+
+  it("application: mirror matches the application/react generator (defaults)", async () => {
+    const { generators } = await import("@canonical/summon-application");
+    const real = generatorToParams(
+      (generators as Record<string, { prompts: unknown[] }>)[
+        "application/react"
+      ].prompts as never,
+    );
+    expect(behavioural(createApplicationVerb.params)).toEqual(
+      behavioural(applyRunInstallOverride(real)),
+    );
+
+    const realRunInstall = real.find((p) => p.name === "runInstall") as
+      | Record<string, unknown>
+      | undefined;
+    const mirrorRunInstall = createApplicationVerb.params.find(
+      (p) => p.name === "runInstall",
+    ) as Record<string, unknown> | undefined;
+    expect(realRunInstall?.default).toBe(true);
+    expect(mirrorRunInstall?.default).toBe(false);
+
+    // appPath is the positional entry point (its default carries across).
+    expect(
+      createApplicationVerb.params.find((p) => p.name === "appPath"),
+    ).toMatchObject({ kind: "string", positional: true, default: "my-app" });
+  });
+});
+
+describe("compiled-binary create gate (M4)", () => {
+  it("detects a module-resolution failure but not a genuine runtime error", () => {
+    // bun --compile's unresolved-specifier error (the shipped-binary case).
+    expect(
+      isModuleNotFound({
+        name: "ResolveMessage",
+        message: "Cannot find module './pickGenerator.js'",
+      }),
+    ).toBe(true);
+    // node ESM's resolution error.
+    expect(
+      isModuleNotFound(
+        Object.assign(new Error("x"), { code: "ERR_MODULE_NOT_FOUND" }),
+      ),
+    ).toBe(true);
+    // A REAL runtime bug in a source build must still propagate (not be masked
+    // as "run from source").
+    expect(
+      isModuleNotFound(new TypeError("cannot read properties of undefined")),
+    ).toBe(false);
+    expect(isModuleNotFound(null)).toBe(false);
+    expect(isModuleNotFound("nope")).toBe(false);
+  });
+});