@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,213 @@
+/**
+ * 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 { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+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 { writeLock } from "../../kernel/runtime/lock.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("emits ONE resource per URI for an OWL-punned subject (A8)", () => {
+    // A punned subject (a class IRI also asserted as an individual) is indexed
+    // as TWO facets — tbox + abox — sharing one prefixed URI. The listing must
+    // dedup them so the MCP resource surface carries no duplicate URI. The abox
+    // facet is listed first here to prove the dedup relies on the schema-first
+    // SORT, not input order.
+    const punned: PackIndex = {
+      version: 2,
+      contentHash: "test",
+      prefixes: {},
+      entities: [
+        {
+          name: "ex:Slider",
+          type: "ex:Category",
+          uri: "https://ex.test/#Slider",
+          prefixed: "ex:Slider",
+          types: ["owl:Class", "ex:Category"],
+          label: "Slider",
+          box: "abox",
+          description: null,
+        },
+        {
+          name: "ex:Slider",
+          type: "owl:Class",
+          uri: "https://ex.test/#Slider",
+          prefixed: "ex:Slider",
+          types: ["owl:Class", "ex:Category"],
+          label: "Slider",
+          box: "tbox",
+          description: null,
+        },
+      ],
+      instanceCountByType: {},
+    };
+    const slider = buildResourceList(punned).filter(
+      (r) => r.uri === "pragma:ex:Slider",
+    );
+    expect(slider).toHaveLength(1);
+    // The retained facet is the schema (tbox) one — surfaced above individuals.
+    expect(slider.at(0)?._meta?.["pragma/box"]).toBe("tbox");
+  });
+
+  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");
+  });
+
+  it("rejects a read of an absent entity as InvalidParams carrying ENTITY_NOT_FOUND", async () => {
+    // The warm embedded pack resolves the `ex:` prefix but holds no `Nonexistent`
+    // subject, so the read fails ENTITY_NOT_FOUND — the caller's fault, which
+    // `mcpErrorFrom` maps to JSON-RPC InvalidParams, NOT the InternalError a cold
+    // store (STORE_UNAVAILABLE) earns.
+    const error = await harness.readResource("pragma:ex:Nonexistent").then(
+      () => undefined,
+      (caught: unknown) => caught,
+    );
+    expect(error, "the read must throw, not swallow to content").toBeDefined();
+    expect((error as Error).message).toMatch(/not found/i);
+    const failure = error as { code?: number; data?: { code?: string } };
+    expect(failure.data?.code).toBe("ENTITY_NOT_FOUND");
+    expect(failure.code).toBe(ErrorCode.InvalidParams);
+    expect(failure.code).not.toBe(ErrorCode.InternalError);
+  });
+});
+
+/**
+ * D3 — a resource-read failure surfaces as a JSON-RPC error (the read analogue of
+ * a tool result's `isError`) carrying the recovery, NOT swallowed into a
+ * `text/plain` "success" body that drops the recovery and reads as though the
+ * entity itself were malformed. A lock pointing at an evicted pack is the cold
+ * store; the read boots the store, so it must refuse with STORE_UNAVAILABLE.
+ */
+describe("resource read — cold-store failure surfaces isError + recovery (D3)", () => {
+  let harness: Awaited<ReturnType<typeof projectMcp>>;
+  beforeAll(async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-resource-cold-"));
+    writeLock(cwd, { version: 1, contentHash: "b".repeat(64), packs: [] });
+    harness = await projectMcp([graphModule], cwd);
+  });
+  afterAll(async () => {
+    await harness.cleanup();
+  });
+
+  it("rejects (does not return text/plain content) with the STORE_UNAVAILABLE recovery", async () => {
+    const error = await harness.readResource("pragma:ex:Button").then(
+      () => undefined,
+      (caught: unknown) => caught,
+    );
+    expect(error, "the read must throw, not swallow to content").toBeDefined();
+    expect((error as Error).message).toMatch(/store unavailable/i);
+    const data = (
+      error as {
+        data?: { code?: string; recovery?: { mcp?: { tool?: string } } };
+      }
+    ).data;
+    expect(data?.code).toBe("STORE_UNAVAILABLE");
+    expect(data?.recovery?.mcp?.tool).toBe("sources_update");
+  });
+});

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/scopeTypeSync.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Type-sync pin (PROTECTED): the CLI's redeclared `ScopeBand`/`ScopeSelection`
+ * mirrors must stay structurally EQUAL to the `@canonical/harnesses` types.
+ *
+ * The CLI redeclares these in `doctor/types.ts` and `setup/types.ts` on purpose
+ * — so those statically-reachable type modules never pull the harnesses runtime
+ * onto the fast-path module graph (the lazy-dispatch invariant). That freedom is
+ * only safe if the mirrors do not DRIFT from the source of truth, which this
+ * `expectTypeOf` pin enforces at `tsc` time.
+ *
+ * Every harnesses import here is `import type` (type-only, erased at emit), so
+ * this file loads no harnesses runtime — the `lazy.test` no-runtime-import guard
+ * stays green (it also never reaches this test file: it walks the graph from
+ * `capabilities/index`, which imports no test).
+ */
+
+import type {
+  ScopeBand as HarnessScopeBand,
+  ScopeSelection as HarnessScopeSelection,
+} from "@canonical/harnesses";
+import { describe, expectTypeOf, it } from "vitest";
+import type { ScopeBand as DoctorScopeBand } from "./doctor/types.js";
+import type {
+  ScopeBand as SetupScopeBand,
+  ScopeSelection as SetupScopeSelection,
+} from "./setup/types.js";
+
+describe("scope type-sync — CLI mirrors == @canonical/harnesses", () => {
+  it("both ScopeBand mirrors equal the harnesses ScopeBand", () => {
+    expectTypeOf<DoctorScopeBand>().toEqualTypeOf<HarnessScopeBand>();
+    expectTypeOf<SetupScopeBand>().toEqualTypeOf<HarnessScopeBand>();
+  });
+
+  it("the setup ScopeSelection mirror equals the harnesses ScopeSelection", () => {
+    expectTypeOf<SetupScopeSelection>().toEqualTypeOf<HarnessScopeSelection>();
+  });
+});

