@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/doctor/doctor.verb.ts

@@ -0,0 +1,46 @@
+/**
+ * The `doctor` verb spec (noun `doctor`, self-verb).
+ *
+ * A read (`mutates: false`) that declares `needsStore: false` — the covenant has
+ * neither flag — so the dispatcher never pre-boots the store. The one store
+ * check boots it lazily inside a try/catch, keeping doctor storeless-by-default
+ * while still reporting store health. `run` lazily imports the orchestrator, so
+ * building the tree pulls neither the checks nor `@canonical/harnesses`.
+ *
+ * Exit-code decision: doctor always exits 0 — failures live in the `{ failed }`
+ * envelope (agents read the data; CI greps it). See PARITY_GAP
+ * `doctor-exit-zero-with-failures`.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { doctorFormatters } from "./doctor.render.js";
+import type { DoctorData } from "./types.js";
+
+const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
+  path: ["doctor"],
+  summary: "Check environment health — Node, config, store, MCP, and skills.",
+  doc: "Runs nine diagnostic checks and reports pass/fail/skip with inline remedies. Storeless by default; the store check boots lazily and never fails the run.",
+  params: [],
+  output: { formatters: doctorFormatters },
+  examples: [
+    { cmd: "pragma doctor" },
+    { cmd: "pragma doctor --format json", note: "machine-readable checks" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./runChecks.js").then((m) => m.runChecks(runtime)),
+};
+
+/** The `doctor` capability module. */
+export const doctorModule: CapabilityModule = {
+  name: "doctor",
+  verbs: [asVerb(doctorVerb)],
+};

package/src/capabilities/doctor/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `doctor` capability barrel.
+ */
+
+export { doctorModule } from "./doctor.verb.js";
+export type { CheckResult, CheckStatus, DoctorData } from "./types.js";

package/src/capabilities/doctor/runChecks.ts

@@ -0,0 +1,76 @@
+/**
+ * The `doctor` run body: orchestrate all environment health checks.
+ *
+ * Checks are started eagerly (they run concurrently) and collected in
+ * declaration order for a deterministic report. Each is guarded so a thrown
+ * check becomes an attributable `fail` rather than aborting the whole run — the
+ * same discipline the old shell used. Lazily imported by `doctor.verb.ts`, so
+ * neither the checks nor `@canonical/harnesses` land on the fast path.
+ */
+
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { checkConfigFile } from "./checks/checkConfigFile.js";
+import { checkKeStore } from "./checks/checkKeStore.js";
+import { checkMcpCommands } from "./checks/checkMcpCommands.js";
+import { checkMcpConfigured } from "./checks/checkMcpConfigured.js";
+import { checkNodeVersion } from "./checks/checkNodeVersion.js";
+import { checkPackageRefs } from "./checks/checkPackageRefs.js";
+import { checkPragmaVersion } from "./checks/checkPragmaVersion.js";
+import { checkShellCompletions } from "./checks/checkShellCompletions.js";
+import { checkSkillsSymlinked } from "./checks/checkSkillsSymlinked.js";
+import type { CheckResult, DoctorData } from "./types.js";
+
+/**
+ * Each check paired with the display name used if it rejects. The fallback name
+ * matches the `name` each check returns on success, so a thrown check reports
+ * the same label and stays correlatable. Declaration order fixes the report
+ * order.
+ */
+function buildChecks(
+  rt: PragmaRuntime,
+): readonly [string, Promise<CheckResult>][] {
+  return [
+    ["Node version", checkNodeVersion()],
+    ["pragma version", checkPragmaVersion(rt)],
+    ["pragma config", checkConfigFile(rt)],
+    ["package refs", checkPackageRefs(rt)],
+    ["ke store", checkKeStore(rt)],
+    ["Shell completions", checkShellCompletions(rt.cwd)],
+    ["MCP configured", checkMcpConfigured(rt.cwd)],
+    ["MCP commands", checkMcpCommands(rt.cwd)],
+    ["Skills symlinked", checkSkillsSymlinked(rt.cwd)],
+  ];
+}
+
+/**
+ * Run every environment health check and aggregate the results.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The `{ checks, passed, failed, skipped }` summary.
+ * @note Impure — the checks read the fs, boot the store, and detect harnesses.
+ */
+export async function runChecks(rt: PragmaRuntime): Promise<DoctorData> {
+  const checks: CheckResult[] = await Promise.all(
+    buildChecks(rt).map(async ([name, promise]): Promise<CheckResult> => {
+      try {
+        return await promise;
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+          name,
+          status: "fail",
+          detail: `Check threw an unexpected error: ${reason}`,
+          remedy:
+            "Re-run `pragma doctor`; if it persists, report this as a bug.",
+        };
+      }
+    }),
+  );
+
+  return {
+    checks,
+    passed: checks.filter((c) => c.status === "pass").length,
+    failed: checks.filter((c) => c.status === "fail").length,
+    skipped: checks.filter((c) => c.status === "skip").length,
+  };
+}

