usesteady 0.1.0-alpha.1

package/dist/src/cursor/adapters/inprocess-adapter.js

@@ -0,0 +1,308 @@
+/**
+ * Cursor In-Process Adapter — first real CursorEditorPlugin implementation.
+ *
+ * ── What this is ───────────────────────────────────────────────────────────────
+ *
+ *   This is the mechanism-agnostic contract made concrete.
+ *   No IPC, no external process, no network — pure filesystem reads and writes.
+ *
+ *   It applies parsedChange (oldValue -> newValue in filePath) directly using
+ *   Node.js fs. It is the simplest valid real adapter and proves the contract
+ *   works outside of a stub.
+ *
+ * ── Three paths this adapter exercises ────────────────────────────────────────
+ *
+ *   Path A (accepted):
+ *     - parsedChange is present
+ *     - target file is readable and within allowedFiles (if non-empty)
+ *     - oldValue appears exactly once in the file
+ *     - file is rewritten with newValue and CursorAccepted is returned
+ *
+ *   Path B (refused_due_to_scope):
+ *     - allowedFiles is empty AND parsedChange has no filePath
+ *     - allowedFiles has multiple entries and oldValue appears in more than one
+ *     - parsedChange is absent and no single target file can be determined
+ *     Returns a structured CursorScopeQuestion for H to resolve.
+ *
+ *   Path C (refused_due_to_execution_error):
+ *     - file_not_found: target file does not exist on disk
+ *     - old_value_not_found: oldValue is not present in the file
+ *     - ambiguous_match: oldValue appears more than once in the file
+ *       (cannot guarantee a safe, targeted replacement)
+ *     - parse_error: parsedChange is absent (no edit directive)
+ *
+ * ── What this adapter does NOT do ─────────────────────────────────────────────
+ *
+ *   - It does not re-derive intent. changeSpec is the sole edit directive.
+ *   - It does not write outside allowedFiles (when non-empty).
+ *   - It does not persist UCP envelopes (the gate owns all persistence).
+ *   - It does not validate workspace constraints (already done by the gate).
+ *   - It does not call back into the intake pipeline.
+ *
+ * ── Replacement strategy ──────────────────────────────────────────────────────
+ *
+ *   Uses exact string matching (indexOf), not regex.
+ *   This is intentional: parsedChange.oldValue is a verbatim extracted string
+ *   from interpretation output. Regex matching would introduce ambiguity.
+ *
+ *   If oldValue appears more than once, the adapter refuses (ambiguous_match)
+ *   rather than replacing all occurrences silently. The caller must clarify.
+ *
+ * See: docs/cursor-delivery-contract.md — delivery paths
+ *      docs/cursor-allowedfiles-policy.md — allowedFiles semantics
+ *      src/cursor/adapters/stub-adapter.ts — the stub this replaces
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync, } from "node:fs";
+import { join, isAbsolute, dirname } from "node:path";
+import { matchesGlob } from "../glob-matcher.js";
+// ─── Adapter ──────────────────────────────────────────────────────────────────
+export class CursorInProcessAdapter {
+    workspaceRoot;
+    /**
+     * @param workspaceRoot  Absolute path to the workspace root.
+     *                       Relative paths in allowedFiles and parsedChange.filePath
+     *                       are resolved against this root.
+     */
+    constructor(workspaceRoot) {
+        this.workspaceRoot = workspaceRoot;
+    }
+    async receive(request) {
+        const { deliveryId, artifact } = request;
+        const { changeSpec, scopeConstraint } = artifact;
+        const parsedChange = changeSpec.parsedChange;
+        // ── Step 1: Resolve target file ──────────────────────────────────────────
+        // If no parsedChange, we have no edit directive — cannot proceed.
+        if (!parsedChange) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "parse_error",
+                detail: "No parsedChange present in changeSpec. Cannot determine an edit directive.",
+            };
+        }
+        // Determine the target file:
+        //   1. parsedChange.filePath (authoritative — proposed by artifact mapper)
+        //   2. single allowedFiles entry (unambiguous — H narrowed to one file)
+        //   3. search all allowedFiles for oldValue (scope clarification if > 1 match)
+        //   4. if allowedFiles is empty, we have no search space → scope question
+        let targetFile;
+        if (parsedChange.filePath) {
+            targetFile = parsedChange.filePath;
+        }
+        else if (scopeConstraint.allowedFiles.length === 1) {
+            targetFile = scopeConstraint.allowedFiles[0];
+        }
+        else if (scopeConstraint.allowedFiles.length > 1) {
+            // Search all allowedFiles for oldValue — clarify if > 1 match
+            const result = this.searchForOldValue(parsedChange.oldValue, scopeConstraint.allowedFiles);
+            if (result.kind === "not_found") {
+                return {
+                    kind: "refused_due_to_execution_error",
+                    deliveryId,
+                    artifactId: artifact.id,
+                    receivedAt: Date.now(),
+                    errorCode: "old_value_not_found",
+                    detail: `"${parsedChange.oldValue}" was not found in any of the allowed files: ${scopeConstraint.allowedFiles.join(", ")}`,
+                };
+            }
+            if (result.kind === "multiple_matches") {
+                return {
+                    kind: "refused_due_to_scope",
+                    deliveryId,
+                    artifactId: artifact.id,
+                    receivedAt: Date.now(),
+                    scopeQuestion: {
+                        questionKind: "need_file_path",
+                        candidates: result.files,
+                        searchedFor: parsedChange.oldValue,
+                        explanation: `Found "${parsedChange.oldValue}" in ${result.files.length} files. Select the target.`,
+                    },
+                };
+            }
+            // result.kind === "single_match" — TypeScript narrowed above via early returns
+            targetFile = result.file;
+        }
+        else {
+            // allowedFiles is empty and parsedChange has no filePath — open search
+            return {
+                kind: "refused_due_to_scope",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                scopeQuestion: {
+                    questionKind: "need_file_path",
+                    candidates: [],
+                    searchedFor: parsedChange.oldValue,
+                    explanation: "No file path specified and allowedFiles is empty. Provide a target file path.",
+                },
+            };
+        }
+        // TypeScript cannot prove targetFile is defined through the branching above,
+        // but all code paths either return early or assign it. Assert non-null here.
+        const resolvedFile = targetFile;
+        // ── Step 2: Scope boundary enforcement ───────────────────────────────────
+        // If allowedFiles is non-empty, resolvedFile must be in it.
+        if (scopeConstraint.allowedFiles.length > 0 && !scopeConstraint.allowedFiles.includes(resolvedFile)) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "scope_outside_allowed",
+                detail: `Target file "${resolvedFile}" is not in allowedFiles.`,
+            };
+        }
+        // If any prohibitedPattern matches resolvedFile, refuse.
+        const normalized = resolvedFile.replace(/\\/g, "/");
+        for (const pattern of scopeConstraint.prohibitedPatterns) {
+            if (matchesGlob(normalized, pattern)) {
+                return {
+                    kind: "refused_due_to_execution_error",
+                    deliveryId,
+                    artifactId: artifact.id,
+                    receivedAt: Date.now(),
+                    errorCode: "prohibited_pattern_match",
+                    detail: `Target file "${resolvedFile}" matches prohibited pattern "${pattern}".`,
+                };
+            }
+        }
+        // ── Step 3: Resolve absolute path ────────────────────────────────────────
+        const absolutePath = isAbsolute(resolvedFile)
+            ? resolvedFile
+            : join(this.workspaceRoot, resolvedFile);
+        // ── Step 4: Read and apply the change ─────────────────────────────────────
+        if (!existsSync(absolutePath)) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "file_not_found",
+                detail: `File not found: ${absolutePath}`,
+            };
+        }
+        let content;
+        try {
+            content = readFileSync(absolutePath, { encoding: "utf8" });
+        }
+        catch (err) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "file_not_found",
+                detail: `Failed to read file "${absolutePath}": ${String(err)}`,
+            };
+        }
+        const { oldValue, newValue } = parsedChange;
+        const firstIndex = content.indexOf(oldValue);
+        if (firstIndex === -1) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "old_value_not_found",
+                detail: `"${oldValue}" was not found in "${resolvedFile}".`,
+            };
+        }
+        const lastIndex = content.lastIndexOf(oldValue);
+        if (lastIndex !== firstIndex) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "ambiguous_match",
+                detail: `"${oldValue}" appears more than once in "${resolvedFile}". Cannot safely apply a targeted replacement.`,
+            };
+        }
+        // Apply the replacement — exact, single occurrence.
+        const updated = content.slice(0, firstIndex) + newValue + content.slice(firstIndex + oldValue.length);
+        try {
+            writeFileSync(absolutePath, updated, "utf8");
+        }
+        catch (err) {
+            return {
+                kind: "refused_due_to_execution_error",
+                deliveryId,
+                artifactId: artifact.id,
+                receivedAt: Date.now(),
+                errorCode: "merge_conflict",
+                detail: `Failed to write file "${absolutePath}": ${String(err)}`,
+            };
+        }
+        // ── Step 5: Return accepted ───────────────────────────────────────────────
+        return {
+            kind: "accepted",
+            deliveryId,
+            artifactId: artifact.id,
+            receivedAt: Date.now(),
+        };
+    }
+    // ── FsPlugin: filesystem primitives ─────────────────────────────────────────
+    async executeFsOp(op) {
+        try {
+            switch (op.operationType) {
+                case "create_dir": {
+                    const abs = isAbsolute(op.dirPath) ? op.dirPath : join(this.workspaceRoot, op.dirPath);
+                    mkdirSync(abs, { recursive: true });
+                    return { kind: "accepted" };
+                }
+                case "write_file": {
+                    const abs = isAbsolute(op.filePath) ? op.filePath : join(this.workspaceRoot, op.filePath);
+                    mkdirSync(dirname(abs), { recursive: true });
+                    writeFileSync(abs, op.content, "utf8");
+                    return { kind: "accepted" };
+                }
+                case "rename": {
+                    const absOld = isAbsolute(op.filePath) ? op.filePath : join(this.workspaceRoot, op.filePath);
+                    const absNew = isAbsolute(op.newPath) ? op.newPath : join(this.workspaceRoot, op.newPath);
+                    renameSync(absOld, absNew);
+                    return { kind: "accepted" };
+                }
+                case "delete_file": {
+                    const abs = isAbsolute(op.filePath) ? op.filePath : join(this.workspaceRoot, op.filePath);
+                    unlinkSync(abs);
+                    return { kind: "accepted" };
+                }
+            }
+        }
+        catch (err) {
+            return { kind: "failed", detail: String(err) };
+        }
+    }
+    // ── Internal helpers ────────────────────────────────────────────────────────
+    /**
+     * Search for oldValue in a list of candidate files.
+     * Returns single_match, multiple_matches, or not_found.
+     * Reads each file from disk; skips files that cannot be read.
+     */
+    searchForOldValue(oldValue, allowedFiles) {
+        const matches = [];
+        for (const file of allowedFiles) {
+            const absPath = isAbsolute(file) ? file : join(this.workspaceRoot, file);
+            if (!existsSync(absPath))
+                continue;
+            let content;
+            try {
+                content = readFileSync(absPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            if (content.includes(oldValue)) {
+                matches.push(file);
+            }
+        }
+        if (matches.length === 0)
+            return { kind: "not_found" };
+        if (matches.length === 1)
+            return { kind: "single_match", file: matches[0] };
+        return { kind: "multiple_matches", files: matches };
+    }
+}
+//# sourceMappingURL=inprocess-adapter.js.map

package/dist/src/cursor/adapters/inprocess-adapter.js.map

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

package/dist/src/cursor/adapters/stub-adapter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Cursor Stub Adapter — in-process transport adapter for testing and development.
+ *
+ * ── Role ───────────────────────────────────────────────────────────────────────
+ *
+ *   The stub adapter is the first concrete implementation of CursorEditorPlugin.
+ *   It is also the proof that the mechanism-agnostic contract works — the same
+ *   delivery gate operates identically whether the plugin returns a response
+ *   immediately (stub) or asynchronously (real Cursor IPC/plugin).
+ *
+ * ── Transport proof ────────────────────────────────────────────────────────────
+ *
+ *   CursorStubAdapter proves all three delivery paths:
+ *     - accepted:                   stub returns CursorAccepted
+ *     - refused_due_to_scope:       stub returns CursorRefusedDueToScope
+ *     - refused_due_to_execution_error: stub returns CursorRefusedDueToExecutionError
+ *
+ *   The gate does not change behavior based on which adapter is used.
+ *   The stub is the simplest valid adapter — a configured response, returned immediately.
+ *
+ * ── Usage ──────────────────────────────────────────────────────────────────────
+ *
+ *   In tests:
+ *     const plugin  = CursorStubAdapter.accepted();
+ *     const gate    = new CursorDeliveryGate(plugin, storeDir);
+ *     const result  = await gate.deliver(approvedArtifact);
+ *     expect(result.outcome).toBe("accepted");
+ *
+ *   For a configurable sequence of responses (e.g., scope refusal then accept):
+ *     const plugin = CursorStubAdapter.sequence([
+ *       CursorStubAdapter.scopeRefusal({ questionKind: "need_file_path", ... }),
+ *       CursorStubAdapter.acceptedResponse(),
+ *     ]);
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────
+ *
+ *   This is not a fake Cursor. It does not apply edits, read files, or produce
+ *   real diffs. It is purely for proving that the delivery gate contract is
+ *   exercised correctly.
+ *
+ *   For a real Cursor adapter, implement CursorEditorPlugin with your transport
+ *   of choice (function call, IPC, file drop). The delivery gate does not change.
+ *
+ * See: docs/cursor-delivery-contract.md — mechanism selection rationale
+ *      src/cursor/delivery-gate.ts — CursorEditorPlugin interface
+ */
+import type { CursorEditorPlugin } from "../delivery-gate.js";
+import type { CursorDeliveryRequest } from "../types.js";
+import type { CursorResponse, CursorAccepted, CursorRefusedDueToScope, CursorRefusedDueToExecutionError, CursorScopeQuestion, CursorExecutionErrorCode } from "../types.js";
+/**
+ * A configurable in-process CursorEditorPlugin.
+ *
+ * Configured at construction with a fixed response or a sequence of responses.
+ * Returns responses immediately (no async delay).
+ */
+export declare class CursorStubAdapter implements CursorEditorPlugin {
+    private readonly responses;
+    private callIndex;
+    constructor(responses: CursorResponse[]);
+    receive(request: CursorDeliveryRequest): Promise<CursorResponse>;
+    /** How many times receive() has been called. */
+    get callCount(): number;
+    /** Adapter that always returns "accepted". */
+    static accepted(overrides?: Partial<CursorAccepted>): CursorStubAdapter;
+    /** Adapter that returns a scope refusal with the given question. */
+    static refusedScope(question: CursorScopeQuestion, overrides?: Partial<CursorRefusedDueToScope>): CursorStubAdapter;
+    /** Adapter that returns an execution error with the given code. */
+    static refusedError(errorCode: CursorExecutionErrorCode, detail?: string): CursorStubAdapter;
+    /** Adapter that returns responses in sequence. Throws if exhausted. */
+    static sequence(responses: CursorResponse[]): CursorStubAdapter;
+    static acceptedResponse(overrides?: Partial<CursorAccepted>): CursorAccepted;
+    static scopeRefusalResponse(question: CursorScopeQuestion, overrides?: Partial<CursorRefusedDueToScope>): CursorRefusedDueToScope;
+    static executionErrorResponse(errorCode: CursorExecutionErrorCode, detail?: string): CursorRefusedDueToExecutionError;
+}
+//# sourceMappingURL=stub-adapter.d.ts.map

package/dist/src/cursor/adapters/stub-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-adapter.d.ts","sourceRoot":"","sources":["../../../../src/cursor/adapters/stub-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gCAAgC,EAChC,mBAAmB,EACnB,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAIrB;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,SAAS,CAAK;gBAEV,SAAS,EAAE,cAAc,EAAE;IAKjC,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAWtE,gDAAgD;IAChD,IAAI,SAAS,IAAI,MAAM,CAA2B;IAIlD,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,iBAAiB;IAIvE,oEAAoE;IACpE,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,iBAAiB;IAInH,mEAAmE;IACnE,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB;IAI5F,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,iBAAiB;IAM/D,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc;IAU5E,MAAM,CAAC,oBAAoB,CACzB,QAAQ,EAAG,mBAAmB,EAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAC3C,uBAAuB;IAW1B,MAAM,CAAC,sBAAsB,CAC3B,SAAS,EAAE,wBAAwB,EACnC,MAAM,SAA6B,GAClC,gCAAgC;CAUpC"}

package/dist/src/cursor/adapters/stub-adapter.js

@@ -0,0 +1,120 @@
+/**
+ * Cursor Stub Adapter — in-process transport adapter for testing and development.
+ *
+ * ── Role ───────────────────────────────────────────────────────────────────────
+ *
+ *   The stub adapter is the first concrete implementation of CursorEditorPlugin.
+ *   It is also the proof that the mechanism-agnostic contract works — the same
+ *   delivery gate operates identically whether the plugin returns a response
+ *   immediately (stub) or asynchronously (real Cursor IPC/plugin).
+ *
+ * ── Transport proof ────────────────────────────────────────────────────────────
+ *
+ *   CursorStubAdapter proves all three delivery paths:
+ *     - accepted:                   stub returns CursorAccepted
+ *     - refused_due_to_scope:       stub returns CursorRefusedDueToScope
+ *     - refused_due_to_execution_error: stub returns CursorRefusedDueToExecutionError
+ *
+ *   The gate does not change behavior based on which adapter is used.
+ *   The stub is the simplest valid adapter — a configured response, returned immediately.
+ *
+ * ── Usage ──────────────────────────────────────────────────────────────────────
+ *
+ *   In tests:
+ *     const plugin  = CursorStubAdapter.accepted();
+ *     const gate    = new CursorDeliveryGate(plugin, storeDir);
+ *     const result  = await gate.deliver(approvedArtifact);
+ *     expect(result.outcome).toBe("accepted");
+ *
+ *   For a configurable sequence of responses (e.g., scope refusal then accept):
+ *     const plugin = CursorStubAdapter.sequence([
+ *       CursorStubAdapter.scopeRefusal({ questionKind: "need_file_path", ... }),
+ *       CursorStubAdapter.acceptedResponse(),
+ *     ]);
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────
+ *
+ *   This is not a fake Cursor. It does not apply edits, read files, or produce
+ *   real diffs. It is purely for proving that the delivery gate contract is
+ *   exercised correctly.
+ *
+ *   For a real Cursor adapter, implement CursorEditorPlugin with your transport
+ *   of choice (function call, IPC, file drop). The delivery gate does not change.
+ *
+ * See: docs/cursor-delivery-contract.md — mechanism selection rationale
+ *      src/cursor/delivery-gate.ts — CursorEditorPlugin interface
+ */
+// ─── Stub adapter ────────────────────────────────────────────────────────────
+/**
+ * A configurable in-process CursorEditorPlugin.
+ *
+ * Configured at construction with a fixed response or a sequence of responses.
+ * Returns responses immediately (no async delay).
+ */
+export class CursorStubAdapter {
+    responses;
+    callIndex = 0;
+    constructor(responses) {
+        if (responses.length === 0)
+            throw new Error("CursorStubAdapter: responses must not be empty");
+        this.responses = responses;
+    }
+    async receive(request) {
+        const response = this.responses[this.callIndex];
+        if (response === undefined) {
+            throw new Error(`CursorStubAdapter: no response configured for call index ${this.callIndex} (deliveryId=${request.deliveryId})`);
+        }
+        this.callIndex++;
+        return response;
+    }
+    /** How many times receive() has been called. */
+    get callCount() { return this.callIndex; }
+    // ── Factory methods ────────────────────────────────────────────────────────
+    /** Adapter that always returns "accepted". */
+    static accepted(overrides) {
+        return new CursorStubAdapter([CursorStubAdapter.acceptedResponse(overrides)]);
+    }
+    /** Adapter that returns a scope refusal with the given question. */
+    static refusedScope(question, overrides) {
+        return new CursorStubAdapter([CursorStubAdapter.scopeRefusalResponse(question, overrides)]);
+    }
+    /** Adapter that returns an execution error with the given code. */
+    static refusedError(errorCode, detail) {
+        return new CursorStubAdapter([CursorStubAdapter.executionErrorResponse(errorCode, detail)]);
+    }
+    /** Adapter that returns responses in sequence. Throws if exhausted. */
+    static sequence(responses) {
+        return new CursorStubAdapter(responses);
+    }
+    // ── Response builders ─────────────────────────────────────────────────────
+    static acceptedResponse(overrides) {
+        return {
+            kind: "accepted",
+            deliveryId: "stub-delivery-id",
+            artifactId: "stub-artifact-id",
+            receivedAt: Date.now(),
+            ...overrides,
+        };
+    }
+    static scopeRefusalResponse(question, overrides) {
+        return {
+            kind: "refused_due_to_scope",
+            deliveryId: "stub-delivery-id",
+            artifactId: "stub-artifact-id",
+            receivedAt: Date.now(),
+            scopeQuestion: question,
+            ...overrides,
+        };
+    }
+    static executionErrorResponse(errorCode, detail = "Stub execution error.") {
+        return {
+            kind: "refused_due_to_execution_error",
+            deliveryId: "stub-delivery-id",
+            artifactId: "stub-artifact-id",
+            receivedAt: Date.now(),
+            errorCode,
+            detail,
+        };
+    }
+}
+//# sourceMappingURL=stub-adapter.js.map

package/dist/src/cursor/adapters/stub-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-adapter.js","sourceRoot":"","sources":["../../../../src/cursor/adapters/stub-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAaH,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IACX,SAAS,CAAmB;IACrC,SAAS,GAAG,CAAC,CAAC;IAEtB,YAAY,SAA2B;QACrC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAC9F,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAA8B;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,4DAA4D,IAAI,CAAC,SAAS,gBAAgB,OAAO,CAAC,UAAU,GAAG,CAChH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,gDAAgD;IAChD,IAAI,SAAS,KAAa,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAElD,8EAA8E;IAE9E,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,SAAmC;QACjD,OAAO,IAAI,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,oEAAoE;IACpE,MAAM,CAAC,YAAY,CAAC,QAA6B,EAAE,SAA4C;QAC7F,OAAO,IAAI,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAC9F,CAAC;IAED,mEAAmE;IACnE,MAAM,CAAC,YAAY,CAAC,SAAmC,EAAE,MAAe;QACtE,OAAO,IAAI,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,sBAAsB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9F,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,SAA2B;QACzC,OAAO,IAAI,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,6EAA6E;IAE7E,MAAM,CAAC,gBAAgB,CAAC,SAAmC;QACzD,OAAO;YACL,IAAI,EAAS,UAAU;YACvB,UAAU,EAAG,kBAAkB;YAC/B,UAAU,EAAG,kBAAkB;YAC/B,UAAU,EAAG,IAAI,CAAC,GAAG,EAAE;YACvB,GAAG,SAAS;SACb,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,oBAAoB,CACzB,QAA8B,EAC9B,SAA4C;QAE5C,OAAO;YACL,IAAI,EAAW,sBAAsB;YACrC,UAAU,EAAK,kBAAkB;YACjC,UAAU,EAAK,kBAAkB;YACjC,UAAU,EAAK,IAAI,CAAC,GAAG,EAAE;YACzB,aAAa,EAAE,QAAQ;YACvB,GAAG,SAAS;SACb,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,sBAAsB,CAC3B,SAAmC,EACnC,MAAM,GAAM,uBAAuB;QAEnC,OAAO;YACL,IAAI,EAAQ,gCAAgC;YAC5C,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;YACtB,SAAS;YACT,MAAM;SACP,CAAC;IACJ,CAAC;CACF"}

package/dist/src/cursor/artifact-mapper.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Cursor artifact mapper — builds the initial CursorHandoffArtifact.
+ *
+ * ── Role ───────────────────────────────────────────────────────────────────────
+ *
+ *   Translates an IntakeResult (mode === "execute") into a CursorHandoffArtifact
+ *   with eligibility: "pending_confirmation" and an initial scopeConstraint.
+ *
+ *   This is the ONLY place that proposes allowedFiles. Specifically, it reads
+ *   parsedChange.filePath when present. When absent, allowedFiles starts empty.
+ *
+ * ── What this mapper does ──────────────────────────────────────────────────────
+ *
+ *   1. Extracts changeSpec from InterpretationResult (execute + structured) or
+ *      IntentInterpretation (execute + vague).
+ *   2. Sets initial allowedFiles = [parsedChange.filePath] or [].
+ *   3. Sets initial prohibitedPatterns from OCD policy (defensive defaults).
+ *   4. Sets eligibility = "pending_confirmation".
+ *   5. Sets ocdClearance = { status: "cleared", rulesFired: [], conflictsDetected: [] }
+ *      (OCD evaluator updates this separately — see ocd-evaluator.ts).
+ *
+ * ── What this mapper does NOT do ──────────────────────────────────────────────
+ *
+ *   - Does not read the filesystem (no path resolution)
+ *   - Does not call OCD (that is a separate step)
+ *   - Does not set eligibility to "approved_for_cursor" (only H does that)
+ *   - Does not validate H-provided paths (that is the delivery gate's job)
+ *   - Does not invent file paths from intent category
+ *
+ * ── CONSTRUCTION RULE: undefined-free payloads ────────────────────────────────
+ *
+ *   All payload objects must be undefined-free per UCP protocol invariant.
+ *   Optional fields are omitted entirely when absent. Never assigned undefined.
+ *
+ * See: docs/cursor-allowedfiles-policy.md — population source hierarchy
+ *      docs/cursor-integration-architecture.md — authority model
+ */
+import type { IntakeResult } from "../intake/types.js";
+import type { ReplaceChange } from "../understand/interpretation/types.js";
+type ParsedChange = ReplaceChange;
+import type { CursorHandoffArtifact, CursorOCDPolicy } from "./types.js";
+/**
+ * Build the initial CursorHandoffArtifact from an IntakeResult.
+ *
+ * PRECONDITION: intake.mode === "execute". Callers must verify this before calling.
+ * Passing a non-execute IntakeResult is a caller contract violation.
+ *
+ * @param intake      The completed intake result (mode must be "execute").
+ * @param intentId    The ucp.intent.v1 envelope id — links back to the root intent.
+ * @param responseId  The ucp.response.v1 envelope id — links back to the mode decision.
+ * @param policy      The OCD policy config (for defensive prohibitedPatterns).
+ * @returns A CursorHandoffArtifact with eligibility: "pending_confirmation".
+ */
+export declare function buildCursorHandoffArtifact(intake: IntakeResult, intentId: string, responseId: string, policy: CursorOCDPolicy, parsedChange?: ParsedChange): CursorHandoffArtifact;
+/**
+ * Rebuild a CursorHandoffArtifact with a narrowed scopeConstraint.
+ *
+ * Called when H narrows the scope at ready_for_confirmation, or when a scope
+ * clarification answer updates allowedFiles. Produces a new artifact with a
+ * new content address (different scopeConstraint → different id).
+ *
+ * The new artifact retains the same intentId, responseId, and changeSpec.
+ * eligibility is reset to "pending_confirmation" — H must re-confirm.
+ *
+ * PRECONDITION: newAllowedFiles ⊆ current artifact.scopeConstraint.allowedFiles
+ *   OR current artifact.scopeConstraint.allowedFiles is empty (H setting from empty).
+ * Callers must enforce the non-widening rule before calling.
+ */
+export declare function narrowArtifactScope(artifact: CursorHandoffArtifact, newAllowedFiles: readonly string[], newAllowedScopes?: readonly string[]): CursorHandoffArtifact;
+/**
+ * Approve a CursorHandoffArtifact — set eligibility to "approved_for_cursor".
+ *
+ * This is the ONLY place that sets eligibility to "approved_for_cursor".
+ * Callers must verify that H has explicitly confirmed before calling.
+ *
+ * Returns a new artifact reference. The id does NOT change (eligibility and
+ * approvedAt are not part of the content-addressed id input).
+ */
+export declare function approveArtifact(artifact: CursorHandoffArtifact, confirmedAt: number): CursorHandoffArtifact;
+export {};
+//# sourceMappingURL=artifact-mapper.d.ts.map

package/dist/src/cursor/artifact-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-mapper.d.ts","sourceRoot":"","sources":["../../../src/cursor/artifact-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAA2B,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAwB,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAEjG,KAAK,YAAY,GAAG,aAAa,CAAC;AAGlC,OAAO,KAAK,EACV,qBAAqB,EAIrB,eAAe,EAChB,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAQ,YAAY,EAC1B,QAAQ,EAAM,MAAM,EACpB,UAAU,EAAI,MAAM,EACpB,MAAM,EAAQ,eAAe,EAC7B,YAAY,CAAC,EAAE,YAAY,GAC1B,qBAAqB,CA4BvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAS,qBAAqB,EACtC,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,qBAAqB,CA0BvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAK,qBAAqB,EAClC,WAAW,EAAE,MAAM,GAClB,qBAAqB,CAMvB"}