@canonical/pragma-cli 0.34.0 → 0.35.0

package/dist/src/kernel/project/cli/suggestNames.js

@@ -0,0 +1,96 @@
+/**
+ * Rank candidate names by similarity to a failed token.
+ *
+ * Ported near-verbatim from the v1 suggester: prefix matches first, then
+ * Damerau-Levenshtein edit-distance matches under a normalized threshold. Used
+ * by the unknown-command suggester to turn a typo into "Did you mean: …?".
+ */
+/**
+ * Return up to {@link maxResults} candidates most similar to `query`.
+ *
+ * Exact matches are excluded — a match means the caller should have resolved it
+ * and never reached here.
+ *
+ * @param query - The token that failed to resolve.
+ * @param candidates - All known names to rank against.
+ * @param opts.maxResults - Max suggestions to return (default 5).
+ * @param opts.threshold - Max normalized edit distance (default 0.4).
+ * @returns Ranked suggestions, original casing preserved.
+ */
+export function suggestNames(query, candidates, opts) {
+    if (query === "")
+        return [];
+    const maxResults = opts?.maxResults ?? 5;
+    const threshold = opts?.threshold ?? 0.4;
+    const queryLower = query.toLowerCase();
+    const scored = [];
+    for (const candidate of candidates) {
+        const candidateLower = candidate.toLowerCase();
+        if (candidateLower === queryLower)
+            continue;
+        if (candidateLower.startsWith(queryLower)) {
+            scored.push({ name: candidate, score: 0 });
+            continue;
+        }
+        const distance = damerauLevenshtein(queryLower, candidateLower);
+        const maxLen = Math.max(queryLower.length, candidateLower.length);
+        const normalized = maxLen === 0 ? 0 : distance / maxLen;
+        if (normalized <= threshold) {
+            scored.push({ name: candidate, score: normalized });
+        }
+    }
+    scored.sort((a, b) => a.score - b.score);
+    return scored.slice(0, maxResults).map((s) => s.name);
+}
+/**
+ * Damerau-Levenshtein distance: insertions, deletions, substitutions, and
+ * adjacent transpositions.
+ */
+function damerauLevenshtein(a, b) {
+    const lenA = a.length;
+    const lenB = b.length;
+    if (lenA === 0)
+        return lenB;
+    if (lenB === 0)
+        return lenA;
+    const matrix = Array.from({ length: lenA + 1 }, () => Array.from({ length: lenB + 1 }).fill(0));
+    for (let i = 0; i <= lenA; i++) {
+        getRow(matrix, i)[0] = i;
+    }
+    const firstRow = getRow(matrix, 0);
+    for (let j = 0; j <= lenB; j++) {
+        firstRow[j] = j;
+    }
+    for (let i = 1; i <= lenA; i++) {
+        const prevRow = getRow(matrix, i - 1);
+        const row = getRow(matrix, i);
+        for (let j = 1; j <= lenB; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min(getCell(prevRow, j) + 1, // deletion
+            getCell(row, j - 1) + 1, // insertion
+            getCell(prevRow, j - 1) + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                const prevPrevRow = getRow(matrix, i - 2);
+                row[j] = Math.min(getCell(row, j), getCell(prevPrevRow, j - 2) + cost);
+            }
+        }
+    }
+    return getCell(getRow(matrix, lenA), lenB);
+}
+/** Read a matrix row that is structurally guaranteed to exist. */
+function getRow(matrix, index) {
+    const row = matrix.at(index);
+    if (row === undefined) {
+        throw new Error(`matrix row ${index} is out of bounds`);
+    }
+    return row;
+}
+/** Read a matrix cell that is structurally guaranteed to exist. */
+function getCell(row, index) {
+    const cell = row.at(index);
+    if (cell === undefined) {
+        throw new Error(`matrix cell ${index} is out of bounds`);
+    }
+    return cell;
+}
+//# sourceMappingURL=suggestNames.js.map

package/dist/src/kernel/project/cli/suggestNames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestNames.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/suggestNames.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/project/cli/verbHelp.js