package/src/capabilities/doctor/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Data shapes for `pragma doctor` (ported verbatim from the old shell).
+ */
+
+/** Status of a doctor check or one of its sub-items. */
+export type CheckStatus = "pass" | "fail" | "skip";
+
+/**
+ * A structured sub-item under a check — e.g. one resolved package under
+ * `package refs`, or one unresolvable server under `MCP commands`. Lets the
+ * formatter render an indented, aligned breakdown instead of cramming
+ * everything into a single `detail` string.
+ */
+export interface CheckItem {
+  /** Left-column label (e.g. the package or server name). */
+  readonly label: string;
+  /** Right-column detail (e.g. `git v0.1.2 · 362 graphs`). */
+  readonly detail?: string;
+  /** Optional per-item status, rendered as its own icon. */
+  readonly status?: CheckStatus;
+}
+
+/** Result of a single doctor check. */
+export interface CheckResult {
+  readonly name: string;
+  readonly status: CheckStatus;
+  /** One-line headline shown next to the check name. */
+  readonly detail: string;
+  /** Optional structured breakdown, rendered as indented sub-items. */
+  readonly items?: readonly CheckItem[];
+  /** Remedial instruction shown inline under a failing check. */
+  readonly remedy?: string;
+}
+
+/** Aggregated results from all doctor checks. */
+export interface DoctorData {
+  readonly checks: readonly CheckResult[];
+  readonly passed: number;
+  readonly failed: number;
+  readonly skipped: number;
+}

