@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -0,0 +1,218 @@
+/**
+ * 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][] = [
+    ["--llm", "Condensed Markdown output for agents"],
+    ["--format <json|plain>", "Select output format"],
+    [
+      "--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;
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Rank candidate names by similarity to a failed token.
+ *
+ * Ported near-verbatim from the v1 suggester: prefix matches first, then
+ * Damerau-Levenshtein edit-distance matches under a normalized threshold. Used
+ * by the unknown-command suggester to turn a typo into "Did you mean: …?".
+ */
+
+/**
+ * Return up to {@link maxResults} candidates most similar to `query`.
+ *
+ * Exact matches are excluded — a match means the caller should have resolved it
+ * and never reached here.
+ *
+ * @param query - The token that failed to resolve.
+ * @param candidates - All known names to rank against.
+ * @param opts.maxResults - Max suggestions to return (default 5).
+ * @param opts.threshold - Max normalized edit distance (default 0.4).
+ * @returns Ranked suggestions, original casing preserved.
+ */
+export function suggestNames(
+  query: string,
+  candidates: readonly string[],
+  opts?: { maxResults?: number; threshold?: number },
+): string[] {
+  if (query === "") return [];
+
+  const maxResults = opts?.maxResults ?? 5;
+  const threshold = opts?.threshold ?? 0.4;
+  const queryLower = query.toLowerCase();
+
+  type Scored = { name: string; score: number };
+  const scored: Scored[] = [];
+
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+
+    if (candidateLower === queryLower) continue;
+
+    if (candidateLower.startsWith(queryLower)) {
+      scored.push({ name: candidate, score: 0 });
+      continue;
+    }
+
+    const distance = damerauLevenshtein(queryLower, candidateLower);
+    const maxLen = Math.max(queryLower.length, candidateLower.length);
+    const normalized = maxLen === 0 ? 0 : distance / maxLen;
+
+    if (normalized <= threshold) {
+      scored.push({ name: candidate, score: normalized });
+    }
+  }
+
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, maxResults).map((s) => s.name);
+}
+
+/**
+ * Damerau-Levenshtein distance: insertions, deletions, substitutions, and
+ * adjacent transpositions.
+ */
+function damerauLevenshtein(a: string, b: string): number {
+  const lenA = a.length;
+  const lenB = b.length;
+
+  if (lenA === 0) return lenB;
+  if (lenB === 0) return lenA;
+
+  const matrix: number[][] = Array.from({ length: lenA + 1 }, () =>
+    Array.from<number>({ length: lenB + 1 }).fill(0),
+  );
+
+  for (let i = 0; i <= lenA; i++) {
+    getRow(matrix, i)[0] = i;
+  }
+  const firstRow = getRow(matrix, 0);
+  for (let j = 0; j <= lenB; j++) {
+    firstRow[j] = j;
+  }
+
+  for (let i = 1; i <= lenA; i++) {
+    const prevRow = getRow(matrix, i - 1);
+    const row = getRow(matrix, i);
+    for (let j = 1; j <= lenB; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+
+      row[j] = Math.min(
+        getCell(prevRow, j) + 1, // deletion
+        getCell(row, j - 1) + 1, // insertion
+        getCell(prevRow, j - 1) + cost, // substitution
+      );
+
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        const prevPrevRow = getRow(matrix, i - 2);
+        row[j] = Math.min(
+          getCell(row, j),
+          getCell(prevPrevRow, j - 2) + cost, // transposition
+        );
+      }
+    }
+  }
+
+  return getCell(getRow(matrix, lenA), lenB);
+}
+
+/** Read a matrix row that is structurally guaranteed to exist. */
+function getRow(matrix: number[][], index: number): number[] {
+  const row = matrix.at(index);
+  if (row === undefined) {
+    throw new Error(`matrix row ${index} is out of bounds`);
+  }
+  return row;
+}
+
+/** Read a matrix cell that is structurally guaranteed to exist. */
+function getCell(row: number[], index: number): number {
+  const cell = row.at(index);
+  if (cell === undefined) {
+    throw new Error(`matrix cell ${index} is out of bounds`);
+  }
+  return cell;
+}

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