@@ -0,0 +1,131 @@
+/**
+ * Verb-level help, rendered from a {@link VerbSpec}.
+ *
+ * Help is designed, not auto-generated: a usage line with positional tokens,
+ * the summary and optional extended doc, a flags block, and the verb's own
+ * authored examples. Reads only the spec's declarative fields — never the run
+ * body — so it stays on the fast `--help` path. Ported from the v1 cli-core
+ * `formatVerbHelp`, retargeted at the grammar.
+ */
+import { kebabCase } from "../../spec/index.js";
+import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
+import { helpColumns, helpDim, helpHeading, helpTerm, 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) {
+    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) {
+    const variadic = param.kind === "string[]" ? "..." : "";
+    return param.required
+        ? `<${param.name}${variadic}>`
+        : `[${param.name}${variadic}]`;
+}
+/** The flag display for a non-positional param (`--kebab` or `--kebab <value>`). */
+function flagDisplay(param) {
+    const flag = `--${kebabCase(param.name)}`;
+    if (param.kind === "boolean")
+        return flag;
+    if (param.kind === "string[]")
+        return `${flag} <values...>`;
+    return `${flag} <value>`;
+}
+/**
+ * Render the full verb help block.
+ *
+ * @param programName - The CLI binary name shown in the usage line.
+ * @param verb - The verb whose interface is documented.
+ * @returns The formatted help text.
+ */
+export function formatVerbHelp(programName, verb) {
+    const commandPath = verb.path
+        .filter((s) => Boolean(s))
+        .join(" ");
+    const positionals = verb.params.filter((p) => p.positional);
+    const flags = verb.params.filter((p) => !p.positional);
+    const positionalStr = positionals.map(positionalToken).join(" ");
+    const usageSuffix = positionalStr ? ` ${positionalStr}` : "";
+    const lines = [
+        helpUsage(`${programName} ${commandPath}${usageSuffix} [flags]`),
+        "",
+        verb.summary,
+    ];
+    if (verb.doc) {
+        const cliDoc = stripToolCallExample(verb.doc);
+        if (cliDoc)
+            lines.push("", cliDoc);
+    }
+    // Every flag the command PARSES is rendered, from the same spec facts
+    // registration reads: the declared params, each default-true boolean's
+    // `--no-` negation, and — on a mutating verb — the auto-injected mutation
+    // flags. Help denying a working flag is the drift this derivation removes.
+    const flagRows = flags.flatMap((flag) => {
+        const rows = [
+            [flagDisplay(flag), flag.doc],
+        ];
+        if (flag.kind === "boolean" && flag.default === true) {
+            const kebab = kebabCase(flag.name);
+            rows.push([`--no-${kebab}`, negationFlagDoc(kebab)]);
+        }
+        return rows;
+    });
+    if (verb.capability.mutates) {
+        flagRows.push(...MUTATION_FLAG_DOCS.map(({ flag, doc }) => [flag, doc]));
+    }
+    if (flagRows.length > 0) {
+        lines.push("", helpHeading("Flags"), ...helpColumns(flagRows));
+    }
+    if (verb.examples && verb.examples.length > 0) {
+        lines.push("", helpHeading("Examples"));
+        for (const example of verb.examples) {
+            lines.push(`  ${helpTerm(example.cmd)}`);
+            if (example.note)
+                lines.push(`    ${helpDim(example.note)}`);
+        }
+    }
+    lines.push("", verbHelpFooter(programName, verb));
+    return lines.join("\n");
+}
+/**
+ * The footer pointing at the next help level: a sub-verb points UP to its noun
+ * page (`pragma block --help`), a self-verb points to the root (`pragma
+ * --help`). Uniform across every verb page — the leaf pages used to have none.
+ */
+function verbHelpFooter(programName, verb) {
+    if (verb.path.length > 1) {
+        const noun = verb.path[0];
+        return helpDim(`Run \`${programName} ${noun} --help\` to see all ${noun} commands.`);
+    }
+    return helpDim(`Run \`${programName} --help\` to see all commands.`);
+}
+/**
+ * Render noun-level help — the list of verbs under a noun parent
+ * (`pragma config --help`).
+ *
+ * @param programName - The CLI binary name shown in the usage line.
+ * @param noun - The noun whose verbs are listed.
+ * @param verbs - All registered verbs (filtered to this noun's sub-verbs).
+ * @returns The formatted help text.
+ */
+export function formatNounHelp(programName, noun, verbs) {
+    const nounVerbs = verbs.filter((v) => v.path[0] === noun && v.path[1] && !v.hidden);
+    if (nounVerbs.length === 0)
+        return `No commands found for "${noun}".`;
+    const lines = [
+        helpUsage(`${programName} ${noun} <verb> [flags]`),
+        "",
+        helpHeading("Verbs"),
+        ...helpColumns(nounVerbs.map((verb) => [verb.path[1], verb.summary])),
+        "",
+        helpDim(`Run \`${programName} ${noun} <verb> --help\` for details on a verb.`),
+    ];
+    return lines.join("\n");
+}
+//# sourceMappingURL=verbHelp.js.map

