@unbrained/pm-cli 2026.8.24 → 2026.8.26

package/dist/sdk/mcp/transport.js

@@ -0,0 +1,261 @@
+/**
+ * @module sdk/mcp/transport
+ *
+ * Implements MCP 2026-07-28 Streamable HTTP header encoding, schema-derived
+ * custom header extraction, and body/header parity validation.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5ffe7128-0fbb-59af-89ef-74d5d799a00d")}catch(e){}}();
+import { PM_MCP_ERROR_CODES, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, isMcpRecord, resolveMcpRequestContext, } from "./protocol.js";
+const BASE64_SENTINEL_PATTERN = /^=\?base64\?([A-Za-z0-9+/]*={0,2})\?=$/u;
+const HEADER_NAME_TOKEN_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+const PLAIN_HEADER_VALUE_PATTERN = /^[\t\x20-\x7E]*$/u;
+const REQUIRED_NAME_METHODS = new Set([
+    "prompts/get",
+    "resources/read",
+    "tools/call",
+]);
+function normalizedHeaders(headers) {
+    const normalized = new Map();
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const entry = typeof value === "string" ? value : value.join(", ");
+        normalized.set(name.toLowerCase(), entry);
+    }
+    return normalized;
+}
+function failHeader(message, header) {
+    throw new PmMcpProtocolError(message, PM_MCP_ERROR_CODES.headerMismatch, {
+        header,
+    });
+}
+/** Encode a name or primitive parameter into the protocol's safe header form. */
+export function encodeMcpHttpHeaderValue(value) {
+    const serialized = typeof value === "boolean" ? String(value).toLowerCase() : String(value);
+    if (serialized.length > 0 &&
+        serialized.trim() === serialized &&
+        PLAIN_HEADER_VALUE_PATTERN.test(serialized) &&
+        !BASE64_SENTINEL_PATTERN.test(serialized)) {
+        return serialized;
+    }
+    return `=?base64?${Buffer.from(serialized, "utf8").toString("base64")}?=`;
+}
+/** Decode and validate a mirrored MCP header value. */
+export function decodeMcpHttpHeaderValue(value, header) {
+    const sentinel = BASE64_SENTINEL_PATTERN.exec(value);
+    if (sentinel) {
+        const encoded = sentinel[1];
+        const decoded = Buffer.from(encoded, "base64");
+        if (decoded.toString("base64") !== encoded || decoded.length === 0) {
+            return failHeader("Malformed MCP Base64 header value", header);
+        }
+        return decoded.toString("utf8");
+    }
+    if (value.length === 0 ||
+        value.trim() !== value ||
+        !PLAIN_HEADER_VALUE_PATTERN.test(value)) {
+        return failHeader("Malformed MCP header value", header);
+    }
+    return value;
+}
+function containsHeaderAnnotation(value) {
+    if (Array.isArray(value))
+        return value.some(containsHeaderAnnotation);
+    if (!isMcpRecord(value))
+        return false;
+    return (Object.prototype.hasOwnProperty.call(value, "x-mcp-header") ||
+        Object.values(value).some(containsHeaderAnnotation));
+}
+/** Validate and normalize one schema-derived custom-header annotation. */
+function parseMcpHeaderAnnotation(propertySchema, propertyPath, names) {
+    const annotation = propertySchema["x-mcp-header"];
+    if (annotation === undefined)
+        return undefined;
+    const type = propertySchema.type;
+    if (typeof annotation !== "string" ||
+        !HEADER_NAME_TOKEN_PATTERN.test(annotation) ||
+        !["boolean", "integer", "string"].includes(String(type)) ||
+        names.has(annotation.toLowerCase())) {
+        throw new PmMcpProtocolError("Invalid MCP x-mcp-header annotation", PM_MCP_ERROR_CODES.invalidParams, { field: propertyPath.join("."), annotation });
+    }
+    names.add(annotation.toLowerCase());
+    return {
+        name: annotation,
+        path: propertyPath,
+        type: type,
+    };
+}
+/** Parse valid statically reachable custom-header annotations from a tool schema. */
+export function collectMcpHeaderAnnotations(schema) {
+    if (!isMcpRecord(schema)) {
+        throw new PmMcpProtocolError("Invalid MCP tool schema", PM_MCP_ERROR_CODES.invalidParams, { field: "inputSchema", expected: "object" });
+    }
+    const annotations = [];
+    const names = new Set();
+    const visitProperties = (node, path) => {
+        const properties = node.properties;
+        if (properties === undefined)
+            return;
+        if (!isMcpRecord(properties)) {
+            throw new PmMcpProtocolError("Invalid MCP tool schema properties", PM_MCP_ERROR_CODES.invalidParams, { field: "inputSchema.properties" });
+        }
+        for (const [property, propertySchema] of Object.entries(properties)) {
+            if (!isMcpRecord(propertySchema))
+                continue;
+            const propertyPath = [...path, property];
+            const annotation = parseMcpHeaderAnnotation(propertySchema, propertyPath, names);
+            if (annotation)
+                annotations.push(annotation);
+            for (const [keyword, nested] of Object.entries(propertySchema)) {
+                if (keyword !== "properties" &&
+                    keyword !== "x-mcp-header" &&
+                    containsHeaderAnnotation(nested)) {
+                    throw new PmMcpProtocolError("MCP x-mcp-header is not statically reachable", PM_MCP_ERROR_CODES.invalidParams, { field: propertyPath.join("."), keyword });
+                }
+            }
+            visitProperties(propertySchema, propertyPath);
+        }
+    };
+    for (const [keyword, nested] of Object.entries(schema)) {
+        if (keyword !== "properties" && containsHeaderAnnotation(nested)) {
+            throw new PmMcpProtocolError("MCP x-mcp-header is not statically reachable", PM_MCP_ERROR_CODES.invalidParams, { field: "inputSchema", keyword });
+        }
+    }
+    visitProperties(schema, []);
+    return annotations;
+}
+function valueAtPath(value, path) {
+    let current = value;
+    for (const part of path) {
+        if (!isMcpRecord(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function mirroredName(method, params) {
+    const value = method === "resources/read" ? params.uri : params.name;
+    return typeof value === "string" ? value : undefined;
+}
+function buildMcpCustomRequestHeaders(params, toolSchema) {
+    const argumentsValue = isMcpRecord(params.arguments) ? params.arguments : {};
+    const headers = {};
+    for (const annotation of collectMcpHeaderAnnotations(toolSchema)) {
+        const value = valueAtPath(argumentsValue, annotation.path);
+        if (value === undefined || value === null)
+            continue;
+        const valid = (annotation.type === "integer" &&
+            typeof value === "number" &&
+            Number.isSafeInteger(value)) ||
+            (annotation.type === "boolean" && typeof value === "boolean") ||
+            (annotation.type === "string" && typeof value === "string");
+        if (!valid) {
+            throw new PmMcpProtocolError("Invalid MCP custom header argument", PM_MCP_ERROR_CODES.invalidParams, { field: annotation.path.join("."), expected: annotation.type });
+        }
+        headers[`Mcp-Param-${annotation.name}`] = encodeMcpHttpHeaderValue(value);
+    }
+    return headers;
+}
+/** Build required Streamable HTTP headers for one modern client request. */
+export function buildMcpHttpRequestHeaders(input) {
+    const params = isMcpRecord(input.request.params)
+        ? input.request.params
+        : undefined;
+    const context = resolveMcpRequestContext(params);
+    const method = input.request.method;
+    if (typeof method !== "string" || method.length === 0) {
+        return failHeader("Missing MCP request method", "Mcp-Method");
+    }
+    const headers = {
+        Accept: "application/json, text/event-stream",
+        "Content-Type": "application/json",
+        "MCP-Protocol-Version": context.protocolVersion,
+        "Mcp-Method": method,
+    };
+    const name = mirroredName(method, params);
+    if (REQUIRED_NAME_METHODS.has(method)) {
+        if (name === undefined)
+            return failHeader("Missing MCP request name", "Mcp-Name");
+        headers["Mcp-Name"] = encodeMcpHttpHeaderValue(name);
+    }
+    if (method === "tools/call" && input.toolSchema !== undefined) {
+        Object.assign(headers, buildMcpCustomRequestHeaders(params, input.toolSchema));
+    }
+    return headers;
+}
+function validateMcpRequiredRequestHeaders(headers, request) {
+    const method = request.method;
+    if (typeof method !== "string" || method.length === 0) {
+        failHeader("Missing MCP request method", "Mcp-Method");
+    }
+    const params = isMcpRecord(request.params) ? request.params : undefined;
+    const expectedProtocol = resolveMcpRequestContext(params).protocolVersion;
+    if (headers.get("mcp-protocol-version") !== expectedProtocol) {
+        failHeader("MCP protocol header does not match request metadata", "MCP-Protocol-Version");
+    }
+    if (headers.get("mcp-method") !== method) {
+        failHeader("MCP method header does not match request body", "Mcp-Method");
+    }
+    if (REQUIRED_NAME_METHODS.has(method)) {
+        const headerName = headers.get("mcp-name");
+        const name = mirroredName(method, params);
+        if (headerName === undefined ||
+            name === undefined ||
+            decodeMcpHttpHeaderValue(headerName, "Mcp-Name") !== name) {
+            failHeader("MCP name header does not match request body", "Mcp-Name");
+        }
+    }
+    if (headers.has("last-event-id")) {
+        // The preceding match is an mcp-deprecation-negative-control: no resume/redelivery.
+        failHeader("MCP SSE resumability is not supported", "Last-Event-ID");
+    }
+}
+function customHeaderMatches(annotation, value, decoded) {
+    if (annotation.type === "integer") {
+        return (typeof value === "number" &&
+            Number.isSafeInteger(value) &&
+            Number(decoded) === value);
+    }
+    if (annotation.type === "boolean") {
+        return typeof value === "boolean" && decoded === String(value);
+    }
+    return typeof value === "string" && decoded === value;
+}
+function validateMcpCustomRequestHeaders(input) {
+    const argumentsValue = isMcpRecord(input.params.arguments)
+        ? input.params.arguments
+        : {};
+    for (const annotation of collectMcpHeaderAnnotations(input.toolSchema)) {
+        const value = valueAtPath(argumentsValue, annotation.path);
+        const header = `Mcp-Param-${annotation.name}`;
+        const mirrored = input.headers.get(header.toLowerCase());
+        if (value === undefined || value === null) {
+            if (mirrored !== undefined)
+                failHeader("Unexpected MCP parameter header", header);
+            continue;
+        }
+        if (mirrored === undefined)
+            failHeader("Missing MCP parameter header", header);
+        if (!customHeaderMatches(annotation, value, decodeMcpHttpHeaderValue(mirrored, header))) {
+            failHeader("MCP parameter header does not match request body", header);
+        }
+    }
+}
+/** Validate required Streamable HTTP headers against the JSON-RPC body. */
+export function validateMcpHttpRequestHeaders(input) {
+    const headers = normalizedHeaders(input.headers);
+    const method = typeof input.request.method === "string" ? input.request.method : "";
+    validateMcpRequiredRequestHeaders(headers, input.request);
+    if (method !== "tools/call" || input.toolSchema === undefined)
+        return;
+    validateMcpCustomRequestHeaders({
+        headers,
+        params: input.request.params,
+        toolSchema: input.toolSchema,
+    });
+}
+/** Required protocol version exposed for clients constructing headers manually. */
+export const PM_MCP_HTTP_PROTOCOL_VERSION = PM_MCP_PROTOCOL_VERSION;
+//# sourceMappingURL=transport.js.map
+//# debugId=5ffe7128-0fbb-59af-89ef-74d5d799a00d

package/dist/sdk/merge/driver.js

@@ -9,14 +9,16 @@
  * merge never corrupts tracker storage the way raw conflict markers do.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8d79e3a4-6104-5855-837f-69a041b87b27")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2c8046a5-06aa-58f8-b347-e757086082d1")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
+import { parseItemDocument } from "../../core/item/item-format.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
 import { nowIso } from "../../core/shared/time.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
@@ -122,10 +124,12 @@ export async function runMergeDriver(options, global) {
     }
     else if (artifact === "item") {
         const settings = await loadOptionalSettings(global);
+        const itemFormat = itemFormatForPath(options.itemPath ?? outputPath, settings);
+        const extensionFieldNames = collectRegisteredItemFieldNames(getActiveExtensionRegistrations());
         const itemMerge = mergeItemDocuments(baseRaw, oursRaw, theirsRaw, {
-            format: itemFormatForPath(options.itemPath ?? outputPath, settings),
+            format: itemFormat,
             schema: settings?.schema,
-            extensionFieldNames: collectRegisteredItemFieldNames(getActiveExtensionRegistrations()),
+            extensionFieldNames,
             preferred,
             conflictResolution: "stable_value_order",
         });
@@ -137,6 +141,19 @@ export async function runMergeDriver(options, global) {
             conflict_resolution: "stable_value_order",
         };
         if (options.itemPath !== undefined) {
+            const mergedDocument = parseItemDocument(merged, {
+                format: itemFormat,
+                schema: settings?.schema,
+                extensionFieldNames,
+            });
+            const mergedMetadata = mergedDocument.metadata;
+            const receiptFields = [
+                ...new Set([
+                    ...itemMerge.fields_from_theirs,
+                    ...itemMerge.union_fields,
+                    ...itemMerge.conflict_decisions.map((decision) => decision.field),
+                ]),
+            ];
             receiptInput = {
                 cwd: process.cwd(),
                 itemPath: options.itemPath,
@@ -144,6 +161,10 @@ export async function runMergeDriver(options, global) {
                 conflictResolution: "stable_value_order",
                 fieldsFromTheirs: itemMerge.fields_from_theirs,
                 unionFields: itemMerge.union_fields,
+                mergedFieldHashes: Object.fromEntries(receiptFields.map((field) => [
+                    field,
+                    sha256Hex(stableStringify(field === "body" ? mergedDocument.body : mergedMetadata[field])),
+                ])),
                 decisions: itemMerge.conflict_decisions,
             };
         }
@@ -187,4 +208,4 @@ export async function runMergeDriver(options, global) {
     };
 }
 //# sourceMappingURL=driver.js.map
-//# debugId=8d79e3a4-6104-5855-837f-69a041b87b27
+//# debugId=2c8046a5-06aa-58f8-b347-e757086082d1

package/dist/sdk/merge/receipt-file-boundary.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module sdk/merge/receipt-file-boundary
+ *
+ * Reads untrusted receipt candidates through a bounded, no-follow file
+ * boundary whose race and short-read behavior can be exercised directly.
+ */
+import { type Stats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+/** Minimal filesystem operations required by the receipt reader. */
+export interface ReceiptFileBoundary {
+    /** Inspect the path without following its final symbolic link. */
+    lstat(receiptPath: string): Promise<Stats>;
+    /** Open the candidate and return the handle used for verified reads. */
+    open(receiptPath: string, flags: number): Promise<FileHandle>;
+}
+/** Resolve the platform no-follow flag, falling back only where Node omits it. */
+export declare function resolveReceiptNoFollowFlag(constants: {
+    O_NOFOLLOW?: number;
+}): number;
+/** Read one regular file only when its opened identity remains bounded and stable. */
+export declare function readBoundedRegularFile(receiptPath: string, maximumBytes: number, boundary?: ReceiptFileBoundary): Promise<string | null>;

package/dist/sdk/merge/receipt-file-boundary.js

@@ -0,0 +1,47 @@
+/**
+ * @module sdk/merge/receipt-file-boundary
+ *
+ * Reads untrusted receipt candidates through a bounded, no-follow file
+ * boundary whose race and short-read behavior can be exercised directly.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6ece0e15-aff5-5e2d-b18a-16ffaa0fe2ea")}catch(e){}}();
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+const NODE_RECEIPT_FILE_BOUNDARY = { lstat, open };
+/** Resolve the platform no-follow flag, falling back only where Node omits it. */
+export function resolveReceiptNoFollowFlag(constants) {
+    return constants.O_NOFOLLOW ?? 0;
+}
+/** Read one regular file only when its opened identity remains bounded and stable. */
+export async function readBoundedRegularFile(receiptPath, maximumBytes, boundary = NODE_RECEIPT_FILE_BOUNDARY) {
+    const pathStats = await boundary.lstat(receiptPath);
+    if (pathStats.isSymbolicLink() ||
+        !pathStats.isFile() ||
+        pathStats.size > maximumBytes) {
+        return null;
+    }
+    const handle = await boundary.open(receiptPath, fsConstants.O_RDONLY | resolveReceiptNoFollowFlag(fsConstants));
+    try {
+        const openedStats = await handle.stat();
+        if (!openedStats.isFile() || openedStats.size > maximumBytes)
+            return null;
+        const buffer = Buffer.alloc(openedStats.size);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        const finalStats = await handle.stat();
+        return finalStats.size === openedStats.size && offset === openedStats.size
+            ? buffer.toString("utf8", 0, offset)
+            : null;
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=receipt-file-boundary.js.map
+//# debugId=6ece0e15-aff5-5e2d-b18a-16ffaa0fe2ea

package/dist/sdk/merge/receipts.d.ts

@@ -19,6 +19,8 @@ export interface MergeDecisionReceipt {
     fields_from_theirs: string[];
     /** Collections combined from both branches. */
     union_fields: string[];
+    /** SHA-256 hashes of the merged values for every field represented by this receipt. Absent on legacy receipts, which cannot prove drift attribution. */
+    merged_field_hashes?: Record<string, string>;
     /** Full recoverable scalar decisions, retained only in the clone. */
     decisions: ItemMergeConflictDecision[];
     /** Whether a merge reconciliation history event consumed this receipt. */
@@ -29,6 +31,8 @@ export interface MergeDecisionReceipt {
     reconciled_at?: string;
     /** Whether decision values are recoverable locally or represented by hashes only. */
     value_availability?: "clone_local" | "hash_only";
+    /** Runtime-only provenance assigned by the reader; serialized values are ignored. */
+    evidence_source?: "clone_local" | "durable";
 }
 /** Privacy-safe receipt summary suitable for committed history context. */
 export interface MergeDecisionReceiptSummary {
@@ -66,6 +70,24 @@ export interface MergeReceiptReport {
     /** ISO timestamp for the report. */
     generated_at: string;
 }
+/** Internal integrity scan result used by health without exposing malformed receipt contents. */
+export interface MergeReceiptEvidenceScan {
+    /** Valid receipts that passed bounded-file, schema, and identity validation. */
+    receipts: MergeDecisionReceipt[];
+    /** Number of JSON receipt candidates that could not be validated safely. */
+    invalid_evidence_count: number;
+}
+declare function prepareReceiptSettlement(params: {
+    receiptPath: string;
+    receiptId: string;
+    evidenceSource: "clone_local" | "durable";
+    reconciledAt: string;
+    readReceipt?: (receiptPath: string) => Promise<string | null>;
+}): Promise<{
+    path: string;
+    content: string;
+    fingerprint: string;
+} | null>;
 /** Convert a raw receipt into privacy-safe history context. */
 export declare function summarizeMergeReceipt(receipt: MergeDecisionReceipt): MergeDecisionReceiptSummary;
 /** Persist one item-driver outcome in the clone-local Git directory. */
@@ -76,8 +98,18 @@ export declare function writeMergeReceipt(params: {
     conflictResolution?: "preferred_side" | "stable_value_order";
     fieldsFromTheirs: string[];
     unionFields: string[];
+    mergedFieldHashes?: Record<string, string>;
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
+/** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
+export declare function inspectMergeReceiptEvidence(cwd: string, options?: {
+    /** Include receipts whose reconciliation state is already settled. */
+    includeReconciled?: boolean;
+    /** Include receipts that contain no discarded scalar values. */
+    includeLossless?: boolean;
+    /** Explicit tracker root used to locate durable receipt evidence. */
+    pmRoot?: string;
+}): Promise<MergeReceiptEvidenceScan>;
 /** Read clone-local receipts with explicit reconciled/lossless classification controls. */
 export declare function listMergeReceipts(cwd: string, options?: {
     includeReconciled?: boolean;
@@ -92,7 +124,9 @@ export declare function partitionMergeReceipts(receipts: MergeDecisionReceipt[])
     lossless: MergeDecisionReceipt[];
 };
 /** Mark a receipt as represented by a committed merge history event. */
-export declare function markMergeReceiptReconciled(cwd: string, receipt: MergeDecisionReceipt): Promise<void>;
+export declare function markMergeReceiptReconciled(cwd: string, receipt: MergeDecisionReceipt, options?: {
+    requireExisting?: boolean;
+}): Promise<void>;
 /** Report pending or historical clone-local merge decisions. */
 export declare function runMergeReceiptReport(options: {
     /** Include receipts already represented by merge history events. */
@@ -100,3 +134,8 @@ export declare function runMergeReceiptReport(options: {
     /** Repository directory to inspect; defaults to the process working directory. */
     cwd?: string;
 }): Promise<MergeReceiptReport>;
+/** Test-only seams for deterministic receipt-boundary fault coverage. */
+export declare const _testOnlyMergeReceipts: {
+    prepareReceiptSettlement: typeof prepareReceiptSettlement;
+};
+export {};