@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/testing/integration/cli-user-stories.test.ts

@@ -52,6 +52,30 @@ function parseJson<T>(result: CommandResult): T {
 }
 
 describe("CLI user stories", () => {
+  it("story: a first-time user is greeted once and gets a global config", () => {
+    const workspace = createWorkspace();
+    const freshXdg = mkdtempSync(join(tmpdir(), "pragma-firstrun-e2e-"));
+    tempDirs.add(freshXdg);
+    const env = { XDG_CONFIG_HOME: freshXdg };
+
+    // First invocation: greeting on stderr, config created, stdout untouched.
+    const first = runCommand(["info", "--format", "json"], workspace, env);
+    expect(first.exitCode).toBe(0);
+    expect(first.stderr).toContain("pre-release pragma CLI");
+    expect(first.stderr).toContain(join(freshXdg, "pragma", "config.json"));
+    expect(() => JSON.parse(first.stdout)).not.toThrow();
+    expect(
+      JSON.parse(
+        readFileSync(join(freshXdg, "pragma", "config.json"), "utf-8"),
+      ),
+    ).toEqual({});
+
+    // Second invocation: no greeting — first-run happens once.
+    const second = runCommand(["info", "--format", "json"], workspace, env);
+    expect(second.exitCode).toBe(0);
+    expect(second.stderr.trim()).toBe("");
+  }, 40_000);
+
   it("story: a new contributor verifies the local installation with info", () => {
     const workspace = createWorkspace();
 
@@ -195,4 +219,43 @@ describe("CLI user stories", () => {
     expect(existsSync(indexFile)).toBe(true);
     expect(readFileSync(indexFile, "utf-8")).toContain("./MySth");
   }, 20_000);
+
+  it("story: --version works at the root, noun, and verb levels", () => {
+    const workspace = createWorkspace();
+    const root = runCommand(["--version"], workspace);
+    const verb = runCommand(["block", "list", "--version"], workspace);
+
+    expectSuccess(root);
+    expectSuccess(verb);
+    expect(root.stdout.trim()).toBe(verb.stdout.trim());
+    expect(root.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+  }, 20_000);
+
+  it("story: an unknown verb under a known noun lists that noun's verbs", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(["standard", "frobnicate"], workspace);
+
+    expect(result.exitCode).not.toBe(0);
+    // Errors, then defers to the category that exists.
+    expect(result.stderr).toContain("unknown command 'frobnicate'");
+    expect(result.stderr).toContain("pragma standard <verb>");
+    expect(result.stderr).toContain("list");
+    expect(result.stderr).toContain("lookup");
+  }, 20_000);
+
+  it("story: a global flag before the noun still lists that noun's verbs", () => {
+    const workspace = createWorkspace();
+
+    // `--format json` sits before the noun; the flag *value* (`json`) must not
+    // be mistaken for the noun, or no verbs would be suggested.
+    const result = runCommand(
+      ["--format", "json", "standard", "frobnicate"],
+      workspace,
+    );
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("pragma standard <verb>");
+    expect(result.stderr).toContain("lookup");
+  }, 20_000);
 });

package/src/testing/integration/cross-binary-byte-equality.test.ts

@@ -0,0 +1,129 @@
+/**
+ * The P.05 byte-equality gate: `pragma create X` and `summon X` must write
+ * identical bytes for the same generator invocation.
+ *
+ * Both binaries reduce to compositions over the shared execution core:
+ * pragma's batch path is `executeGenerator` (which stamps via
+ * `createStampOnEffectStart`), and summon's Ink executor runs
+ * `runGeneratorTask` with the same stamp transform and the defaults prompt
+ * handler. This test runs both compositions over the real generators into
+ * separate directories and asserts the trees are byte-identical — stamps
+ * included.
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import {
+  answerPromptWithDefaults,
+  createGeneratorStamp,
+  createStampOnEffectStart,
+  executeGenerator,
+  runGeneratorTask,
+} from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
+import type { GeneratorDefinition } from "@canonical/summon-core";
+import { generators as packageGenerators } from "@canonical/summon-package";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+interface Case {
+  readonly name: string;
+  readonly gen: GeneratorDefinition;
+  readonly answers: Record<string, unknown>;
+}
+
+const cases: Case[] = [
+  {
+    name: "component/react",
+    gen: componentGenerators["component/react"] as GeneratorDefinition,
+    answers: { componentPath: "src/components/Button" },
+  },
+  {
+    name: "package/library",
+    gen: packageGenerators.package as GeneratorDefinition,
+    answers: { name: "@canonical/example", type: "library" },
+  },
+];
+
+/** Collect every file under root as relative path → raw content bytes. */
+const readTree = (root: string, dir = root): Map<string, Buffer> => {
+  const files = new Map<string, Buffer>();
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      for (const [k, v] of readTree(root, full)) files.set(k, v);
+    } else {
+      files.set(relative(root, full), readFileSync(full));
+    }
+  }
+  return files;
+};
+
+describe("cross-binary byte equality — pragma create ≡ summon", () => {
+  let dir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    dir = mkdtempSync(join(tmpdir(), "byte-equality-"));
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  for (const testCase of cases) {
+    it(`${testCase.name} — both binaries write identical bytes, stamps included`, async () => {
+      const pragmaDir = join(dir, "pragma");
+      const summonDir = join(dir, "summon");
+      mkdirSync(pragmaDir);
+      mkdirSync(summonDir);
+
+      // pragma path: the create command's batch execution (stamps by default).
+      const result = await executeGenerator(
+        testCase.gen,
+        { ...testCase.answers, yes: true },
+        {
+          cwd: pragmaDir,
+          globalFlags: { llm: false, format: "text", verbose: false },
+        },
+      );
+      expect(result.tag).toBe("output");
+
+      // summon path: the Ink executor's exact composition over the shared
+      // core. Both binaries fold prompt defaults into the answers before
+      // generating; do the same here.
+      const answers = { ...testCase.answers };
+      for (const prompt of testCase.gen.prompts) {
+        if (!(prompt.name in answers) && prompt.default !== undefined) {
+          answers[prompt.name] = prompt.default;
+        }
+      }
+      await runGeneratorTask(testCase.gen.generate(answers), {
+        cwd: summonDir,
+        promptHandler: answerPromptWithDefaults,
+        onEffectStart: createStampOnEffectStart(
+          createGeneratorStamp(testCase.gen),
+        ),
+      });
+
+      const pragmaTree = readTree(pragmaDir);
+      const summonTree = readTree(summonDir);
+
+      expect([...pragmaTree.keys()].sort()).toEqual(
+        [...summonTree.keys()].sort(),
+      );
+      for (const [path, content] of pragmaTree) {
+        expect(summonTree.get(path)?.equals(content), path).toBe(true);
+      }
+      expect(pragmaTree.size).toBeGreaterThan(0);
+    });
+  }
+});