package/dist/src/kernel/project/cli/verbHelp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbHelp.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/verbHelp.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/project/mcp/buildServer.js

@@ -0,0 +1,67 @@
+/**
+ * Build the MCP server from the grammar.
+ *
+ * Constructs an {@link McpServer} whose wire identity PROJECTS from the
+ * distribution: `serverInfo.name` is the declared distribution name (the same
+ * projection that names the CLI bin, so existing agent wiring resolves it) and
+ * `serverInfo.version` the package version — a fork's server introduces itself
+ * under the fork's own name with no code change. The covenant records the rule
+ * (`surface.v2.json` `mcpSurface.serverInfo`) and `identity.test.ts` pins it on
+ * the wire from a fork's config. Then registers every exposed verb as a tool
+ * and each module's optional `mcpResources` surface (the graph resource
+ * browser, wired below via `module.mcpResources?.register`). One runtime is
+ * booted for the server's lifetime and shared by every tool; the store stays
+ * lazy, booting only when a resource read needs it.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MCP_SERVER_NAME, VERSION } from "../../../constants.js";
+import { bootRuntime } from "../../runtime/index.js";
+import { buildInstructions } from "./instructions.js";
+import { registerVerb } from "./registerVerb.js";
+/**
+ * Neutral flags for the MCP runtime. Output shaping is the projector's job
+ * (every tool returns the machine envelope), so these only seed `run` bodies
+ * that read `globalFlags` — none do in PR1.
+ */
+const MCP_FLAGS = {
+    llm: true,
+    autoLlm: false,
+    format: "json",
+    verbose: false,
+};
+/**
+ * Assemble the MCP server, registering all exposed verbs as tools and any
+ * module resource surfaces.
+ *
+ * Async because a module's `mcpResources.register` dynamic-imports the SDK's
+ * `ResourceTemplate` (so the resource browser never lands on the storeless
+ * `--help`/`__complete` fast path).
+ *
+ * @param modules - The capability modules to project.
+ * @param cwd - The working directory for the server's runtime.
+ * @returns The configured MCP server, ready to `connect` to a transport.
+ * @note Impure by default — reads `process.cwd()` unless `cwd` is provided.
+ */
+export async function buildServer(modules, cwd = process.cwd()) {
+    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) });
+    const runtime = bootRuntime(MCP_FLAGS, cwd);
+    for (const module of modules) {
+        for (const verb of module.verbs) {
+            if (verb.capability.mcp.expose) {
+                registerVerb(server, verb, runtime);
+            }
+        }
+        // A module's optional resource surface (NOT a tool) — the `{+uri}` template.
+        // The WHOLE module set goes with it: the listing the provider installs is
+        // the union of every module's declared `mcpListable` slices, which the
+        // declaring module cannot see from where it sits.
+        await module.mcpResources?.register(server, runtime, modules);
+        // A module's optional native prompt surface (NOT a tool) — `prompts/*`.
+        await module.mcpPrompts?.register(server, runtime);
+    }
+    return server;
+}
+//# sourceMappingURL=buildServer.js.map

package/dist/src/kernel/project/mcp/buildServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildServer.js","sourceRoot":"","sources":["../../../../../src/kernel/project/mcp/buildServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,SAAS,GAAgB;IAC7B,GAAG,EAAE,IAAI;IACT,OAAO,EAAE,KAAK;IACd,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,KAAK;CACf,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAoC,EACpC,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE;IAC3C,yEAAyE;IACzE,6EAA6E;IAC7E,EAAE,YAAY,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAC7C,CAAC;IACF,MAAM,OAAO,GAAG,WAAW,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAE5C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;gBAC/B,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QACD,6EAA6E;QAC7E,0EAA0E;QAC1E,uEAAuE;QACvE,kDAAkD;QAClD,MAAM,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9D,wEAAwE;QACxE,MAAM,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/kernel/project/mcp/envelope.js

