@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/kernel/project/cli/dispatch.ts

@@ -34,6 +34,7 @@ import type {
   GlobalFlags,
   InteractionRuntime,
   PragmaRuntime,
+  StoreSession,
 } from "../../runtime/types.js";
 import { kebabCase, type ParamSpec, type VerbSpec } from "../../spec/index.js";
 import { EXIT, mapExitCode } from "./exitCodes.js";
@@ -175,9 +176,10 @@ function renderData(
     // is distinguishable from an unbuilt store or a mistyped filter, and an
     // ambiguous lookup hit from an unambiguous one. `data` keeps its uniform
     // shape, and MCP builds the same key from the same seam
-    // (`mcp/registerVerb.ts#noticeMeta`) — the two machine surfaces stay
-    // byte-equal.
-    const notice = verb.output.formatters.notice?.(data);
+    // (`mcp/registerVerb.ts#noticeMeta`). The two envelopes are equal EXCEPT
+    // for spelling inside this sentence: a next step reads as a command here
+    // and as a tool call there, because each is printed where it will be used.
+    const notice = verb.output.formatters.notice?.(data, "cli");
     // The machine half of the same seam: facts the read wants to hand an agent
     // as data rather than prose (`meta.scope`). MCP merges the same seam into
     // the same keys (`mcp/registerVerb.ts#readMeta`).
@@ -204,7 +206,9 @@ function renderData(
   const text = verb.output.formatters.plain(data, context);
   // The calm notice is success-path guidance — `--quiet` mutes it.
   const notice =
-    flags.quiet === true ? undefined : verb.output.formatters.notice?.(data);
+    flags.quiet === true
+      ? undefined
+      : verb.output.formatters.notice?.(data, "cli");
   return {
     stdout: text ? `${text}\n` : "",
     ...(notice ? { stderr: `${notice}\n` } : {}),
@@ -320,9 +324,9 @@ export async function executeVerb(
   // The lazy-store seam: boot the store (once, memoized) only for verbs that
   // declare they need it. A storeless verb never reaches the store factory, so
   // the storeless guarantee holds by construction (no STORE_SKIP triage).
-  if (verb.capability.needsStore) {
-    await runtime.store.get();
-  }
+  const session = verb.capability.needsStore
+    ? await runtime.store.get()
+    : undefined;
 
   if (verb.capability.mutates) {
     // Tell the verb whether this is a plan-only preview (`--dry-run`) or a real
@@ -468,7 +472,29 @@ export async function executeVerb(
   const data = await Promise.resolve(
     verb.run(params, runtime) as Promise<unknown>,
   );
-  return renderData(verb, flags, data, {});
+  return renderData(verb, flags, data, storeMeta(session));
+}
+
+/**
+ * The envelope facts about the STORE this read was answered from, as data.
+ *
+ * One fact so far: the project's own built pack, when the boot passed over it
+ * because an older CLI built it. An agent that reads `block lookup button` and
+ * gets the snapshot's answer has no way to learn from the payload that this
+ * directory also holds a pack — so the fact rides `meta`, from the session the
+ * answer came from, on every read verb at once.
+ *
+ * `meta` ONLY, deliberately: the read's answer is not wrong (the snapshot is the
+ * current graph, which is the whole point of passing the pack over), so the
+ * plain and llm renderings of every read stay byte for byte what they were, and
+ * the sentence a person reads stays where a person goes for it — `sources
+ * status` and `doctor`.
+ *
+ * @param session - The booted session, or `undefined` for a storeless verb.
+ * @returns The base `meta` for the envelope (empty for an ordinary read).
+ */
+function storeMeta(session: StoreSession | undefined): Record<string, unknown> {
+  return session?.ignoredPack ? { ignoredPack: session.ignoredPack } : {};
 }
 
 /**

package/src/kernel/project/cli/suggest.test.ts

@@ -118,4 +118,81 @@ describe("suggestNames", () => {
       "Timeline ",
     ]);
   });
+
+  describe("a candidate that is a whole-segment part of the query", () => {
+    it("is offered for a name with a segment too many", () => {
+      // Recorded: `token lookup color.text.primary` suggested NOTHING although
+      // `color.text` exists — it is no prefix of the query's, and eight extra
+      // characters is past any edit-distance threshold.
+      expect(
+        suggestNames("color.text.primary", ["color.text", "color.border"]),
+      ).toEqual(["color.text"]);
+    });
+
+    it("is offered for the last segment of a pasted local name", () => {
+      expect(
+        suggestNames("apps_lxd.component.meter", ["Meter", "Metric"]),
+      ).toEqual(["Meter"]);
+    });
+
+    it("ranks first, longest run first, ahead of a candidate the query prefixes", () => {
+      expect(
+        suggestNames("color.text.muted", [
+          "color.text.muted.hover",
+          "color",
+          "color.text",
+          "text.muted",
+        ]),
+      ).toEqual([
+        "color.text",
+        "text.muted",
+        "color",
+        "color.text.muted.hover",
+      ]);
+    });
+
+    it("cuts at segment boundaries only", () => {
+      expect(
+        suggestNames("color.text.primary", ["color.te", "lor.text"]),
+      ).toEqual([]);
+    });
+
+    it("reads a slash-separated path the same way", () => {
+      expect(
+        suggestNames("react/component/tsdoc/extra", ["react/component/tsdoc"]),
+      ).toEqual(["react/component/tsdoc"]);
+    });
+
+    it("reads past a prefix, so a prefixed name suggests like its bare form", () => {
+      expect(
+        suggestNames("dt:color.text.zzz", ["color.text", "color"]),
+      ).toEqual(["color.text", "color"]);
+    });
+
+    it("builds no runs for a query too long to be a name", () => {
+      const parts = Array.from({ length: 3000 }, (_, i) => `s${i}`);
+      const started = performance.now();
+      expect(suggestNames(parts.join("."), ["s1.s2"])).toEqual([]);
+      expect(performance.now() - started).toBeLessThan(100);
+    });
+
+    it("keeps the five-result cap", () => {
+      const parts = ["a1", "b2", "c3", "d4", "e5", "f6", "g7"];
+      expect(suggestNames(parts.join("."), parts)).toHaveLength(5);
+    });
+
+    it("stays cheap against a pool the size of the shipped pack", () => {
+      // The length prefilter exists because ranking 4,380 names once cost
+      // 1.2 s; this branch is a map lookup per candidate and must not undo
+      // it. The pool is names the prefilter rejects on length, so what is
+      // timed is the branch and the prefilter, not the edit distances.
+      const pool = Array.from(
+        { length: 5000 },
+        (_, i) => `color.group${i}.tone.on.a.path.far.longer.than.the.query.is`,
+      );
+      const started = performance.now();
+      expect(suggestNames("apps_lxd.component.meter", pool)).toEqual([]);
+      expect(performance.now() - started).toBeLessThan(100);
+    });
+  });
 });

package/src/kernel/project/cli/suggestNames.ts

@@ -6,6 +6,40 @@
  * by the unknown-command suggester to turn a typo into "Did you mean: …?".
  */
 
+/** How many suggestions are returned unless a caller asks for fewer or more. */
+export const MAX_SUGGESTIONS = 5;
+
+/** What separates the segments of a path-shaped name (`:` ends a prefix). */
+const SEGMENT_SEPARATOR = /[./:]/;
+
+/** Past this many segments a query is not a name, and its runs are not built. */
+const MAX_RUN_SEGMENTS = 16;
+
+/**
+ * Every contiguous run of whole segments of `query` shorter than the query,
+ * mapped to the number of segments it spans; empty for a query of one segment
+ * or of more than {@link MAX_RUN_SEGMENTS}.
+ */
+function segmentRuns(query: string): ReadonlyMap<string, number> {
+  if (query.split(SEGMENT_SEPARATOR).length > MAX_RUN_SEGMENTS) {
+    return new Map();
+  }
+  const starts = [0];
+  for (const [index, char] of [...query].entries()) {
+    if (SEGMENT_SEPARATOR.test(char)) starts.push(index + 1);
+  }
+  const ends = [...starts.slice(1).map((start) => start - 1), query.length];
+  const runs = new Map<string, number>();
+  for (const [from, start] of starts.entries()) {
+    for (const [to, end] of ends.entries()) {
+      const run = query.slice(start, end);
+      if (to < from || run === "" || run === query) continue;
+      runs.set(run, to - from + 1);
+    }
+  }
+  return runs;
+}
+
 /**
  * Return up to {@link maxResults} candidates most similar to `query`.
  *
@@ -19,6 +53,10 @@
  * if a candidate really is the query, the miss is the bug and the suggestion
  * would only hide it.
  *
+ * Ranking, best first: a candidate that is a run of the query's whole segments
+ * (`color.text` for `color.text.primary`), longest first; then a candidate the
+ * query is a prefix of; then edit distance.
+ *
  * Scoring reads the same trimmed forms, so padding costs a candidate no edit
  * distance either; what is RETURNED is the candidate verbatim, padding and
  * casing intact, because a suggestion names a value the graph holds.
@@ -34,7 +72,7 @@ export function suggestNames(
   candidates: readonly string[],
   opts?: { maxResults?: number; threshold?: number },
 ): string[] {
-  const maxResults = opts?.maxResults ?? 5;
+  const maxResults = opts?.maxResults ?? MAX_SUGGESTIONS;
   const threshold = opts?.threshold ?? 0.4;
   const queryLower = query.trim().toLowerCase();
 
@@ -44,12 +82,20 @@ export function suggestNames(
 
   type Scored = { name: string; score: number };
   const scored: Scored[] = [];
+  const runs = segmentRuns(queryLower);
 
   for (const candidate of candidates) {
     const candidateLower = candidate.trim().toLowerCase();
 
     if (candidateLower === queryLower) continue;
 
+    // Below zero: every run outranks a prefix match, the longest run first.
+    const spanned = runs.get(candidateLower);
+    if (spanned !== undefined) {
+      scored.push({ name: candidate, score: -spanned });
+      continue;
+    }
+
     if (candidateLower.startsWith(queryLower)) {
       scored.push({ name: candidate, score: 0 });
       continue;

package/src/kernel/project/cli/verbHelp.ts

@@ -8,7 +8,9 @@
  * `formatVerbHelp`, retargeted at the grammar.
  */
 
-import type { ParamSpec, VerbSpec } from "../../spec/index.js";
+import { renderCall } from "../../spec/call.js";
+import { exampleCall, useWhenSentence } from "../../spec/guidance.js";
+import type { Example, ParamSpec, VerbSpec } from "../../spec/index.js";
 import { kebabCase } from "../../spec/index.js";
 import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
 import {
@@ -19,18 +21,6 @@ import {
   helpUsage,
 } from "./helpFormat.js";
 
-/**
- * A verb's `doc` doubles as its MCP tool description, so a pack's authored
- * `toolDescription` may end with an MCP tool-call example — `Example:
- * token_lookup { names: ["…"] }`. That `noun_verb {…}` syntax is MCP-transport
- * shape, meaningless on the CLI, so the CLI projector drops the trailing example
- * sentence; the MCP projector keeps the authored text whole. Hand-written docs
- * carry no such example and pass through untouched.
- */
-function stripToolCallExample(doc: string): string {
-  return doc.replace(/\s*Example:\s+[a-z][a-z0-9_]*\s*\{[^{}]*\}\.?\s*$/, "");
-}
-
 /** The positional usage token for a param (`<name>` / `[name]`, `...` variadic). */
 function positionalToken(param: ParamSpec): string {
   const variadic = param.kind === "string[]" ? "..." : "";
@@ -69,10 +59,9 @@ export function formatVerbHelp(programName: string, verb: VerbSpec): string {
     verb.summary,
   ];
 
-  if (verb.doc) {
-    const cliDoc = stripToolCallExample(verb.doc);
-    if (cliDoc) lines.push("", cliDoc);
-  }
+  if (verb.doc) lines.push("", verb.doc);
+  const question = useWhenSentence(verb);
+  if (question) lines.push("", question);
 
   // Every flag the command PARSES is rendered, from the same spec facts
   // registration reads: the declared params, each default-true boolean's
@@ -97,9 +86,17 @@ export function formatVerbHelp(programName: string, verb: VerbSpec): string {
     lines.push("", helpHeading("Flags"), ...helpColumns(flagRows));
   }
 
-  if (verb.examples && verb.examples.length > 0) {
+  // The verb's declared example leads, spelled as a command by the same
+  // renderer that spells it as a tool call in the MCP description.
+  const declaredExample = exampleCall(verb);
+  const generated = declaredExample && renderCall(declaredExample, "cli");
+  const examples = [
+    ...(generated ? [{ cmd: generated } as Example] : []),
+    ...(verb.examples ?? []).filter((example) => example.cmd !== generated),
+  ];
+  if (examples.length > 0) {
     lines.push("", helpHeading("Examples"));
-    for (const example of verb.examples) {
+    for (const example of examples) {
       lines.push(`  ${helpTerm(example.cmd)}`);
       if (example.note) lines.push(`    ${helpDim(example.note)}`);
     }

package/src/kernel/project/mcp/buildServer.ts

@@ -18,8 +18,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { MCP_SERVER_NAME, VERSION } from "../../../constants.js";
 import type { GlobalFlags } from "../../runtime/index.js";
 import { bootRuntime } from "../../runtime/index.js";
+import { declareVerbs } from "../../spec/call.js";
 import type { CapabilityModule } from "../../spec/index.js";
-import { buildInstructions } from "./instructions.js";
+import { buildInstructions, INSTRUCTIONS_MAX_CHARS } from "./instructions.js";
 import { registerVerb } from "./registerVerb.js";
 
 /**
@@ -53,11 +54,21 @@ export async function buildServer(
 ): Promise<McpServer> {
   const server = new McpServer(
     { name: MCP_SERVER_NAME, version: VERSION },
-    // Handshake orientation (sent once at initialize), derived from the SAME
-    // conventions/discovery as the `capabilities` tool so the two never diverge.
-    { instructions: buildInstructions(modules) },
+    // Handshake orientation (sent once at initialize): the distribution's
+    // conventions plus a question → tool index generated from the registry. It
+    // is FITTED to the length clients keep; when a project's packs push it over,
+    // the dropped index lines are noted on stderr (stdout is the JSON-RPC frame).
+    {
+      instructions: buildInstructions(modules, (dropped) =>
+        process.stderr.write(
+          `MCP instructions: ${dropped} index line(s) did not fit ${INSTRUCTIONS_MAX_CHARS} characters and were left to the capabilities catalogue.\n`,
+        ),
+      ),
+    },
   );
   const runtime = bootRuntime(MCP_FLAGS, cwd);
+  // Tells the call renderer which verbs exist (see `spec/call.ts`).
+  declareVerbs(modules.flatMap((module) => module.verbs));
 
   for (const module of modules) {
     for (const verb of module.verbs) {

package/src/kernel/project/mcp/envelope.ts

@@ -4,8 +4,9 @@
  * The MCP projector returns the *same* `{ ok, data, meta }` / `{ ok, error }`
  * envelope the CLI emits under `--format json` — built by the shared
  * `successEnvelope` / `errorEnvelope` — serialized into a single text content
- * block (D4). Reusing the shared builders is what guarantees CLI-JSON and MCP
- * output are byte-identical.
+ * block (D4). Reusing the shared builders is what keeps CLI-JSON and MCP output
+ * the same envelope — equal in everything but the spelling of a next step
+ * inside `meta.notice`, which follows the surface it is printed on.
  */
 
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

package/src/kernel/project/mcp/instructions.ts

@@ -2,52 +2,140 @@
  * The MCP server `instructions` string — orientation sent ONCE in the
  * initialize handshake (not per tool call), so agents arrive oriented.
  *
- * It carries the same content the retired `llm` tool front-loaded: the
- * conventions + the discovery sequence. To guarantee it never diverges from the
- * `capabilities` tool, the WHOLE orientation — the opening line included —
- * derives from the SAME source: `CONVENTIONS` and
- * `buildDiscoverySequence` in `capabilities/capabilities/catalog.ts`. Live
- * numbers (tier/channel/entity counts) are deliberately DROPPED (they would need
- * a store boot at handshake); agents fetch those via `info`/`config show`/
- * `sources status`. Kept short (a hard length ceiling is asserted in the test),
- * since it counts against every session's context.
+ * A client may defer tools: the agent then sees only tool NAMES and this text
+ * until it searches for a tool by name, so a description it never loads cannot
+ * steer it. The instructions therefore carry a generated "question → tool"
+ * index, built from the SAME `useWhen` each verb declares for its description:
+ *
+ * - the distribution's conventions, handed over as data (`mcpOrientation` —
+ *   they name its tiers and nouns, so the kernel writes none of them);
+ * - one line per read tool that is not part of a noun's list/lookup/sample
+ *   trio, `tool — useWhen`;
+ * - the trio explained ONCE, with the nouns that have each verb enumerated;
+ * - the writes on one shared, plan-first line.
+ *
+ * Everything listed is derived from the registry: a new verb adds itself. Live
+ * numbers (tier/channel/entity counts) are deliberately absent — they would
+ * need a store boot at handshake.
+ */
+
+import type { CapabilityModule, VerbSpec } from "../../spec/index.js";
+import { emitSurface, toolName } from "../../spec/index.js";
+
+/**
+ * HARD ceiling on the instructions length, unlike the catalogue budget: clients
+ * cap server instructions at about 2 KB and cut the rest, so text past this is
+ * text no agent reads. Fit by tightening sentences, never by raising it.
  */
+export const INSTRUCTIONS_MAX_CHARS = 2000;
 
-import {
-  buildDiscoverySequence,
-  CONVENTIONS,
-} from "../../../capabilities/capabilities/catalog.js";
-import type { CapabilityModule } from "../../spec/index.js";
-import { emitSurface } from "../../spec/index.js";
+/** The verbs every read story compiles to; explained once rather than per noun. */
+const TRIO = ["list", "lookup", "sample"] as const;
 
-/** Hard ceiling on the instructions length (asserted by the protected test). */
-export const INSTRUCTIONS_MAX_CHARS = 1500;
+/** How most `useWhen` clauses open; the index says it once. */
+const ASKED = /^when asked /;
+
+/** Which of the trio a verb is, or nothing for a verb that stands alone. */
+function trioVerbOf(verb: VerbSpec): (typeof TRIO)[number] | undefined {
+  return TRIO.find((name) => verb.path[1] === name);
+}
 
 /**
  * Build the handshake orientation string from the live capability modules.
  *
- * @param modules - The capability modules (for the live discovery-sample list).
- * @returns A short, single-source orientation string (≤ {@link INSTRUCTIONS_MAX_CHARS}).
+ * The registry is not fixed — a project's packs add verbs at runtime — so the
+ * text is FITTED, not merely measured: everything that is one line whatever the
+ * registry holds comes first, the index comes last, and index lines are dropped
+ * from the end until the whole fits, the last line saying how many were dropped
+ * and where the full list is. A client would otherwise cut the tail silently.
+ *
+ * @param modules - The capability modules; the one declaring `mcpOrientation`
+ *   supplies the conventions, the registry everything else.
+ * @param onTruncate - Told how many index lines did not fit, when any did not.
+ * @returns The orientation (≤ {@link INSTRUCTIONS_MAX_CHARS}); empty when no
+ *   module declares one.
  */
 export function buildInstructions(
   modules: readonly CapabilityModule[],
+  onTruncate?: (dropped: number) => void,
 ): string {
-  // Tools AND resource templates come from the one emitted surface: the
-  // `<scheme>:{+uri}` template is declared by the module that serves it and
-  // frozen in the covenant, so quoting it here rather than deriving it would be
-  // a second copy of a string the kernel does not own.
-  const { tools, resources } = emitSurface(modules).mcpSurface;
-  const steps = buildDiscoverySequence(tools)
-    .map((stage) => `${stage.stage}. ${stage.tool} — ${stage.purpose}`)
-    .join("\n");
-  const templates = resources.map((template) => `\`${template}\``).join(", ");
-
-  return [
-    `${CONVENTIONS.system} ${CONVENTIONS.model} ${CONVENTIONS.querying} ${CONVENTIONS.mutations}`,
+  const orientation = modules.find(
+    (module) => module.mcpOrientation,
+  )?.mcpOrientation;
+  if (!orientation) return "";
+  const tools = modules
+    .flatMap((module) => module.verbs)
+    .filter((verb) => !verb.hidden && verb.capability.mcp.expose);
+  const reads = tools.filter((verb) => !verb.capability.mutates);
+
+  // The trio, once: every noun that has any of the three, marked for what it
+  // has beyond `list` — a noun is never promised a verb it lacks.
+  const has = (noun: string, name: (typeof TRIO)[number]): boolean =>
+    reads.some((verb) => verb.path[0] === noun && trioVerbOf(verb) === name);
+  const nouns = [
+    ...new Set(reads.filter(trioVerbOf).map((verb) => verb.path[0])),
+  ].map(
+    (noun) =>
+      `${noun}${has(noun, "lookup") ? "" : "†"}${has(noun, "sample") ? "*" : ""}`,
+  );
+  const writes = tools
+    .filter((verb) => verb.capability.mutates)
+    .map((verb) => toolName(verb.path))
+    .join(", ");
+  // The resource templates come from the emitted surface: the scheme is
+  // declared by the module that serves it and frozen in the covenant.
+  const templates = emitSurface(modules)
+    .mcpSurface.resources.map((template) => `\`${template}\``)
+    .join(", ");
+  const fixed = [
+    orientation.conventions.join(" "),
     "",
-    "Discovery sequence:",
-    steps,
+    `Per noun, <noun>_list finds entries and <noun>_lookup reads them by name († has no lookup); * also has <noun>_sample, which shows real data shapes: ${nouns.join(", ")}.`,
+    `Writes are plan-first — the first call returns a plan; repeat it with confirm: true to apply: ${writes}.`,
+    `Entity detail: read ${templates} resources.`,
     "",
-    `Call the \`capabilities\` tool for the full annotated tool catalog; read ${templates} resources (or \`graph_inspect\`) for entity detail.`,
-  ].join("\n");
+  ];
+
+  // The index. Verbs that read the store come first — they are the ones that
+  // answer questions about the data — so what an overflow drops is the
+  // administrative tail. A verb declaring no `useWhen` has no line to give.
+  const standalone = reads
+    .filter((verb) => !trioVerbOf(verb) && verb.useWhen)
+    .sort(
+      (a, b) =>
+        Number(b.capability.needsStore) - Number(a.capability.needsStore),
+    );
+  // Most clauses open "when asked …"; saying that once, as a heading, is what
+  // lets every question fit under the ceiling.
+  const lineFor = (verb: VerbSpec): string =>
+    `${toolName(verb.path)} — ${verb.useWhen?.replace(ASKED, "")}`;
+  const group = (heading: string, verbs: readonly VerbSpec[]): string[] =>
+    verbs.length > 0 ? [heading, ...verbs.map(lineFor)] : [];
+  const index = [
+    ...group(
+      "When asked:",
+      standalone.filter((verb) => ASKED.test(verb.useWhen ?? "")),
+    ),
+    ...group(
+      "Also:",
+      standalone.filter((verb) => !ASKED.test(verb.useWhen ?? "")),
+    ),
+  ];
+
+  // Where the full list lives: the distribution's own orientation tool.
+  const catalogue = tools.find((verb) => verb.category === "orientation");
+  const render = (kept: number): string => {
+    const dropped = index.length - kept;
+    const more =
+      dropped === 0
+        ? []
+        : [
+            `… and ${dropped} more${catalogue ? `: call ${toolName(catalogue.path)}` : ""}.`,
+          ];
+    return [...fixed, ...index.slice(0, kept), ...more].join("\n");
+  };
+  let kept = index.length;
+  while (kept > 0 && render(kept).length > INSTRUCTIONS_MAX_CHARS) kept--;
+  if (kept < index.length) onTruncate?.(index.length - kept);
+  return render(kept);
 }