wingfoil 0.2.2 → 0.3.0

package/dist/mcp/prompt.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.roleSessionPromptName = roleSessionPromptName;
+exports.promptRequestError = promptRequestError;
+exports.buildSessionContext = buildSessionContext;
 exports.registerRolePrompts = registerRolePrompts;
 /**
  * The role-scoped MCP **Prompts** channel — `{role}-session` prompts that embed the role's assigned
@@ -19,7 +21,7 @@ exports.registerRolePrompts = registerRolePrompts;
  * files and returns text. There is no code path in this module that writes, and it registers no Tool —
  * so Prompts cannot become the agent write path REQ-SEC-05 reserves for validated Tools
  * (`test/mcp/role-prompts.test.ts` asserts both: files byte-for-byte unchanged after a round trip, and
- * `tools/list` still unroutable on a Prompts-only server).
+ * no Tools channel declared on a Prompts-only server).
  *
  * **Nothing is re-implemented here.** Role catalogue via `loadDnaYaml`, bindings via `loadRolesYaml`,
  * directive files via `loadDirectives`, and the role → directive resolution itself via
@@ -33,7 +35,9 @@ exports.registerRolePrompts = registerRolePrompts;
 const path_1 = require("path");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const core_1 = require("../core");
+const error_details_1 = require("../core/error-details");
 const storage_1 = require("../storage");
+const read_only_1 = require("./read-only");
 /** spec-004 §3.1's prompt-name suffix: one prompt per role, named `{role}-session`. Module-local —
  * {@link roleSessionPromptName} is the only naming API this channel exposes. */
 const ROLE_PROMPT_NAME_SUFFIX = '-session';