@@ -0,0 +1,37 @@
+/**
+ * MCP transport wrapping of the shared machine envelope.
+ *
+ * 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.
+ */
+import { errorEnvelope, successEnvelope } from "../../render/index.js";
+/**
+ * Wrap success data as an MCP tool result.
+ *
+ * @param data - The JSON-safe data projection.
+ * @param meta - Envelope metadata (e.g. plan-first flags); defaults to `{}`.
+ * @returns The tool result carrying the success envelope.
+ */
+export function toolSuccess(data, meta = {}) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(successEnvelope(data, meta)) },
+        ],
+    };
+}
+/**
+ * Wrap a {@link PragmaError} as an MCP tool result flagged `isError`.
+ *
+ * @param error - The structured error to serialize.
+ * @returns The tool result carrying the failure envelope.
+ */
+export function toolError(error) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(errorEnvelope(error)) }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/kernel/project/mcp/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../../../src/kernel/project/mcp/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,IAAa,EACb,OAAgC,EAAE;IAElC,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE;SACpE;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAkB;IAC1C,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/src/kernel/project/mcp/index.js

@@ -0,0 +1,8 @@
+/**
+ * MCP projector barrel — the server builder and the verb→tool adapter.
+ */
+export { buildServer } from "./buildServer.js";
+export { toolError, toolSuccess } from "./envelope.js";
+export { buildZodSchema, registerVerb } from "./registerVerb.js";
+export { serveMcp } from "./serve.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/project/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/kernel/project/mcp/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/kernel/project/mcp/instructions.js

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+import { buildDiscoverySequence, CONVENTIONS, } from "../../../capabilities/capabilities/catalog.js";
+import { emitSurface } from "../../spec/index.js";
+/** Hard ceiling on the instructions length (asserted by the protected test). */
+export const INSTRUCTIONS_MAX_CHARS = 1500;
+/**
+ * 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}).
+ */
+export function buildInstructions(modules) {
+    // 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}`,
+        "",
+        "Discovery sequence:",
+        steps,
+        "",
+        `Call the \`capabilities\` tool for the full annotated tool catalog; read ${templates} resources (or \`graph_inspect\`) for entity detail.`,
+    ].join("\n");
+}
+//# sourceMappingURL=instructions.js.map

package/dist/src/kernel/project/mcp/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../../../src/kernel/project/mcp/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,sBAAsB,EACtB,WAAW,GACZ,MAAM,+CAA+C,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAoC;IAEpC,sEAAsE;IACtE,0EAA0E;IAC1E,8EAA8E;IAC9E,qDAAqD;IACrD,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC;IAC7D,MAAM,KAAK,GAAG,sBAAsB,CAAC,KAAK,CAAC;SACxC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;SAClE,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5E,OAAO;QACL,GAAG,WAAW,CAAC,MAAM,IAAI,WAAW,CAAC,KAAK,IAAI,WAAW,CAAC,QAAQ,IAAI,WAAW,CAAC,SAAS,EAAE;QAC7F,EAAE;QACF,qBAAqB;QACrB,KAAK;QACL,EAAE;QACF,4EAA4E,SAAS,sDAAsD;KAC5I,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/src/kernel/project/mcp/mcpError.js

@@ -0,0 +1,42 @@
+/**
+ * Project a {@link PragmaError} into an SDK `McpError` for the NATIVE MCP
+ * surfaces (the `prompts/*` provider, the `pragma:{+uri}` resource browser),
+ * which signal failure by throwing a JSON-RPC error rather than by returning the
+ * `{ ok, error }` tool envelope.
+ *
+ * A native read must not swallow a failure into plain-text "success" content: it
+ * carries the machine `code` AND the structured `recovery` into the JSON-RPC
+ * `data`, so an agent that hits a cold store over `prompts/list` or a resource
+ * read sees the SAME `STORE_UNAVAILABLE` + `sources_update` recovery the tool
+ * envelope carries — never a bare string with the recovery dropped.
+ *
+ * The SDK's `McpError`/`ErrorCode` are PASSED IN by the caller (which already
+ * dynamic-imported them in its `register`), so this module — reachable on the
+ * capabilities import graph — never statically pulls the SDK onto the
+ * `--help`/`__complete` fast path.
+ */
+/**
+ * Build an `McpError` from a {@link PragmaError}, mapping the machine code to a
+ * JSON-RPC code and preserving `code`/`recovery`/`suggestions`/`validOptions` in
+ * `data`.
+ *
+ * @param error - The structured pragma error to project.
+ * @param primitives - The SDK `McpError`/`ErrorCode` the caller imported.
+ * @returns An `McpError` carrying the diagnostic + recovery in its `data`.
+ */
+export function mcpErrorFrom(error, { McpError: McpErrorCtor, ErrorCode: ErrorCodeEnum }) {
+    // A bad/missing entity or rejected input is the caller's fault (InvalidParams);
+    // an unreachable store or internal fault is the server's (InternalError).
+    const jsonRpcCode = error.code === "ENTITY_NOT_FOUND" || error.code === "INVALID_INPUT"
+        ? ErrorCodeEnum.InvalidParams
+        : ErrorCodeEnum.InternalError;
+    const data = { code: error.code };
+    if (error.recovery)
+        data.recovery = error.recovery;
+    if (error.suggestions.length > 0)
+        data.suggestions = error.suggestions;
+    if (error.validOptions)
+        data.validOptions = error.validOptions;
+    return new McpErrorCtor(jsonRpcCode, error.message, data);
+}
+//# sourceMappingURL=mcpError.js.map

