@canonical/pragma-cli 0.32.0 → 0.33.0

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

@@ -7,11 +7,16 @@
  * 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";
@@ -44,6 +49,48 @@ describe("resource listing (storeless, over the pack index)", () => {
     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");
@@ -111,4 +158,56 @@ describe("resource surface over the server (embedded pack)", () => {
     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/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

@@ -3,4 +3,10 @@
  */
 
 export { setupModule } from "./setup.verb.js";
-export type { SetupResult, SetupSkillsResult, SymlinkAction } from "./types.js";
+export type {
+  ConfiguredTarget,
+  ScopeSelection,
+  SetupResult,
+  SetupSkillsResult,
+  SymlinkAction,
+} from "./types.js";

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

@@ -10,6 +10,7 @@
  * `setup completions`").
  */
 
+import { existsSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import {
   deleteFile,
@@ -26,15 +27,39 @@ import {
   detectShell,
   type ShellId,
 } from "../shell.js";
+import type { CompletionsState } from "../types.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.
+ * 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";
+  }
 }
 
 /**
@@ -52,7 +77,7 @@ export async function detectCompletions(
   cwd: string,
 ): Promise<CompletionsDetection> {
   const shell = detectShell();
-  if (!shell) return { shell: null, path: null, script: null };
+  if (!shell) return { shell: null, path: null, script: null, state: "absent" };
 
   const [{ capabilities }, { emitScripts }, { readConfig }] = await Promise.all(
     [
@@ -68,18 +93,16 @@ export async function detectCompletions(
         .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],
-  };
+  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) };
 }
 
 /**
@@ -89,6 +112,12 @@ export async function detectCompletions(
  * 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.
  */
@@ -98,9 +127,13 @@ export function composeCompletions(d: CompletionsDetection): Task<void> {
       "Could not detect your shell — set $SHELL to zsh, bash, or fish.",
     );
   }
-  const { path, script, shell } = d;
+  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(`Installing ${shell} completions to ${path}...`),
+    info(opening),
     mkdir(dirname(path), true),
     writeFile(path, script, { undo: deleteFile(path) }),
     info(activationHint(shell)),