@@ -46,8 +50,9 @@ function roleSessionPromptName(role) {
     return `${role}${ROLE_PROMPT_NAME_SUFFIX}`;
 }
 /**
- * A `prompts/get` refusal whose JSON-RPC error carries `message` **verbatim** with code `InvalidParams`
- * (-32602, the code the MCP SDK itself uses for an unknown prompt name).
+ * A request refusal — of `prompts/get`, or of the session Resource's read (`./session-resource.ts`, task-236) —
+ * whose JSON-RPC error carries `message` **verbatim** with code `InvalidParams` (-32602, the code the MCP SDK
+ * itself uses for an unknown prompt name or resource).
  *
  * Deliberately a plain `Error` with a `code`, not the SDK's `McpError`: `McpError`'s constructor
  * prefixes its own message with `MCP error <code>: `, and the SDK serializes `error.message` as-is, so a
@@ -56,6 +61,82 @@ function roleSessionPromptName(role) {
 function promptRequestError(message) {
     return Object.assign(new Error(message), { code: types_js_1.ErrorCode.InvalidParams });
 }
+/** {@link promptRequestError} carrying `details` as `error.data.details` when there are any (spec-004 §3.4). */
+function promptRequestErrorWithDetails(message, details) {
+    const error = promptRequestError(message);
+    return details.length > 0 ? Object.assign(error, { data: { details } }) : error;
+}
+/**
+ * The two optional arguments of every `{role}-session` Prompt (task-195, `spec-016` §2.4, approver
+ * ruling R18, spec-004 §3.1): given together, they turn the Prompt into the carrier of the `spec-012` §7
+ * execution context for `(role, element, state)`; given neither, the Prompt is the role header and
+ * directive blocks it always was.
+ */
+const ROLE_PROMPT_ARGUMENTS = [
+    {
+        name: 'element',
+        description: "the Memory element to build the execution context for, as <type>:<id> (e.g. task:task-042-foo); given together with 'state'",
+        required: false,
+    },
+    {
+        name: 'state',
+        description: "the commit the execution context is read at (a sha, as agent execute passes it); given together with 'element'",
+        required: false,
+    },
+];
+const ROLE_PROMPT_ARGUMENT_NAMES = ROLE_PROMPT_ARGUMENTS.map((argument) => argument.name);
+/**
+ * The details of a context refusal that is a failed read: the issues `errorDetails` selects, then the
+ * `details.cause` of an absent pillar file (`assembleExecutionContext`), which no `issues` carries.
+ */
+function contextRefusalDetails(error) {
+    const cause = error.details?.cause;
+    return [...(0, error_details_1.errorDetails)(error), ...(typeof cause === 'string' ? [{ detail: cause }] : [])];
+}
+/**
+ * The execution context for `role`, `element` and `state` (task-195, spec-004 §3.2): `assembleExecutionContext`'s
+ * §7 payload, as returned — never re-serialized, and never indexed by its body markers (`bug-265`). `state` is
+ * resolved once, here, and the builder reads everything at that sha, so neither a later commit nor an uncommitted
+ * edit changes the answer. ONE builder for both carriers: the `{role}-session` Prompt wraps it in `messages`
+ * ({@link buildContextPrompt}), the session Resource in `contents` (`./session-resource.ts`, task-236), so the two
+ * answer the same bytes for the same arguments.
+ *
+ * The diagnostics: the directive-resolution warnings (`spec-012` §5.1 order), then the builder's notes (§3 stage
+ * order), then the `W_MEMORY_UNREADABLE` lines of the files the scan left out (path order, task-171).
+ *
+ * Refusals (spec-004 §3.4): a `state` that is not a commit and an element the commit does not hold are request
+ * errors, `-32602` — the latter with the unreadable files as `error.data.details`, so a subject that does not parse
+ * is not reported as merely absent. Every other refusal is about the repository (an archived subject, one in a
+ * newer `format:`, a missing pillar file) and is a failed read, as a failed Resource read is: the core message with
+ * its details.
+ */
+function buildSessionContext(root, role, element, state) {
+    let sha;
+    try {
+        sha = (0, core_1.resolveRevision)(root, state);
+    }
+    catch (error) {
+        if (error instanceof core_1.RevisionError)
+            throw promptRequestError(error.message);
+        throw error;
+    }
+    const result = (0, core_1.assembleExecutionContext)(root, { role, element, stateRef: sha });
+    if (!result.ok) {
+        const { error } = result;
+        if (error.code === 'NOT_FOUND') {
+            const unreadable = error.details?.unreadable;
+            throw promptRequestErrorWithDetails(error.message, (0, read_only_1.warningDetails)(Array.isArray(unreadable) ? unreadable : []));
+        }
+        throw (0, read_only_1.readRefusalError)(error.message, contextRefusalDetails(error));
+    }
+    const { payload, context, notes } = result.value;
+    return { text: payload, warnings: [...context.warnings, ...notes, ...(result.warnings ?? [])] };
+}
+/** The `prompts/get` result for `role` with `element` and `state`: one `user` message, the {@link buildSessionContext} text. */
+function buildContextPrompt(root, role, element, state) {
+    const { text, warnings } = buildSessionContext(root, role, element, state);
+    return (0, read_only_1.withWarnings)({ messages: [{ role: 'user', content: { type: 'text', text } }] }, warnings);
+}
 /**
  * The P5.2.2 undefined-role refusal, verbatim from `p5-interaction/P5.2.2-mcp-prompts.feature`
  * (Scenario "Error - requesting a prompt for an undefined role"): `no prompt for undefined role '<role>'`.
@@ -76,10 +157,48 @@ function undefinedRolePromptError(role) {
 function readDirectiveBody(root, file) {
     return (0, storage_1.splitFrontmatter)((0, storage_1.readDocument)((0, path_1.join)(root, storage_1.WINGFOIL_DIR, file.path))).body.trim();
 }
+/** An ATX heading line: up to three spaces of indent, one to six `#`, then a space, a tab or the end. */
+const ATX_HEADING = /^( {0,3})(#{1,6})(?=[ \t]|$)/;
+/** A code-fence line: up to three spaces of indent, then three or more backticks or tildes. */
+const CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
+/** How many levels a directive body's headings are pushed down inside a prompt (`dl-039` headings 1). */
+const EMBEDDED_HEADING_DEMOTION = 2;
+/**
+ * Push every heading of a directive `body` down {@link EMBEDDED_HEADING_DEMOTION} levels, capped at H6
+ * (`dl-039` headings 1, spec-004 §3.2). A directive file opens with its own H1, so embedded verbatim
+ * under a `## Directive:` block it outranked the block holding it, and every directive after the first
+ * read, structurally, as a new top-level section beside `# Role:`. Demoted, the body's H1 becomes an H3
+ * under its H2 block, and the prompt's outline matches its nesting.
+ *
+ * Only ATX headings (`#` … `######`) are rewritten. A line inside a fenced code block (``` or ~~~,
+ * closed by a fence of the same character at least as long) is code, not outline, and is left as
+ * written — a `# comment` in a shell example stays one. Every other byte is unchanged.
+ */
+function demoteHeadings(body) {
+    let fence = null;
+    return body
+        .split('\n')
+        .map((line) => {
+        const fenceMatch = CODE_FENCE.exec(line);
+        if (fence !== null) {
+            const closing = fenceMatch?.[1];
+            if (closing !== undefined && closing[0] === fence[0] && closing.length >= fence.length && line.trim() === closing) {
+                fence = null;
+            }
+            return line;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1];
+            return line;
+        }
+        return line.replace(ATX_HEADING, (_whole, indent, hashes) => `${indent}${'#'.repeat(Math.min(6, hashes.length + EMBEDDED_HEADING_DEMOTION))}`);
+    })
+        .join('\n');
+}
 /**
  * Compose the prompt text for `role` from its already-resolved directives — spec-004 §3.2's shape: a
  * `# Role: {role}` header followed by one `## Directive: {id}` block per directive, each carrying that
- * directive's full body.
+ * directive's full body with its headings demoted two levels ({@link demoteHeadings}).
  *
  * The heading uses `frontmatter.id`, not `name`: spec-004 §3.2's own example headings read
  * `## Directive: code-quality` / `security-secrets`, which are the `id` values of the real directive
@@ -87,13 +206,13 @@ function readDirectiveBody(root, file) {
  * by id.
  *
  * Block order is `resolveRoleDirectives`' — deduplicated by id and sorted id-ascending per
- * `spec-012-context-loader-relevance-filtering` §5 / REQ-SYS-07 — rather than the "own directives,
- * then globals" grouping spec-004 §3.2's illustrative example happens to print. §3.2 states the
- * resolution itself as a *set* union (`roles.yaml[R].directives` ∪ `global`), which fixes membership,
- * not sequence; an explicit total order is what makes two runs byte-identical.
+ * `spec-012-context-loader-relevance-filtering` §5 / REQ-SYS-07. spec-004 §3.2 states the resolution
+ * as a *set* (`roles.yaml[R].directives` ∪ `global`) and the order as id-ascending (`dl-039` ordering
+ * 1). The choice rests on reusing the one resolver, which keeps REQ-INT-02's "100%" and REQ-STATE-05's
+ * disjointness a single guarantee; an own-then-global grouping would be equally deterministic.
  */
 function composeRolePromptText(role, directives) {
-    const blocks = directives.map(({ id, body }) => `## Directive: ${id}\n${body}`);
+    const blocks = directives.map(({ id, body }) => `## Directive: ${id}\n${demoteHeadings(body)}`);
     return [`# Role: ${role}`, ...blocks].join('\n\n');
 }
 /**
@@ -110,55 +229,45 @@ function buildRolePrompt(root, role) {
     const { directives } = (0, core_1.resolveRoleDirectives)((0, core_1.loadDirectives)(root), (0, core_1.loadRolesYaml)(root), role);
     const text = composeRolePromptText(role, directives.map((file) => ({ id: file.frontmatter.id, body: readDirectiveBody(root, file) })));
     // MCP's `PromptMessage.role` is the two-value enum `"user" | "assistant"` (the SDK's
-    // `PromptMessageSchema`), so spec-004 §3.2's illustrative `role: "system"` is not representable on
-    // this protocol by any conformant server; `user` is the only wire role that can deliver
-    // instructional content. Open as `dl-039-spec-004-prompt-example-corrections`.
+    // `PromptMessageSchema`); `user` is the only wire role that can deliver instructional content.
+    // spec-004 §3.2's example says so since `dl-039` (role 1) — it used to show an unrepresentable
+    // `role: "system"`.
     return { messages: [{ role: 'user', content: { type: 'text', text } }] };
 }
 /**
- * The DNA role catalogue as `dna.yaml` declares it **now**, in declaration order. Read per request (see
- * {@link registerRolePrompts}); a missing or invalid `dna.yaml` throws the loader's own error, which the
- * SDK returns to the client as that request's error — the same way `wingfoil://dna` reports it.
- */
-function loadRoleNames(root) {
-    return (0, core_1.loadDnaYaml)(root).team.roles.map(({ name }) => name);
-}
-/**
- * Register the role-scoped Prompts channel: one `{role}-session` Prompt per role in `dna.yaml`'s
- * `team.roles` catalogue (spec-004 §3.1), each embedding that role's directives (§3.2), and a refusal
- * for a session prompt naming a role DNA does not declare (P5.2.2's undefined-role scenario).
- *
- * **Nothing is read here — every read happens per request** (task-058 second pass, rejection `ff13321`).
- * spec-014 §2 requires `createMcpServer` to perform "no I/O at construction time beyond wiring
- * handlers", so the DNA role catalogue is loaded inside the `prompts/list` / `prompts/get` handlers,
- * next to the per-request directive resolution spec-004 §3.2 already mandated (REQ-INT-02's "a newly
- * assigned directive appears on the next session start"). Two consequences, both deliberate:
+ * Register the role-scoped Prompts channel: one `{role}-session` Prompt per role in `options.roles`
+ * (spec-004 §3.1), each embedding that role's directives (§3.2), and the refusals of §3.4.
  *
- * - `wingfoil mcp` starts in a git root with no `.wingfoil/dna.yaml` (e.g. a repository that has not
- *   run `wingfoil init`) exactly as the Resources channel always has; the missing DNA surfaces as the
- *   error of each Prompts request instead of aborting the process start.
- * - spec-004 §3.1's "fixed set derived from DNA at server start" is served as the DNA role set **at
- *   request time**: a role added to `dna.yaml` while the server runs is listed on the next
- *   `prompts/list`. That tension between spec-014 §2 and spec-004 §3.1 is open for the approver.
+ * **The role set is fixed; the directives are not** (`dl-049` (b), task-174). `options.roles` is the
+ * DNA role set `wingfoil mcp` read once, in its pre-flight, before the server started; it is copied
+ * here and never re-read, so `prompts/list` and the undefined-role check read nothing, and a role added
+ * to `dna.yaml` while the server runs is served after a restart. The Prompts capability is therefore
+ * declared without `listChanged`: the list cannot change during a session. What a Prompt *embeds* is
+ * still resolved per request — `roles.yaml` and the directive files are read on every `prompts/get`
+ * (spec-004 §3.2, REQ-INT-02's "a newly assigned directive appears on the next session start"). This
+ * function itself reads nothing, so `createMcpServer` keeps spec-014 §2's "no I/O at construction".
  *
  * **Why the low-level handlers, not `McpServer.registerPrompt`.** The high-level API answers an
  * unregistered name with its own `Prompt <name> not found` before any WingFoil code runs, so the BDD's
- * `no prompt for undefined role 'wizard'` cannot be expressed through it (and it would need the role
- * set at registration time). This function therefore owns `prompts/list` and `prompts/get` on
- * `server.server` — the same pattern `./read-only.ts`'s `registerWriteRefusalHandler` uses — and a
- * later `registerPrompt` on the same server fails loudly ("A request handler for prompts/list already
- * exists") instead of being silently shadowed. A requested name that is not `{role}-session`-shaped
- * keeps the SDK-equivalent `Prompt <name> not found` wording: it names no role, so it is not an
- * undefined-role request, and it is answered without reading anything.
+ * `no prompt for undefined role 'wizard'` cannot be expressed through it. This function therefore owns
+ * `prompts/list` and `prompts/get` on `server.server` — the same pattern `./read-only.ts`'s
+ * `registerWriteRefusalHandler` uses — and a later `registerPrompt` on the same server fails loudly ("A
+ * request handler for prompts/list already exists") instead of being silently shadowed. spec-004 §3.4's
+ * two refusals, both `-32602`: a `{role}-session` name whose role is not in the set is `no prompt for
+ * undefined role '<role>'`; a name that is not `{role}-session`-shaped names no role and keeps the SDK's
+ * `Prompt <name> not found`. A read that fails while a Prompt is built carries the loader's details as
+ * `error.data.details`, as a failed Resource read does (`withRefusalDetails`, `bug-184`).
  *
  * Call before the server is connected (MCP capabilities cannot be registered after connecting).
  */
 function registerRolePrompts(server, options) {
+    const roles = [...options.roles];
     server.server.registerCapabilities({ prompts: {} });
     server.server.setRequestHandler(types_js_1.ListPromptsRequestSchema, () => ({
-        prompts: loadRoleNames(options.resolveRoot()).map((role) => ({
+        prompts: roles.map((role) => ({
             name: roleSessionPromptName(role),
-            description: `session instructions for the '${role}' role, embedding its assigned directives (read-only)`,
+            description: `session instructions for the '${role}' role, embedding its assigned directives (read-only); with element and state, the execution context for that element at that commit`,
+            arguments: ROLE_PROMPT_ARGUMENTS.map((argument) => ({ ...argument })),
         })),
     }));
     server.server.setRequestHandler(types_js_1.GetPromptRequestSchema, (request) => {
@@ -167,10 +276,30 @@ function registerRolePrompts(server, options) {
             throw promptRequestError(`Prompt ${name} not found`);
         }
         const role = name.slice(0, -ROLE_PROMPT_NAME_SUFFIX.length);
-        const root = options.resolveRoot();
-        if (!loadRoleNames(root).includes(role))
+        if (!roles.includes(role))
             throw undefinedRolePromptError(role);
-        return buildRolePrompt(root, role);
+        // task-195: the two optional arguments (spec-004 §3.1); an unknown name is refused rather than
+        // ignored, so a misspelt `State` never falls back to the argument-less Prompt. Sorted: the first
+        // unknown name reported does not depend on the client's key order (REQ-SYS-07).
+        const args = request.params.arguments ?? {};
+        const unknown = Object.keys(args).sort().find((key) => !ROLE_PROMPT_ARGUMENT_NAMES.includes(key));
+        if (unknown !== undefined) {
+            throw promptRequestError(`unknown prompt argument '${unknown}': '${name}' takes only 'element' and 'state'`);
+        }
+        // An empty string is an absent argument (spec-004 §3.1): a client that submits every declared
+        // field sends `""` for the ones its user left blank.
+        const element = args.element === '' ? undefined : args.element;
+        const state = args.state === '' ? undefined : args.state;
+        if (element === undefined && state === undefined) {
+            return (0, read_only_1.withRefusalDetails)(() => buildRolePrompt(options.resolveRoot(), role));
+        }
+        if (element === undefined || state === undefined) {
+            throw promptRequestError(`prompt arguments 'element' and 'state' go together: '${element === undefined ? 'element' : 'state'}' is missing`);
+        }
+        const ref = (0, core_1.parseElementRef)(element);
+        if (!ref.ok)
+            throw promptRequestError(ref.error.message);
+        return (0, read_only_1.withRefusalDetails)(() => buildContextPrompt(options.resolveRoot(), role, ref.value, state));
     });
 }
 //# sourceMappingURL=prompt.js.map

package/dist/mcp/prompt.js.map

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

package/dist/mcp/read-only.d.ts

@@ -1,4 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ErrorDetail } from '../core/error-details';
+import type { CoreResult } from '../core/types';
 /** spec-004 §2.3's exact, verbatim write-refusal string. */
 export declare const WRITE_REFUSAL_MESSAGE = "resources are read-only";
 /**
@@ -16,6 +18,33 @@ export declare function refuseIfWriteIntent(meta: Record<string, unknown> | unde
 /** spec-004 §2.2's "resource not found" shape — distinct wording from the write refusal above, per
  * the BDD scenario (`P5.2.1-mcp-resources.feature`) `resource not found: {identifier}` format. */
 export declare function resourceNotFoundError(identifier: string): Error;
+/**
+ * A failed read's JSON-RPC error: `message` as its text and, when there are any, the refusal's
+ * operator-facing `details` as `error.data.details` (spec-004 §4.3 item 4; task-130, `dl-055` option 1).
+ * The SDK forwards an `Error`'s `data` as the JSON-RPC `error.data`. No details, no `data` — the shape
+ * a refusal always had. Shared by the core-derived Resources (`./registrar.ts`) and the bespoke ones.
+ */
+export declare function readRefusalError(message: string, details: readonly ErrorDetail[]): Error;
+/**
+ * Run a Resource or Prompt read, and give a loader refusal it throws the same details the CLI prints
+ * (task-174, `bug-184`). The handlers registered here call the pillar loaders directly, not through a
+ * `CoreOperation`, so a refusal reached the client without the `error.data` `./registrar.ts` gives
+ * one. The thrown error is mapped once, by core's own `coreErrorOf`; one that carries details is
+ * re-thrown as {@link readRefusalError} with its message unchanged, and anything else — a refusal with
+ * no details, a write refusal, a "resource not found", a programmer bug — is re-thrown as it was.
+ */
+export declare function withRefusalDetails<T>(read: () => T | Promise<T>): Promise<T>;
+/**
+ * `result` with the read's diagnostics as a top-level `warnings` array (task-195, `bug-231`,
+ * spec-004 §2.2 / §3.2): the read-only twin of a Tool's `structuredContent.warnings` (§4.3 item 5).
+ * MCP's result objects are loose (the SDK's `ResultSchema` is a `looseObject`), so the field reaches
+ * the client beside `contents` or `messages`. No warnings, no field — the shape a read always had.
+ */
+export declare function withWarnings<T extends object>(result: T, warnings: readonly string[]): T & {
+    warnings?: string[];
+};
+/** One `error.data.details` entry per diagnostic line (`{detail}`), as {@link readRefusalError} carries them. */
+export declare function warningDetails(warnings: readonly string[]): ErrorDetail[];
 /**
  * The `ReadResourceResult` shape every JSON-bodied Resource in `memory-resource.ts` (collection
  * listing), `dna-resource.ts`, and `workflow-resource.ts` returns — one `contents[]` entry,
@@ -31,6 +60,16 @@ export declare function jsonResourceResult(uri: URL, value: unknown): {
         text: string;
     }];
 };
+/**
+ * A core operation's result as a JSON-bodied Resource read (task-239): its value as {@link jsonResourceResult}'s
+ * `text` — the bytes the CLI's `--format json` prints, without the final newline — with its warnings beside
+ * `contents` ({@link withWarnings}); a `CoreResult.error` is thrown as the failed read
+ * {@link readRefusalError} builds, with the CLI's message and details (spec-004 §4.3 item 4). The registrar's
+ * derived Resources (`./registrar.ts`) shape theirs the same way.
+ */
+export declare function coreResultResource(uri: URL, result: CoreResult<unknown>): ReturnType<typeof jsonResourceResult> & {
+    warnings?: string[];
+};
 /**
  * Install the `resources/write` refusal (see module doc, case 1). MCP's own protocol does not define
  * `resources/write` at all — no client capability or built-in handler exists for it — so this method

package/dist/mcp/read-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../src/mcp/read-only.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAInF;AAED;kGACkG;AAClG,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAU5H;AAUD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAInE"}
+{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../src/mcp/read-only.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAInF;AAED;kGACkG;AAClG,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,KAAK,CAExF;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CASlF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAElH;AAED,iHAAiH;AACjH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,EAAE,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAU5H;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAGzI;AAUD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAInE"}

package/dist/mcp/read-only.js

@@ -3,7 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WRITE_INTENT_META_KEY = exports.WRITE_REFUSAL_MESSAGE = void 0;
 exports.refuseIfWriteIntent = refuseIfWriteIntent;
 exports.resourceNotFoundError = resourceNotFoundError;
+exports.readRefusalError = readRefusalError;
+exports.withRefusalDetails = withRefusalDetails;
+exports.withWarnings = withWarnings;
+exports.warningDetails = warningDetails;
 exports.jsonResourceResult = jsonResourceResult;
+exports.coreResultResource = coreResultResource;
 exports.registerWriteRefusalHandler = registerWriteRefusalHandler;
 /**
  * Shared conventions for every bespoke Resource this task registers (`memory-resource`,
@@ -29,6 +34,8 @@ exports.registerWriteRefusalHandler = registerWriteRefusalHandler;
  *    bespoke read handler before it does anything else.
  */
 const zod_1 = require("zod");
+const core_1 = require("../core");
+const error_details_1 = require("../core/error-details");
 /** spec-004 §2.3's exact, verbatim write-refusal string. */
 exports.WRITE_REFUSAL_MESSAGE = 'resources are read-only';
 /**
@@ -52,6 +59,48 @@ function refuseIfWriteIntent(meta) {
 function resourceNotFoundError(identifier) {
     return new Error(`resource not found: ${identifier}`);
 }
+/**
+ * A failed read's JSON-RPC error: `message` as its text and, when there are any, the refusal's
+ * operator-facing `details` as `error.data.details` (spec-004 §4.3 item 4; task-130, `dl-055` option 1).
+ * The SDK forwards an `Error`'s `data` as the JSON-RPC `error.data`. No details, no `data` — the shape
+ * a refusal always had. Shared by the core-derived Resources (`./registrar.ts`) and the bespoke ones.
+ */
+function readRefusalError(message, details) {
+    return details.length > 0 ? Object.assign(new Error(message), { data: { details } }) : new Error(message);
+}
+/**
+ * Run a Resource or Prompt read, and give a loader refusal it throws the same details the CLI prints
+ * (task-174, `bug-184`). The handlers registered here call the pillar loaders directly, not through a
+ * `CoreOperation`, so a refusal reached the client without the `error.data` `./registrar.ts` gives
+ * one. The thrown error is mapped once, by core's own `coreErrorOf`; one that carries details is
+ * re-thrown as {@link readRefusalError} with its message unchanged, and anything else — a refusal with
+ * no details, a write refusal, a "resource not found", a programmer bug — is re-thrown as it was.
+ */
+async function withRefusalDetails(read) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        const refusal = (0, core_1.coreErrorOf)(error);
+        const details = refusal === null ? [] : (0, error_details_1.errorDetails)(refusal);
+        if (refusal === null || details.length === 0)
+            throw error;
+        throw readRefusalError(refusal.message, details);
+    }
+}
+/**
+ * `result` with the read's diagnostics as a top-level `warnings` array (task-195, `bug-231`,
+ * spec-004 §2.2 / §3.2): the read-only twin of a Tool's `structuredContent.warnings` (§4.3 item 5).
+ * MCP's result objects are loose (the SDK's `ResultSchema` is a `looseObject`), so the field reaches
+ * the client beside `contents` or `messages`. No warnings, no field — the shape a read always had.
+ */
+function withWarnings(result, warnings) {
+    return warnings.length > 0 ? { ...result, warnings: [...warnings] } : result;
+}
+/** One `error.data.details` entry per diagnostic line (`{detail}`), as {@link readRefusalError} carries them. */
+function warningDetails(warnings) {
+    return warnings.map((detail) => ({ detail }));
+}
 /**
  * The `ReadResourceResult` shape every JSON-bodied Resource in `memory-resource.ts` (collection
  * listing), `dna-resource.ts`, and `workflow-resource.ts` returns — one `contents[]` entry,
@@ -71,6 +120,18 @@ function jsonResourceResult(uri, value) {
         ],
     };
 }
+/**
+ * A core operation's result as a JSON-bodied Resource read (task-239): its value as {@link jsonResourceResult}'s
+ * `text` — the bytes the CLI's `--format json` prints, without the final newline — with its warnings beside
+ * `contents` ({@link withWarnings}); a `CoreResult.error` is thrown as the failed read
+ * {@link readRefusalError} builds, with the CLI's message and details (spec-004 §4.3 item 4). The registrar's
+ * derived Resources (`./registrar.ts`) shape theirs the same way.
+ */
+function coreResultResource(uri, result) {
+    if (!result.ok)
+        throw readRefusalError(result.error.message, (0, error_details_1.errorDetails)(result.error));
+    return withWarnings(jsonResourceResult(uri, result.value), result.warnings ?? []);
+}
 /** The raw JSON-RPC shape of an (unsupported) `resources/write` request — just enough to extract the
  * method literal `setRequestHandler` needs; `params` is never inspected, since every call is refused
  * unconditionally regardless of its payload. */

