@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/project/cli/globalFlags.ts

@@ -0,0 +1,149 @@
+/**
+ * Global-flag pre-parsing, ahead of Commander.
+ *
+ * `--format`, `--verbose`, and `--detail` may appear anywhere on the line, so
+ * they are scanned and stripped before Commander sees argv — otherwise
+ * `enablePositionalOptions()` scoping would reject a flag placed after a verb.
+ * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
+ * flag and the `--format text` value renamed to `plain` (the kernel's
+ * {@link OutputFormat}). The dedicated `--llm` flag was folded into
+ * `--format llm`, leaving auto-detection as the sole implicit trigger. Both the
+ * space (`--format json`) and equals (`--format=json`) forms are recognized.
+ */
+
+import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+
+/**
+ * Read a `--flag`'s value, accepting both `--flag value` and `--flag=value`.
+ *
+ * @param argv - Raw argv (already sliced to the user's arguments).
+ * @param flag - The flag including leading dashes (e.g. `--format`).
+ * @returns The value, or `undefined` when the flag is absent.
+ */
+function readFlagValue(
+  argv: readonly string[],
+  flag: string,
+): string | undefined {
+  const equalsPrefix = `${flag}=`;
+  const equalsArg = argv.find((arg) => arg.startsWith(equalsPrefix));
+  if (equalsArg !== undefined) {
+    return equalsArg.slice(equalsPrefix.length);
+  }
+  const spaceIndex = argv.indexOf(flag);
+  return spaceIndex === -1 ? undefined : argv[spaceIndex + 1];
+}
+
+/**
+ * Read the raw `--format` value exactly as typed, for validation.
+ *
+ * Unlike {@link parseGlobalFlags} this does not normalize — the caller decides
+ * how to reject an unknown value. A bare `--format` with no following value is
+ * reported as `""` (not `undefined`) so it is rejected rather than silently
+ * falling through.
+ *
+ * @param argv - Raw argv (the user's arguments).
+ * @returns The raw value, `""` for a valueless `--format`, or `undefined`.
+ */
+export function readRawFormat(argv: readonly string[]): string | undefined {
+  const equalsArg = argv.find((arg) => arg.startsWith("--format="));
+  if (equalsArg !== undefined) return equalsArg.slice("--format=".length);
+
+  const spaceIndex = argv.indexOf("--format");
+  if (spaceIndex === -1) return undefined;
+
+  const value = argv[spaceIndex + 1];
+  return value !== undefined && !value.startsWith("-") ? value : "";
+}
+
+/**
+ * Environment probe for the auto-LLM default. Injectable so detection can be
+ * unit-tested without touching the real process.
+ */
+export interface OutputEnvironment {
+  /** Whether stdout is attached to an interactive terminal. */
+  readonly isTty: boolean;
+  /** Whether the auto-LLM default is explicitly disabled. */
+  readonly noAutoLlm: boolean;
+}
+
+/** Read the real stdout/env output environment. @note Impure — reads process. */
+function readOutputEnvironment(): OutputEnvironment {
+  return {
+    isTty: process.stdout.isTTY === true,
+    noAutoLlm: Boolean(process.env.PRAGMA_NO_AUTO_LLM),
+  };
+}
+
+/** Narrow a raw `--detail` value to a recognized level, else `undefined`. */
+function readDetail(argv: readonly string[]): DetailLevel | undefined {
+  const raw = readFlagValue(argv, "--detail");
+  if (raw !== undefined && (DETAIL_LEVELS as readonly string[]).includes(raw)) {
+    return raw as DetailLevel;
+  }
+  return undefined;
+}
+
+/**
+ * Extract the global flags from raw argv (the user's arguments, argv[2:]).
+ *
+ * Auto-LLM: with no explicit `--format` and a non-interactive stdout (piped or
+ * redirected — the shape an agent captures), `llm` defaults to true so agents
+ * get condensed Markdown without a flag. Any explicit `--format` overrides it —
+ * `--format plain` forces human output down a pipe, `--format llm` forces the
+ * condensed form even on a TTY — as does `PRAGMA_NO_AUTO_LLM`.
+ *
+ * @param argv - The user's arguments (no `node`/script prefix).
+ * @param env - Output environment probe (defaults to the real process).
+ * @returns The parsed global flags.
+ * @note Impure by default — reads process.stdout/env unless `env` is injected.
+ */
+export function parseGlobalFlags(
+  argv: readonly string[],
+  env: OutputEnvironment = readOutputEnvironment(),
+): GlobalFlags {
+  const rawFormat = readFlagValue(argv, "--format");
+  const format =
+    rawFormat === "json" ? "json" : rawFormat === "llm" ? "llm" : "plain";
+  const formatRequested = rawFormat !== undefined;
+  const autoLlm = !formatRequested && !env.isTty && !env.noAutoLlm;
+  const detail = readDetail(argv);
+  return {
+    llm: format === "llm" || autoLlm,
+    autoLlm,
+    format,
+    verbose: argv.includes("--verbose"),
+    ...(detail !== undefined ? { detail } : {}),
+  };
+}
+
+/**
+ * Return a copy of argv with every global flag (and its value) removed.
+ *
+ * Since {@link parseGlobalFlags} pre-parses these, they are dropped so they do
+ * not collide with Commander's positional scoping, letting the user place them
+ * anywhere on the line.
+ *
+ * @param argv - The user's arguments.
+ * @returns A new array with global flags stripped.
+ */
+export function stripGlobalFlags(argv: readonly string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--verbose") continue;
+    if (
+      arg?.startsWith("--format=") ||
+      arg?.startsWith("--verbose=") ||
+      arg?.startsWith("--detail=")
+    ) {
+      continue;
+    }
+    if (arg === "--format" || arg === "--detail") {
+      i += 1; // skip the space-form value too
+      continue;
+    }
+    result.push(arg as string);
+  }
+  return result;
+}

