@canonical/pragma-cli 0.20.0 → 0.21.0

package/src/pipeline/runInteractiveCommand.ts

@@ -0,0 +1,198 @@
+import { stdout as processStdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import {
+  createExitResult,
+  type InteractiveHandler,
+  type InteractiveSpec,
+} from "@canonical/cli-core";
+
+type PromptWithWhen = InteractiveSpec["generator"]["prompts"][number] & {
+  readonly when?: ((answers: Record<string, unknown>) => boolean) | undefined;
+};
+
+const isInteractiveTerminal = (): boolean =>
+  process.stdin.isTTY === true && process.stdout.isTTY === true;
+
+const getPromptDefault = (
+  prompt: PromptWithWhen,
+  answers: Record<string, unknown>,
+): unknown => {
+  if (prompt.name in answers) {
+    return answers[prompt.name];
+  }
+  return prompt.default;
+};
+
+async function promptForText(
+  rl: ReturnType<typeof createInterface>,
+  prompt: PromptWithWhen,
+  answers: Record<string, unknown>,
+): Promise<string> {
+  const defaultValue = getPromptDefault(prompt, answers);
+  const defaultSuffix =
+    defaultValue !== undefined ? ` (${String(defaultValue)})` : "";
+
+  while (true) {
+    const response = (
+      await rl.question(`${prompt.message}${defaultSuffix}: `)
+    ).trim();
+    if (response.length > 0) {
+      return response;
+    }
+    if (defaultValue !== undefined) {
+      return String(defaultValue);
+    }
+  }
+}
+
+async function promptForConfirm(
+  rl: ReturnType<typeof createInterface>,
+  prompt: PromptWithWhen,
+  answers: Record<string, unknown>,
+): Promise<boolean> {
+  const defaultValue = getPromptDefault(prompt, answers);
+  const hint =
+    defaultValue === true ? "Y/n" : defaultValue === false ? "y/N" : "y/n";
+
+  while (true) {
+    const response = (await rl.question(`${prompt.message} [${hint}]: `))
+      .trim()
+      .toLowerCase();
+
+    if (response.length === 0 && defaultValue !== undefined) {
+      return Boolean(defaultValue);
+    }
+    if (["y", "yes"].includes(response)) {
+      return true;
+    }
+    if (["n", "no"].includes(response)) {
+      return false;
+    }
+  }
+}
+
+async function promptForSelect(
+  rl: ReturnType<typeof createInterface>,
+  prompt: PromptWithWhen,
+  answers: Record<string, unknown>,
+  multiple: boolean,
+): Promise<string | string[]> {
+  const choices = prompt.choices ?? [];
+  const defaultValue = getPromptDefault(prompt, answers);
+
+  if (choices.length === 0) {
+    return multiple
+      ? Array.isArray(defaultValue)
+        ? defaultValue.map(String)
+        : defaultValue !== undefined
+          ? [String(defaultValue)]
+          : []
+      : String(defaultValue ?? "");
+  }
+
+  processStdout.write(`${prompt.message}\n`);
+  choices.forEach((choice, index) => {
+    processStdout.write(`  ${index + 1}) ${choice.label}\n`);
+  });
+
+  const defaultSuffix =
+    defaultValue === undefined
+      ? ""
+      : ` (${Array.isArray(defaultValue) ? defaultValue.join(",") : String(defaultValue)})`;
+
+  while (true) {
+    const response = (
+      await rl.question(
+        multiple
+          ? `Choose one or more values${defaultSuffix}: `
+          : `Choose a value${defaultSuffix}: `,
+      )
+    ).trim();
+
+    if (response.length === 0 && defaultValue !== undefined) {
+      return multiple
+        ? Array.isArray(defaultValue)
+          ? defaultValue.map(String)
+          : [String(defaultValue)]
+        : String(defaultValue);
+    }
+
+    const parsed = response
+      .split(",")
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0)
+      .map((part) => {
+        const index = Number(part);
+        if (Number.isInteger(index) && index >= 1 && index <= choices.length) {
+          return choices[index - 1]?.value;
+        }
+
+        const matched = choices.find(
+          (choice) => choice.value === part || choice.label === part,
+        );
+        return matched?.value;
+      })
+      .filter((value): value is string => typeof value === "string");
+
+    if (parsed.length === 0) {
+      continue;
+    }
+
+    return multiple ? parsed : (parsed[0] ?? String(defaultValue ?? ""));
+  }
+}
+
+async function promptForValue(
+  rl: ReturnType<typeof createInterface>,
+  prompt: PromptWithWhen,
+  answers: Record<string, unknown>,
+): Promise<unknown> {
+  switch (prompt.type) {
+    case "confirm":
+      return promptForConfirm(rl, prompt, answers);
+    case "select":
+      return promptForSelect(rl, prompt, answers, false);
+    case "multiselect":
+      return promptForSelect(rl, prompt, answers, true);
+    default:
+      return promptForText(rl, prompt, answers);
+  }
+}
+
+const runInteractiveCommand: InteractiveHandler = async ({
+  spec,
+  command,
+  params,
+  ctx,
+}) => {
+  if (!isInteractiveTerminal()) {
+    return null;
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answers: Record<string, unknown> = { ...spec.partialAnswers };
+
+  try {
+    processStdout.write("\n");
+
+    for (const prompt of spec.generator.prompts as readonly PromptWithWhen[]) {
+      if (prompt.when && prompt.when(answers) !== true) {
+        continue;
+      }
+
+      answers[prompt.name] = await promptForValue(rl, prompt, answers);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      process.exitCode = 130;
+      return createExitResult(130);
+    }
+    throw error;
+  } finally {
+    rl.close();
+  }
+
+  return command.execute({ ...params, ...answers, yes: true }, ctx);
+};
+
+export default runInteractiveCommand;

package/src/testing/cli.ts

@@ -29,7 +29,7 @@ function runCommand(args: string[], cwd?: string): CommandResult {
   const result = spawnSync("bun", ["run", binPath, ...args], {
     cwd,
     encoding: "utf-8",
-    timeout: 10_000,
+    timeout: 20_000,
   });
 
   return {
@@ -39,5 +39,5 @@ function runCommand(args: string[], cwd?: string): CommandResult {
   };
 }
 
-export { runCommand };
 export type { CommandResult };
+export { runCommand };

package/src/testing/fixtures.ts

@@ -27,8 +27,8 @@ const MOCK_BIN_PATHS: Record<string, string> = {
 };
 
 export {
+  MOCK_BIN_PATHS,
+  SAMPLE_CONFIG_EMPTY,
   SAMPLE_CONFIG_FULL,
   SAMPLE_CONFIG_TIER_ONLY,
-  SAMPLE_CONFIG_EMPTY,
-  MOCK_BIN_PATHS,
 };

package/src/testing/integration/boot.test.ts

@@ -26,13 +26,13 @@ describe("PragmaRuntime boot", () => {
     expect(rt.config.channel).toBe("normal");
   });
 
-  it("boots in under 100ms", async () => {
+  it("boots in under 250ms", async () => {
     const start = performance.now();
     const rt = await createTestRuntime();
     const elapsed = performance.now() - start;
     runtimes.push(rt);
 
-    expect(elapsed).toBeLessThan(100);
+    expect(elapsed).toBeLessThan(250);
   });
 
   it("respects filtered config for tier", async () => {

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

@@ -0,0 +1,198 @@
+/**
+ * Layer 4b: CLI user-story end-to-end tests.
+ *
+ * Runs the real `pragma` binary through subprocesses and validates
+ * realistic user journeys against its JSON output.
+ */
+
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { type CommandResult, runCommand } from "../cli.js";
+
+const tempDirs = new Set<string>();
+
+afterEach(() => {
+  for (const dir of tempDirs) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  tempDirs.clear();
+});
+
+function createWorkspace(config?: Record<string, unknown>): string {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-cli-e2e-"));
+  tempDirs.add(dir);
+
+  if (config !== undefined) {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      `${JSON.stringify(config, null, 2)}\n`,
+      "utf-8",
+    );
+  }
+
+  return dir;
+}
+
+function expectSuccess(result: CommandResult): void {
+  expect(result.exitCode).toBe(0);
+  expect(result.stderr.trim()).toBe("");
+}
+
+function parseJson<T>(result: CommandResult): T {
+  expectSuccess(result);
+  return JSON.parse(result.stdout) as T;
+}
+
+describe("CLI user stories", () => {
+  it("story: a new contributor verifies the local installation with info", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(["info", "--format", "json"], workspace);
+    const data = parseJson<{
+      version: string;
+      pm: string;
+      installSource: string;
+      channel: string;
+      store: { tripleCount: number };
+    }>(result);
+
+    expect(data.version).toMatch(/^\d+\.\d+\.\d+/);
+    expect(data.pm).toBe("bun");
+    expect(data.installSource).toContain("local");
+    expect(data.channel).toBe("normal");
+    expect(data.store.tripleCount).toBeGreaterThan(0);
+  }, 20_000);
+
+  it("story: an explorer sees duplicate Button matches before scoping the workspace", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(
+      ["block", "lookup", "button", "--format", "json"],
+      workspace,
+    );
+    const data = parseJson<{
+      results: { name: string; tier: string }[];
+      errors: unknown[];
+    }>(result);
+
+    expect(data.errors).toEqual([]);
+    expect(data.results.length).toBeGreaterThan(1);
+    expect(data.results.every((item) => item.name === "Button")).toBe(true);
+    expect(data.results.some((item) => item.tier === "global")).toBe(true);
+  }, 20_000);
+
+  it("story: an app engineer scopes to global and resolves Button case-insensitively", () => {
+    const workspace = createWorkspace({ tier: "global", channel: "normal" });
+
+    const configResult = runCommand(
+      ["config", "show", "--format", "json"],
+      workspace,
+    );
+    const config = parseJson<{
+      tier: string;
+      channel: string;
+      configFileExists: boolean;
+      configFilePath: string;
+    }>(configResult);
+
+    expect(config.tier).toBe("global");
+    expect(config.channel).toBe("normal");
+    expect(config.configFileExists).toBe(true);
+    expect(config.configFilePath).toContain("pragma.config.json");
+
+    const lookupResult = runCommand(
+      ["block", "lookup", "button", "--format", "json"],
+      workspace,
+    );
+    const block = parseJson<{
+      name: string;
+      tier: string;
+      uri: string;
+    }>(lookupResult);
+
+    expect(block.name).toBe("Button");
+    expect(block.tier).toBe("global");
+    expect(block.uri).toContain("global.component.button");
+  }, 20_000);
+
+  it("story: a standards auditor inspects a code rule in structured output", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(
+      ["standard", "lookup", "code/function/purity", "--format", "json"],
+      workspace,
+    );
+    const standard = parseJson<{
+      name: string;
+      category: string;
+      description: string;
+    }>(result);
+
+    expect(standard.name).toBe("code/function/purity");
+    expect(standard.category).toBe("code");
+    expect(standard.description.toLowerCase()).toContain("pure");
+  }, 20_000);
+
+  it("story: a component author previews a React scaffold before writing files", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(
+      [
+        "create",
+        "component",
+        "react",
+        "src/components/Button",
+        "--dry-run",
+        "--yes",
+        "--format",
+        "json",
+      ],
+      workspace,
+    );
+    const plan = parseJson<{
+      generator: { name: string };
+      answers: { componentPath: string };
+      plan: { action: string; path: string }[];
+      files: Record<string, string>;
+    }>(result);
+
+    expect(plan.generator.name).toBe("component/react");
+    expect(plan.answers.componentPath).toBe("src/components/Button");
+    expect(
+      plan.plan.some(
+        (step) =>
+          step.action === "create" &&
+          step.path === "src/components/Button/Button.tsx",
+      ),
+    ).toBe(true);
+    expect(plan.files).toHaveProperty("src/components/Button/styles.css");
+    expect(plan.files).toHaveProperty("src/components/index.ts");
+  }, 20_000);
+
+  it("story: a component author can create a React scaffold from positional args", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(
+      ["create", "component", "react", "MySth"],
+      workspace,
+    );
+
+    expectSuccess(result);
+    expect(result.stdout).toContain("Generation complete.");
+
+    const componentFile = join(workspace, "MySth", "MySth.tsx");
+    const indexFile = join(workspace, "MySth", "index.ts");
+
+    expect(existsSync(componentFile)).toBe(true);
+    expect(existsSync(indexFile)).toBe(true);
+    expect(readFileSync(indexFile, "utf-8")).toContain("./MySth");
+  }, 20_000);
+});

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