package/src/testing/integration/edge-cases.test.ts

@@ -10,6 +10,7 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../domains/token/featureFlag.js";
 import createTestMcpClient from "../helpers/createTestMcpClient.js";
 import createTestRuntime from "../helpers/createTestRuntime.js";
 
@@ -122,21 +123,24 @@ describe("all-fail batch lookups", () => {
     expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
   });
 
-  it("token_lookup: unknown token → error", async () => {
-    const res = await client.callTool({
-      name: "token_lookup",
-      arguments: { names: ["color.nonexistent"] },
-    });
-    const body = parseEnvelope(res);
-    expect(body.ok).toBe(true);
-    const data = body.data as {
-      results: unknown[];
-      errors: { query: string; code: string }[];
-    };
-    expect(data.results).toHaveLength(0);
-    expect(data.errors).toHaveLength(1);
-    expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_lookup: unknown token → error",
+    async () => {
+      const res = await client.callTool({
+        name: "token_lookup",
+        arguments: { names: ["color.nonexistent"] },
+      });
+      const body = parseEnvelope(res);
+      expect(body.ok).toBe(true);
+      const data = body.data as {
+        results: unknown[];
+        errors: { query: string; code: string }[];
+      };
+      expect(data.results).toHaveLength(0);
+      expect(data.errors).toHaveLength(1);
+      expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
+    },
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -144,33 +148,38 @@ describe("all-fail batch lookups", () => {
 // ---------------------------------------------------------------------------
 
 describe("empty result sets", () => {
-  it("standard_list with nonexistent category → error envelope", async () => {
+  it("standard_list with nonexistent category → empty rows", async () => {
     const res = await client.callTool({
       name: "standard_list",
       arguments: { category: "nonexistent_category" },
     });
     const body = parseEnvelope(res);
-    // resolveStandardList throws when no results found
-    expect(body.ok).toBe(false);
-    const error = body.error as { code: string };
-    expect(error.code).toBeDefined();
+    // The bundled pack's value-free category filter returns zero rows for
+    // an unmatched value; the old EMPTY_RESULTS error is a pinned
+    // PARITY_GAP of the standard cutover (packs have no emptyError hook).
+    expect(body.ok).toBe(true);
+    expect(body.data).toEqual([]);
+    expect((body.meta as { count: number }).count).toBe(0);
   });
 
-  it("token_list with nonexistent category → empty or error", async () => {
-    const res = await client.callTool({
-      name: "token_list",
-      arguments: { category: "NonexistentType" },
-    });
-    const body = parseEnvelope(res);
-    if (body.ok) {
-      const data = body.data as unknown[];
-      expect(data).toHaveLength(0);
-    } else {
-      // Token list may throw on empty results
-      const error = body.error as { code: string };
-      expect(error.code).toBeDefined();
-    }
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_list with nonexistent category → empty or error",
+    async () => {
+      const res = await client.callTool({
+        name: "token_list",
+        arguments: { category: "NonexistentType" },
+      });
+      const body = parseEnvelope(res);
+      if (body.ok) {
+        const data = body.data as unknown[];
+        expect(data).toHaveLength(0);
+      } else {
+        // Token list may throw on empty results
+        const error = body.error as { code: string };
+        expect(error.code).toBeDefined();
+      }
+    },
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -245,19 +254,22 @@ describe("condensed mode error rendering", () => {
     expect(text).toContain("nonexistent");
   });
 
-  it("token_lookup condensed: includes error for unknown token", async () => {
-    const res = await client.callTool({
-      name: "token_lookup",
-      arguments: {
-        names: ["color.primary", "color.nonexistent"],
-        condensed: true,
-      },
-    });
-    const body = parseEnvelope(res);
-    expect(body.condensed).toBe(true);
-    const text = body.text as string;
-    expect(text).toContain("color.primary");
-    expect(text).toContain("Errors");
-    expect(text).toContain("color.nonexistent");
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_lookup condensed: includes error for unknown token",
+    async () => {
+      const res = await client.callTool({
+        name: "token_lookup",
+        arguments: {
+          names: ["color.primary", "color.nonexistent"],
+          condensed: true,
+        },
+      });
+      const body = parseEnvelope(res);
+      expect(body.condensed).toBe(true);
+      const text = body.text as string;
+      expect(text).toContain("color.primary");
+      expect(text).toContain("Errors");
+      expect(text).toContain("color.nonexistent");
+    },
+  );
 });

package/src/testing/integration/executor-execution.test.ts

@@ -0,0 +1,103 @@
+/**
+ * End-to-end characterization of the real-execution path the executor merge
+ * (4a) rewired: every generator the CLI actually dispatches, and a real setup
+ * task, run through the shared UI-free core ({@link runGeneratorTask}) and
+ * produce their files on disk.
+ *
+ * The golden snapshots (executor-golden.test.ts) lock the *preview* modes
+ * (dry-run/json/llm), which never execute. This locks the *real* run: the
+ * merged core executes the genuine task trees — not test doubles — with the
+ * correct working-directory semantics.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runGeneratorTask } from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
+import { generators as packageGenerators } from "@canonical/summon-package";
+import type { Task } from "@canonical/task";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import setupMcp from "../../domains/setup/operations/setupMcp.js";
+
+interface Case {
+  readonly name: string;
+  readonly build: () => Task<unknown>;
+}
+
+const componentParams = { componentPath: "src/components/Button" };
+const packageParams = { name: "@canonical/example", type: "library" };
+
+const cases: Case[] = [
+  {
+    name: "component/react",
+    build: () =>
+      componentGenerators["component/react"].generate(componentParams),
+  },
+  {
+    name: "component/svelte",
+    build: () =>
+      componentGenerators["component/svelte"].generate(componentParams),
+  },
+  {
+    name: "component/lit",
+    build: () => componentGenerators["component/lit"].generate(componentParams),
+  },
+  {
+    name: "package/library",
+    build: () => packageGenerators.package.generate(packageParams),
+  },
+];
+
+const countFiles = (root: string): number => {
+  let total = 0;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    total += entry.isDirectory() ? countFiles(join(root, entry.name)) : 1;
+  }
+  return total;
+};
+
+describe("shared executor — real execution over the dispatched tasks", () => {
+  let dir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    dir = mkdtempSync(join(tmpdir(), "executor-execution-"));
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  for (const testCase of cases) {
+    it(`${testCase.name} — executes for real in the target cwd`, async () => {
+      const targetDir = join(dir, "target");
+      mkdirSync(targetDir);
+
+      await runGeneratorTask(testCase.build(), { cwd: targetDir });
+
+      expect(countFiles(targetDir)).toBeGreaterThan(0);
+      expect(process.cwd()).toBe(originalCwd);
+    });
+  }
+
+  // A real setup task on the rewired production surface. setupMcp in force
+  // mode writes root-relative config (no prompts, no home-dir writes), so it
+  // is safe to execute in a sandbox.
+  it("setup/mcp (force) — writes the harness config for real", async () => {
+    const root = join(dir, "project");
+    mkdirSync(root);
+
+    await runGeneratorTask(setupMcp(root, "cursor"));
+
+    expect(existsSync(join(root, ".cursor", "mcp.json"))).toBe(true);
+  });
+});

package/src/testing/integration/executor-golden.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Characterization (golden) snapshots of the two current executors —
+ * `executeGenerator` (cli-core, drives `pragma create`) and `runSetupTask`
+ * (drives `pragma setup`) — across the real generators and setup tasks.
+ *
+ * These lock the *observable output* of each executor for representative,
+ * fully-answered inputs in every non-interactive mode. Both executors now run
+ * real execution through the shared UI-free core (`runGeneratorTask`), and the
+ * merged path must keep reproducing these byte-for-byte; the execution
+ * characterization test alongside asserts the real-run path. Interactive
+ * behavior is characterized separately, since it runs through the injected
+ * `promptHandler` seam.
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CommandContext, CommandResult } from "@canonical/cli-core";
+import { executeGenerator } from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
+import { generators as packageGenerators } from "@canonical/summon-package";
+import { describe, expect, it } from "vitest";
+import runSetupTask from "../../domains/setup/helpers/runSetupTask.js";
+import setupCompletions from "../../domains/setup/operations/setupCompletions.js";
+import setupLsp from "../../domains/setup/operations/setupLsp.js";
+
+const ROOT = "/tmp/characterization-project";
+
+const ctx = (format: "text" | "json", llm = false): CommandContext => ({
+  cwd: ROOT,
+  globalFlags: { llm, format, verbose: false },
+});
+
+/**
+ * Render an executor result to the plain string a user would see, with
+ * environment-specific bytes normalised so a committed baseline compares
+ * equal on every machine and in CI: ANSI color codes are stripped (chalk
+ * enables them under nx's FORCE_COLOR in CI but not in a plain local run),
+ * then the repo checkout root (package-generator plans embed absolute
+ * template source paths) and the home directory (shell-completion install
+ * targets embed `$HOME`) become stable tokens. The repo root is replaced
+ * first — on a dev machine it usually lives under `$HOME`.
+ */
+const plain = (result: CommandResult): string => {
+  let text =
+    result.tag === "output"
+      ? result.render.plain(result.value)
+      : `[${result.tag}]`;
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching the ANSI escape byte is the point
+  text = text.replace(/\u001b\[[0-9;]*m/g, "");
+  const repoRoot = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "../../../../../..",
+  );
+  text = text.split(repoRoot).join("<repo>");
+  const home = process.env.HOME ?? "";
+  return home === "" ? text : text.split(home).join("<home>");
+};
+
+// =============================================================================
+// create — executeGenerator across the real component + package generators
+// =============================================================================
+
+const componentParams = { componentPath: "src/components/Button" };
+const packageParams = { name: "@canonical/example", type: "library" };
+
+describe("golden: executeGenerator — components", () => {
+  for (const framework of ["react", "svelte", "lit"] as const) {
+    const gen = componentGenerators[`component/${framework}`];
+
+    it(`${framework} — dry-run plan`, async () => {
+      const result = await executeGenerator(
+        gen,
+        { ...componentParams, dryRun: true },
+        ctx("text"),
+      );
+      expect(plain(result)).toMatchSnapshot();
+    });
+
+    it(`${framework} — json plan`, async () => {
+      const result = await executeGenerator(
+        gen,
+        { ...componentParams },
+        ctx("json"),
+      );
+      expect(plain(result)).toMatchSnapshot();
+    });
+
+    it(`${framework} — llm plan`, async () => {
+      const result = await executeGenerator(
+        gen,
+        { ...componentParams },
+        ctx("text", true),
+      );
+      expect(plain(result)).toMatchSnapshot();
+    });
+  }
+});
+
+describe("golden: executeGenerator — package", () => {
+  const gen = packageGenerators.package;
+
+  it("library — dry-run plan", async () => {
+    const result = await executeGenerator(
+      gen,
+      { ...packageParams, dryRun: true },
+      ctx("text"),
+    );
+    expect(plain(result)).toMatchSnapshot();
+  });
+
+  it("library — json plan", async () => {
+    const result = await executeGenerator(
+      gen,
+      { ...packageParams },
+      ctx("json"),
+    );
+    expect(plain(result)).toMatchSnapshot();
+  });
+});
+
+// =============================================================================
+// setup — runSetupTask across representative deterministic setup tasks
+// =============================================================================
+
+describe("golden: runSetupTask — setups", () => {
+  it("lsp — dry-run", async () => {
+    const result = await runSetupTask(setupLsp(ROOT), { dryRun: true });
+    expect(plain(result)).toMatchSnapshot();
+  });
+
+  it("completions (bash) — dry-run", async () => {
+    const result = await runSetupTask(setupCompletions("bash"), {
+      dryRun: true,
+    });
+    expect(plain(result)).toMatchSnapshot();
+  });
+
+  it("lsp — dry-run json", async () => {
+    const result = await runSetupTask(setupLsp(ROOT), {
+      dryRun: true,
+      format: "json",
+    });
+    expect(plain(result)).toMatchSnapshot();
+  });
+});