package/src/kernel/project/cli/helpFormat.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared help-rendering primitives — the ONE visual system every help page
+ * composes from.
+ *
+ * Root help (`rootHelp.ts`), noun help, and verb help (`verbHelp.ts`) all build
+ * their pages out of these helpers so the front door and the leaf pages read as
+ * the same CLI: a dim `Usage:` label, bold section headers, a cyan-term /
+ * dim-description two-column body, and a dim footer that points at the next help
+ * level. chalk auto-disables color off a TTY, so goldens, piped output, and MCP
+ * transports all capture plain text — only an interactive terminal gets color.
+ */
+
+import chalk from "chalk";
+
+/** Two-space indent for every list body row. */
+const INDENT = "  ";
+/** Two-space gap between a term column and its description. */
+const GAP = "  ";
+
+/** A bold section header (`Flags`, `Verbs`, `Explore the design system`). */
+export function helpHeading(text: string): string {
+  return chalk.bold(text);
+}
+
+/** Dim secondary text — an example note, or the footer line. */
+export function helpDim(text: string): string {
+  return chalk.dim(text);
+}
+
+/** A cyan term — a command, verb, flag, or example, as shown in the body. */
+export function helpTerm(text: string): string {
+  return chalk.cyan(text);
+}
+
+/** The `Usage:` line: a dim label followed by the given command shape. */
+export function helpUsage(body: string): string {
+  return `${chalk.dim("Usage:")} ${body}`;
+}
+
+/**
+ * Render aligned two-column rows: a cyan term padded to a common width, then its
+ * dim description. Pass an explicit `width` to align across several lists (the
+ * root's grouped sections share one column); omit it to size to these rows
+ * alone.
+ *
+ * @param rows - `[term, description]` pairs.
+ * @param width - Optional shared column width; defaults to the widest term.
+ * @returns One formatted line per row.
+ */
+export function helpColumns(
+  rows: readonly (readonly [term: string, description: string])[],
+  width?: number,
+): string[] {
+  const column = width ?? Math.max(0, ...rows.map(([term]) => term.length));
+  return rows.map(([term, description]) =>
+    `${INDENT}${chalk.cyan(term.padEnd(column))}${GAP}${chalk.dim(description)}`.trimEnd(),
+  );
+}