package/src/capabilities/emptyRecovery.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Empty-state for pack list verbs (U5, PROTECTED).
+ *
+ * Listing zero rows is a calm SUCCESS, not an error. The run body returns `[]`
+ * (no throw), dispatch renders a non-blank message and exits 0, and JSON stays
+ * `[]`. A pack's authored `emptyRecovery` becomes that message's HINT — the v2
+ * story still points at `pragma sources update` — but as guidance on the
+ * success path, never a thrown EMPTY_RESULTS (which maps to exit 1 and would
+ * break the uniform `ok:true` list contract).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compilePack } from "../kernel/packs/compile.js";
+import type { PackDefinition } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { executeVerb } from "../kernel/project/cli/dispatch.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { modifierPack } from "./modifier/pack.js";
+import { standardPack } from "./standard/pack.js";
+import { tokenPack } from "./token/pack.js";
+
+const PREFIXES = {
+  ds: "https://ds.canonical.com/",
+  cs: "https://ds.canonical.com/code-standards/",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+// The ontology (TBox) with NO individuals — a booted-but-empty store.
+const TTL = `
+@prefix ds: <https://ds.canonical.com/> .
+@prefix cs: <https://ds.canonical.com/code-standards/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+ds:ModifierFamily a owl:Class .
+ds:Modifier a owl:Class .
+ds:Token a owl:Class .
+ds:TokenType a owl:Class .
+cs:CodeStandard a owl:Class .
+cs:Category a owl:Class .
+ds:name a owl:DatatypeProperty ; rdfs:domain ds:ModifierFamily ; rdfs:range xsd:string .
+ds:hasModifier a owl:ObjectProperty ; rdfs:domain ds:ModifierFamily ; rdfs:range ds:Modifier .
+ds:modifierFamily a owl:ObjectProperty ; rdfs:domain ds:Modifier ; rdfs:range ds:ModifierFamily .
+ds:tokenId a owl:DatatypeProperty ; rdfs:domain ds:Token ; rdfs:range xsd:string .
+ds:tokenType a owl:ObjectProperty ; rdfs:domain ds:Token ; rdfs:range ds:TokenType .
+cs:description a owl:DatatypeProperty ; rdfs:domain cs:CodeStandard ; rdfs:range xsd:string .
+cs:slug a owl:DatatypeProperty ; rdfs:domain cs:Category ; rdfs:range xsd:string .
+`;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+const listVerb = (pack: PackDefinition): VerbSpec =>
+  compilePack(pack, `bundled:${pack.noun}`, DEFAULT_PREFIX_MAP).find(
+    (v) => verbKey(v.path) === `${pack.noun} list`,
+  ) as VerbSpec;
+
+/**
+ * Every bundled pack list verb, with the hint expected in its empty message:
+ * an authored `emptyRecovery` surfaces `pragma sources update`; the others fall
+ * back to the generic build/broaden hint.
+ */
+const PACK_LISTS: readonly { pack: PackDefinition; hint: RegExp }[] = [
+  { pack: modifierPack, hint: /pragma sources update/ },
+  { pack: tokenPack, hint: /pragma sources update/ },
+  { pack: standardPack, hint: /broaden your filter/ },
+];
+
+const REAL = { dryRun: false, undo: false, yes: false };
+
+describe("pack list empty-state (U5, PROTECTED)", () => {
+  it.each(
+    PACK_LISTS,
+  )("$pack.noun list on an empty store returns [] — never throws", async ({
+    pack,
+  }) => {
+    await expect(listVerb(pack).run({}, rt)).resolves.toEqual([]);
+  });
+
+  it.each(
+    PACK_LISTS,
+  )("$pack.noun list renders a non-blank message (+ hint) and keeps JSON []", ({
+    pack,
+    hint,
+  }) => {
+    const { formatters } = listVerb(pack).output;
+    const plain = formatters.plain([]);
+    expect(plain).toContain(`No ${pack.noun} entries found.`);
+    expect(plain).toMatch(hint);
+    // JSON is the uniform empty array — unchanged by the message.
+    expect(formatters.json([])).toBe("[]");
+    // The llm view stays non-blank too (the `(0)` heading plus the message).
+    expect(formatters.llm([]).trim().length).toBeGreaterThan(0);
+  });
+
+  it("dispatch prints the empty message on stdout and exits 0 (end-to-end)", async () => {
+    const outcome = await executeVerb(listVerb(modifierPack), {}, REAL, rt);
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("No modifier entries found.");
+    expect(outcome.stdout).toContain("pragma sources update");
+  });
+});

package/src/capabilities/graph/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The `graph` capability module — `inspect` (single-entity read) plus `query`
+ * (the raw SPARQL escape hatch, PR6). The covenant blesses both.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { resourceProvider } from "../resources/index.js";
+import { graphInspectVerb } from "./inspect.verb.js";
+import { graphQueryVerb } from "./query.verb.js";
+
+/**
+ * The `graph` capability module. Carries the MCP resource browser: `graph
+ * inspect` (CLI) and the resource read (MCP) share one entity reader, so the
+ * two projections stay in lockstep. Resources are NOT tools — the emitted tool
+ * surface (and the golden) is unaffected.
+ */
+export const graphModule: CapabilityModule = {
+  name: "graph",
+  verbs: [graphInspectVerb, graphQueryVerb],
+  mcpResources: resourceProvider,
+};

package/src/capabilities/graph/inspect.render.ts

@@ -0,0 +1,38 @@
+/**
+ * Formatters for `graph inspect` — predicate/object groups, prefix-compacted.
+ */
+
+import { compactUri } from "../../kernel/render/compactUri.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { InspectResult } from "../../kernel/runtime/readEntity.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+
+const compact = (value: string): string =>
+  compactUri(value, DEFAULT_PREFIX_MAP);
+
+export const inspectFormatters: Formatters<InspectResult> = {
+  plain(data) {
+    const title = data.label
+      ? `${compact(data.uri)} — ${data.label}`
+      : compact(data.uri);
+    const lines = [title, "═".repeat(Math.max(title.length, 24)), ""];
+    for (const group of data.groups) {
+      lines.push(`  ${compact(group.predicate)}:`);
+      for (const object of group.objects) lines.push(`    ${compact(object)}`);
+    }
+    return lines.join("\n").trimEnd();
+  },
+  llm(data) {
+    const lines = [
+      `## ${compact(data.uri)}${data.label ? ` — ${data.label}` : ""}`,
+      "",
+    ];
+    for (const group of data.groups) {
+      lines.push(
+        `- **${compact(group.predicate)}**: ${group.objects.map(compact).join(", ")}`,
+      );
+    }
+    return lines.join("\n").trimEnd();
+  },
+  json: (data) => JSON.stringify(data, null, 2),
+};

package/src/capabilities/graph/inspect.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `graph inspect` over the block fixture graph.
+ *
+ * Resolves a prefixed name / absolute IRI and returns every predicate/object on
+ * the subject, ordered by predicate. (The identical-content mirror with the MCP
+ * resource read is asserted in the resources suite.)
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import type { InspectResult } from "../../kernel/runtime/readEntity.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  BLOCK_PREFIXES,
+  BLOCK_TTL,
+} from "../../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { graphModule } from "./index.js";
+
+const DS = "https://ds.canonical.com/";
+const inspectVerb = graphModule.verbs.find(
+  (v) => verbKey(v.path) === "graph inspect",
+) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({
+    ttl: BLOCK_TTL,
+    prefixes: BLOCK_PREFIXES,
+  }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+describe("graph inspect", () => {
+  it("resolves a prefixed name and groups triples by predicate", async () => {
+    const result = (await inspectVerb.run(
+      { uri: "ds:button" },
+      rt,
+    )) as InspectResult;
+    expect(result.uri).toBe(`${DS}button`);
+    const rdfType = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+    const typeGroup = result.groups.find((g) => g.predicate === rdfType);
+    expect(typeGroup?.objects).toContain(`${DS}Component`);
+    const summary = result.groups.find((g) => g.predicate === `${DS}summary`);
+    expect(summary?.objects[0]).toBe(
+      "Primary action trigger with optional icon and label.",
+    );
+  });
+
+  it("resolves an absolute IRI to the same result", async () => {
+    const byPrefixed = (await inspectVerb.run(
+      { uri: "ds:button" },
+      rt,
+    )) as InspectResult;
+    const byIri = (await inspectVerb.run(
+      { uri: `${DS}button` },
+      rt,
+    )) as InspectResult;
+    expect(byIri).toEqual(byPrefixed);
+  });
+
+  it("rejects an unknown subject with a not-found error", async () => {
+    await expect(inspectVerb.run({ uri: "ds:nonesuch" }, rt)).rejects.toThrow(
+      /not found/i,
+    );
+  });
+
+  it("rejects an injection payload in the URI instead of embedding it", async () => {
+    // A prefixed name whose local part tries to break out of the `<iri>` token:
+    // resolveUri → assertSafeIri rejects the IRI-breaking characters (`>`, `}`,
+    // whitespace) BEFORE any SPARQL is built, so the payload never reaches the
+    // query text. It must surface as INVALID_INPUT, not a benign not-found.
+    await expect(
+      inspectVerb.run({ uri: 'ds:button> } INSERT { ?s ?p "x" } #' }, rt),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+});

package/src/capabilities/graph/inspect.verb.ts

@@ -0,0 +1,51 @@
+/**
+ * `graph inspect <uri>` — every triple where the URI is the subject, grouped by
+ * predicate. The CLI twin of the MCP resource read (both share {@link readEntity}
+ * in PR3's resources browser); `graph query` (arbitrary SPARQL) lands in PR6.
+ *
+ * Store-backed: the URI is resolved through the store's merged prefix map and
+ * validated to the embeddable shape before it is interpolated, so a prefixed
+ * name or absolute IRI addresses the subject exactly.
+ */
+
+import type { InspectResult } from "../../kernel/runtime/readEntity.js";
+import { readEntity } from "../../kernel/runtime/readEntity.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { inspectFormatters } from "./inspect.render.js";
+
+const inspectVerb: VerbSpec<Record<string, unknown>, InspectResult> = {
+  path: ["graph", "inspect"],
+  summary:
+    "Show every triple where a URI is the subject, grouped by predicate.",
+  doc: "Inspect one entity: all predicate/object pairs asserted on the subject. Address it by prefixed name (ds:button) or absolute IRI.",
+  params: [
+    {
+      kind: "string",
+      name: "uri",
+      doc: "The subject URI — a prefixed name or absolute IRI.",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "index", type: "" } },
+    },
+  ],
+  output: { formatters: inspectFormatters },
+  examples: [
+    { cmd: "pragma graph inspect ds:button" },
+    { cmd: "pragma graph inspect https://ds.canonical.com/button" },
+  ],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
+    readEntity(rt, String(params.uri)),
+};
+
+/** The `graph inspect` verb. */
+export const graphInspectVerb = asVerb(inspectVerb);

package/src/capabilities/graph/query.render.ts

@@ -0,0 +1,77 @@
+/**
+ * Formatters for `pragma graph query` — plain, llm, json (no ink).
+ *
+ * Ported verbatim from the old shell's `graph/formatters/query.ts`:
+ * - plain: a tab-separated table for SELECT, `ASK: true/false`, readable triple
+ *   lines for CONSTRUCT.
+ * - llm: condensed Markdown (a table for SELECT, one line for ASK, a triple list
+ *   for CONSTRUCT).
+ * - json: the serialized {@link QueryResult}.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+
+// Inline `import("…")` type (no `from`) — keeps the ke types off the static
+// import graph the lazy-dispatch probe walks (see query.verb.ts).
+type QueryResult = import("@canonical/ke").QueryResult;
+
+/**
+ * Render CONSTRUCT triples as readable `subject\tpredicate\tobject` lines,
+ * collapsing any newlines in literal objects so each triple stays on one line.
+ */
+function formatTriples(
+  triples: ReadonlyArray<{
+    subject: string;
+    predicate: string;
+    object: string;
+  }>,
+): string {
+  if (triples.length === 0) return "No triples.";
+  return triples
+    .map((t) => {
+      const object = t.object.replace(/\s*\n\s*/g, " ").trim();
+      return `${t.subject}\t${t.predicate}\t${object}`;
+    })
+    .join("\n");
+}
+
+export const queryFormatters: Formatters<QueryResult> = {
+  plain(result) {
+    if (result.type === "select") {
+      if (result.bindings.length === 0) return "No results.";
+      const cols = Object.keys(result.bindings[0] ?? {});
+      const rows = result.bindings.map((b) =>
+        cols.map((c) => b[c] ?? "").join("\t"),
+      );
+      return [cols.join("\t"), ...rows].join("\n");
+    }
+    if (result.type === "ask") {
+      return `ASK: ${String(result.result)}`;
+    }
+    return formatTriples(result.triples);
+  },
+
+  llm(result) {
+    if (result.type === "select") {
+      if (result.bindings.length === 0) return "_No results._";
+      const cols = Object.keys(result.bindings[0] ?? {});
+      const header = `| ${cols.join(" | ")} |`;
+      const divider = `| ${cols.map(() => "---").join(" | ")} |`;
+      const rows = result.bindings.map(
+        (b) => `| ${cols.map((c) => b[c] ?? "").join(" | ")} |`,
+      );
+      return [header, divider, ...rows].join("\n");
+    }
+    if (result.type === "ask") {
+      return `**ASK** → ${String(result.result)}`;
+    }
+    return formatTriples(result.triples)
+      .split("\n")
+      .map((line) => (line.includes("\t") ? `- ${line}` : line))
+      .join("\n");
+  },
+
+  json(result) {
+    return JSON.stringify(result);
+  },
+};