@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/capabilities/wireContract.test.ts

@@ -0,0 +1,110 @@
+/**
+ * The wire contract of list-valued parameters, derived from the registry.
+ *
+ * Two recorded failures are the reason this file exists. A weak model asked
+ * for twenty tokens' variables with twenty `variable_list` calls, because over
+ * MCP a filter took ONE value while the CLI took the flag repeated; a stronger
+ * one passed `name: "color.text"` to `token_lookup` and was refused by schema
+ * validation over a pair of brackets. So: every parameter that takes several
+ * values ADVERTISES an array, and accepts one bare value as a list of one.
+ *
+ * Derived rather than listed — a story declared tomorrow is held to the rule
+ * by the act of declaring it.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { buildToolShape } from "../kernel/project/mcp/registerVerb.js";
+import { toolName } from "../kernel/spec/index.js";
+import type { ParamSpec, VerbSpec } from "../kernel/spec/types.js";
+import { type McpHarness, projectMcp } from "../testing/helpers/projectMcp.js";
+import { capabilities } from "./index.js";
+
+const exposed: readonly VerbSpec[] = capabilities
+  .flatMap((module) => module.verbs)
+  .filter((verb) => !verb.hidden && verb.capability.mcp.expose !== false);
+
+/** Every `[tool, param]` pair whose param satisfies `test`. */
+function paramsWhere(
+  test: (param: ParamSpec) => boolean,
+): (readonly [string, string, VerbSpec, ParamSpec])[] {
+  return exposed.flatMap((verb) =>
+    verb.params
+      .filter(test)
+      .map((param) => [toolName(verb.path), param.name, verb, param] as const),
+  );
+}
+
+/** One admissible value for a param: its first enum value, else any word. */
+const sample = (param: ParamSpec): string =>
+  param.kind === "enum" ? (param.values.at(0) ?? "") : "anything";
+
+/** Parse ONE field of a tool's input shape, leaving its other params aside. */
+function parseField(verb: VerbSpec, param: ParamSpec, value: unknown) {
+  const field = buildToolShape(verb)[param.name];
+  if (!field) throw new Error(`no "${param.name}" in the tool shape`);
+  return z.object({ [param.name]: field }).safeParse({ [param.name]: value });
+}
+
+const variadic = paramsWhere((param) => param.kind === "string[]");
+const repeatable = paramsWhere(
+  (param) => param.kind !== "string[]" && param.repeatable === true,
+);
+
+describe("a parameter that takes several values takes one, too", () => {
+  it("the registry has both kinds (the derivation is not vacuous)", () => {
+    expect(variadic.length).toBeGreaterThan(0);
+    expect(repeatable.length).toBeGreaterThan(0);
+  });
+
+  it.each(variadic)(
+    "%s { %s }: a bare string is a list of one",
+    (_tool, name, verb, param) => {
+      expect(parseField(verb, param, "color.text")).toEqual({
+        success: true,
+        data: { [name]: ["color.text"] },
+      });
+      expect(parseField(verb, param, ["a", "b"]).success).toBe(true);
+    },
+  );
+
+  it.each(repeatable)(
+    "%s { %s }: an array and a bare string are both accepted",
+    (_tool, name, verb, param) => {
+      const value = sample(param);
+      expect(parseField(verb, param, [value, value]).success).toBe(true);
+      expect(parseField(verb, param, value)).toEqual({
+        success: true,
+        data: { [name]: [value] },
+      });
+    },
+  );
+});
+
+describe("what is advertised is a plain array", () => {
+  let harness: McpHarness;
+  let schemas: Map<string, Record<string, Record<string, unknown>>>;
+  beforeAll(async () => {
+    harness = await projectMcp(capabilities);
+    schemas = new Map(
+      (await harness.listTools()).map((tool) => [
+        tool.name,
+        ((tool.inputSchema as { properties?: unknown }).properties ??
+          {}) as Record<string, Record<string, unknown>>,
+      ]),
+    );
+  });
+  afterAll(() => harness.cleanup());
+
+  // `anyOf` is what a `string | string[]` union would emit, and it is the
+  // shape the weaker models read badly — so the coercion must not leak into
+  // the advertised schema.
+  it.each([...variadic, ...repeatable])(
+    "%s { %s } is `type: array`, never `anyOf`",
+    (tool, name) => {
+      const advertised = schemas.get(tool)?.[name];
+      expect(advertised?.type).toBe("array");
+      expect(advertised).not.toHaveProperty("anyOf");
+    },
+  );
+});

package/src/constants.ts

@@ -61,9 +61,10 @@ const PROJECT_CONFIG_FILENAME = `${identity.name}.config.ts`;
 /**
  * The distribution's name plus a space: the prefix a `recovery.cli` hint carries
  * so it quotes a command the installed binary answers to (D5). Kernel hints are
- * authored through `cliRecovery`, which prepends it; `packs/schema.ts` REJECTS
- * it in a user-authored pack's `emptyRecovery.cli`, because the CONSUMING
- * distribution's renderer supplies its own. Use {@link BIN_NAME} for prose —
+ * authored through `callRecovery`, whose call renderer prepends it; a pack's
+ * `emptyRecovery.call` names a verb path and never a binary (`packs/schema.ts`
+ * rejects a command line there), because the CONSUMING distribution's renderer
+ * supplies its own. Use {@link BIN_NAME} for prose —
  * this constant's trailing space belongs to the recovery invariant, not to
  * sentences.
  */

package/src/kernel/completion/shellDrive.test.ts

@@ -339,7 +339,7 @@ const STRUCTURE = [
     at: "pragma create <TAB>",
     words: ["pragma", "create", ""],
     cword: 2,
-    offers: ["application", "component", "package"],
+    offers: ["application", "component", "package", "page"],
   },
   {
     at: "pragma --format <TAB>",
@@ -546,7 +546,7 @@ describe.skipIf(!hasShell("fish"))(
       },
       {
         line: "pragma create ",
-        offers: ["application", "component", "package"],
+        offers: ["application", "component", "package", "page"],
       },
       // fish's own inline convention: it returns the whole `--flag=value` word,
       // not the bare value bash offers. Assert what fish returns.

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(
       [