@@ -0,0 +1,138 @@
+import chalk from "chalk";
+import { afterAll, describe, expect, it } from "vitest";
+import type { VerbSpec } from "../../spec/types.js";
+import { formatNounHelp, formatVerbHelp } from "./verbHelp.js";
+
+// Help styling (helpFormat.ts) routes through chalk, whose `supports-color`
+// enables color when GITHUB_ACTIONS is set — even off a TTY — so CI would paint
+// ANSI into these plain goldens (locally chalk stays at level 0, which is why it
+// only failed in CI). Pin the level to 0 for a deterministic, color-free render
+// (the same guard colophon.render.test.ts uses). Set at module scope so the
+// collection-time formatVerbHelp() call below renders plain too.
+const prevChalkLevel = chalk.level;
+chalk.level = 0;
+afterAll(() => {
+  chalk.level = prevChalkLevel;
+});
+
+const passthrough = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+const get: VerbSpec = {
+  path: ["block", "get"],
+  summary: "Get a block by name.",
+  doc: "Resolves the block and prints its anatomy.",
+  params: [
+    {
+      kind: "string",
+      name: "name",
+      doc: "Block name.",
+      positional: true,
+      required: true,
+    },
+    { kind: "boolean", name: "withAnatomy", doc: "Include the anatomy tree." },
+  ],
+  output: { formatters: passthrough },
+  examples: [{ cmd: "pragma block get Button", note: "the primary button" }],
+  capability: { needsStore: true, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+const list: VerbSpec = {
+  path: ["block", "list"],
+  summary: "List blocks.",
+  params: [],
+  output: { formatters: passthrough },
+  capability: { needsStore: true, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+/** A self-verb (`path.length === 1`) to exercise the root-pointing footer. */
+const selfVerb: VerbSpec = {
+  path: ["doctor"],
+  summary: "Check environment health.",
+  params: [],
+  output: { formatters: passthrough },
+  capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+describe("formatVerbHelp", () => {
+  const help = formatVerbHelp("pragma", get);
+
+  it("renders the usage line with the positional", () => {
+    expect(help).toContain("Usage: pragma block get <name> [flags]");
+  });
+
+  it("renders summary, extended doc, the kebab flag, and examples", () => {
+    expect(help).toContain("Get a block by name.");
+    expect(help).toContain("Resolves the block and prints its anatomy.");
+    expect(help).toContain("--with-anatomy");
+    expect(help).toContain("pragma block get Button");
+    expect(help).toContain("the primary button");
+  });
+
+  it("closes a sub-verb page with a footer pointing at the noun page", () => {
+    expect(help).toContain(
+      "Run `pragma block --help` to see all block commands.",
+    );
+  });
+
+  it("closes a self-verb page with a footer pointing at the root", () => {
+    expect(formatVerbHelp("pragma", selfVerb)).toContain(
+      "Run `pragma --help` to see all commands.",
+    );
+  });
+
+  it("renders the unified verb page (restyle golden)", () => {
+    expect(help).toMatchInlineSnapshot(`
+      "Usage: pragma block get <name> [flags]
+
+      Get a block by name.
+
+      Resolves the block and prints its anatomy.
+
+      Flags
+        --with-anatomy  Include the anatomy tree.
+
+      Examples
+        pragma block get Button
+          the primary button
+
+      Run \`pragma block --help\` to see all block commands."
+    `);
+  });
+});
+
+describe("formatNounHelp", () => {
+  it("lists the noun's verbs with summaries", () => {
+    const help = formatNounHelp("pragma", "block", [get, list]);
+    expect(help).toContain("Usage: pragma block <verb> [flags]");
+    expect(help).toContain("get");
+    expect(help).toContain("list");
+    expect(help).toContain("Get a block by name.");
+  });
+
+  it("renders the unified noun page (restyle golden)", () => {
+    expect(
+      formatNounHelp("pragma", "block", [get, list]),
+    ).toMatchInlineSnapshot(`
+      "Usage: pragma block <verb> [flags]
+
+      Verbs
+        get   Get a block by name.
+        list  List blocks.
+
+      Run \`pragma block <verb> --help\` for details on a verb."
+    `);
+  });
+
+  it("handles a noun with no verbs", () => {
+    expect(formatNounHelp("pragma", "ghost", [])).toBe(
+      'No commands found for "ghost".',
+    );
+  });
+});