package/dist/mcp/read-only.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-only.js","sourceRoot":"","sources":["../../src/mcp/read-only.ts"],"names":[],"mappings":";;;AA0CA,kDAIC;AAID,sDAEC;AAUD,gDAUC;AAiBD,kEAIC;AA7FD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6BAAwB;AAIxB,4DAA4D;AAC/C,QAAA,qBAAqB,GAAG,yBAAyB,CAAC;AAE/D;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,uBAAuB,CAAC;AAE7D;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,IAAyC;IAC3E,IAAI,IAAI,IAAI,6BAAqB,IAAI,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,6BAAqB,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;kGACkG;AAClG,SAAgB,qBAAqB,CAAC,UAAkB;IACtD,OAAO,IAAI,KAAK,CAAC,uBAAuB,UAAU,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,GAAQ,EAAE,KAAc;IACzD,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE;gBACnB,QAAQ,EAAE,kBAAkB;gBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;aAC5B;SACF;KACF,CAAC;AACJ,CAAC;AAED;;gDAEgD;AAChD,MAAM,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,OAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;IACpC,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,SAAgB,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,IAAI,KAAK,CAAC,6BAAqB,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"read-only.js","sourceRoot":"","sources":["../../src/mcp/read-only.ts"],"names":[],"mappings":"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"}