package/dist/src/kernel/project/mcp/mcpError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpError.js","sourceRoot":"","sources":["../../../../../src/kernel/project/mcp/mcpError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAkB,EAClB,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAsB;IAExE,gFAAgF;IAChF,0EAA0E;IAC1E,MAAM,WAAW,GACf,KAAK,CAAC,IAAI,KAAK,kBAAkB,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe;QACjE,CAAC,CAAC,aAAa,CAAC,aAAa;QAC7B,CAAC,CAAC,aAAa,CAAC,aAAa,CAAC;IAClC,MAAM,IAAI,GAA4B,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IAC3D,IAAI,KAAK,CAAC,QAAQ;QAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACnD,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACvE,IAAI,KAAK,CAAC,YAAY;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC/D,OAAO,IAAI,YAAY,CAAC,WAAW,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAC5D,CAAC"}

package/dist/src/kernel/project/mcp/prompts/index.js

@@ -0,0 +1,36 @@
+/**
+ * Prompt entities, read two ways from one graph type.
+ *
+ * A prompt lives in the graph as an entity the distribution's vocabulary
+ * declares, and two surfaces offer it: the native MCP `prompts/list` +
+ * `prompts/get` handlers, and the `prompt list` / `prompt lookup` verbs behind
+ * the covenant tools. The pair is the cohesion principle — the reader here is
+ * the ONE place either surface learns what a prompt is, so the two can never
+ * report a different set of prompts or a different template body for one.
+ *
+ * The barrel carries both halves, and they READ DIFFERENTLY — the distinction
+ * matters to anyone rerouting imports through here, so it is stated rather
+ * than implied.
+ *
+ * `promptProvider` is the MCP module hook. Its `prompts/list` is STORELESS:
+ * it projects the pack index through `listPromptSummaries`, returning `[]`
+ * when no index is reachable and never booting the store. Its `prompts/get`
+ * is store-backed. The provider is imported STATICALLY by the prompt
+ * capability (`capabilities/prompt/index.ts`) — what it defers is the MCP SDK
+ * itself, whose request schemas it reaches through a dynamic import so the SDK
+ * stays off the `--help`/`__complete` fast path.
+ *
+ * `readPrompts` and `readPrompt` are the reads the CLI verbs take, and BOTH
+ * are store-backed: they query through `runSelect` directly, not through the
+ * index projection. A caller that expects a listing here to be as cheap as the
+ * MCP one is mistaken, and a reroute that makes either reachable statically
+ * from the capability graph puts a store boot on the fast path.
+ *
+ * `listPromptSummaries` stays internal. It is the MCP list path's projection,
+ * not a shared foundation under the two exported reads, and a caller choosing
+ * it directly is choosing a partial prompt without the store-backed body that
+ * makes it usable.
+ */
+export { promptProvider } from "./provider.js";
+export { readPrompt, readPrompts } from "./source.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/project/mcp/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/kernel/project/mcp/prompts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/kernel/project/mcp/prompts/provider.js

