@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/resources/provider.ts

@@ -0,0 +1,231 @@
+/**
+ * The MCP resource browser — a `pragma:{+uri}` template over the pack index.
+ *
+ * Listing and autocomplete are STORELESS: they read the enriched `index.json`
+ * (readPackIndex) off disk, so the resource surface costs nothing until an agent
+ * reads one. A read is STORE-BACKED through the SHARED {@link readEntity} — the
+ * same reader `graph inspect` uses — so a resource read and a `graph inspect` of
+ * the same URI return identical content (the mirror contract).
+ *
+ * Degradation (Risk4): on a missing or legacy (pre-v2) index the listing returns
+ * a single "run `pragma sources update`" hint — never a live re-index of the
+ * store on the resource path.
+ *
+ * The MCP SDK's `ResourceTemplate` is dynamic-imported inside `register` so this
+ * module — reachable on the capabilities import graph — never pulls the SDK onto
+ * the `--help`/`__complete` fast path.
+ */
+
+import { readPackIndex } from "../../kernel/completion/entitySource.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
+import { readEntity } from "../../kernel/runtime/readEntity.js";
+import type { McpResourceProvider } from "../../kernel/spec/types.js";
+
+/** Max autocomplete suggestions returned for a partial URI. */
+const COMPLETION_LIMIT = 50;
+
+/** MCP annotation priority for a schema (TBox) entry — surfaced above individuals. */
+const CLASS_PRIORITY = 0.9;
+/** MCP annotation priority for an individual (ABox) entry. */
+const INDIVIDUAL_PRIORITY = 0.3;
+
+/** The `pragma:` URI scheme + the single reserved-expansion template variable. */
+const URI_TEMPLATE = "pragma:{+uri}";
+
+const TEMPLATE_DESCRIPTION =
+  "Knowledge-graph entities from the local pack. Read any entry by its prefixed " +
+  "URI (e.g. pragma:ds:button); autocomplete matches URI or label substrings. " +
+  "Content mirrors `pragma graph inspect <uri>`.";
+
+/** Agent-navigability annotations mirrored onto a listed resource. */
+export interface ResourceAnnotations {
+  /** MCP audience roles (the SDK's literal union) — always the assistant here. */
+  readonly audience: ("user" | "assistant")[];
+  readonly priority: number;
+}
+
+/** The audience every listed resource carries (assistant-facing). */
+const ASSISTANT_AUDIENCE: ("user" | "assistant")[] = ["assistant"];
+
+/** One resource entry in the listing. */
+export interface ListedResource {
+  readonly uri: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly mimeType: "application/json";
+  /** Audience + priority (schema surfaced above individuals). */
+  readonly annotations?: ResourceAnnotations;
+  /** Taxonomy metadata: `pragma/box` (tbox|abox) + optional instance count. */
+  readonly _meta?: Record<string, unknown>;
+}
+
+/**
+ * Build the resource listing from the storeless pack index.
+ *
+ * @param index - The active pack index, or `undefined` when none is reachable.
+ * @returns One resource per indexed entity, schema (TBox) first; a single
+ *   recovery entry when the index is missing or pre-v2 (no enrichment).
+ */
+export function buildResourceList(
+  index: PackIndex | undefined,
+): ListedResource[] {
+  // readPackIndex returns raw JSON.parse output (no zod), so guard structurally:
+  // a malformed index missing `version` must degrade to the recovery hint, not
+  // fall through to `[...index.entities]` (a TypeError inside the MCP handler).
+  if (!index || index.version !== 2 || !Array.isArray(index.entities)) {
+    return [
+      {
+        uri: "pragma:sources",
+        name: "Store not indexed",
+        description:
+          "No enriched entity index. Run `pragma sources update` to build it.",
+        mimeType: "application/json",
+      },
+    ];
+  }
+  const ordered = [...index.entities].sort((a, b) => {
+    const boxRank = (e: typeof a) => (e.box === "tbox" ? 0 : 1);
+    return boxRank(a) - boxRank(b) || a.name.localeCompare(b.name);
+  });
+  return ordered.map((entity) => {
+    const isTbox = entity.box === "tbox";
+    // Port of the old shell's `_meta` taxonomy: `pragma/box` + a priority that
+    // ranks schema (classes/properties) above individuals, so an agent browsing
+    // the resource list sees the schema first. `pragma/instanceCount` is the
+    // per-type count carried in the index for a TBox class entry.
+    // `instanceCountByType` is keyed by the full type IRI; a TBox class entry's
+    // own IRI is that key, so it carries the count of its individuals.
+    const instanceCount =
+      isTbox && entity.uri ? index.instanceCountByType[entity.uri] : undefined;
+    const meta: Record<string, unknown> = {
+      "pragma/box": entity.box ?? "abox",
+    };
+    if (typeof instanceCount === "number") {
+      meta["pragma/instanceCount"] = instanceCount;
+    }
+    return {
+      uri: `pragma:${entity.prefixed ?? entity.name}`,
+      name: entity.label || entity.name,
+      ...(entity.description ? { description: entity.description } : {}),
+      mimeType: "application/json" as const,
+      annotations: {
+        audience: ASSISTANT_AUDIENCE,
+        priority: isTbox ? CLASS_PRIORITY : INDIVIDUAL_PRIORITY,
+      },
+      _meta: meta,
+    };
+  });
+}
+
+/**
+ * Rank URI autocomplete candidates against a partial query (case-insensitive over
+ * both the prefixed URI and the label; exact > prefix > substring), capped.
+ */
+export function rankUriCompletions(
+  entities: readonly PackIndex["entities"][number][],
+  query: string,
+  limit: number,
+): string[] {
+  const needle = query.toLowerCase();
+  const score = (field: string): number =>
+    field === needle
+      ? 3
+      : field.startsWith(needle)
+        ? 2
+        : field.includes(needle)
+          ? 1
+          : 0;
+  const scored: { prefixed: string; score: number }[] = [];
+  for (const entity of entities) {
+    const prefixed = entity.prefixed ?? entity.name;
+    const uriScore = score(prefixed.toLowerCase());
+    const labelScore = entity.label ? score(entity.label.toLowerCase()) : 0;
+    const best = Math.max(uriScore, labelScore);
+    if (best > 0) scored.push({ prefixed, score: best });
+  }
+  scored.sort((a, b) =>
+    b.score !== a.score
+      ? b.score - a.score
+      : a.prefixed.localeCompare(b.prefixed),
+  );
+  const seen = new Set<string>();
+  const ranked: string[] = [];
+  for (const { prefixed } of scored) {
+    if (seen.has(prefixed)) continue;
+    seen.add(prefixed);
+    ranked.push(prefixed);
+    if (ranked.length >= limit) break;
+  }
+  return ranked;
+}
+
+/** Read the single `uri` template variable, tolerating array expansion. */
+function readUriVariable(value: string | string[] | undefined): string {
+  const uri = Array.isArray(value) ? value.at(0) : value;
+  if (uri === undefined) {
+    throw PragmaError.invalidInput("uri", String(value), {
+      recovery: { message: "Provide a prefixed or full entity URI." },
+    });
+  }
+  return uri;
+}
+
+/** The graph-entity resource provider (registered by buildServer). */
+export const resourceProvider: McpResourceProvider = {
+  // The single authoring point for the template id — the surface emitter reads
+  // this so `mcpSurface.resources` cannot drift from what `register` installs.
+  surface: { templates: [URI_TEMPLATE] },
+  async register(server, runtime) {
+    const { ResourceTemplate } = await import(
+      "@modelcontextprotocol/sdk/server/mcp.js"
+    );
+    const template = new ResourceTemplate(URI_TEMPLATE, {
+      list: async () => ({
+        resources: buildResourceList(readPackIndex(runtime.cwd)),
+      }),
+      complete: {
+        uri: async (value: string) =>
+          rankUriCompletions(
+            readPackIndex(runtime.cwd)?.entities ?? [],
+            value,
+            COMPLETION_LIMIT,
+          ),
+      },
+    });
+
+    server.registerResource(
+      "graph-entity",
+      template,
+      { description: TEMPLATE_DESCRIPTION, mimeType: "application/json" },
+      async (
+        url: URL,
+        variables: Record<string, string | string[] | undefined>,
+      ) => {
+        try {
+          const uri = readUriVariable(variables.uri);
+          const entity = await readEntity(runtime, uri);
+          return {
+            contents: [
+              {
+                uri: url.href,
+                mimeType: "application/json",
+                text: JSON.stringify(entity, null, 2),
+              },
+            ],
+          };
+        } catch (error) {
+          const message =
+            error instanceof PragmaError
+              ? JSON.stringify({ code: error.code, message: error.message })
+              : String(error);
+          return {
+            contents: [
+              { uri: url.href, mimeType: "text/plain", text: message },
+            ],
+          };
+        }
+      },
+    );
+  },
+};