package/dist/mcp/registrar.d.ts

@@ -49,6 +49,16 @@ export declare function deriveMcpResourceUri(moduleName: string, verb: string):
  * response (spec-004 §4.3's "rejected identically to the CLI path") or, for a Resource read (which
  * has no `isError` flag in the MCP protocol), a thrown error surfaced as a protocol-level read
  * failure (spec-004 §2.2's "resource not found"-style refusal, generalized to any read failure).
+ * Either way the error's operator-facing details (`../core/error-details.ts`) travel with it — as the
+ * read error's JSON-RPC `error.data.details`, or as the tool result's `structuredContent` (task-130).
+ * A successful Tool result carries the operation's `CoreResult.warnings`, when it has any, as
+ * `structuredContent: {value, warnings}` (task-169). A successful Resource read carries them as a
+ * top-level `warnings` array beside `contents` (task-195, `bug-231`: since task-171 a read-only scan does
+ * report the documents it left out). Note that the shipped
+ * `wingfoil mcp` server (`./server.ts`) does not call this function and registers no Tools (P5.2.3,
+ * v0.4), so the Tool warning field is reachable only where this registrar is used; when Tools ship,
+ * `directive.assign` and the four `dna` write Tools (task-193) also need `force` as a Tool input
+ * (`spec-004` §4.3).
  */
 export declare function registerCoreModules(server: McpServer, modules: readonly CoreModule[], options: RegisterCoreModulesOptions): void;
 //# sourceMappingURL=registrar.d.ts.map

package/dist/mcp/registrar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/mcp/registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGlE,wIAAwI;AACxI,MAAM,WAAW,0BAA0B;IACzC,+GAA+G;IAC/G,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,CAAC;IACnC,iHAAiH;IACjH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI,CA+CN"}
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/mcp/registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKlE,wIAAwI;AACxI,MAAM,WAAW,0BAA0B;IACzC,+GAA+G;IAC/G,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,CAAC;IACnC,iHAAiH;IACjH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI,CA0EN"}