@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/capabilities/create/create.verb.ts

@@ -129,6 +129,13 @@ const PACKAGE_MIRROR: PromptDefinition[] = [
   },
 ];
 
+// The include-flag prompts carry the CLI grammar's `--with-X` names
+// (`withSsr`/`withRouter`/`withForms`/`withRelay`, AV-228 B8) rather than the
+// summon generator's bare prompt names (`ssr`/`router`/`forms`/`relay`). {@link
+// INCLUDE_FLAG_ALIASES} maps them back at the CLI↔generator boundary so the
+// generator prompt names — and their embedded templates + byte-equality
+// goldens — stay stable. `--run-install` (default false) is an action flag, not
+// an include, so it keeps its spelling.
 const APPLICATION_MIRROR: PromptDefinition[] = [
   {
     name: "appPath",
@@ -137,21 +144,21 @@ const APPLICATION_MIRROR: PromptDefinition[] = [
     default: "my-app",
     positional: true,
   },
-  { name: "ssr", type: "confirm", message: "Include SSR?", default: true },
+  { name: "withSsr", type: "confirm", message: "Include SSR?", default: true },
   {
-    name: "router",
+    name: "withRouter",
     type: "confirm",
     message: "Include router?",
     default: true,
   },
   {
-    name: "forms",
+    name: "withForms",
     type: "confirm",
     message: "Include form components?",
     default: true,
   },
   {
-    name: "relay",
+    name: "withRelay",
     type: "confirm",
     message: "Include a Relay (GraphQL) data layer?",
     default: false,
@@ -164,6 +171,50 @@ const APPLICATION_MIRROR: PromptDefinition[] = [
   },
 ];
 
+/**
+ * CLI include-flag names → summon generator prompt names, per create kind
+ * (AV-228 B8). All four `create application` include-flags are exposed on the
+ * unified `--with-X` convention, so their params arrive keyed `withSsr`/
+ * `withRouter`/`withForms`/`withRelay`; the summon generator reads the bare
+ * `ssr`/`router`/`forms`/`relay`. We normalize at the ONE CLI↔generator seam
+ * ({@link toGeneratorAnswers}), keeping the generator prompt names (and their
+ * templates/goldens) untouched. Component and package already use `--with-X`
+ * names that match their prompts, so their maps are empty.
+ */
+export const INCLUDE_FLAG_ALIASES: Record<
+  CreateKind,
+  Readonly<Record<string, string>>
+> = {
+  component: {},
+  package: {},
+  application: {
+    withSsr: "ssr",
+    withRouter: "router",
+    withForms: "forms",
+    withRelay: "relay",
+  },
+};
+
+/**
+ * Re-key a param bag's CLI include-flag aliases to the generator prompt names,
+ * so the summon generator reads `ssr` where the CLI grammar exposes `--with-ssr`.
+ *
+ * @param kind - The create noun (selects the alias map).
+ * @param params - The coerced CLI/MCP param bag.
+ * @returns A new bag with aliased keys renamed to the generator prompt names.
+ */
+export function toGeneratorAnswers(
+  kind: CreateKind,
+  params: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const aliases = INCLUDE_FLAG_ALIASES[kind];
+  const answers: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    answers[aliases[key] ?? key] = value;
+  }
+  return answers;
+}
+
 const componentParams: ParamSpec[] = [
   FRAMEWORK_PARAM,
   COMPONENT_PATH_PARAM,
@@ -291,15 +342,20 @@ async function runCreate(
   // injected here. `package`/`application` stay a source-run feature in the binary.
   const { pickGenerator, summon } = await loadCreateRuntime(kind);
 
-  const generator = pickGenerator(kind, params);
+  // Normalize the CLI/MCP `--with-X` include-flags to the generator prompt names
+  // (AV-228 B8) once, at this seam; every summon interaction below reads the
+  // generator-facing `answers` bag so the generator prompt names stay stable.
+  const answers = toGeneratorAnswers(kind, params);
+
+  const generator = pickGenerator(kind, answers);
 
   // SEC-2: reject a path escaping the workspace BEFORE any effect runs.
   const pathParam = PATH_PARAM[kind];
-  if (pathParam) assertInsideWorkspace(pathParam, params[pathParam], rt.cwd);
+  if (pathParam) assertInsideWorkspace(pathParam, answers[pathParam], rt.cwd);
 
   // Reject a flag/arg-provided answer that fails its prompt's own constraint,
   // with a clean INVALID_INPUT (execute re-validates as a backstop).
-  const invalid = summon.validateAnswers(generator.prompts, params);
+  const invalid = summon.validateAnswers(generator.prompts, answers);
   if (invalid !== null) {
     throw new PragmaError({ code: "INVALID_INPUT", message: invalid });
   }
@@ -336,14 +392,16 @@ async function runCreate(
     };
     return summon.execute(generator, {
       prompt: session.promptHandler,
-      params,
+      params: answers,
       signal,
     });
   }
 
   // Non-interactive: MCP → params-or-error; CLI/--yes/CI → flags+defaults.
   const prompt =
-    transport === "mcp" ? summon.mcpPrompt(params) : summon.autoPrompt(params);
+    transport === "mcp"
+      ? summon.mcpPrompt(answers)
+      : summon.autoPrompt(answers);
   // Same per-call write root as the Ink branch: `rt.cwd` feeds both the SEC-2
   // jail and the interpreter's effect-path base, atomically.
   rt.exec = {
@@ -353,7 +411,7 @@ async function runCreate(
     onLog: (_level, message) => process.stderr.write(`${message}\n`),
     signal,
   };
-  return summon.execute(generator, { prompt, params, signal });
+  return summon.execute(generator, { prompt, params: answers, signal });
 }
 
 /**
@@ -430,6 +488,6 @@ export const createApplicationVerb = createVerb(
   applicationParams,
   [
     { cmd: "pragma create application my-app" },
-    { cmd: "pragma create application my-app --relay" },
+    { cmd: "pragma create application my-app --with-relay" },
   ],
 );

package/src/capabilities/doctor/checks/checkConfigFile.ts

@@ -36,6 +36,6 @@ export async function checkConfigFile(rt: PragmaRuntime): Promise<CheckResult> {
     name: "pragma config",
     status: "fail",
     detail: "not found",
-    remedy: "pragma config tier <path>",
+    remedy: "pragma config set tier <path>",
   };
 }

package/src/capabilities/doctor/checks/checkMcpCommands.ts

@@ -4,6 +4,7 @@ import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
 import { runTask } from "@canonical/task/node";
 import type { CheckItem, CheckResult } from "../types.js";
+import { deriveBand } from "./deriveBand.js";
 
 const NAME = "MCP commands";
 
@@ -56,6 +57,9 @@ export async function checkMcpCommands(cwd: string): Promise<CheckResult> {
     return { name: NAME, status: "skip", detail: "no MCP configs found" };
   }
 
+  // Band the finding by the harnesses whose configs were actually examined, so
+  // a global-scope harness's broken command is reported under the global band.
+  const band = deriveBand(withConfig);
   const broken: CheckItem[] = [];
   let checked = 0;
 
@@ -94,6 +98,7 @@ export async function checkMcpCommands(cwd: string): Promise<CheckResult> {
       name: NAME,
       status: "pass",
       detail: `${checked} command${checked === 1 ? "" : "s"} resolve on PATH`,
+      band,
     };
   }
 
@@ -104,5 +109,6 @@ export async function checkMcpCommands(cwd: string): Promise<CheckResult> {
     items: broken,
     remedy:
       "Install the missing command or remove the entry — every agent session tries and fails to boot it.",
+    band,
   };
 }

package/src/capabilities/doctor/checks/checkMcpConfigured.ts

@@ -2,9 +2,13 @@ import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
 import { runTask } from "@canonical/task/node";
 import type { CheckResult } from "../types.js";
+import { deriveBand } from "./deriveBand.js";
 
 /**
- * Check that at least one AI harness has pragma configured as an MCP server.
+ * Check that at least one AI harness has pragma configured as an MCP server. The
+ * result's band is derived from the harnesses actually found (Windsurf ⇒ global,
+ * Cursor ⇒ project), not the check name — so a global-scope harness is not
+ * mislabeled PROJECT.
  *
  * @param cwd - The project root to detect harnesses against.
  * @returns A CheckResult listing configured harnesses, or fail with a remedy.
@@ -32,12 +36,12 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
     };
   }
 
-  const configured: string[] = [];
+  const configured: DetectedHarness[] = [];
   for (const d of detected) {
     if (!d.configExists) continue;
     try {
       const servers = await runTask(readMcpConfig(d.harness, cwd));
-      if ("pragma" in servers) configured.push(d.harness.name);
+      if ("pragma" in servers) configured.push(d);
     } catch {
       // Config unreadable — skip.
     }
@@ -47,7 +51,8 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
     return {
       name: "MCP configured",
       status: "pass",
-      detail: configured.join(", "),
+      detail: configured.map((d) => d.harness.name).join(", "),
+      band: deriveBand(configured),
     };
   }
 
@@ -57,5 +62,6 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
     status: "fail",
     detail: `detected ${names} but pragma not configured`,
     remedy: "pragma setup mcp",
+    band: deriveBand(detected),
   };
 }

package/src/capabilities/doctor/checks/deriveBand.test.ts

@@ -0,0 +1,42 @@
+/**
+ * `deriveBand` — band a doctor check by the harnesses it actually found.
+ *
+ * Fixtures wrap REAL harness definitions (via `findHarnessById`, no casts), so
+ * the scope→band mapping is exercised against the true `scope` fields: the
+ * regression this guards is a global-scope harness (Windsurf) being mislabeled
+ * PROJECT by a static per-name guess.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { findHarnessById } from "@canonical/harnesses";
+import { describe, expect, it } from "vitest";
+import { deriveBand } from "./deriveBand.js";
+
+/** A minimal {@link DetectedHarness} over a real definition (no `as` casts). */
+function detect(id: string): DetectedHarness {
+  const harness = findHarnessById(id);
+  if (!harness) throw new Error(`unknown harness fixture: ${id}`);
+  return { harness, confidence: "high", configExists: true, configPath: "x" };
+}
+
+describe("deriveBand", () => {
+  it("bands a project-scope harness (Cursor) as project", () => {
+    expect(deriveBand([detect("cursor")])).toBe("project");
+  });
+
+  it("bands a global-scope harness (Windsurf) as global — the fixed mislabel", () => {
+    expect(deriveBand([detect("windsurf")])).toBe("global");
+  });
+
+  it("bands a dual-scope harness (Claude Code) by its default band (project)", () => {
+    expect(deriveBand([detect("claude-code")])).toBe("project");
+  });
+
+  it("leaves a set spanning BOTH bands unbanded (general, not mislabeled)", () => {
+    expect(deriveBand([detect("cursor"), detect("windsurf")])).toBeUndefined();
+  });
+
+  it("leaves an empty set unbanded", () => {
+    expect(deriveBand([])).toBeUndefined();
+  });
+});

package/src/capabilities/doctor/checks/deriveBand.ts

@@ -0,0 +1,28 @@
+/**
+ * Derive a doctor check's config band from the harnesses it actually found,
+ * rather than a static per-check-name guess. The aggregate MCP checks read each
+ * harness's DEFAULT-band file (`defaultBandOf` — the home config for a
+ * global-only harness like Windsurf, the project file otherwise), so the band a
+ * finding belongs to is exactly that default band.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { defaultBandOf } from "@canonical/harnesses";
+import type { ScopeBand } from "../types.js";
+
+/**
+ * The single config band a set of detected harnesses shares, or `undefined` when
+ * the set is empty or genuinely spans BOTH bands. A two-band finding stays
+ * unbanded (rendered in the general section) instead of being mislabeled as one
+ * band — faithful to the two-band model: band by what was found, never a guess.
+ *
+ * @param harnesses - The detected harnesses the check reports on.
+ * @returns The shared {@link ScopeBand}, or `undefined` when none/mixed.
+ */
+export function deriveBand(
+  harnesses: readonly DetectedHarness[],
+): ScopeBand | undefined {
+  const bands = new Set<ScopeBand>();
+  for (const detected of harnesses) bands.add(defaultBandOf(detected.harness));
+  return bands.size === 1 ? bands.values().next().value : undefined;
+}

package/src/capabilities/doctor/doctor.render.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Render goldens for `pragma doctor` — the band-grouped report AND the plain-path
+ * color gate (F1).
+ *
+ * The banded Global/Project grouping (`partitionByBand` → sections) is pinned for
+ * both the plain and llm formatters, locking the unified Global/Project
+ * vocabulary (the report no longer says MACHINE/PROJECT). Separately, the plain
+ * formatter tints ONLY on a color-capable TTY: `supports-color` reports a
+ * non-zero `chalk.level` off a TTY under `GITHUB_ACTIONS` / `FORCE_COLOR`, so the
+ * `isTTY` gate (via the shared style seam) keeps ANSI out of
+ * `doctor --format plain | tee`. `beforeEach` forces color OFF so the banded
+ * goldens stay deterministic; the color tests opt a level back in explicitly.
+ */
+
+import chalk from "chalk";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { doctorFormatters } from "./doctor.render.js";
+import type { DoctorData } from "./types.js";
+
+/** A fixture spanning all three groups: environment (no band), global, project. */
+const BANDED_DATA: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v20 detected" },
+    {
+      name: "Shell completions",
+      status: "pass",
+      detail: "zsh installed and resolving",
+      band: "global",
+    },
+    {
+      name: "MCP configured",
+      status: "fail",
+      detail: "detected Windsurf but pragma not configured",
+      remedy: "pragma setup mcp",
+      band: "global",
+    },
+    {
+      name: "Skills symlinked",
+      status: "skip",
+      detail: "no AI harnesses detected",
+      band: "project",
+    },
+  ],
+  passed: 2,
+  failed: 1,
+  skipped: 1,
+};
+
+/** A fixture spanning pass/fail/skip, sub-items, and a remedy — every color path. */
+const COLOR_DATA: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v24" },
+    {
+      name: "package refs",
+      status: "fail",
+      detail: "3 configured, 0 locked",
+      items: [
+        { label: "core", status: "fail", detail: "unlocked" },
+        { label: "ui", status: "fail", detail: "unlocked" },
+      ],
+      remedy: "pragma sources update",
+    },
+    { name: "Skills symlinked", status: "skip", detail: "no harness" },
+  ],
+  passed: 1,
+  failed: 1,
+  skipped: 1,
+};
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+let prevLevel: number;
+beforeAll(() => {
+  prevLevel = chalk.level;
+});
+beforeEach(() => {
+  chalk.level = 0; // color-free ⇒ deterministic text (color tests opt back in)
+});
+afterAll(() => {
+  chalk.level = prevLevel;
+});
+
+describe("doctor render — banded plain report", () => {
+  it("groups checks under Global then Project headers (unified labels)", () => {
+    const out = doctorFormatters.plain(BANDED_DATA);
+    const lines = out.split("\n");
+    // The two banded section headers use the unified Global/Project vocabulary.
+    expect(lines).toContain("Global");
+    expect(lines).toContain("Project");
+    // The superseded MACHINE/PROJECT labels are gone.
+    expect(out).not.toContain("MACHINE");
+    expect(out).not.toMatch(/^PROJECT$/m);
+  });
+
+  it("orders environment → Global → Project, banding each check correctly", () => {
+    const out = doctorFormatters.plain(BANDED_DATA);
+    // Environment check leads with no header; the two global-band checks sit
+    // under Global; the project-band check sits under Project.
+    const at = (needle: string): number => out.indexOf(needle);
+    expect(at("Node version")).toBeGreaterThanOrEqual(0);
+    expect(at("Node version")).toBeLessThan(at("Global"));
+    expect(at("Global")).toBeLessThan(at("Shell completions"));
+    expect(at("MCP configured")).toBeLessThan(at("Project"));
+    expect(at("Project")).toBeLessThan(at("Skills symlinked"));
+    // A failing banded check keeps its inline remedy under its band.
+    expect(out).toContain("fix: pragma setup mcp");
+    // The tally closes the report.
+    expect(out).toContain("2 passed");
+  });
+});
+
+describe("doctor render — banded llm report", () => {
+  it("groups checks under ### Global then ### Project headers", () => {
+    const out = doctorFormatters.llm(BANDED_DATA);
+    expect(out).toContain("### Global");
+    expect(out).toContain("### Project");
+    expect(out).not.toContain("### Machine");
+    const at = (needle: string): number => out.indexOf(needle);
+    // Environment leads (no section header), then the two banded sections.
+    expect(at("Node version")).toBeLessThan(at("### Global"));
+    expect(at("### Global")).toBeLessThan(at("Shell completions"));
+    expect(at("Shell completions")).toBeLessThan(at("### Project"));
+    expect(at("### Project")).toBeLessThan(at("Skills symlinked"));
+    expect(out).toContain("_2 passed, 1 failed, 1 skipped_");
+  });
+});
+
+describe("doctor render — json", () => {
+  it("is the exact DoctorData round-trip", () => {
+    expect(JSON.parse(doctorFormatters.json(BANDED_DATA))).toEqual(BANDED_DATA);
+  });
+});
+
+describe("doctor render — piped output is ANSI-free (F1)", () => {
+  it("plain emits ZERO ANSI off a TTY even when chalk reports color (CI/FORCE_COLOR)", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = doctorFormatters.plain(COLOR_DATA);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      // The structural, color-free content still renders (glyphs, names, remedy).
+      expect(out).toContain("pragma doctor");
+      expect(out).toContain("✓  Node version");
+      expect(out).toContain("✗  package refs");
+      expect(out).toContain("○  Skills symlinked");
+      expect(out).toContain("↳ fix: pragma sources update");
+      expect(out).toContain("  1 passed · 1 failed · 1 skipped");
+    });
+  });
+});
+
+describe("doctor render — color ON (attended TTY)", () => {
+  it("plain tints the output on a color-capable TTY", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
+      expect(doctorFormatters.plain(COLOR_DATA)).toMatch(/\x1b\[/);
+    });
+  });
+});