@@ -0,0 +1,263 @@
+/**
+ * Layer 3b: Edge-case and error-path tests.
+ *
+ * Covers error conditions that are not exercised by the happy-path
+ * parity tests or the basic MCP surface tests: unknown prefixes,
+ * all-fail batches, empty result sets, and condensed-mode error
+ * rendering.
+ */
+
+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 createTestMcpClient from "../helpers/createTestMcpClient.js";
+import createTestRuntime from "../helpers/createTestRuntime.js";
+
+let rt: PragmaRuntime;
+let client: Client;
+let cleanup: () => Promise<void>;
+
+beforeAll(async () => {
+  rt = await createTestRuntime();
+  const mcp = await createTestMcpClient(rt);
+  client = mcp.client;
+  cleanup = mcp.cleanup;
+});
+
+afterAll(async () => {
+  await cleanup();
+  rt.dispose();
+});
+
+/** Parse MCP response envelope. */
+function parseEnvelope(
+  mcpResponse: Record<string, unknown>,
+): Record<string, unknown> {
+  const content = mcpResponse.content as unknown[];
+  const first = content[0] as { text: string };
+  return JSON.parse(first.text) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Unknown prefix IRI resolution
+// ---------------------------------------------------------------------------
+
+describe("IRI resolution edge cases", () => {
+  it("block_lookup with unknown prefix returns error", async () => {
+    const res = await client.callTool({
+      name: "block_lookup",
+      arguments: { names: ["zz:nonexistent.block"] },
+    });
+    const body = parseEnvelope(res);
+    expect(body.ok).toBe(true);
+    const data = body.data as { results: unknown[]; errors: unknown[] };
+    expect(data.results).toHaveLength(0);
+    expect(data.errors).toHaveLength(1);
+  });
+
+  it("standard_lookup with unknown prefix returns error", async () => {
+    const res = await client.callTool({
+      name: "standard_lookup",
+      arguments: { names: ["zz:nonexistent.standard"] },
+    });
+    const body = parseEnvelope(res);
+    expect(body.ok).toBe(true);
+    const data = body.data as { results: unknown[]; errors: unknown[] };
+    expect(data.results).toHaveLength(0);
+    expect(data.errors).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// All-fail batch lookups
+// ---------------------------------------------------------------------------
+
+describe("all-fail batch lookups", () => {
+  it("block_lookup: all names unknown → empty results, all errors", async () => {
+    const res = await client.callTool({
+      name: "block_lookup",
+      arguments: { names: ["Unknown1", "Unknown2", "Unknown3"] },
+    });
+    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(3);
+    for (const err of data.errors) {
+      expect(err.code).toBe("ENTITY_NOT_FOUND");
+    }
+  });
+
+  it("standard_lookup: all names unknown → empty results, all errors", async () => {
+    const res = await client.callTool({
+      name: "standard_lookup",
+      arguments: { names: ["no/such/standard", "also/missing"] },
+    });
+    const body = parseEnvelope(res);
+    expect(body.ok).toBe(true);
+    const data = body.data as {
+      results: unknown[];
+      errors: { query: string }[];
+    };
+    expect(data.results).toHaveLength(0);
+    expect(data.errors).toHaveLength(2);
+  });
+
+  it("modifier_lookup: unknown family → error", async () => {
+    const res = await client.callTool({
+      name: "modifier_lookup",
+      arguments: { names: ["nonexistent_family"] },
+    });
+    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("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");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Empty result sets (filtered lists)
+// ---------------------------------------------------------------------------
+
+describe("empty result sets", () => {
+  it("standard_list with nonexistent category → error envelope", 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();
+  });
+
+  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();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ontology_show with unknown prefix
+// ---------------------------------------------------------------------------
+
+describe("ontology_show edge cases", () => {
+  it("unknown prefix → error envelope", async () => {
+    const res = await client.callTool({
+      name: "ontology_show",
+      arguments: { prefix: "zzz" },
+    });
+    const body = parseEnvelope(res);
+    expect(body.ok).toBe(false);
+    const error = body.error as { code: string };
+    expect(error.code).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Condensed mode with errors
+// ---------------------------------------------------------------------------
+
+describe("condensed mode error rendering", () => {
+  it("block_lookup condensed: includes error section for unknown blocks", async () => {
+    const res = await client.callTool({
+      name: "block_lookup",
+      arguments: {
+        names: ["Button", "Nonexistent"],
+        condensed: true,
+      },
+    });
+    const body = parseEnvelope(res);
+    expect(body.condensed).toBe(true);
+    const text = body.text as string;
+    // Should contain the successful block
+    expect(text).toContain("Button");
+    // Should contain the errors section
+    expect(text).toContain("Errors");
+    expect(text).toContain("Nonexistent");
+  });
+
+  it("standard_lookup condensed: includes error section for unknown standards", async () => {
+    const res = await client.callTool({
+      name: "standard_lookup",
+      arguments: {
+        names: ["react/component/folder-structure", "no/such/standard"],
+        condensed: true,
+      },
+    });
+    const body = parseEnvelope(res);
+    expect(body.condensed).toBe(true);
+    const text = body.text as string;
+    expect(text).toContain("folder-structure");
+    expect(text).toContain("Errors");
+    expect(text).toContain("no/such/standard");
+  });
+
+  it("modifier_lookup condensed: includes error for unknown family", async () => {
+    const res = await client.callTool({
+      name: "modifier_lookup",
+      arguments: {
+        names: ["importance", "nonexistent"],
+        condensed: true,
+      },
+    });
+    const body = parseEnvelope(res);
+    expect(body.condensed).toBe(true);
+    const text = body.text as string;
+    expect(text).toContain("importance");
+    expect(text).toContain("Errors");
+    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");
+  });
+});