@@ -0,0 +1,98 @@
+/**
+ * The native MCP `prompts/*` provider — the `mcpPrompts` module hook, mirroring
+ * the resource provider exactly.
+ *
+ * `register` wires the low-level `prompts/list` + `prompts/get` request handlers
+ * and advertises the `prompts` capability (so the server declares it even with
+ * zero prompts — an empty list is a valid, honest surface). Listing is STORELESS
+ * (index-backed via {@link listPromptSummaries}); a get is STORE-BACKED (SPARQL
+ * via {@link readPrompt}), then the template body is filled with the call's
+ * arguments. The SDK request schemas are dynamic-imported inside `register`, so
+ * this module — reachable on the capabilities import graph through the prompt
+ * module — never pulls the SDK types onto the `--help`/`__complete` fast path.
+ *
+ * Both handlers open with a STORELESS cold-store pre-check ({@link
+ * checkStoreAvailable}), and the store-backed `get` projects any read failure
+ * through {@link mcpErrorFrom}, so the native surface converges with the
+ * store-backed `prompt_list` tool: a cold store — or a store that cannot answer
+ * the prompt query — surfaces the SAME machine code and recovery here as the
+ * tool envelope carries, rather than a silent `[]` (list) or a bogus "not found"
+ * (get) that masks it. When the store is available (including the embedded
+ * fallback) both handlers behave exactly as before.
+ */
+import { asPragmaError } from "../../../error/fromTaskError.js";
+import { resolveSources } from "../../../runtime/resolveSources.js";
+import { checkStoreAvailable } from "../../../runtime/storeReadiness.js";
+import { mcpErrorFrom } from "../mcpError.js";
+import { listPromptSummaries, readPrompt } from "./source.js";
+/** Substitute `{{arg}}` placeholders in a template body with provided values. */
+export function fillTemplate(body, args) {
+    if (!args)
+        return body;
+    return body.replace(/\{\{\s*(\w+)\s*\}\}/g, (whole, key) => {
+        const value = args[key];
+        return value === undefined || value === null ? whole : String(value);
+    });
+}
+/** The native prompt provider (registered by buildServer via `mcpPrompts`). */
+export const promptProvider = {
+    async register(server, runtime) {
+        const { ListPromptsRequestSchema, GetPromptRequestSchema, McpError, ErrorCode, } = await import("@modelcontextprotocol/sdk/types.js");
+        // Advertise the capability even when empty — the surface exists regardless
+        // of whether the active graph ships prompt entities.
+        server.server.registerCapabilities({ prompts: { listChanged: false } });
+        // A STORELESS cold-store pre-check, shared with the store-backed `prompt_list`
+        // tool (whose `needsStore` guard throws) and the resource browser: a cold
+        // store must present the SAME STORE_UNAVAILABLE + `sources_update` recovery on
+        // native `prompts/*` as on the tool surface, not silently list from a stale
+        // index (or `[]`) here while the tool errors. Available (incl. the embedded
+        // fallback) → the native list stays storeless and the get stays store-backed.
+        const guardStore = async () => {
+            const unavailable = checkStoreAvailable(await runtime.loadConfig(), runtime.cwd);
+            if (unavailable)
+                throw mcpErrorFrom(unavailable, { McpError, ErrorCode });
+        };
+        server.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            await guardStore();
+            return {
+                prompts: listPromptSummaries(resolveSources(await runtime.loadConfig(), runtime.cwd)).map((prompt) => ({
+                    name: prompt.name,
+                    ...(prompt.description ? { description: prompt.description } : {}),
+                })),
+            };
+        });
+        server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            await guardStore();
+            const { name, arguments: args } = request.params;
+            // The read can fail (a store that cannot answer the prompt query), and a
+            // native surface signals that by THROWING — so project it the way the
+            // resource browser does, carrying the machine code and the recovery into
+            // the JSON-RPC `data` instead of letting a bare Error reach the agent.
+            let entry;
+            try {
+                entry = await readPrompt(runtime, name);
+            }
+            catch (error) {
+                throw mcpErrorFrom(asPragmaError(error), { McpError, ErrorCode });
+            }
+            if (!entry) {
+                // Reached only when the store IS available — a genuine miss, not a cold
+                // store (which `guardStore` already surfaced as STORE_UNAVAILABLE).
+                throw new McpError(ErrorCode.InvalidParams, `Prompt "${name}" not found`);
+            }
+            return {
+                ...(entry.description ? { description: entry.description } : {}),
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: fillTemplate(entry.body, args),
+                        },
+                    },
+                ],
+            };
+        });
+    },
+};
+//# sourceMappingURL=provider.js.map

package/dist/src/kernel/project/mcp/prompts/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../../../../src/kernel/project/mcp/prompts/provider.ts"],"names":[],"mappings":"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"}