@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -0,0 +1,154 @@
+/**
+ * The ONE source of truth for prompt entities — read TWO ways from ONE KG type,
+ * so the native MCP `prompts/*` surface and the covenant `prompt_list`/
+ * `prompt_lookup` content tools never diverge.
+ *
+ * The type and its four properties are DECLARED by the distribution
+ * (`kernel/vocabulary.ts`), not named here — this module knows the shape of a
+ * prompt, not whose prompt it is. With `<type>`/`<body>`/`<argument>`/
+ * `<argName>`/`<argRequired>` standing for the declared terms, a prompt entity
+ * is authored as:
+ *
+ *   ex:prompt.x a <type> ;
+ *     rdfs:label "x" ;               # the prompt NAME (indexed → storeless list)
+ *     rdfs:comment "…" ;             # the description (indexed)
+ *     <body> "…" ;                   # the template body (store-backed)
+ *     <argument> [ <argName> "a" ; rdfs:comment "…" ; <argRequired> true ] .
+ *
+ * Listing is STORELESS (over the pack index — `label`/`description` are indexed),
+ * so `prompts/list` and native discovery cost nothing until a `get`. A `get`
+ * (body + arguments) is STORE-BACKED through `runSelect` — identical laziness to
+ * the resource browser (list storeless, read store-backed). An empty or missing
+ * index yields zero prompts (never a store boot on the list path).
+ *
+ * The store-backed reads route through `runSelect` and DO NOT catch. A cold
+ * store is already refused upstream — the tools are `needsStore`, and the native
+ * provider calls `guardStore()` first — so a swallowed failure here could only
+ * ever hide a real one, reporting a broken query as an empty graph. `runSelect`
+ * classifies an unbound prefix as STORE_UNAVAILABLE with its `sources update`
+ * recovery and lets everything else propagate.
+ */
+import { readPackIndex } from "../../../completion/entitySource.js";
+import { runSelect } from "../../../packs/sparql/index.js";
+import { distributionSource } from "../../../packs/types.js";
+import { VOCABULARY } from "../../../vocabulary.js";
+/** The declared prompt terms this module reads the graph with. */
+const PROMPT = VOCABULARY.prompt;
+/** Whether an index entity carries the prompt type (primary type or any type). */
+function isPromptEntity(entity) {
+    return (entity.type === PROMPT.type ||
+        (Array.isArray(entity.types) && entity.types.includes(PROMPT.type)));
+}
+/**
+ * List prompt summaries STORELESSLY from the index of the pack the boot decision
+ * names. Returns `[]` when no index is reachable (including an unavailable
+ * store) or the index carries no prompts — never boots the store.
+ *
+ * @param decision - The boot decision from `resolveSources`.
+ * @returns Prompt summaries (name from the entity label, sorted by name).
+ */
+export function listPromptSummaries(decision) {
+    const index = readPackIndex(decision);
+    if (!index || !Array.isArray(index.entities))
+        return [];
+    const summaries = [];
+    for (const entity of index.entities) {
+        if (!isPromptEntity(entity))
+            continue;
+        const name = entity.label || entity.name;
+        summaries.push({
+            name,
+            ...(entity.description ? { description: entity.description } : {}),
+        });
+    }
+    return summaries.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The SPARQL that materializes prompts (all, or one when `label` is bound). */
+function promptQuery(labelFilter) {
+    const filter = labelFilter
+        ? `  FILTER(LCASE(STR(?name)) = LCASE(${JSON.stringify(labelFilter)}))`
+        : "";
+    return [
+        "SELECT ?name ?description ?body ?argName ?argDescription ?argRequired WHERE {",
+        `  ?prompt a ${PROMPT.type} ;`,
+        "          rdfs:label ?name .",
+        filter,
+        "  OPTIONAL { ?prompt rdfs:comment ?description }",
+        `  OPTIONAL { ?prompt ${PROMPT.body} ?body }`,
+        "  OPTIONAL {",
+        `    ?prompt ${PROMPT.argument} ?arg .`,
+        `    ?arg ${PROMPT.argName} ?argName .`,
+        "    OPTIONAL { ?arg rdfs:comment ?argDescription }",
+        `    OPTIONAL { ?arg ${PROMPT.argRequired} ?argRequired }`,
+        "  }",
+        "}",
+        "ORDER BY ?name ?argName",
+    ].join("\n");
+}
+/**
+ * Fold SELECT rows (one per argument; the body repeats) into distinct
+ * {@link PromptEntry}s. Rows are keyed by SELECT variable name with plain string
+ * values, and an unbound OPTIONAL variable is simply absent.
+ */
+function foldPromptRows(rows) {
+    const byName = new Map();
+    for (const row of rows) {
+        const name = row.name;
+        if (!name)
+            continue;
+        let entry = byName.get(name);
+        if (!entry) {
+            entry = { body: "", args: new Map() };
+            if (row.description)
+                entry.description = row.description;
+            byName.set(name, entry);
+        }
+        if (row.body)
+            entry.body = row.body;
+        const argName = row.argName;
+        if (argName && !entry.args.has(argName)) {
+            entry.args.set(argName, {
+                name: argName,
+                ...(row.argDescription ? { description: row.argDescription } : {}),
+                ...(row.argRequired !== undefined
+                    ? { required: row.argRequired === "true" }
+                    : {}),
+            });
+        }
+    }
+    return [...byName.entries()]
+        .map(([name, entry]) => ({
+        name,
+        ...(entry.description ? { description: entry.description } : {}),
+        body: entry.body,
+        arguments: [...entry.args.values()],
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Read every prompt entity STORE-BACKED (body + arguments).
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The materialized prompt entries, sorted by name.
+ * @throws PragmaError STORE_UNAVAILABLE when the store cannot answer; any other
+ *   query failure propagates, so a broken read is never an empty graph.
+ * @note Impure — boots the store through `runSelect`.
+ */
+export async function readPrompts(rt) {
+    return foldPromptRows(await runSelect(rt, promptQuery(), distributionSource("prompt")));
+}
+/**
+ * Read ONE prompt entity by name (case-insensitive), STORE-BACKED.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param name - The prompt name (its `rdfs:label`).
+ * @returns The materialized prompt, or `undefined` when the graph has no such
+ *   prompt — a genuine miss, never a failed read.
+ * @throws PragmaError STORE_UNAVAILABLE when the store cannot answer; any other
+ *   query failure propagates.
+ * @note Impure — boots the store through `runSelect`.
+ */
+export async function readPrompt(rt, name) {
+    return foldPromptRows(await runSelect(rt, promptQuery(name), distributionSource("prompt"))).at(0);
+}
+//# sourceMappingURL=source.js.map

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

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

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

@@ -0,0 +1,300 @@
+/**
+ * Adapter: {@link VerbSpec} → an MCP tool.
+ *
+ * This is the one seam where the grammar meets the MCP SDK — the only place a
+ * projector reaches for zod (to build the input schema the SDK validates). The
+ * tool name follows the grammar's naming rule, annotations derive from the
+ * capability, and a mutating verb gains the plan-first `confirm` flow: without
+ * `confirm`, the verb's `Task` is dry-run and a plan is returned
+ * (`{ planOnly: true, confirmRequired: true }`); with `confirm: true`, it runs
+ * for real. That plan is rendered through the SAME shared effect formatter the
+ * CLI preview uses, so the agent-facing and human-facing surfaces describe one
+ * plan rather than two views of it.
+ */
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { describeEffect } from "@canonical/task";
+import { runPreview, runTask } from "@canonical/task/node";
+import { z } from "zod";
+import { asPragmaError } from "../../error/fromTaskError.js";
+import { PragmaError } from "../../error/index.js";
+import { toolName } from "../../spec/index.js";
+import { toolError, toolSuccess } from "./envelope.js";
+/**
+ * Resolve the effective per-call write root for a mutating tool call.
+ *
+ * The MCP-only injected `cwd` arg lets an agent target a project directory other
+ * than the server's launch dir. It MUST be an absolute, existing directory —
+ * this is the SINGLE cwd the SEC-2 jail validates AND the interpreter resolves
+ * effect paths against, so a write dir the jail never checked can never exist.
+ *
+ * @throws PragmaError INVALID_INPUT for a relative or non-directory `cwd`.
+ */
+function resolveEffectiveCwd(rawCwd, fallback) {
+    if (typeof rawCwd !== "string" || rawCwd === "")
+        return fallback;
+    if (!isAbsolute(rawCwd)) {
+        throw PragmaError.invalidInput("cwd", rawCwd, {
+            recovery: { message: "Provide an absolute project directory path." },
+        });
+    }
+    let isDir = false;
+    try {
+        isDir = statSync(rawCwd).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        throw PragmaError.invalidInput("cwd", rawCwd, {
+            recovery: { message: "The cwd must be an existing directory." },
+        });
+    }
+    return rawCwd;
+}
+/** The base zod type for a param, before `.describe()`/`.optional()`. */
+function zodForParam(param) {
+    switch (param.kind) {
+        case "string":
+            return z.string();
+        case "number":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "enum":
+            return z.enum(param.values);
+        case "string[]":
+            return z.array(z.string());
+    }
+}
+/**
+ * Build the zod input shape for a verb's params.
+ *
+ * Each param becomes a described field; non-required params are optional. The
+ * returned raw shape is what the MCP SDK validates tool arguments against.
+ *
+ * @param params - The verb's parameter specs.
+ * @returns A zod raw shape keyed by param name.
+ */
+export function buildZodSchema(params) {
+    const shape = {};
+    for (const param of params) {
+        let field = zodForParam(param);
+        if (param.doc)
+            field = field.describe(param.doc);
+        // Apply a declared default so the MCP schema matches the CLI, which fills
+        // ParamSpec.default when a flag is omitted (dispatch.extractParams).
+        if ("default" in param && param.default !== undefined) {
+            field = field.default(param.default);
+        }
+        else if (!param.required) {
+            field = field.optional();
+        }
+        shape[param.name] = field;
+    }
+    return shape;
+}
+/** Derive the MCP annotations for a verb from its capability. */
+function annotationsFor(verb) {
+    return {
+        readOnlyHint: !verb.capability.mutates,
+        ...(verb.capability.destructive !== undefined
+            ? { destructiveHint: verb.capability.destructive }
+            : {}),
+        openWorldHint: false,
+    };
+}
+/** Pick just the verb's declared params out of the parsed tool arguments. */
+function paramsFromArgs(verb, args) {
+    const params = {};
+    for (const param of verb.params) {
+        if (param.name in args)
+            params[param.name] = args[param.name];
+    }
+    return params;
+}
+/**
+ * Apply the injected `detail` argument to a per-call runtime.
+ *
+ * A verb with a {@link DisclosureSpec} gains a `detail` enum tool param (see
+ * {@link registerVerb}); when the agent sets it, this seeds `globalFlags.detail`
+ * for THIS call so the verb's `run` resolves the level through the same uniform
+ * `resolveDetail` the CLI `--detail` flag feeds — no VerbSpec field, no
+ * Formatters-signature change, no MCP-opts-out asymmetry.
+ */
+function withDetail(verb, runtime, args) {
+    if (!verb.disclosure || typeof args.detail !== "string")
+        return runtime;
+    return {
+        ...runtime,
+        globalFlags: { ...runtime.globalFlags, detail: args.detail },
+    };
+}
+/** The tool handler for a read verb: run, project, envelope. */
+function readHandler(verb, runtime) {
+    return async (args) => {
+        try {
+            if (verb.capability.needsStore)
+                await runtime.store.get();
+            const params = paramsFromArgs(verb, args);
+            const result = await Promise.resolve(verb.run(params, withDetail(verb, runtime, args)));
+            return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+        }
+        catch (error) {
+            return toolError(asPragmaError(error));
+        }
+    };
+}
+/**
+ * Route a Task's log effects to STDERR. The default interpreter logs to
+ * `console.log` (stdout), which would corrupt the MCP stdio JSON-RPC frame;
+ * diagnostics belong on stderr. Mirrors the CLI dispatcher's `logToStderr`.
+ */
+const logToStderr = (_level, message) => {
+    process.stderr.write(`${message}\n`);
+};
+/** The tool handler for a mutating verb: plan-first unless `confirm: true`. */
+function mutateHandler(verb, runtime) {
+    return async (args) => {
+        try {
+            // The SINGLE per-call write root: validated here (absolute + existing dir)
+            // and threaded as `rt.cwd`, so the SEC-2 jail and the interpreter's
+            // effect-path base are literally the same value — no jail bypass.
+            const effectiveCwd = resolveEffectiveCwd(args.cwd, runtime.cwd);
+            if (verb.capability.needsStore)
+                await runtime.store.get();
+            const params = paramsFromArgs(verb, args);
+            // Without `confirm`, this is a plan-only preview: tell the verb so a
+            // network-touching mutation stays offline and never fetches on discovery.
+            const preview = args.confirm !== true;
+            // MCP has no interactive channel: transport "mcp" makes an interactive
+            // verb pick the params-or-error prompt strategy, so a tool call can never
+            // hang waiting for input.
+            const interaction = {
+                isTTY: false,
+                transport: "mcp",
+                yes: args.confirm === true,
+            };
+            const mutationRuntime = {
+                ...runtime,
+                cwd: effectiveCwd,
+                mutation: { preview, undo: false },
+                interaction,
+            };
+            const task = await Promise.resolve(verb.run(params, mutationRuntime));
+            if (preview) {
+                // The HONEST preview (PR7), the same interpreter `--dry-run` uses:
+                // reads are real, writes are recorded and never executed. A tool call
+                // whose confirmed run would fail now returns that error instead of a
+                // confident plan, so plan-first predicts rather than reassures.
+                //
+                // NO `onLog`: a preview that PERFORMS an effect is not a preview of
+                // that effect, and the recorded `Log`s are already about to be listed.
+                // The interpreter prints nothing of its own when it is absent.
+                const previewExec = mutationRuntime.exec ?? {};
+                try {
+                    const { effects } = await runPreview(task, {
+                        cwd: previewExec.cwd,
+                        onEffectStart: previewExec.onEffectStart,
+                    });
+                    // This payload is read by an LLM on a token budget, so it carries
+                    // the plan a person is shown rather than the interpreter's
+                    // transcript: the same `visiblePlanEffects` filter the CLI preview
+                    // applies, from the same module. Without it every internal
+                    // `Check exists:` and every repeat of the output directory spent
+                    // tokens burying the real artifacts.
+                    //
+                    // The FILTER is what the surfaces share; the ROW FORMAT is not.
+                    // These strings are structured data, so they stay `describeEffect` —
+                    // the description `@canonical/task` gives its own effects, which
+                    // carries byte counts, has no terminal chrome, and cannot embed an
+                    // ANSI escape however the editor that spawned this server configured
+                    // colour. That also lets the CLI's `--format json` plan and this one
+                    // be compared string for string, which is the A6 invariant.
+                    //
+                    // Loaded lazily, and from the LIGHT `/format` subpath: the kernel
+                    // keeps summon-core proper (and React) off its static import graph.
+                    const { visiblePlanEffects } = await import("@canonical/summon-core/format");
+                    const plan = visiblePlanEffects(effects, runtime.globalFlags.verbose === true).map(describeEffect);
+                    return toolSuccess({ plan }, { planOnly: true, confirmRequired: true });
+                }
+                finally {
+                    // No `store.invalidate()`: a preview cannot have changed disk. Only
+                    // the verb's own teardown (e.g. an interactive session) runs here.
+                    await previewExec.dispose?.();
+                }
+            }
+            // Real execution: spread the verb's runner options (prompt handler,
+            // stamping) into the interpreter; run teardown afterwards.
+            const exec = mutationRuntime.exec ?? {};
+            try {
+                const result = await runTask(task, { onLog: logToStderr, ...exec });
+                return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+            }
+            finally {
+                // A real mutation may have changed the pack/config on disk. This runtime
+                // is booted ONCE for the whole server lifetime and shared by every tool,
+                // so drop its server-lifetime caches (store session + the config memo the
+                // boot depends on) FIRST — before teardown, so a throwing `dispose` can
+                // never skip the cache-drop — then the next read re-boots against the new
+                // state instead of serving a stale pack/config. `mutationRuntime` spreads
+                // `runtime`, so this is the same shared LazyStore. Only reached on the
+                // real-run branch (`confirm: true`); the plan-only preview never mutates.
+                runtime.store.invalidate();
+                await exec.dispose?.();
+            }
+        }
+        catch (error) {
+            return toolError(asPragmaError(error));
+        }
+    };
+}
+/**
+ * Register one exposed verb as an MCP tool on the server.
+ *
+ * @param server - The MCP server to register onto.
+ * @param verb - The verb to expose (caller ensures `mcp.expose === true`).
+ * @param runtime - The runtime handed to the verb's `run`.
+ * @note Impure — mutates the server's tool registry.
+ */
+export function registerVerb(server, verb, runtime) {
+    const shape = buildZodSchema(verb.params);
+    // A verb with progressive disclosure gains a `detail` enum param derived from
+    // its DisclosureSpec (Risk2 — NO new VerbSpec field). The handler seeds
+    // globalFlags.detail from it per call, so MCP and CLI share one resolveDetail.
+    if (verb.disclosure) {
+        shape.detail = z
+            .enum(verb.disclosure.levels)
+            .optional()
+            .describe(`Progressive-disclosure level (${verb.disclosure.levels.join(", ")}); default ${verb.disclosure.default}.`);
+    }
+    if (verb.capability.mutates) {
+        shape.confirm = z
+            .boolean()
+            .default(false)
+            .describe("Set true to execute; otherwise a plan is returned.");
+        // Injected MCP-only per-call write root — added to the zod shape but NOT to
+        // verb.params (like `confirm`/`detail`), so `emitVerb` never emits it and the
+        // surface golden is untouched. The handler validates it and threads it as the
+        // single `rt.cwd` the jail + interpreter share (SEC-2 atomicity).
+        shape.cwd = z
+            .string()
+            .optional()
+            .describe("Absolute project directory to write into; defaults to the server's working directory.");
+    }
+    const config = {
+        // The agent-facing tool description is the verb's richer `doc` when present
+        // (pack `toolDescription`s compile into it; hand-written verbs author it
+        // directly), falling back to the one-line `summary`. Tool descriptions are
+        // NOT part of the frozen surface, so this stays covenant-safe.
+        description: verb.doc ?? verb.summary,
+        annotations: annotationsFor(verb),
+    };
+    if (Object.keys(shape).length > 0)
+        config.inputSchema = shape;
+    const handler = verb.capability.mutates
+        ? mutateHandler(verb, runtime)
+        : readHandler(verb, runtime);
+    server.registerTool(toolName(verb.path), config, handler);
+}
+//# sourceMappingURL=registerVerb.js.map

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

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

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

@@ -0,0 +1,35 @@
+/**
+ * Serve the MCP projector over stdio.
+ *
+ * The bin's `mcp` special-case (D9) and the hidden `mcp` meta verb both call
+ * this: build the server from the capabilities and connect it to a stdio
+ * transport. Kept separate from {@link buildServer} so tests can build a server
+ * without touching stdio.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadEffectiveModules } from "../../packs/index.js";
+import { buildServer } from "./buildServer.js";
+/**
+ * Build the MCP server and serve it over stdio until the transport closes.
+ *
+ * The server is a real invocation (not a fast path), so it merges the package-
+ * and config-declared story packs into the static capabilities before projecting
+ * the tool surface.
+ *
+ * @param modules - The static capability modules to project.
+ * @param cwd - The working directory for the server's runtime.
+ * @note Impure — reads config, connects to stdin/stdout.
+ */
+export async function serveMcp(modules, cwd) {
+    const dir = cwd ?? process.cwd();
+    const effective = await loadEffectiveModules(modules, dir);
+    // stderr only — the stdio transport owns stdout, so naming an unusable
+    // package story here is safe and reaches the host's server log.
+    for (const problem of effective.problems) {
+        process.stderr.write(`Ignored story ${problem.source}: ${problem.message}\n`);
+    }
+    const server = await buildServer(effective.modules, dir);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=serve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../../../../src/kernel/project/mcp/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAoC,EACpC,GAAY;IAEZ,MAAM,GAAG,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACjC,MAAM,SAAS,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC3D,uEAAuE;IACvE,gEAAgE;IAChE,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;QACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iBAAiB,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,OAAO,IAAI,CACxD,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/src/kernel/render/compactUri.js

@@ -0,0 +1,24 @@
+/**
+ * Compact a full URI to its prefixed form using the longest matching
+ * namespace. When two registered namespaces both prefix the URI (a base
+ * namespace and a sub-namespace), the longer — more specific — one wins.
+ * Falls back to the original URI when no namespace matches.
+ *
+ * @param fullUri - The absolute URI to compact.
+ * @param prefixes - A map of prefix to namespace IRI.
+ * @returns The `prefix:local` form, or `fullUri` unchanged when none matches.
+ */
+export function compactUri(fullUri, prefixes) {
+    let best;
+    for (const [prefix, namespace] of Object.entries(prefixes)) {
+        if (!fullUri.startsWith(namespace))
+            continue;
+        if (best === undefined || namespace.length > best.namespace.length) {
+            best = { prefix, namespace };
+        }
+    }
+    if (best === undefined)
+        return fullUri;
+    return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
+}
+//# sourceMappingURL=compactUri.js.map

package/dist/src/kernel/render/compactUri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactUri.js","sourceRoot":"","sources":["../../../../src/kernel/render/compactUri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,QAA0C;IAE1C,IAAI,IAAuD,CAAC;IAC5D,KAAK,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,SAAS;QAC7C,IAAI,IAAI,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YACnE,IAAI,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACvC,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;AAClE,CAAC"}

package/dist/src/kernel/render/contracts.js

@@ -0,0 +1,10 @@
+/**
+ * Layout contracts for the generic list and lookup renderers.
+ *
+ * These describe *how* a domain's data is projected to text — which columns a
+ * list shows, which fields and sections a lookup renders — with no coupling to
+ * store shapes, filters, or effects. Domain formatters (PR2+) build these
+ * option bags and hand them to {@link renderers}.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/src/kernel/render/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../../src/kernel/render/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/src/kernel/render/disclosure.js

@@ -0,0 +1,34 @@
+/**
+ * Progressive-disclosure resolution.
+ *
+ * A verb renders at one of {@link DETAIL_LEVELS}. The effective level is chosen
+ * from four sources, most specific first: the `--detail` flag, the resolved
+ * config's `detail`, the verb's own `disclosure.default`, and finally the
+ * built-in `"standard"`. Every source is validated upstream (the flag by
+ * `readDetail`, the config field by `z.enum` at load, a spec default by the
+ * pack grammar), so the fall-back here is a last belt against a source added
+ * later without validation — output never fails on disclosure.
+ */
+import { DEFAULT_DETAIL_LEVEL, DETAIL_LEVELS, } from "../../constants.js";
+export { DETAIL_LEVELS };
+/** Type guard: is a string one of the recognized detail levels? */
+function isDetailLevel(value) {
+    return DETAIL_LEVELS.includes(value);
+}
+/**
+ * Resolve the effective disclosure level from its ordered sources.
+ *
+ * @param sources - Candidate levels, applied most-specific first.
+ * @param sources.flag - The explicit `--detail` value, if any.
+ * @param sources.config - The resolved config's `detail`, if any.
+ * @param sources.specDefault - The verb's `disclosure.default`, if any.
+ * @returns The first recognized level, or `"standard"` when none matches.
+ */
+export function resolveDetail(sources) {
+    const candidate = sources.flag ??
+        sources.config ??
+        sources.specDefault ??
+        DEFAULT_DETAIL_LEVEL;
+    return isDetailLevel(candidate) ? candidate : DEFAULT_DETAIL_LEVEL;
+}
+//# sourceMappingURL=disclosure.js.map

package/dist/src/kernel/render/disclosure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disclosure.js","sourceRoot":"","sources":["../../../../src/kernel/render/disclosure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,oBAAoB,EACpB,aAAa,GAEd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,mEAAmE;AACnE,SAAS,aAAa,CAAC,KAAa;IAClC,OAAQ,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAI7B;IACC,MAAM,SAAS,GACb,OAAO,CAAC,IAAI;QACZ,OAAO,CAAC,MAAM;QACd,OAAO,CAAC,WAAW;QACnB,oBAAoB,CAAC;IACvB,OAAO,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC;AACrE,CAAC"}

package/dist/src/kernel/render/envelope.js

@@ -0,0 +1,30 @@
+/**
+ * The machine-output envelope (D3, D4).
+ *
+ * Both projectors emit the same two shapes: `{ ok: true, data, meta }` for a
+ * success and `{ ok: false, error }` for a failure. The CLI writes them to
+ * stdout under `--format json`; the MCP projector returns them as tool
+ * content. Building both here — from one `successEnvelope` / `errorEnvelope`
+ * pair — is what makes CLI-JSON and MCP output provably identical.
+ */
+import { serializeError } from "../error/index.js";
+/**
+ * Wrap already-JSON-safe data in the success envelope.
+ *
+ * @param data - The verb's data projection (JSON-safe).
+ * @param meta - Envelope metadata (e.g. plan-first flags); defaults to `{}`.
+ * @returns The `{ ok: true, data, meta }` envelope.
+ */
+export function successEnvelope(data, meta = {}) {
+    return { ok: true, data, meta };
+}
+/**
+ * Wrap a {@link PragmaError} in the failure envelope.
+ *
+ * @param error - The structured error to serialize.
+ * @returns The `{ ok: false, error }` envelope.
+ */
+export function errorEnvelope(error) {
+    return { ok: false, error: serializeError(error) };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/kernel/render/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../../src/kernel/render/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAenD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAa,EACb,OAAgC,EAAE;IAElC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAkB;IAC9C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;AACrD,CAAC"}