package/src/capabilities/resources/resources.test.ts

@@ -0,0 +1,114 @@
+/**
+ * The MCP resource browser (PROTECTED).
+ *
+ * list/autocomplete are storeless over the enriched pack index; a read is
+ * store-backed and shares `graph inspect`'s entity reader (the mirror). Resources
+ * never enter the emitted tool surface. On a missing/legacy index the listing
+ * degrades to a `pragma sources update` hint (never a live re-index).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { readPackIndex } from "../../kernel/completion/entitySource.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
+import type { InspectResult } from "../../kernel/runtime/readEntity.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { graphModule } from "../graph/index.js";
+import { buildResourceList, rankUriCompletions } from "./provider.js";
+
+describe("resource listing (storeless, over the pack index)", () => {
+  it("degrades to a recovery entry on a missing or legacy index", () => {
+    expect(buildResourceList(undefined)).toEqual([
+      expect.objectContaining({
+        uri: "pragma:sources",
+        name: "Store not indexed",
+      }),
+    ]);
+    const legacy = { version: 1, entities: [] } as unknown as PackIndex;
+    expect(buildResourceList(legacy)[0]?.uri).toBe("pragma:sources");
+  });
+
+  it("lists the enriched (v2) embedded index, schema entries first", () => {
+    const index = readPackIndex(process.cwd());
+    expect(index?.version).toBe(2);
+    const resources = buildResourceList(index);
+    expect(resources.some((r) => r.uri === "pragma:ex:Button")).toBe(true);
+    // A class (tbox) sorts before an individual (abox).
+    const componentIdx = resources.findIndex(
+      (r) => r.uri === "pragma:ex:Component",
+    );
+    const buttonIdx = resources.findIndex((r) => r.uri === "pragma:ex:Button");
+    expect(componentIdx).toBeLessThan(buttonIdx);
+  });
+
+  it("enriches each entry with the _meta taxonomy (pragma/box + priority)", () => {
+    const resources = buildResourceList(readPackIndex(process.cwd()));
+    const component = resources.find((r) => r.uri === "pragma:ex:Component");
+    const button = resources.find((r) => r.uri === "pragma:ex:Button");
+    // A schema class: tbox, higher priority, carries its instance count.
+    expect(component?._meta?.["pragma/box"]).toBe("tbox");
+    expect(component?.annotations?.audience).toEqual(["assistant"]);
+    expect(component?.annotations?.priority).toBe(0.9);
+    expect(component?._meta?.["pragma/instanceCount"]).toBe(3);
+    // An individual: abox, lower priority, no instance count.
+    expect(button?._meta?.["pragma/box"]).toBe("abox");
+    expect(button?.annotations?.priority).toBe(0.3);
+    expect(button?._meta?.["pragma/instanceCount"]).toBeUndefined();
+  });
+
+  it("ranks autocomplete over prefixed URI and label", () => {
+    const index = readPackIndex(process.cwd());
+    const hits = rankUriCompletions(index?.entities ?? [], "but", 10);
+    expect(hits).toContain("ex:Button");
+  });
+});
+
+describe("resource surface over the server (embedded pack)", () => {
+  let harness: Awaited<ReturnType<typeof projectMcp>>;
+  beforeAll(async () => {
+    harness = await projectMcp([graphModule]);
+  });
+  afterAll(async () => {
+    await harness.cleanup();
+  });
+
+  it("registers the {+uri} template and lists resources (not tools)", async () => {
+    const resources = await harness.listResources();
+    expect(resources.some((r) => r.uri === "pragma:ex:Button")).toBe(true);
+    // Resources are NOT tools — the graph module's tools (inspect + the PR6
+    // SPARQL escape hatch) are what appear in the tool surface.
+    const tools = await harness.listTools();
+    expect(tools.map((t) => t.name).sort()).toEqual([
+      "graph_inspect",
+      "graph_query",
+    ]);
+  });
+
+  it("autocompletes a partial URI through the template", async () => {
+    const values = await harness.completeResource("But");
+    expect(values).toContain("ex:Button");
+  });
+
+  it("reads an entity, mirroring `graph inspect` content", async () => {
+    const read = await harness.readResource("pragma:ex:Button");
+    expect(read.mimeType).toBe("application/json");
+    const fromResource = JSON.parse(read.text) as InspectResult;
+
+    // The CLI twin over the same (embedded) pack must return identical content.
+    const rt = bootRuntime(TEST_FLAGS);
+    const inspect = graphModule.verbs.find(
+      (v) => verbKey(v.path) === "graph inspect",
+    ) as VerbSpec;
+    const fromCli = (await inspect.run(
+      { uri: "ex:Button" },
+      rt,
+    )) as InspectResult;
+    (await rt.store.get()).store.dispose();
+
+    expect(fromResource).toEqual(fromCli);
+    expect(fromResource.uri).toBe("https://pragma.canonical.com/sample#Button");
+  });
+});

package/src/capabilities/roundtrip.test.ts

@@ -0,0 +1,107 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { VERSION } from "../constants.js";
+import { executeVerb } from "../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { projectMcp } from "../testing/helpers/projectMcp.js";
+import { configModule } from "./config/index.js";
+import { infoModule } from "./info/index.js";
+
+const infoVerb = infoModule.verbs[0] as VerbSpec;
+const showVerb = configModule.verbs[0] as VerbSpec;
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+
+function flags(format: "plain" | "json", llm = false): GlobalFlags {
+  return { llm, autoLlm: false, format, verbose: false };
+}
+
+const originalConfigHome = process.env.XDG_CONFIG_HOME;
+
+/** A fresh XDG config home + a fresh cwd, so config resolves deterministically. */
+function freshEnv(): string {
+  process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "pragma-rt-cfg-"));
+  return mkdtempSync(join(tmpdir(), "pragma-rt-cwd-"));
+}
+
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = originalConfigHome;
+});
+
+describe("info round-trip", () => {
+  it("renders plain and llm on the CLI", async () => {
+    const cwd = freshEnv();
+    const plain = await executeVerb(
+      infoVerb,
+      {},
+      NO_MUT,
+      bootRuntime(flags("plain"), cwd),
+    );
+    expect(plain.stdout).toContain(`pragma v${VERSION}`);
+    expect(plain.stdout).toContain("channel: normal");
+
+    const llm = await executeVerb(
+      infoVerb,
+      {},
+      NO_MUT,
+      bootRuntime(flags("plain", true), cwd),
+    );
+    expect(llm.stdout).toContain(`# pragma v${VERSION}`);
+  });
+
+  it("CLI --format json deep-equals the MCP tool envelope", async () => {
+    const cwd = freshEnv();
+    const cli = await executeVerb(
+      infoVerb,
+      {},
+      NO_MUT,
+      bootRuntime(flags("json"), cwd),
+    );
+    const cliEnvelope = JSON.parse(cli.stdout as string);
+
+    const mcp = await projectMcp([infoModule], cwd);
+    const mcpEnvelope = await mcp.callTool("info");
+    await mcp.cleanup();
+
+    expect(cliEnvelope).toEqual(mcpEnvelope);
+    expect(cliEnvelope.ok).toBe(true);
+    expect((cliEnvelope.data as { version: string }).version).toBe(VERSION);
+  });
+});
+
+describe("config show round-trip", () => {
+  it("renders plain with origin markers on the CLI", async () => {
+    const cwd = freshEnv();
+    const plain = await executeVerb(
+      showVerb,
+      {},
+      NO_MUT,
+      bootRuntime(flags("plain"), cwd),
+    );
+    expect(plain.stdout).toContain("channel: normal");
+    expect(plain.stdout).toContain("detail: standard");
+  });
+
+  it("CLI --format json deep-equals the MCP tool envelope", async () => {
+    const cwd = freshEnv();
+    const cli = await executeVerb(
+      showVerb,
+      {},
+      NO_MUT,
+      bootRuntime(flags("json"), cwd),
+    );
+    const cliEnvelope = JSON.parse(cli.stdout as string);
+
+    const mcp = await projectMcp([configModule], cwd);
+    const mcpEnvelope = await mcp.callTool("config_show");
+    await mcp.cleanup();
+
+    expect(cliEnvelope).toEqual(mcpEnvelope);
+    expect(
+      (cliEnvelope.data as { config: { channel: string } }).config.channel,
+    ).toBe("normal");
+  });
+});

