@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/sources/runUpdate.ts

@@ -31,22 +31,24 @@ import {
   writeFile,
 } from "@canonical/task";
 import { VERSION } from "../../constants.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+// DIRECT LEAF IMPORT, not `graphpack/index.js`. The barrel re-exports
+// `embedded.ts`, which statically imports the ~1.9 MB generated pack — and
+// with per-file `tsc` output ESM evaluates that re-export when this module
+// loads. `sources update` builds a USER pack; it must not pay the embedded
+// pack's cost to do it.
 import { buildPack } from "../../kernel/runtime/graphpack/build.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { activePackPath, readActivePack } from "../../kernel/runtime/paths.js";
-import type { PackageRef } from "../../kernel/runtime/refs/parseRef.js";
-import {
-  parsePackDeclaration,
-  redactUrl,
-} from "../../kernel/runtime/refs/parseRef.js";
+import type { PackageRef } from "../../kernel/runtime/refs/index.js";
 import {
   detectPrefixClashes,
   harvestPrefixes,
+  parsePackDeclaration,
   type ResolvedPackage,
+  redactUrl,
   resolvePackage,
-} from "../../kernel/runtime/refs/resolve.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+} from "../../kernel/runtime/refs/index.js";
 import { installedSkillsDir } from "../skill/discover.js";
 import { planSkillInstall } from "./installSkills.js";
 import type { SourcesUpdateData } from "./types.js";
