@cjhyy/code-shell-capability-coding 0.8.0

package/dist/tools/apply-patch/NOTICE.md

@@ -0,0 +1,29 @@
+# Third-party attribution
+
+Files in this directory contain code adapted from
+[OpenAI Codex `codex-rs/apply-patch`](https://github.com/openai/codex/tree/main/codex-rs/apply-patch),
+licensed under the Apache License 2.0. See `LICENSE-codex` for the full
+license text.
+
+## What was adapted
+
+| Source (Rust)                      | Target (TypeScript)           | Notes                                         |
+| ---------------------------------- | ----------------------------- | --------------------------------------------- |
+| `src/seek_sequence.rs`             | `seek-sequence.ts`            | Direct port — same four-pass strategy         |
+| `src/parser.rs`                    | `parser.ts`                   | Direct port of the V4A grammar parser         |
+| `src/lib.rs` (chunk replacement)   | `applier.ts`                  | `compute_replacements` algorithm port         |
+| `apply_patch_tool_instructions.md` | tool description (`index.ts`) | Patch-format prompt cribbed from the original |
+| `tests/fixtures/scenarios/`        | `tests/fixtures/apply-patch/` | 22 golden scenarios used verbatim             |
+
+## Intentional behavioral divergence
+
+`applier.ts` adds a two-phase commit (plan → snapshot → write → rollback)
+that Codex does not have. As a consequence:
+
+- Fixture `015_failure_after_partial_success_leaves_changes` produces a
+  different on-disk result here than in Codex: we leave **no** files
+  behind when a hunk fails, whereas Codex leaves the partial writes from
+  earlier hunks. The conformance test asserts our stronger guarantee.
+
+Set `allowPartialOnCommit: true` on `applyPatch()` to fall back to
+codex-style non-atomic semantics if needed.

package/dist/tools/apply-patch/applier.d.ts

@@ -0,0 +1,26 @@
+import { Hunk } from "./types.js";
+export interface ApplyPatchOptions {
+    /** Working directory for resolving relative paths in the patch. */
+    cwd: string;
+    /**
+     * If true, skip the snapshot/rollback safety net and apply each planned
+     * change one at a time, leaving partial work on disk if a later write
+     * fails. Mostly useful for codex-parity testing. Default: false.
+     */
+    allowPartialOnCommit?: boolean;
+}
+export interface ApplyPatchResult {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+}
+/**
+ * Plan and commit the patch atomically.
+ *
+ * Phase 1 (plan): walk every hunk, compute the resulting file content in
+ * memory. Throws if any hunk cannot be applied; nothing is written.
+ *
+ * Phase 2 (commit): write all planned changes. If any write fails, restore
+ * from the in-memory snapshot captured in phase 1 and rethrow.
+ */
+export declare function applyPatch(hunks: Hunk[], options: ApplyPatchOptions): Promise<ApplyPatchResult>;

package/dist/tools/apply-patch/applier.js

@@ -0,0 +1,306 @@
+// Atomic patch applier — dry-runs all hunks, then commits all-or-nothing.
+//
+// This deliberately diverges from codex-rs/apply-patch which applies hunks
+// one-by-one and leaves partial changes on disk if a later hunk fails (see
+// fixture 015_failure_after_partial_success_leaves_changes for codex's
+// behavior). We treat the patch as a transaction: either every hunk applies
+// or none do. Set `allowPartialOnCommit` to mimic codex semantics for the
+// rare case where you want it.
+//
+// Algorithm uses code adapted from codex-rs/apply-patch/src/lib.rs (Apache-2.0)
+// for the chunk-replacement phase (compute_replacements, apply_replacements).
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { seekSequence } from "./seek-sequence.js";
+import { detectEol, toLf, applyEol } from "./eol.js";
+/**
+ * Plan and commit the patch atomically.
+ *
+ * Phase 1 (plan): walk every hunk, compute the resulting file content in
+ * memory. Throws if any hunk cannot be applied; nothing is written.
+ *
+ * Phase 2 (commit): write all planned changes. If any write fails, restore
+ * from the in-memory snapshot captured in phase 1 and rethrow.
+ */
+export async function applyPatch(hunks, options) {
+    if (hunks.length === 0) {
+        throw new Error("No files were modified.");
+    }
+    const planned = await planHunks(hunks, options.cwd);
+    return commitPlanned(planned, !!options.allowPartialOnCommit);
+}
+async function planHunks(hunks, cwd) {
+    const set = {
+        byPath: new Map(),
+        added: [],
+        modified: [],
+        deleted: [],
+    };
+    function schedule(path, change) {
+        if (set.byPath.has(path)) {
+            throw new Error(`Patch references ${path} more than once. Combine the operations into a single hunk.`);
+        }
+        set.byPath.set(path, change);
+    }
+    for (const hunk of hunks) {
+        const original = hunk.path;
+        const sourcePath = resolveAgainst(original, cwd);
+        if (hunk.kind === "add") {
+            const existed = await readIfExists(sourcePath);
+            schedule(sourcePath, {
+                path: sourcePath,
+                newContent: hunk.contents,
+                originalContent: existed,
+            });
+            set.added.push(original);
+            continue;
+        }
+        if (hunk.kind === "delete") {
+            const stats = await safeStat(sourcePath);
+            if (!stats)
+                throw new Error(`Failed to delete file: ${sourcePath} not found`);
+            if (stats.isDirectory()) {
+                throw new Error(`Failed to delete file: ${sourcePath} is a directory`);
+            }
+            const content = await readFile(sourcePath, "utf-8");
+            schedule(sourcePath, {
+                path: sourcePath,
+                newContent: null,
+                originalContent: content,
+            });
+            set.deleted.push(original);
+            continue;
+        }
+        // Update (with optional rename).
+        const stats = await safeStat(sourcePath);
+        if (!stats) {
+            throw new Error(`Failed to update file: ${sourcePath} does not exist`);
+        }
+        const originalRaw = await readFile(sourcePath, "utf-8");
+        // CRLF handling: patch context lines are LF (the model emits LF). Match in
+        // LF space, then write back in the file's original EOL so a CRLF file isn't
+        // silently converted to LF (which would diff the whole file). originalText
+        // (LF) is what we compare; originalRaw is preserved for rollback so a
+        // restore writes back the exact bytes. See eol.ts.
+        const eol = detectEol(originalRaw);
+        const originalText = toLf(originalRaw);
+        const newText = applyEol(applyChunksToText(originalText, hunk.chunks, sourcePath), eol);
+        if (hunk.movePath !== undefined) {
+            const destPath = resolveAgainst(hunk.movePath, cwd);
+            if (destPath === sourcePath) {
+                // Rename to self → degenerate update.
+                schedule(sourcePath, {
+                    path: sourcePath,
+                    newContent: newText,
+                    originalContent: originalRaw,
+                });
+            }
+            else {
+                const destOriginal = await readIfExists(destPath);
+                schedule(sourcePath, {
+                    path: sourcePath,
+                    newContent: null,
+                    originalContent: originalRaw,
+                });
+                schedule(destPath, {
+                    path: destPath,
+                    newContent: newText,
+                    originalContent: destOriginal,
+                });
+            }
+            set.modified.push(original);
+        }
+        else {
+            schedule(sourcePath, {
+                path: sourcePath,
+                newContent: newText,
+                originalContent: originalRaw,
+            });
+            set.modified.push(original);
+        }
+    }
+    return set;
+}
+/** Apply the chunk list to a file's text and return the new text. */
+function applyChunksToText(original, chunks, pathForError) {
+    // split('\n') leaves an empty trailing element when the file ends with \n;
+    // drop it so line indices match standard diff semantics. We re-add the
+    // trailing newline at the end.
+    const lines = original.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    // Each replacement: [startIndex, oldLen, newLines]
+    const replacements = [];
+    let lineIndex = 0;
+    for (const chunk of chunks) {
+        if (chunk.changeContext !== undefined) {
+            const found = seekSequence(lines, [chunk.changeContext], lineIndex, false);
+            if (found === null) {
+                throw new Error(`Failed to find context '${chunk.changeContext}' in ${pathForError}`);
+            }
+            lineIndex = found + 1;
+        }
+        if (chunk.oldLines.length === 0) {
+            // Pure addition — append at end. Mirrors codex behavior: even when the
+            // chunk has a `@@ <context>` anchor, pure additions are inserted at
+            // EOF rather than near the anchor. Models should include at least one
+            // `-` or ` ` line if they want positional insertion.
+            const insertionIdx = lines.length > 0 && lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
+            replacements.push([insertionIdx, 0, [...chunk.newLines]]);
+            continue;
+        }
+        let pattern = chunk.oldLines;
+        let newSlice = chunk.newLines;
+        let found = seekSequence(lines, pattern, lineIndex, chunk.isEndOfFile);
+        if (found === null && pattern.length > 0 && pattern[pattern.length - 1] === "") {
+            // Retry without trailing empty sentinel that represents the file's final newline.
+            pattern = pattern.slice(0, -1);
+            if (newSlice.length > 0 && newSlice[newSlice.length - 1] === "") {
+                newSlice = newSlice.slice(0, -1);
+            }
+            found = seekSequence(lines, pattern, lineIndex, chunk.isEndOfFile);
+        }
+        if (found === null) {
+            throw new Error(`Failed to find expected lines in ${pathForError}:\n${chunk.oldLines.join("\n")}`);
+        }
+        replacements.push([found, pattern.length, [...newSlice]]);
+        lineIndex = found + pattern.length;
+    }
+    // Apply in descending start-index order so indices stay valid.
+    replacements.sort((a, b) => a[0] - b[0]);
+    const working = lines.slice();
+    for (let i = replacements.length - 1; i >= 0; i--) {
+        const [start, oldLen, newSeg] = replacements[i];
+        working.splice(start, oldLen, ...newSeg);
+    }
+    // Always end with a trailing newline.
+    if (working.length === 0 || working[working.length - 1] !== "") {
+        working.push("");
+    }
+    return working.join("\n");
+}
+// ─── Phase 2: commit ──────────────────────────────────────────────
+async function commitPlanned(set, allowPartial) {
+    // Iterate insertion order (Map iteration is spec-guaranteed).
+    const ordered = [...set.byPath.values()];
+    if (allowPartial) {
+        for (const change of ordered) {
+            await writeChange(change);
+        }
+        return { added: set.added, modified: set.modified, deleted: set.deleted };
+    }
+    // Track which writes have completed so rollback only touches them. We use
+    // the originalContent captured during plan() rather than re-reading from
+    // disk — this avoids a TOCTOU window between planning and committing.
+    const committed = [];
+    try {
+        for (const change of ordered) {
+            await writeChange(change);
+            committed.push(change);
+        }
+    }
+    catch (err) {
+        for (let i = committed.length - 1; i >= 0; i--) {
+            const c = committed[i];
+            try {
+                if (c.originalContent === null) {
+                    // File did not exist before we wrote it — remove our write.
+                    if (existsSync(c.path))
+                        await unlink(c.path);
+                }
+                else {
+                    await writeFile(c.path, c.originalContent, "utf-8");
+                }
+            }
+            catch {
+                // Best-effort restore — surface the original error to the caller.
+            }
+        }
+        throw err;
+    }
+    return { added: set.added, modified: set.modified, deleted: set.deleted };
+}
+async function writeChange(change) {
+    if (change.newContent === null) {
+        if (existsSync(change.path))
+            await unlink(change.path);
+        return;
+    }
+    const parent = dirname(change.path);
+    if (!existsSync(parent)) {
+        await mkdir(parent, { recursive: true });
+    }
+    await writeFile(change.path, change.newContent, "utf-8");
+}
+// ─── helpers ──────────────────────────────────────────────────────
+/**
+ * Resolve a patch-relative (or absolute) path against cwd, then HARD-ENFORCE
+ * that the result stays inside cwd.
+ *
+ * This is the applier's own containment guard, independent of the executor-level
+ * pathPolicy. apply-patch is reachable with the path gate bypassed (e.g.
+ * bypassPermissions, or a direct call), so the last line of defense lives here.
+ *
+ * Containment is checked against the REAL paths: we realpath cwd and walk the
+ * target up to its nearest existing ancestor and realpath that. This defeats a
+ * symlink planted inside cwd that points outside — a plain string `resolve()`
+ * would look contained while the write follows the link out.
+ */
+function resolveAgainst(p, cwd) {
+    const resolved = isAbsolute(p) ? p : resolve(cwd, p);
+    const realCwd = nearestRealPath(cwd);
+    const realTarget = nearestRealPath(resolved);
+    if (!isInside(realTarget, realCwd)) {
+        throw new Error(`Refusing to apply patch outside the working directory: "${p}" resolves to "${realTarget}", which escapes "${realCwd}".`);
+    }
+    return resolved;
+}
+/**
+ * Realpath the nearest existing ancestor of `abs`, then re-attach the
+ * not-yet-existing trailing segments. Mirrors path-policy.safeRealpath so
+ * symlinked ancestors are resolved even when the leaf doesn't exist yet.
+ */
+function nearestRealPath(abs) {
+    let candidate = abs;
+    const segments = [];
+    for (let i = 0; i < 64; i++) {
+        try {
+            const real = realpathSync(candidate);
+            if (segments.length === 0)
+                return real;
+            return resolve(real, ...segments.reverse());
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return abs;
+            segments.push(candidate.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+            candidate = parent;
+        }
+    }
+    return abs;
+}
+function isInside(child, parent) {
+    if (child === parent)
+        return true;
+    const p = parent.endsWith(sep) ? parent : parent + sep;
+    return child.startsWith(p);
+}
+async function safeStat(path) {
+    try {
+        return await stat(path);
+    }
+    catch {
+        return null;
+    }
+}
+async function readIfExists(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/tools/apply-patch/backup-targets.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Coding capability files an ApplyPatch would modify-in-place or delete — i.e. the files
+ * that already exist and therefore have pre-patch content worth snapshotting
+ * for /undo. Pure (parse-only, no fs): given the patch text and the cwd to
+ * resolve relative paths against, return absolute target paths.
+ *
+ * "add" hunks are excluded: a newly-created file has no prior content to back
+ * up (undo of an add = delete, handled separately if/when /undo grows that).
+ */
+export declare function patchBackupTargets(patchText: string, cwd: string): string[];

package/dist/tools/apply-patch/backup-targets.js

@@ -0,0 +1,30 @@
+/**
+ * Coding capability files an ApplyPatch would modify-in-place or delete — i.e. the files
+ * that already exist and therefore have pre-patch content worth snapshotting
+ * for /undo. Pure (parse-only, no fs): given the patch text and the cwd to
+ * resolve relative paths against, return absolute target paths.
+ *
+ * "add" hunks are excluded: a newly-created file has no prior content to back
+ * up (undo of an add = delete, handled separately if/when /undo grows that).
+ */
+import { resolve as resolvePath } from "node:path";
+import { parsePatch } from "./parser.js";
+export function patchBackupTargets(patchText, cwd) {
+    let parsed;
+    try {
+        parsed = parsePatch(patchText, "lenient");
+    }
+    catch {
+        // Unparseable patch → nothing to back up; the tool itself will reject it.
+        return [];
+    }
+    const out = [];
+    for (const hunk of parsed.hunks) {
+        if (hunk.kind === "update" || hunk.kind === "delete") {
+            out.push(resolvePath(cwd, hunk.path));
+        }
+    }
+    // De-dupe while preserving order (a patch shouldn't target one file twice,
+    // but be defensive — saveSnapshot is idempotent on identical content anyway).
+    return [...new Set(out)];
+}

package/dist/tools/apply-patch/eol.d.ts

@@ -0,0 +1,4 @@
+export type Eol = "\r\n" | "\n";
+export declare function detectEol(content: string): Eol;
+export declare function toLf(content: string): string;
+export declare function applyEol(content: string, eol: Eol): string;

package/dist/tools/apply-patch/eol.js

@@ -0,0 +1,9 @@
+export function detectEol(content) {
+    return content.includes("\r\n") ? "\r\n" : "\n";
+}
+export function toLf(content) {
+    return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+export function applyEol(content, eol) {
+    return eol === "\n" ? content : content.replace(/\n/g, "\r\n");
+}

package/dist/tools/apply-patch/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ApplyPatch tool — atomic, multi-file V4A patch application.
+ *
+ * Adapted from openai/codex codex-rs/apply-patch (Apache-2.0). See LICENSE-codex.
+ *
+ * Compared to Codex's reference implementation:
+ *   - We dry-run all hunks first; nothing is written until every hunk
+ *     successfully resolves.
+ *   - On commit we snapshot every target file, so a write failure rolls back
+ *     to the pre-patch state instead of leaving partial changes.
+ *
+ * Compared to CodeShell's existing Edit:
+ *   - Multi-file in one call (cuts LLM round-trips for large changes).
+ *   - Supports create / update / delete / rename in one transaction.
+ *   - Context-anchor matching tolerates whitespace and Unicode quirks.
+ */
+import { type ToolContext, type ToolDefinition } from "@cjhyy/code-shell-core/extension";
+export { applyPatch } from "./applier.js";
+export declare const applyPatchToolDef: ToolDefinition;
+export declare function applyPatchTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tools/apply-patch/index.js

@@ -0,0 +1,106 @@
+/**
+ * ApplyPatch tool — atomic, multi-file V4A patch application.
+ *
+ * Adapted from openai/codex codex-rs/apply-patch (Apache-2.0). See LICENSE-codex.
+ *
+ * Compared to Codex's reference implementation:
+ *   - We dry-run all hunks first; nothing is written until every hunk
+ *     successfully resolves.
+ *   - On commit we snapshot every target file, so a write failure rolls back
+ *     to the pre-patch state instead of leaving partial changes.
+ *
+ * Compared to CodeShell's existing Edit:
+ *   - Multi-file in one call (cuts LLM round-trips for large changes).
+ *   - Supports create / update / delete / rename in one transaction.
+ *   - Context-anchor matching tolerates whitespace and Unicode quirks.
+ */
+import { invalidateFileCache } from "@cjhyy/code-shell-core/extension";
+import { applyPatch } from "./applier.js";
+import { parsePatch } from "./parser.js";
+import { resolve as resolvePath } from "node:path";
+export { applyPatch } from "./applier.js";
+export const applyPatchToolDef = {
+    name: "ApplyPatch",
+    description: "Apply a V4A-format patch atomically across one or more files. " +
+        "Supports create, update, delete, and rename operations in a single call. " +
+        "If any hunk fails to apply, the entire patch is rejected and no files are modified. " +
+        "Patch envelope:\n" +
+        "  *** Begin Patch\n" +
+        "  *** Add File: <path>\n" +
+        "  +<line>\n" +
+        "  *** Update File: <path>\n" +
+        "  *** Move to: <new path>   # optional rename\n" +
+        "  @@ <context>              # optional anchor\n" +
+        "   <unchanged line>\n" +
+        "  -<removed line>\n" +
+        "  +<added line>\n" +
+        "  *** End of File           # optional, anchors to file end\n" +
+        "  *** Delete File: <path>\n" +
+        "  *** End Patch\n" +
+        "Use relative paths; they resolve against the working directory.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            patch: {
+                type: "string",
+                description: "Full patch text including '*** Begin Patch' and '*** End Patch' markers. " +
+                    "All paths must be relative (preferred) or absolute. " +
+                    "Each Update hunk must include enough context lines (' '-prefixed) " +
+                    "to uniquely locate the change within the file.",
+            },
+        },
+        required: ["patch"],
+    },
+};
+export async function applyPatchTool(args, ctx) {
+    const patchText = args.patch;
+    if (typeof patchText !== "string" || patchText.length === 0) {
+        return "Error: patch is required and must be a non-empty string";
+    }
+    let parsed;
+    try {
+        parsed = parsePatch(patchText, "lenient");
+    }
+    catch (err) {
+        return `Error: ${err.message}`;
+    }
+    if (parsed.hunks.length === 0) {
+        return "Error: patch contains no hunks";
+    }
+    // A4: resolve relative patch paths against the Engine's cwd, not the
+    // host process cwd. See standard §S5.
+    const cwd = ctx?.cwd ?? process.cwd();
+    let result;
+    try {
+        result = await applyPatch(parsed.hunks, { cwd });
+    }
+    catch (err) {
+        return `Error applying patch: ${err.message}`;
+    }
+    // Invalidate file cache for every touched path. The cache is keyed by
+    // ABSOLUTE path (see file-cache.ts), and patch paths are relative to the
+    // Engine cwd — resolve them the same way the path-policy gate did above, or
+    // the stale entry survives and a later Read returns pre-patch content.
+    for (const hunk of parsed.hunks) {
+        invalidateFileCache(resolvePath(cwd, hunk.path));
+        if (hunk.kind === "update" && hunk.movePath) {
+            invalidateFileCache(resolvePath(cwd, hunk.movePath));
+        }
+    }
+    const parts = [];
+    if (result.added.length > 0)
+        parts.push(`added ${result.added.length}`);
+    if (result.modified.length > 0)
+        parts.push(`modified ${result.modified.length}`);
+    if (result.deleted.length > 0)
+        parts.push(`deleted ${result.deleted.length}`);
+    const summary = parts.join(", ");
+    const lines = [`Patch applied successfully — ${summary}`];
+    for (const p of result.added)
+        lines.push(`  A ${p}`);
+    for (const p of result.modified)
+        lines.push(`  M ${p}`);
+    for (const p of result.deleted)
+        lines.push(`  D ${p}`);
+    return lines.join("\n");
+}

package/dist/tools/apply-patch/parser.d.ts

@@ -0,0 +1,17 @@
+import { Hunk } from "./types.js";
+export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
+export declare const END_PATCH_MARKER = "*** End Patch";
+export declare const ADD_FILE_MARKER = "*** Add File: ";
+export declare const DELETE_FILE_MARKER = "*** Delete File: ";
+export declare const UPDATE_FILE_MARKER = "*** Update File: ";
+export declare const MOVE_TO_MARKER = "*** Move to: ";
+export declare const EOF_MARKER = "*** End of File";
+export declare const CHANGE_CONTEXT_MARKER = "@@ ";
+export declare const EMPTY_CHANGE_CONTEXT_MARKER = "@@";
+export interface ParsedPatch {
+    hunks: Hunk[];
+    /** The patch body with any heredoc wrapper stripped. */
+    patch: string;
+}
+export type ParseMode = "strict" | "lenient";
+export declare function parsePatch(text: string, mode?: ParseMode): ParsedPatch;