package/src/kernel/project/cli/index.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI projector barrel — the Commander program, dispatcher, help, and
+ * exit-code model. The bin composes these; tests build programs from arbitrary
+ * modules via the `projectCli` helper.
+ */
+
+export type { BuildProgramOptions } from "./buildProgram.js";
+export { buildProgram } from "./buildProgram.js";
+export type { DispatchOutcome, MutationFlags } from "./dispatch.js";
+export { dispatch, executeVerb, extractParams } from "./dispatch.js";
+export { EXIT, mapExitCode } from "./exitCodes.js";
+export type { OutputEnvironment } from "./globalFlags.js";
+export {
+  parseGlobalFlags,
+  readRawFormat,
+  stripGlobalFlags,
+} from "./globalFlags.js";
+export { formatRootHelp } from "./rootHelp.js";
+export { nounVerbMap, resolveUnknownCommand } from "./suggest.js";
+export { suggestNames } from "./suggestNames.js";
+export { formatNounHelp, formatVerbHelp } from "./verbHelp.js";

package/src/kernel/project/cli/interactionSeam.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The §0 spine: a mutating verb reads `runtime.interaction` and sets
+ * `runtime.exec`, and the dispatcher spreads `exec` into the node interpreter
+ * on the REAL-run branch only — so an interactive Prompt effect is resolved by
+ * the injected handler (not the bare `NO_PROMPT_HANDLER` throw), while
+ * `--dry-run` stays handler-free and mocks the prompt.
+ */
+
+import { $, gen, prompt } from "@canonical/task";
+import { describe, expect, it, vi } from "vitest";
+import { bootRuntime } from "../../runtime/boot.js";
+import type { GlobalFlags, VerbSpec } from "../../spec/types.js";
+import { executeVerb, type MutationFlags } from "./dispatch.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const noMutation: MutationFlags = { dryRun: false, undo: false, yes: false };
+
+const json = (d: unknown) => JSON.stringify(d);
+
+/** A mutating verb whose task prompts once and whose `run` wires `exec`. */
+function seamVerb(onExec?: () => void): VerbSpec {
+  return {
+    path: ["fixture", "seam"],
+    summary: "A prompting mutation.",
+    params: [],
+    output: { formatters: { plain: json, llm: json, json } },
+    capability: {
+      needsStore: false,
+      mutates: true,
+      interactive: true,
+      mcp: { expose: false, reason: "test fixture" },
+    },
+    run: (_params, rt) => {
+      // The verb picks its strategy from the interaction context and records it
+      // as the injected prompt handler + optional teardown.
+      const answer = rt.interaction?.yes ? "confirmed" : "attended";
+      rt.exec = {
+        promptHandler: () => Promise.resolve(answer),
+        dispose: onExec,
+      };
+      return gen(function* () {
+        const value = yield* $(
+          prompt({ type: "text", name: "which", message: "Which?" }),
+        );
+        return { value };
+      });
+    },
+  };
+}
+
+describe("interaction/exec seam (PROTECTED)", () => {
+  it("resolves an interactive Prompt through the verb's injected handler", async () => {
+    const runtime = bootRuntime(FLAGS);
+    const outcome = await executeVerb(
+      seamVerb(),
+      {},
+      { ...noMutation, yes: true },
+      runtime,
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("confirmed");
+  });
+
+  it("passes the interaction context (yes flag) to the verb", async () => {
+    const runtime = bootRuntime(FLAGS);
+    const outcome = await executeVerb(seamVerb(), {}, noMutation, runtime);
+    expect(outcome.stdout).toContain("attended");
+  });
+
+  it("runs the verb's exec.dispose teardown after a real run", async () => {
+    const dispose = vi.fn();
+    const runtime = bootRuntime(FLAGS);
+    await executeVerb(
+      seamVerb(dispose),
+      {},
+      { ...noMutation, yes: true },
+      runtime,
+    );
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("dry-run stays handler-free, mocks the prompt, and omits it from the plan", async () => {
+    const runtime = bootRuntime(FLAGS);
+    const outcome = await executeVerb(
+      seamVerb(),
+      {},
+      { ...noMutation, dryRun: true },
+      runtime,
+    );
+    expect(outcome.exitCode).toBe(0);
+    // The only effect is the Prompt (mocked) — filtered from the plan.
+    expect(outcome.stdout).toContain("no effects");
+  });
+});

package/src/kernel/project/cli/rootHelp.ts

@@ -0,0 +1,220 @@
+/**
+ * Curated root `--help` for `pragma`.
+ *
+ * The front door is hand-curated, not auto-generated: nouns are grouped into
+ * task-oriented sections with real one-line summaries, and each section is
+ * reconciled against the *live* nouns (from the registered verbs) so a noun
+ * that is not built yet is dropped and an uncatalogued one still surfaces under
+ * "Other" rather than vanishing. Ported from the v1 root help, retargeted at
+ * the grammar and the v2 noun set (no `llm`/`graphql`/`trace`/`tokens`).
+ */
+
+import type { VerbSpec } from "../../spec/types.js";
+import {
+  helpColumns,
+  helpDim,
+  helpHeading,
+  helpTerm,
+  helpUsage,
+} from "./helpFormat.js";
+
+interface NounSummary {
+  readonly noun: string;
+  readonly summary: string;
+}
+
+interface HelpGroup {
+  readonly title: string;
+  readonly nouns: readonly NounSummary[];
+}
+
+/**
+ * Task-oriented grouping with curated summaries. Order is intentional: what
+ * people reach for most (exploring, generating) comes first; agent tooling
+ * comes last.
+ */
+const HELP_GROUPS: readonly HelpGroup[] = [
+  {
+    title: "Explore the design system",
+    nouns: [
+      {
+        noun: "block",
+        summary: "Inspect components & patterns and their anatomy",
+      },
+      { noun: "token", summary: "Look up design tokens and their values" },
+      { noun: "modifier", summary: "Inspect modifiers and modifier families" },
+      { noun: "standard", summary: "Browse code standards and categories" },
+      {
+        noun: "ontology",
+        summary: "Explore the loaded ontologies (classes, properties)",
+      },
+      { noun: "tier", summary: "List the design-system tiers" },
+    ],
+  },
+  {
+    title: "Generate code",
+    nouns: [
+      { noun: "create", summary: "Scaffold components, packages, and apps" },
+    ],
+  },
+  {
+    title: "Query & serve the graph",
+    nouns: [
+      {
+        noun: "graph",
+        summary: "Run SPARQL queries or inspect a URI directly",
+      },
+    ],
+  },
+  {
+    title: "Set up & maintain",
+    nouns: [
+      { noun: "doctor", summary: "Check environment health" },
+      {
+        noun: "setup",
+        summary: "Configure MCP, skills, completions, and the LSP",
+      },
+      {
+        noun: "sources",
+        summary: "Build and refresh the local store from packages",
+      },
+      { noun: "config", summary: "Read and write pragma configuration" },
+      { noun: "info", summary: "Show version, config, and update status" },
+      {
+        noun: "upgrade",
+        summary: "Upgrade the pragma CLI to the latest version",
+      },
+    ],
+  },
+  {
+    title: "For AI agents",
+    nouns: [
+      {
+        noun: "capabilities",
+        summary: "Discover conventions, tools, and the discovery sequence",
+      },
+      {
+        noun: "colophon",
+        summary: "Read how pragma and the active domain are made",
+      },
+      {
+        noun: "skill",
+        summary: "Browse agent skills from design-system packages",
+      },
+      { noun: "prompt", summary: "Browse reusable prompt templates" },
+      { noun: "mcp", summary: "Start the MCP server over stdio" },
+    ],
+  },
+];
+
+/** All distinct, non-hidden top-level nouns present in the registered verbs. */
+function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
+  const nouns = new Set<string>();
+  for (const verb of verbs) {
+    if (verb.hidden) continue;
+    nouns.add(verb.path[0]);
+  }
+  return nouns;
+}
+
+/** The summary to show for an uncatalogued but live noun. */
+function fallbackSummary(noun: string, verbs: readonly VerbSpec[]): string {
+  const first = verbs.find((v) => v.path[0] === noun && !v.hidden);
+  return first?.summary ?? `${noun} commands`;
+}
+
+/**
+ * Build the curated root help string.
+ *
+ * @param programName - The CLI binary name (`pragma`).
+ * @param description - The program description shown in the header.
+ * @param verbs - All registered verbs, used to derive the live noun set.
+ * @returns The formatted, colorized help text.
+ */
+export function formatRootHelp(
+  programName: string,
+  description: string,
+  verbs: readonly VerbSpec[],
+): string {
+  const present = nounsFrom(verbs);
+  // `mcp` is served by the bin's special-case, not a projected verb, but is
+  // always available — surface it so the front door is complete.
+  present.add("mcp");
+  const catalogued = new Set(
+    HELP_GROUPS.flatMap((g) => g.nouns.map((n) => n.noun)),
+  );
+
+  const uncatalogued = [...present].filter((n) => !catalogued.has(n)).sort();
+  const groups: HelpGroup[] = [
+    ...HELP_GROUPS.map((g) => ({
+      ...g,
+      nouns: g.nouns.filter((n) => present.has(n.noun)),
+    })),
+    ...(uncatalogued.length > 0
+      ? [
+          {
+            title: "Other",
+            nouns: uncatalogued.map((noun) => ({
+              noun,
+              summary: fallbackSummary(noun, verbs),
+            })),
+          },
+        ]
+      : []),
+  ].filter((g) => g.nouns.length > 0);
+
+  // One column width across ALL groups so the noun column aligns section to
+  // section, not just within a section.
+  const nounWidth = Math.max(
+    ...groups.flatMap((g) => g.nouns.map((n) => n.noun.length)),
+    0,
+  );
+
+  const lines: string[] = [
+    `${helpHeading(programName)} — ${description}`,
+    "",
+    helpUsage(
+      `${programName} ${helpTerm("<command>")} ${helpDim("[subcommand] [flags]")}`,
+    ),
+    "",
+  ];
+
+  for (const group of groups) {
+    lines.push(helpHeading(group.title));
+    lines.push(
+      ...helpColumns(
+        group.nouns.map((n) => [n.noun, n.summary] as const),
+        nounWidth,
+      ),
+    );
+    lines.push("");
+  }
+
+  // The frozen global-flags block: these doc strings MUST stay byte-consistent
+  // with FIXED_SURFACE.globalFlags (emitSurface.ts) — restyle the LAYOUT only,
+  // never these strings.
+  lines.push(helpHeading("Global flags"));
+  const flags: [string, string][] = [
+    [
+      "--format <plain|llm|json>",
+      "Select output format (llm = condensed Markdown for agents)",
+    ],
+    [
+      "--detail <level>",
+      "Progressive-disclosure level (summary, standard, detailed)",
+    ],
+    ["--verbose", "Diagnostic output on stderr"],
+    ["--help", "Show help (works on any command)"],
+    ["--version", "Show the CLI version"],
+  ];
+  lines.push(...helpColumns(flags));
+  lines.push("");
+
+  lines.push(
+    helpDim(
+      `Run \`${programName} <command> --help\` for details, or \`${programName} capabilities\` to get oriented.`,
+    ),
+  );
+
+  return lines.join("\n");
+}

package/src/kernel/project/cli/suggest.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { fixtureModule } from "../../../testing/fixtures/fixtureCapability.js";
+import { nounVerbMap, resolveUnknownCommand } from "./suggest.js";
+import { suggestNames } from "./suggestNames.js";
+
+const verbs = [...fixtureModule.verbs];
+
+describe("nounVerbMap", () => {
+  it("maps nouns to their non-hidden verb labels", () => {
+    const map = nounVerbMap(verbs);
+    expect(map.get("widget")).toEqual(["list", "make"]);
+    expect([...map.keys()]).toEqual(["widget"]);
+  });
+});
+
+describe("resolveUnknownCommand", () => {
+  const map = nounVerbMap(verbs);
+
+  it("flags an unknown noun against the noun set", () => {
+    expect(resolveUnknownCommand(["widgt"], map)).toEqual({
+      token: "widgt",
+      candidates: ["widget"],
+    });
+  });
+
+  it("flags an unknown verb against its noun's verbs", () => {
+    expect(resolveUnknownCommand(["widget", "lst"], map)).toEqual({
+      token: "lst",
+      candidates: ["list", "make"],
+    });
+  });
+
+  it("resolves a valid command to undefined", () => {
+    expect(resolveUnknownCommand(["widget", "list"], map)).toBeUndefined();
+    expect(resolveUnknownCommand([], map)).toBeUndefined();
+  });
+});
+
+describe("suggestNames", () => {
+  it("ranks prefix matches ahead of edit-distance matches", () => {
+    expect(suggestNames("con", ["config", "connect", "block"])).toEqual([
+      "config",
+      "connect",
+    ]);
+  });
+
+  it("catches a single-character typo", () => {
+    expect(suggestNames("cofnig", ["config", "block"])).toEqual(["config"]);
+  });
+
+  it("returns nothing for an empty query", () => {
+    expect(suggestNames("", ["config"])).toEqual([]);
+  });
+});

package/src/kernel/project/cli/suggest.ts

@@ -0,0 +1,67 @@
+/**
+ * Turn an unknown command into an actionable "Did you mean?".
+ *
+ * When Commander rejects an unrecognized noun or verb, the bin resolves the
+ * offending token and the set of siblings it should have matched, then raises a
+ * `PragmaError.unknownVerb` (its suggestions ranked by `suggestNames`) rendered
+ * through the shared error renderers — so the plain path gets the same `Error:`
+ * prefix and "Did you mean?" list as every other error. The resolution is
+ * data-driven — a noun→verbs map built from the grammar — so no Commander
+ * internals leak into the suggester.
+ */
+
+import type { VerbSpec } from "../../spec/types.js";
+
+/** An unresolved token and the sibling names to rank it against. */
+export interface UnknownCommand {
+  readonly token: string;
+  readonly candidates: readonly string[];
+}
+
+/**
+ * Build the noun → verb-labels map from the registered verbs.
+ *
+ * Hidden verbs are excluded. A self-verb (path length 1, e.g. `["info"]`)
+ * contributes an entry with no sub-verbs.
+ *
+ * @param verbs - All registered verbs.
+ * @returns A map from noun to its verb labels (empty for self-verbs).
+ */
+export function nounVerbMap(verbs: readonly VerbSpec[]): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+  for (const verb of verbs) {
+    if (verb.hidden) continue;
+    const [noun, sub] = verb.path;
+    const labels = map.get(noun) ?? [];
+    if (sub) labels.push(sub);
+    map.set(noun, labels);
+  }
+  return map;
+}
+
+/**
+ * Locate the first token that does not resolve against the known commands.
+ *
+ * @param positionals - The stripped positional args (no flags), in order.
+ * @param nouns - The noun → verb-labels map from {@link nounVerbMap}.
+ * @returns The unresolved token with its candidates, or `undefined` when the
+ *   args resolve cleanly.
+ */
+export function resolveUnknownCommand(
+  positionals: readonly string[],
+  nouns: ReadonlyMap<string, readonly string[]>,
+): UnknownCommand | undefined {
+  const [noun, verb] = positionals;
+  if (noun === undefined) return undefined;
+
+  if (!nouns.has(noun)) {
+    return { token: noun, candidates: [...nouns.keys()] };
+  }
+
+  const labels = nouns.get(noun) ?? [];
+  if (verb !== undefined && labels.length > 0 && !labels.includes(verb)) {
+    return { token: verb, candidates: labels };
+  }
+
+  return undefined;
+}