@@ -209,17 +211,17 @@ export async function buildUpdateTask(
   // prefix. Display-only, so a warning (not a hard failure) is the right call.
   for (const clash of detectPrefixClashes(inputs)) {
     report?.(
-      `Prefix "${clash.label}:" is declared with conflicting IRIs across packages (${clash.iris.join(" vs ")}); last wins, so some entities may compact to the wrong prefix.`,
+      `Prefix "${clash.label}:" is declared with conflicting IRIs across packs (${clash.iris.join(" vs ")}); last wins, so some entities may compact to the wrong prefix.`,
     );
   }
 
   report?.(`Building store from ${inputs.length} source(s)`);
   if (verbose) for (const input of inputs) report?.(`  parse ${input.path}`);
   if (stories.length > 0)
-    report?.(`Carrying ${stories.length} package read story file(s)`);
+    report?.(`Carrying ${stories.length} pack read story file(s)`);
 
   // Build the pack. On a parse/build failure, classify it as a NAMED data error
-  // (U6) — not INTERNAL_ERROR's "please report this issue" — identifying the
+  // (U6) — not INTERNAL_ERROR's "report this issue" — identifying the
   // offending package source, since ke's parser error carries only line/column.
   // With `--skip-invalid`, drop the unparseable sources (warning LOUDLY about
   // each — never a silent partial graph) and build from the rest instead of
@@ -262,7 +264,7 @@ export async function buildUpdateTask(
     );
     if (usableInputs.length === 0)
       throw PragmaError.configError(
-        `All ${inputs.length} configured source(s) failed to parse — nothing to build.`,
+        `None of the ${inputs.length} configured source(s) can be parsed — nothing to build.`,
         {
           recovery: cliRecovery(
             "sources update --verbose",
@@ -299,7 +301,7 @@ export async function buildUpdateTask(
       {
         recovery: cliRecovery(
           "sources update --verbose",
-          "Check that the package sources actually contain RDF triples, then re-run.",
+          "Check that the pack sources actually contain RDF triples, then re-run.",
         ),
       },
     );
@@ -322,13 +324,24 @@ export async function buildUpdateTask(
 
   // Install package-provided skills (U10): symlink each resolved package's
   // `skills/*` into the installed-skills root, so `skill list` / `setup skills`
-  // see them after an update. Kept in this Task (reversible: created links carry
-  // an unlink undo) so `sources update --undo` also removes them.
-  const skillLinks = planSkillInstall(resolved).filter(
-    (link) => link.action !== "skipped",
+  // see them after an update — and RETIRE the links of skills those packages
+  // have since dropped, which the same plan reports as `pruned`. Kept in this
+  // Task (reversible: a created link carries an unlink undo, a pruned one a
+  // re-link undo) so `sources update --undo` restores the root as it was.
+  //
+  // The two are split, not counted together: a prune is a deletion, so folding
+  // it into "Installing N skill(s)" would report a removal as an install.
+  const skillPlan = planSkillInstall(resolved);
+  const skillLinks = skillPlan.filter(
+    (link) => link.action === "created" || link.action === "replaced",
   );
+  const staleLinks = skillPlan.filter((link) => link.action === "pruned");
   if (skillLinks.length > 0)
     report?.(`Installing ${skillLinks.length} skill(s)`);
+  if (staleLinks.length > 0)
+    report?.(
+      `Removing ${staleLinks.length} skill link(s) no longer provided by any package`,
+    );
 
   report?.(`Pointing ${runtime.cwd} at pack ${built.contentHash.slice(0, 12)}`);
   return gen(function* () {
@@ -344,6 +357,25 @@ export async function buildUpdateTask(
         );
       }
     }
+    // No `mkdir` guard here: a stale link can only have been enumerated FROM
+    // the installed root, so the root necessarily exists.
+    //
+    // The undo re-creates the link exactly as found — dangling target and all —
+    // because undo's job is to restore the prior state, not to improve on it. It
+    // clears the path first because the undo interpreter MOCKS forward effects
+    // when collecting: the delete above may never have run, and `fs.symlink`
+    // refuses a path that already exists. Same delete-then-link shape the
+    // `replaced` branch above uses, for the same reason.
+    for (const stale of staleLinks) {
+      yield* $(
+        deleteFile(stale.linkPath, {
+          undo: gen(function* () {
+            yield* $(deleteFile(stale.linkPath));
+            yield* $(symlink(stale.target, stale.linkPath));
+          }),
+        }),
+      );
+    }
     return data;
   });
 }
@@ -385,12 +417,12 @@ export async function classifySourceBuildError(
   const culprit = await isolateBadSource(inputs);
   const detail = culprit?.message ?? parserMessage;
   const where = culprit
-    ? `Package source "${culprit.path}" could not be parsed`
-    : "The configured package sources could not be built into a store";
+    ? `Pack source "${culprit.path}" cannot be parsed`
+    : "The configured packs cannot be built into a store";
   return PragmaError.configError(`${where}: ${detail}`, {
     recovery: cliRecovery(
       "sources update --verbose",
-      "Re-run with --verbose to see each file as it parses. If a package ships malformed RDF, report it to that package's maintainer.",
+      "Re-run with --verbose to see each file as it parses. If a pack ships malformed RDF, report it to that pack's maintainer.",
     ),
   });
 }

package/src/capabilities/sources/sources.test.ts

@@ -1,9 +1,12 @@
 import { execFileSync } from "node:child_process";
 import {
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
+  readlinkSync,
   rmSync,
   symlinkSync,
   writeFileSync,
@@ -200,7 +203,7 @@ describe("sources update round-trip (PROTECTED)", () => {
   it("does not recurse into a symlinked directory cycle (L6 safety)", async () => {
     // The L6 fix follows symlinked FILES but must NOT recurse into a symlinked
     // DIRECTORY: a link to an ancestor dir is a cycle that, if walked, recurses
-    // without bound → a stack-overflow RangeError (an INTERNAL "please report").
+    // without bound → a stack-overflow RangeError (an INTERNAL "report").
     // The real `.ttl` is still ingested and the build completes.
     const pkg = tmp("pragma-symlink-cycle-");
     mkdirSync(join(pkg, "definitions"), { recursive: true });
@@ -499,7 +502,7 @@ describe("sources update — data-failure classification (U6)", () => {
     expect(err.message).toContain("bad-pkg/definitions/broken.ttl");
     // … carries the parser's own detail …
     expect(err.message.toLowerCase()).toContain("parser error");
-    // … and is NOT the internal-bug "please report this issue" path.
+    // … and is NOT the internal-bug "report this issue" path.
     expect(err.message).not.toContain("Internal error");
     expect(err.recovery?.message ?? "").not.toContain("report this issue");
     // The recovery points the user at a runnable, useful next step.
@@ -768,6 +771,155 @@ describe("sources update — installs package skills (U10)", () => {
 
     expect(existsSync(join(dataHome, "pragma", "skills", "bar"))).toBe(false);
   });
+
+  /** The installed-skills root, created so a prior install can be seeded into it. */
+  function installedRoot(): string {
+    const root = join(dataHome, "pragma", "skills");
+    mkdirSync(root, { recursive: true });
+    return root;
+  }
+
+  /** A symlink at `<installedRoot>/<name>` whose target does not exist. */
+  function danglingLink(root: string, name: string): string {
+    const target = join(tmp("pragma-uninstalled-"), "skills", name);
+    symlinkSync(target, join(root, name));
+    return target;
+  }
+
+  // The `@canonical/design-system` 0.2.0 regression: 0.1.2 shipped
+  // `component-specifier`, 0.2.0 deleted it in favour of `specify-component`,
+  // and every machine that had updated against 0.1.2 kept a symlink into a
+  // package directory that no longer exists.
+  it("prunes a link whose package dropped the skill", async () => {
+    const pkg = skillPackage("specify-component"); // the 0.2.0 shape
+    const root = installedRoot();
+    danglingLink(root, "component-specifier"); // what 0.1.2 left behind
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    expect(readdirSync(root)).toEqual(["specify-component"]);
+    expect(discoverSkills(cwd).map((s) => s.name)).not.toContain(
+      "component-specifier",
+    );
+  });
+
+  it("spares a manually-installed skill and a foreign link that still resolves", async () => {
+    const pkg = skillPackage("specify-component");
+    const root = installedRoot();
+    danglingLink(root, "component-specifier");
+
+    // A hand-installed skill: a REAL directory, belonging to no package. The
+    // install pass already refuses to clobber these; so must the prune pass.
+    const manual = join(root, "hand-written");
+    mkdirSync(manual, { recursive: true });
+    writeFileSync(
+      join(manual, "SKILL.md"),
+      "---\nname: hand-written\ndescription: Mine.\n---\n",
+    );
+    // Someone's own link into a checkout this update knows nothing about, and
+    // which still resolves. Deliberately RELATIVE: a relative target is stored
+    // relative to the LINK's directory, so resolving it against anything else
+    // (the cwd, say) would read as broken and eat a perfectly live link.
+    const foreign = join(dataHome, "elsewhere", "my-own");
+    mkdirSync(foreign, { recursive: true });
+    writeFileSync(
+      join(foreign, "SKILL.md"),
+      "---\nname: my-own\ndescription: Theirs.\n---\n",
+    );
+    symlinkSync(join("..", "..", "elsewhere", "my-own"), join(root, "my-own"));
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    // Only the dangling link went.
+    expect(readdirSync(root).sort()).toEqual([
+      "hand-written",
+      "my-own",
+      "specify-component",
+    ]);
+    expect(lstatSync(manual).isDirectory()).toBe(true);
+    expect(existsSync(join(manual, "SKILL.md"))).toBe(true);
+    expect(lstatSync(join(root, "my-own")).isSymbolicLink()).toBe(true);
+    expect(existsSync(join(root, "my-own"))).toBe(true); // still resolves
+    const found = discoverSkills(cwd).map((s) => s.name);
+    expect(found).toEqual(
+      expect.arrayContaining(["hand-written", "my-own", "specify-component"]),
+    );
+  });
+
+  it("re-points, rather than prunes, a dangling link the package still provides", async () => {
+    const pkg = skillPackage("foo");
+    const root = installedRoot();
+    danglingLink(root, "foo"); // e.g. the package moved to a new cache dir
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    // `replaced`, never `pruned`: the prune pass skips every name this run
+    // planned, or it would delete the link the install pass just created.
+    expect(readlinkSync(join(root, "foo"))).toBe(join(pkg, "skills", "foo"));
+    expect(discoverSkills(cwd).map((s) => s.name)).toContain("foo");
+  });
+
+  it("is reversible — undo restores a pruned link, dangling target and all", async () => {
+    const pkg = skillPackage("specify-component");
+    const root = installedRoot();
+    const staleTarget = danglingLink(root, "component-specifier");
+    const link = join(root, "component-specifier");
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    // The plan is made while the stale link is still there; `runUndo` MOCKS the
+    // forward effects, so stand in for the delete it would have performed.
+    const task = await buildUpdateTask(runtime);
+    rmSync(link);
+
+    const { runUndo } = await import("@canonical/task/node");
+    await runUndo(task);
+
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(link)).toBe(staleTarget); // the target it always had
+  });
+
+  it("undoes a prune whose forward delete never ran, rather than failing EEXIST", async () => {
+    const pkg = skillPackage("specify-component");
+    const root = installedRoot();
+    const staleTarget = danglingLink(root, "component-specifier");
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    // No `rmSync` this time: the link is still in place when the undo re-links,
+    // and `fs.symlink` refuses an existing path — so the undo must clear it.
+    const { runUndo } = await import("@canonical/task/node");
+    await expect(runUndo(await buildUpdateTask(runtime))).resolves.toBeTruthy();
+
+    expect(readlinkSync(join(root, "component-specifier"))).toBe(staleTarget);
+  });
+
+  it("plans no prunes when nothing was ever installed", async () => {
+    const pkg = skillPackage("foo"); // $XDG_DATA_HOME/pragma/skills absent
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    expect(readdirSync(join(dataHome, "pragma", "skills"))).toEqual(["foo"]);
+  });
 });
 
 describe("sources status — entityCount from the manifest (A10)", () => {

package/src/capabilities/sources/status.render.ts

@@ -4,7 +4,7 @@
 
 import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { SourcesStatusData } from "./types.js";
 
 /**

package/src/capabilities/sources/status.verb.ts

@@ -9,7 +9,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { statusFormatters } from "./status.render.js";
 import type { SourcesStatusData } from "./types.js";
 

package/src/capabilities/sources/update.render.ts

@@ -2,7 +2,7 @@
  * Formatters for `pragma sources update` — plain, llm, json.
  */
 
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { SourcesUpdateData } from "./types.js";
 
 export const updateFormatters: Formatters<SourcesUpdateData> = {

package/src/capabilities/sources/update.verb.ts

@@ -14,7 +14,7 @@
 
 import type { Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import type { SourcesUpdateData } from "./types.js";
 import { updateFormatters } from "./update.render.js";
 

package/src/capabilities/surface.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { buildOptionInfo } from "@canonical/summon-core/projection";
 import { describe, expect, it } from "vitest";
 import { MCP_SERVER_NAME, VERSION } from "../constants.js";
 import { emitSurface } from "../kernel/spec/emitSurface.js";
@@ -8,6 +9,7 @@ import {
   type Covenant,
 } from "../kernel/spec/surfaceConformance.js";
 import { projectMcp } from "../testing/helpers/projectMcp.js";
+import { CREATE_SURFACE } from "./create/createSurface.generated.js";
 import { capabilities } from "./index.js";
 
 /** The committed covenant, read from disk exactly as a consumer would. */
@@ -25,22 +27,40 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     expect(() => assertConforms(emitted, golden)).not.toThrow();
   });
 
-  it("emits config show + the one-command config set, in covenant order (field-verbs retired, B3)", () => {
+  it("emits the four config verbs — show, get, set, unset — in covenant order", () => {
     // AV-228 B3 retired the per-field `tier`/`channel`/`detail` setters; the
-    // config noun is now just the `show` reader and the `set <key> <value>` writer.
+    // config noun is the `show` dump, the `get <key>` single read, the
+    // `set <key> <value>` writer, and the `unset <key>` clearer. Reading one
+    // value and clearing one field are commands of their own — neither hides
+    // inside `show --format json` nor inside a reserved `set` value.
     expect(emitted.nouns.config?.verbs).toEqual([
       { v: "show", mcp: "config_show" },
+      { v: "get", args: ["<key>"], mcp: "config_get" },
       {
         v: "set",
         args: ["<key>", "<value>"],
         mutates: true,
         mcp: "config_set",
       },
+      {
+        v: "unset",
+        args: ["<key>"],
+        mutates: true,
+        mcp: "config_unset",
+      },
     ]);
     // info stays a data-only enrichment — its emitted verb is unchanged.
     expect(emitted.nouns.info?.verbs).toEqual([{ v: "info", mcp: "info" }]);
-    // Hidden meta verbs (__complete, mcp) are excluded from the surface.
-    expect(emitted.nouns.mcp).toBeUndefined();
+    // `version` is the command form of `--version`: one value, two spellings
+    // of the same read, and no tool — the version already rides `info`.
+    expect(emitted.nouns.version?.verbs).toEqual([
+      { v: "version", mcp: false },
+    ]);
+    // The server entry is a real noun/verb pair, emitted like any other and
+    // carrying no tool — it serves a protocol, it is not an agent tool.
+    expect(emitted.nouns.mcp?.verbs).toEqual([{ v: "serve", mcp: false }]);
+    // The completion resolver stays hidden — it is a protocol between the
+    // shell script and the bin, not a command anyone types.
     expect(emitted.nouns.__complete).toBeUndefined();
   });
 
@@ -105,15 +125,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
         needsStore: true,
         mcp: "ontology_lookup",
       },
-      // `show` is the deprecated alias of `lookup` (AV-228 B1) — same shape,
-      // both blessed in the covenant.
-      {
-        v: "show",
-        args: ["<prefix>"],
-        flags: ["--properties", "--full-uris", "--class"],
-        needsStore: true,
-        mcp: "ontology_show",
-      },
+      // One job, one spelling: `lookup` is the by-name read, and nothing
+      // else answers to it.
     ]);
     // skill discovery is storeless (filesystem) — no needsStore.
     expect(emitted.nouns.skill?.verbs).toEqual([
@@ -137,6 +150,92 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     ]);
   });
 
+  it("emits the L-CIS create noun — projected grammar, deep-equal to the covenant", () => {
+    // The create surface DERIVES from the generators' prompts (L-CIS): the
+    // framework tree segment is a required positional enum, component's flags
+    // are the framework union (incl. the svelte-only --use-ts-stories), and
+    // every flag AND positional token is the REGISTERED spelling (L-CIS-2) —
+    // a default-true confirm registers ONLY its `--no-<kebab>` form, and the
+    // args carry the kebab positional the usage line prints, so the covenant
+    // names `--no-with-styles` and `[component-path]`, never a
+    // `--with-styles` the CLI rejects or a `[componentPath]` its help never
+    // prints. Pin the three entries verbatim so a prompt edit that moves the
+    // covenant is SEEN.
+    expect(emitted.nouns.create?.verbs).toEqual([
+      {
+        v: "component",
+        args: ["<framework>", "[component-path]"],
+        flags: [
+          "--no-with-styles",
+          "--no-with-stories",
+          "--no-with-ssr-tests",
+          "--use-ts-stories",
+        ],
+        mutates: true,
+        mcp: "create_component",
+      },
+      {
+        v: "package",
+        flags: [
+          "--name",
+          "--type",
+          "--description",
+          "--with-react",
+          "--with-storybook",
+          "--with-cli",
+          "--with-pr-template",
+          "--no-run-install",
+        ],
+        mutates: true,
+        mcp: "create_package",
+      },
+      {
+        v: "application",
+        args: ["[app-path]"],
+        // ssr/router are GONE: always-on facts, not prompts — the pair had no
+        // reachable explicit form (only `--no-` spellings the generator's own
+        // guard rejected), so the projection no longer carries them.
+        flags: ["--no-forms", "--intl", "--relay", "--no-run-install"],
+        mutates: true,
+        mcp: "create_application",
+      },
+    ]);
+  });
+
+  it("every create covenant flag token is buildOptionInfo's primary registered long form (L-CIS-2)", () => {
+    // The derivation tie: the covenant's create tokens must be EXACTLY the
+    // long forms the single flag-shape authority yields for the projected
+    // prompts — the same expression both binaries register from — so the
+    // covenant can never again teach a spelling the CLI rejects (the
+    // round-15 F2 defect: kebab-cased param names blessed `--with-styles`
+    // and rejected the real `--no-with-styles`).
+    const registered = new Map<string, string>();
+    for (const surface of Object.values(CREATE_SURFACE)) {
+      for (const prompt of surface.prompts) {
+        if (prompt.positional === true) continue;
+        registered.set(
+          prompt.name,
+          buildOptionInfo(prompt).flags.split(" ")[0] as string,
+        );
+      }
+    }
+    for (const verb of emitted.nouns.create?.verbs ?? []) {
+      expect(verb.flags?.length ?? 0).toBeGreaterThan(0);
+      for (const token of verb.flags ?? []) {
+        expect([...registered.values()]).toContain(token);
+      }
+    }
+    // …and every non-positional projected prompt is named by some entry.
+    const covenantTokens = new Set(
+      (emitted.nouns.create?.verbs ?? []).flatMap((verb) => verb.flags ?? []),
+    );
+    for (const [name, token] of registered) {
+      expect(covenantTokens.has(token), `${name} → ${token} missing`).toBe(
+        true,
+      );
+    }
+  });
+
   it("emits the PR6 effect/diagnostic self-verbs (doctor, upgrade)", () => {
     // doctor is a storeless read self-verb — no args, no flags, no needsStore.
     expect(emitted.nouns.doctor?.verbs).toEqual([
@@ -167,20 +266,36 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
         mutates: true,
         mcp: "setup",
       },
+      {
+        v: "config",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      {
+        v: "completions",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      {
+        v: "lsp",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
       {
         v: "mcp",
         flags: ["--scope", "--global", "--local"],
         mutates: true,
         mcp: false,
       },
-      { v: "completions", mutates: true, mcp: false },
       {
         v: "skills",
         flags: ["--scope", "--global", "--local"],
         mutates: true,
         mcp: false,
       },
-      { v: "lsp", mutates: true, mcp: false },
     ]);
   });
 
@@ -200,6 +315,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       "standard_sample",
       "tier_list",
       "config_show",
+      "config_get",
+      "config_unset",
       "colophon",
     ]) {
       expect(tools).toContain(tool);
@@ -213,14 +330,14 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
   // The CLOSING direction: assertConforms already proves emitted ⊆ covenant;
   // this proves covenant ⊆ emitted, so together the tool sets are EQUAL — the
   // surface-complete milestone. After PR7, every covenant tool is realized.
-  it("emits every covenant tool (all 37) — set equality with the covenant", () => {
+  it("emits every covenant tool (all 42) — set equality with the covenant", () => {
     const emittedTools = new Set(emitted.mcpSurface.tools);
     const missing = golden.mcpSurface.tools.filter((t) => !emittedTools.has(t));
     expect(missing).toEqual([]);
     expect([...emitted.mcpSurface.tools].sort()).toEqual(
       [...golden.mcpSurface.tools].sort(),
     );
-    expect(emitted.mcpSurface.tools).toHaveLength(37);
+    expect(emitted.mcpSurface.tools).toHaveLength(42);
   });
 
   // The covenant edit: the non-tool MCP surface is frozen too.

package/src/capabilities/upgrade/runUpgrade.ts

@@ -21,13 +21,15 @@
  */
 
 import { $, exec, gen, info, type Task, warn } from "@canonical/task";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import { assertExecOk, guardMissingBinary } from "../shared/assertExecOk.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import {
+  assertExecOk,
+  checkRegistryVersion,
   detectInstallSource,
+  guardMissingBinary,
+  PRAGMA_PACKAGE,
   pmUpdateCommand,
-} from "../shared/packageManager.js";
-import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+} from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
 /**
@@ -61,9 +63,7 @@ export async function runUpgrade(
       executed: false,
     };
     return gen(function* () {
-      yield* $(
-        warn("Could not reach the registry — skipped the update check."),
-      );
+      yield* $(warn("Cannot reach the registry — skipped the update check."));
       return data;
     });
   }
@@ -97,7 +97,7 @@ export async function runUpgrade(
   const bin = parts[0] ?? "npm";
   const args = parts.slice(1);
   // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
-  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("please report
+  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("report
   // this issue"). Surface it as a named "`<pm>` not found on PATH" instead.
   return guardMissingBinary(
     bin,