package/src/capabilities/setup/index.ts

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

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

@@ -0,0 +1,141 @@
+/**
+ * `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 { existsSync, readFileSync } from "node:fs";
+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";
+import type { CompletionsState } from "../types.js";
+
+/**
+ * The detected completion install target: the shell, the absolute script path,
+ * the emitted script body — all `null` when no shell could be detected — and the
+ * prior on-disk {@link CompletionsState} (whether an up-to-date/stale script is
+ * already installed), read up front so the recap and a `--dry-run` are accurate
+ * and an identical rewrite is skipped.
+ */
+export interface CompletionsDetection {
+  readonly shell: ShellId | null;
+  readonly path: string | null;
+  readonly script: string | null;
+  readonly state: CompletionsState;
+}
+
+/**
+ * Classify the completion script already at `path` against the body we would
+ * write: `installed` when byte-identical (a re-run skips it), `stale` when a
+ * different script is present, `absent` when no file exists.
+ *
+ * @param path - The install path.
+ * @param script - The body a write would emit.
+ * @returns The prior {@link CompletionsState}.
+ * @note Impure — reads the install path.
+ */
+function classifyCompletions(path: string, script: string): CompletionsState {
+  if (!existsSync(path)) return "absent";
+  try {
+    return readFileSync(path, "utf8") === script ? "installed" : "stale";
+  } catch {
+    return "stale";
+  }
+}
+
+/**
+ * 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, state: "absent" };
+
+  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;
+  const path = completionScriptPath(shell);
+  const script = emitScripts(capabilities, {
+    ...(completion?.minChars !== undefined
+      ? { minChars: completion.minChars }
+      : {}),
+    ...(disabledFamilies && disabledFamilies.length > 0
+      ? { disabledFamilies }
+      : {}),
+  })[shell];
+  return { shell, path, script, state: classifyCompletions(path, script) };
+}
+
+/**
+ * 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.
+ *
+ * The prior `state` drives the MESSAGE only ("already up to date" / "Updating" /
+ * "Installing"), NOT whether the write happens: the (idempotent) write is always
+ * composed so it carries its `undo` — `--undo` reverses the SAME task and must
+ * find the reversible effect, and `execute` interprets the task twice. A
+ * byte-identical rewrite in the `installed` case is harmless.
+ *
+ * @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, state } = d;
+  const opening =
+    state === "installed"
+      ? `${shell} completions already up to date at ${path}.`
+      : `${state === "stale" ? "Updating" : "Installing"} ${shell} completions to ${path}...`;
+  return sequence_([
+    info(opening),
+    mkdir(dirname(path), true),
+    writeFile(path, script, { undo: deleteFile(path) }),
+    info(activationHint(shell)),
+  ]);
+}