@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/kernel/copy.test.ts

@@ -438,7 +438,7 @@ describe("capability commands (PROTECTED)", () => {
   it("no command quoted in capability prose is a bare literal", () => {
     // The other half of the same promise, and the half the position rule cannot
     // reach: an empty-state hint, a recovery MESSAGE (the second argument to
-    // `cliRecovery`, beside a first argument the position rule already covers),
+    // `callRecovery`, beside a first argument the position rule already covers),
     // a `sources status` headline, a wizard step's title. They reach the same
     // user with the same instruction, and seven of them named this distribution
     // while the rule above reported zero exemptions.

package/src/kernel/error/PragmaError.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import { ISSUES_URL } from "../../constants.js";
 import { errorEnvelope, successEnvelope } from "../render/envelope.js";
 import { PragmaError } from "./PragmaError.js";
-import { cliRecovery } from "./recovery.js";
+import { callRecovery } from "./recovery.js";
 import { serializeError } from "./serialize.js";
 
 describe("PragmaError factories", () => {
@@ -76,13 +76,17 @@ describe("serializeError", () => {
   it("includes suggestions, recovery, validOptions, and filters when present", () => {
     const error = PragmaError.notFound("block", "Buton", {
       suggestions: ["Button"],
-      recovery: cliRecovery("block list", "List blocks."),
+      recovery: callRecovery({ verb: "block list" }, "List blocks."),
     });
     expect(serializeError(error)).toEqual({
       code: "ENTITY_NOT_FOUND",
       message: 'block "Buton" not found.',
       suggestions: ["Button"],
-      recovery: { cli: "pragma block list", message: "List blocks." },
+      recovery: {
+        cli: "pragma block list",
+        message: "List blocks.",
+        mcp: { tool: "block_list", params: {} },
+      },
     });
   });
 });

package/src/kernel/error/index.ts

@@ -8,7 +8,7 @@
 
 export { ERROR_CODES } from "./constants.js";
 export { PragmaError } from "./PragmaError.js";
-export { cliRecovery } from "./recovery.js";
+export { callRecovery } from "./recovery.js";
 export {
   renderErrorJson,
   renderErrorLlm,

package/src/kernel/error/recovery.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { RECOVERY_CLI_PREFIX } from "../../constants.js";
-import { cliRecovery } from "./recovery.js";
+import { callRecovery } from "./recovery.js";
 
 describe("recovery.cli invariant (D5)", () => {
   it("carries the shipped distribution's recovery prefix", () => {
@@ -11,27 +11,61 @@ describe("recovery.cli invariant (D5)", () => {
     expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
   });
 
-  it("prepends the distribution's prefix to the command it is given", () => {
-    // The caller passes the SUFFIX, so a hint naming the wrong binary is
-    // unwritable rather than merely asserted against. What replaced the deleted
-    // `assertRecoveryCli` is `kernel/copy.test.ts`'s position rule, which sees
-    // the raw `cli:` literals that never reached this function at all — the only
-    // place a wrong prefix was ever actually written.
-    expect(cliRecovery("config show", "See the resolved config.")).toEqual({
-      cli: "pragma config show",
-      message: "See the resolved config.",
+  it("derives both spellings from the one call it is given", () => {
+    // The caller names a CALL, so a hint naming the wrong binary — or a CLI
+    // string and an MCP hint that disagree about an argument — is unwritable
+    // rather than merely asserted against. `kernel/copy.test.ts`'s position
+    // rule still sees the raw `cli:` literals that never reach this function.
+    expect(
+      callRecovery(
+        { verb: "config unset", params: { key: "tier" } },
+        "Clear the field.",
+      ),
+    ).toEqual({
+      cli: "pragma config unset tier",
+      message: "Clear the field.",
+      // A mutating tool is plan-first: the recovery never carries `confirm`.
+      mcp: { tool: "config_unset", params: { key: "tier" } },
     });
   });
 
-  it("carries an MCP tool alongside the command when one is given", () => {
+  it("spells a flag, quotes what a shell would split, and repeats a variadic positional", () => {
     expect(
-      cliRecovery("sources update", "Build the store.", {
-        tool: "sources_update",
-      }),
-    ).toEqual({
-      cli: "pragma sources update",
-      message: "Build the store.",
-      mcp: { tool: "sources_update" },
+      callRecovery(
+        { verb: "token consumers", params: { symbol: "color.text" } },
+        "m",
+      ).cli,
+    ).toBe("pragma token consumers --symbol color.text");
+    expect(
+      callRecovery(
+        { verb: "graph query", params: { sparql: "ASK { ?s ?p 'x' }" } },
+        "m",
+      ).cli,
+    ).toBe("pragma graph query 'ASK { ?s ?p '\\''x'\\'' }'");
+    expect(
+      callRecovery(
+        { verb: "block lookup", params: { name: ["Button", "Card"] } },
+        "m",
+      ).cli,
+    ).toBe("pragma block lookup Button Card");
+    expect(
+      callRecovery(
+        { verb: "sources update", params: { skipInvalid: true } },
+        "m",
+      ).cli,
+    ).toBe("pragma sources update --skip-invalid");
+    expect(
+      callRecovery(
+        { verb: "sources update", params: { skipInvalid: false } },
+        "m",
+      ).cli,
+    ).toBe("pragma sources update");
+  });
+
+  it("names no MCP tool for a verb withheld from MCP", () => {
+    expect(callRecovery({ verb: "version" }, "See the version.")).toEqual({
+      cli: "pragma version",
+      message: "See the version.",
     });
   });
 });

package/src/kernel/error/recovery.ts

@@ -1,58 +1,37 @@
 /**
- * The recovery-string invariant (D5).
+ * The recovery invariant (D5): a `recovery.cli` hint quotes a command the
+ * installed binary answers to, so it begins with {@link RECOVERY_CLI_PREFIX}.
  *
- * A `recovery.cli` hint quotes a command the installed binary answers to, so it
- * must begin with {@link RECOVERY_CLI_PREFIX} — the distribution's own `name`
- * plus a space. {@link cliRecovery} takes the command SUFFIX and prepends the
- * prefix itself, so a hint that names the wrong binary is unwritable rather
- * than merely detected. That is why there is no assertion here: an assertion
- * over a string the caller composed from the prefix cannot fail, and the hints
- * that were actually wrong were raw `cli:` object literals that never reached
- * this function at all. `kernel/copy.test.ts` covers those, at the position.
- *
- * A THIRD authoring route is also legal and reached by NEITHER guard: a `cli`
- * DERIVED from the program's own name at the call site. One site does this —
- * the create mount (`capabilities/create/mount.ts`,
- * `[...detail.chain, suggestion].join(" ")`), whose `chain[0]` is the root
- * Commander program's name, `BIN_NAME` by wiring. It bypasses
- * {@link cliRecovery}, and the position rule is structurally blind to it (it
- * flags QUOTED literals containing the distribution's name, never a computed
- * expression) — so D5 holds there by derivation, and the derivation is pinned
- * where the value surfaces: `createGrammar.test.ts` COMPOSES its expected
- * `cli` from {@link RECOVERY_CLI_PREFIX}, so a renamed root program reddens
- * the cell naming the constant. (A separate `startsWith` assertion cannot
- * pin it — behind an exact pin of the same value it has no reachable
- * failing input.)
- *
- * `kernel/packs/schema.ts` holds a user-authored pack's `emptyRecovery.cli` to
- * the same shape from the other side — it must NOT carry a prefix, because the
- * consuming distribution's renderer supplies one.
+ * {@link callRecovery} takes a CALL and the one call renderer spells it, prefix
+ * included, so a hint naming the wrong binary — or a `cli` and an `mcp` that
+ * disagree — is unwritable. Two routes do not pass through here:
+ * raw `cli:` object literals (`kernel/copy.test.ts` polices those at the
+ * position), and the create mount, which DERIVES its `cli` from the root
+ * program's name (`capabilities/create/mount.ts`; pinned by
+ * `createGrammar.test.ts`, whose expectation is composed from the prefix).
+ * A pack's `emptyRecovery.call` is held to the same shape from the other side
+ * by `kernel/packs/schema.ts`: a verb path, never a binary name.
  */
 
-import { RECOVERY_CLI_PREFIX } from "../../constants.js";
+import { callTool, renderCall } from "../spec/call.js";
+import type { Call } from "../spec/types.js";
 import type { Recovery } from "./types.js";
 
 /**
- * Build a {@link Recovery} whose `cli` command carries the distribution's own
- * prefix, optionally pairing it with an MCP tool an agent can call.
+ * Build a {@link Recovery} from the call that recovers.
  *
- * A recovery may need to speak to BOTH surfaces: the `cli` string guides a human,
- * while `mcp` names the tool an agent invokes (an agent cannot run a shell
- * command). The single human `message` is shared by both.
+ * A recovery speaks to BOTH surfaces: `cli` guides a person, while `mcp` names
+ * the tool an agent invokes (an agent cannot run a shell command). Both derive
+ * from the one call, so they cannot disagree about the verb or its arguments;
+ * `mcp` is absent only when the verb is withheld from MCP. Neither spelling
+ * ever carries `confirm`: a mutating tool is plan-first, and the plan it
+ * returns says how to proceed.
  *
- * @param command - The recovery command WITHOUT the binary name (`sources update`).
+ * @param call - The verb to run and the params to run it with.
  * @param message - Human-readable guidance shown alongside the command.
- * @param mcp - The MCP tool (and optional params) an agent calls to recover.
- * @returns A recovery hint whose `cli` names this distribution's binary.
+ * @returns A recovery hint carrying the call in both spellings.
  */
-export function cliRecovery(
-  command: string,
-  message: string,
-  mcp?: Recovery["mcp"],
-): Recovery {
-  return {
-    message,
-    cli: `${RECOVERY_CLI_PREFIX}${command}`,
-    ...(mcp ? { mcp } : {}),
-  };
+export function callRecovery(call: Call, message: string): Recovery {
+  const mcp = callTool(call);
+  return { message, cli: renderCall(call, "cli"), ...(mcp ? { mcp } : {}) };
 }

package/src/kernel/error/types.ts

@@ -16,7 +16,7 @@ type ErrorCode = (typeof ERROR_CODES)[number];
  *
  * `cli` — when present — is the command as a user would type it: this
  * distribution's own bin name (`RECOVERY_CLI_PREFIX`) plus a grammar path (D5).
- * `cliRecovery` takes the path alone and prepends the prefix, so there is no
+ * `callRecovery` takes the path alone and prepends the prefix, so there is no
  * assertion to make; the one COMPUTED producer (the create mount) derives
  * the prefix from the program's own name, pinned by a test expectation
  * COMPOSED from `RECOVERY_CLI_PREFIX` — the routes are enumerated in the

package/src/kernel/packs/collect.test.ts

@@ -19,6 +19,7 @@ import type { CapabilityModule, VerbSpec } from "../spec/types.js";
 import {
   assembleEffectiveModules,
   loadEffectiveModules,
+  migrateLegacyRecoveries,
   validateStories,
 } from "./collect.js";
 import { assertUniqueVerbs } from "./uniqueness.js";
@@ -210,6 +211,84 @@ describe("validateStories — package stories NEVER throw (PROTECTED)", () => {
     ]);
   });
 
+  it("carries a package story's retired emptyRecovery.cli forward instead of losing the noun", () => {
+    // A pack built before the grammar changed still has `cli` on disk. The
+    // project config gets a hard error for it (its author can rename the key);
+    // a package is third-party data, so the hint is migrated when it IS a verb
+    // path and otherwise only the hint is dropped — never the noun.
+    const withCli = (noun: string, cli: string) => ({
+      noun,
+      list: {
+        ...validPack(noun).list,
+        emptyRecovery: { message: "None yet.", cli },
+      },
+      verbs: [
+        {
+          ...validPack(noun).list,
+          verb: "extras",
+          emptyRecovery: { message: "None yet.", cli },
+        },
+      ],
+    });
+    const result = validateStories(
+      [
+        record(
+          "pkg/stories/recipe.json",
+          JSON.stringify(withCli("recipe", "sources update")),
+        ),
+        record(
+          "pkg/stories/menu.json",
+          JSON.stringify(withCli("menu", "acme sources update --all")),
+        ),
+      ],
+      STATIC,
+    );
+    const [recipe, menu] = result.entries.map((entry) => entry.definition);
+    expect(recipe?.list?.emptyRecovery).toEqual({
+      message: "None yet.",
+      call: { verb: "sources update" },
+    });
+    expect(recipe?.verbs?.at(0)?.emptyRecovery?.call).toEqual({
+      verb: "sources update",
+    });
+    // Not a verb path: the story survives, the hint does not, and doctor hears.
+    expect(menu?.noun).toBe("menu");
+    expect(menu?.list?.emptyRecovery).toEqual({ message: "None yet." });
+    expect(result.problems.map((problem) => problem.source)).toEqual([
+      "pkg/stories/menu.json",
+      "pkg/stories/menu.json",
+    ]);
+    expect(result.problems.at(0)?.message).toMatch(
+      /story is kept.*emptyRecovery\.cli.*emptyRecovery\.call/,
+    );
+  });
+
+  it("leaves a story with nothing to migrate, and a non-object, untouched", () => {
+    const story = validPack("recipe");
+    expect(migrateLegacyRecoveries(story)).toEqual({ raw: story, dropped: [] });
+    expect(migrateLegacyRecoveries("nope")).toEqual({
+      raw: "nope",
+      dropped: [],
+    });
+    // A half that already names a call keeps it; the stale `cli` beside it goes.
+    const both = {
+      message: "m",
+      cli: "doctor",
+      call: { verb: "sources update" },
+    };
+    expect(
+      migrateLegacyRecoveries({ noun: "x", verbs: [{ emptyRecovery: both }] }),
+    ).toEqual({
+      raw: {
+        noun: "x",
+        verbs: [
+          { emptyRecovery: { message: "m", call: { verb: "sources update" } } },
+        ],
+      },
+      dropped: [],
+    });
+  });
+
   it("last declaration wins for a noun, and the shadowed file is reported", () => {
     const result = validateStories(
       [

package/src/kernel/packs/collect.ts

@@ -28,9 +28,11 @@ import type { ConfigLayers } from "../config/index.js";
 import { PragmaError } from "../error/index.js";
 import type { PackStoryRecord } from "../runtime/graphpack/stories.js";
 import type { CapabilityModule } from "../spec/index.js";
-import { compileStoryModule } from "./compile.js";
+import { compileStoryModule, storyOf } from "./compile.js";
 import { parsePackDefinition } from "./schema.js";
-import type { PackDefinition, PackEntry } from "./types.js";
+import { nounsNamed } from "./storyRules.js";
+import type { NounLookups, PackDefinition, PackEntry } from "./types.js";
+import { VERB_PATH_PATTERN } from "./types.js";
 import { assertUniqueVerbs } from "./uniqueness.js";
 
 /** One package-declared story that could not be used, and why. */
@@ -83,10 +85,14 @@ export function validateStories(
   const problems: StoryProblem[] = [];
   for (const record of records) {
     try {
-      const definition = parsePackDefinition(
-        JSON.parse(record.content),
-        record.source,
-      );
+      const migrated = migrateLegacyRecoveries(JSON.parse(record.content));
+      for (const hint of migrated.dropped) {
+        problems.push({
+          source: record.source,
+          message: `its story is kept, but its emptyRecovery.cli hint "${hint}" is not a verb path and was dropped; the key is now emptyRecovery.call.`,
+        });
+      }
+      const definition = parsePackDefinition(migrated.raw, record.source);
       if (reserved.has(definition.noun)) {
         problems.push({
           source: record.source,
@@ -112,6 +118,55 @@ export function validateStories(
   return { entries: [...byNoun.values()], problems };
 }
 
+/**
+ * Carry a PACKAGE story written against the old grammar forward.
+ *
+ * `emptyRecovery.cli: "sources update"` became `emptyRecovery.call: { verb }`. A
+ * project's own config gets the hard error that names the change — its author
+ * can fix it. A package is third-party data, often already built into a pack on
+ * disk, and refusing the key would cost the user the whole noun for the sake of
+ * a hint. So the old string becomes a call when it IS a verb path, and
+ * otherwise only the hint is dropped, reported once under `doctor`.
+ *
+ * @param raw - The parsed story JSON (untrusted; returned unchanged when it
+ *   carries no legacy key).
+ * @returns The story to validate, and the legacy hints that could not be kept.
+ */
+export function migrateLegacyRecoveries(raw: unknown): {
+  raw: unknown;
+  dropped: string[];
+} {
+  const dropped: string[] = [];
+  const migrateHalf = (half: unknown): unknown => {
+    const recovery = (
+      half as { emptyRecovery?: Record<string, unknown> } | null
+    )?.emptyRecovery;
+    if (typeof recovery?.cli !== "string") return half;
+    const { cli, ...rest } = recovery;
+    const keep = VERB_PATH_PATTERN.test(cli);
+    if (!keep) dropped.push(cli);
+    return {
+      ...(half as object),
+      emptyRecovery:
+        keep && rest.call === undefined
+          ? { ...rest, call: { verb: cli } }
+          : rest,
+    };
+  };
+  if (typeof raw !== "object" || raw === null) return { raw, dropped };
+  const story = raw as { list?: unknown; verbs?: unknown };
+  return {
+    raw: {
+      ...story,
+      ...(story.list === undefined ? {} : { list: migrateHalf(story.list) }),
+      ...(Array.isArray(story.verbs)
+        ? { verbs: story.verbs.map(migrateHalf) }
+        : {}),
+    },
+    dropped,
+  };
+}
+
 /**
  * The PROJECT's config-declared stories, weakest tier first.
  *
@@ -147,8 +202,8 @@ function projectStoryTiers(layers: ConfigLayers): readonly unknown[][] {
  *   carries (see {@link validateStories}); weaker than either config tier.
  * @returns The effective modules, uniqueness-checked.
  * @throws PragmaError CONFIG_ERROR on an invalid CONFIG story, a config story
- *   claiming an authored non-story noun, or a duplicate noun within one config
- *   tier. Package stories were already screened and never throw here.
+ *   claiming an authored non-story noun, a duplicate noun within one config
+ *   tier, or a config or shipped story naming a noun no story declares. Package stories were already screened and never throw here.
  */
 export function assembleEffectiveModules(
   staticModules: readonly CapabilityModule[],
@@ -171,6 +226,19 @@ export function assembleEffectiveModules(
   // Keyed by noun so the stronger tier REPLACES the weaker one — declaring a
   // story both on its pack and at the top level is a refinement, not an error.
   const dynamic = new Map<string, CapabilityModule>();
+  // The EFFECTIVE lookup of a noun, for shipped and project stories alike.
+  // Read at run time, so it sees every tier whatever order they compile in.
+  const nouns: NounLookups = (noun) => {
+    const module =
+      dynamic.get(noun) ?? staticModules.find((m) => m.name === noun);
+    const story = module && storyOf(module);
+    if (story && !story.definition.lookup) {
+      throw PragmaError.configError(
+        `The "${noun}" story in ${story.source.label} declares no lookup, so a filter that takes a ${noun} cannot resolve its value. Add a lookup to that story.`,
+      );
+    }
+    return story?.definition.lookup;
+  };
   for (const entry of packageStories) {
     dynamic.set(
       entry.definition.noun,
@@ -178,6 +246,7 @@ export function assembleEffectiveModules(
         entry.definition,
         { label: entry.source, origin: "package" },
         prefixes,
+        nouns,
       ),
     );
   }
@@ -205,6 +274,7 @@ export function assembleEffectiveModules(
           definition,
           { label: "config", origin: "config" },
           prefixes,
+          nouns,
         ),
       );
     }
@@ -212,12 +282,79 @@ export function assembleEffectiveModules(
 
   // Drop the static module for any noun a config story overrides, then append
   // the dynamic modules.
-  const kept = staticModules.filter((module) => !dynamic.has(module.name));
+  const kept = staticModules
+    .filter((module) => !dynamic.has(module.name))
+    // Recompiled so a shipped filter naming an overridden noun resolves
+    // through the project's lookup, as the project's own stories do.
+    .map((module) => {
+      const story = storyOf(module);
+      return story
+        ? compileStoryModule(
+            story.definition,
+            story.source,
+            story.prefixes,
+            nouns,
+          )
+        : module;
+    });
   const effective = [...kept, ...dynamic.values()];
+  // A noun some story declares without a lookup is refused when a filter on it
+  // is used, not here: only a noun NO story declares is a declaration error.
+  // Package stories never throw; {@link screenPackageStories} drops them.
+  for (const module of effective) {
+    const story = storyOf(module);
+    const unknown =
+      story && story.source.origin !== "package"
+        ? undeclaredNoun(story.definition, effective)
+        : undefined;
+    if (story && unknown) {
+      throw PragmaError.configError(
+        `Invalid story in ${story.source.label}: "${module.name}" names the noun "${unknown}", and no story declares it.`,
+      );
+    }
+  }
   assertUniqueVerbs(effective.flatMap((module) => [...module.verbs]));
   return effective;
 }
 
+/** The first noun a story names that no effective story declares. */
+function undeclaredNoun(
+  definition: PackDefinition,
+  effective: readonly CapabilityModule[],
+): string | undefined {
+  return nounsNamed(definition).find(
+    (noun) => !effective.some((m) => m.name === noun && storyOf(m)),
+  );
+}
+
+/**
+ * Drop each PACKAGE story naming a noun no effective story declares, reporting
+ * it — judged over the assembled set, so the order of declaration is nothing.
+ *
+ * @param effective - The assembled modules.
+ * @returns The modules kept, and one problem per story dropped.
+ */
+export function screenPackageStories(effective: readonly CapabilityModule[]): {
+  readonly modules: readonly CapabilityModule[];
+  readonly problems: readonly StoryProblem[];
+} {
+  const problems: StoryProblem[] = [];
+  const modules = effective.filter((module) => {
+    const story = storyOf(module);
+    const unknown =
+      story?.source.origin === "package"
+        ? undeclaredNoun(story.definition, effective)
+        : undefined;
+    if (!story || unknown === undefined) return true;
+    problems.push({
+      source: story.source.label,
+      message: `it names the noun "${unknown}", and no story declares it.`,
+    });
+    return false;
+  });
+  return { modules: problems.length === 0 ? effective : modules, problems };
+}
+
 /**
  * Load the effective modules for a real invocation: read the layered config and
  * the answering pack's carried stories, and merge both into the static
@@ -252,8 +389,11 @@ export async function loadEffectiveModules(
     activeStories(resolveSources(layers, cwd)),
     staticModules,
   );
+  const screened = screenPackageStories(
+    assembleEffectiveModules(staticModules, layers, entries),
+  );
   return {
-    modules: assembleEffectiveModules(staticModules, layers, entries),
-    problems,
+    modules: screened.modules,
+    problems: [...problems, ...screened.problems],
   };
 }