package/src/capabilities/setup/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `setup` capability barrel.
+ */
+
+export { setupModule } from "./setup.verb.js";
+export type { SetupResult, SetupSkillsResult, SymlinkAction } from "./types.js";

package/src/capabilities/setup/operations/setupCompletions.ts

@@ -0,0 +1,108 @@
+/**
+ * `setup completions` — install the static shell-completion script.
+ *
+ * Split into a `detect` phase (a REAL read of the shell, the `completion` config,
+ * and the grammar-driven `emitScripts(capabilities)` body — with the config's
+ * `minChars` gate and per-family opt-out baked in at emit time — done up front so
+ * the wizard's recap/preview and a `--dry-run` are accurate) and a pure `compose`
+ * phase (the file write the dry-run interpreter mocks). The script body is the
+ * static tier the covenant names ("shell script tier emitted by
+ * `setup completions`").
+ */
+
+import { dirname } from "node:path";
+import {
+  deleteFile,
+  info,
+  mkdir,
+  sequence_,
+  type Task,
+  warn,
+  writeFile,
+} from "@canonical/task";
+import {
+  activationHint,
+  completionScriptPath,
+  detectShell,
+  type ShellId,
+} from "../shell.js";
+
+/**
+ * The detected completion install target: the shell, the absolute script path,
+ * and the emitted script body — all `null` when no shell could be detected.
+ */
+export interface CompletionsDetection {
+  readonly shell: ShellId | null;
+  readonly path: string | null;
+  readonly script: string | null;
+}
+
+/**
+ * Detect the shell and pre-render its completion script, baking in the
+ * `completion` config (read from `cwd`): `minChars` gates the `__complete` exec
+ * in the emitted scripts, and a family mapped to `false` drops its name
+ * completion. Read here at emit time — never on the storeless `__complete` fast
+ * path.
+ *
+ * @param cwd - Directory the `completion` config layers are resolved from.
+ * @returns The install target, or an all-`null` shape when `$SHELL` is unset.
+ * @note Impure — reads `$SHELL`, the capability registry, and the config layers.
+ */
+export async function detectCompletions(
+  cwd: string,
+): Promise<CompletionsDetection> {
+  const shell = detectShell();
+  if (!shell) return { shell: null, path: null, script: null };
+
+  const [{ capabilities }, { emitScripts }, { readConfig }] = await Promise.all(
+    [
+      import("../../index.js"),
+      import("../../../kernel/completion/emitScripts.js"),
+      import("../../../kernel/config/readConfig.js"),
+    ],
+  );
+  const { config } = await readConfig(cwd);
+  const completion = config.completion;
+  const disabledFamilies = completion?.families
+    ? Object.entries(completion.families)
+        .filter(([, enabled]) => enabled === false)
+        .map(([family]) => family)
+    : undefined;
+  return {
+    shell,
+    path: completionScriptPath(shell),
+    script: emitScripts(capabilities, {
+      ...(completion?.minChars !== undefined
+        ? { minChars: completion.minChars }
+        : {}),
+      ...(disabledFamilies && disabledFamilies.length > 0
+        ? { disabledFamilies }
+        : {}),
+    })[shell],
+  };
+}
+
+/**
+ * Compose the completion-script write from a detection.
+ *
+ * Built from re-runnable combinators (NOT a single-use `gen`): `execute`
+ * interprets a generator's task TWICE — once for the confirm-gate preview and
+ * once to perform it — so the composed task must survive a second drive.
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task that writes the script (with an undo), or warns if no shell.
+ */
+export function composeCompletions(d: CompletionsDetection): Task<void> {
+  if (d.shell === null || d.path === null || d.script === null) {
+    return warn(
+      "Could not detect your shell — set $SHELL to zsh, bash, or fish.",
+    );
+  }
+  const { path, script, shell } = d;
+  return sequence_([
+    info(`Installing ${shell} completions to ${path}...`),
+    mkdir(dirname(path), true),
+    writeFile(path, script, { undo: deleteFile(path) }),
+    info(activationHint(shell)),
+  ]);
+}