dsh-patch-edit-plus 0.1.0

package/lib/parse/codex.js

@@ -0,0 +1,189 @@
+/**
+ * Codex `apply_patch` syntax parser.
+ *
+ * Accepts the OpenAI Codex CLI patch grammar:
+ * ```
+ * *** Begin Patch
+ * *** Add File: path
+ * +content lines
+ * *** Update File: path
+ * *** Move to: new-path
+ * @@ optional context label
+ *  context
+ * -removed
+ * +added
+ * *** End of File
+ * *** Delete File: path
+ * *** End Patch
+ * ```
+ * A wrapper (heredoc, code fence, prose) around the markers is tolerated by
+ * slicing from `*** Begin Patch` to the last `*** End Patch`.
+ * @module dsh-patch-edit-plus/parse/codex
+ */
+import { parseError, unrecognizedPatchError } from '../errors.js';
+import { normalizeLines } from './unified.js';
+const BEGIN = '*** Begin Patch';
+const END = '*** End Patch';
+const ADD_FILE = '*** Add File: ';
+const DELETE_FILE = '*** Delete File: ';
+const UPDATE_FILE = '*** Update File: ';
+const MOVE_TO = '*** Move to: ';
+const END_OF_FILE = '*** End of File';
+const ENVIRONMENT_ID = '*** Environment ID:';
+/**
+ * Parse a Codex `apply_patch` patch into the shared IR.
+ * @throws {@link PatchError} code `PARSE` for malformed or unrecognized input.
+ */
+export function parseCodexPatch(patch) {
+    const slice = extractPatchBody(patch);
+    if (slice === null)
+        throw unrecognizedPatchError();
+    const lines = normalizeLines(slice);
+    // normalizeLines dropped the trailing empty element of "*** End Patch\n".
+    if (lines.at(-1) !== END)
+        throw parseError(lines.length, `patch must end with "${END}"`);
+    const ops = [];
+    let index = 1; // skip "*** Begin Patch"
+    while (index < lines.length) {
+        const line = lines[index];
+        const lineNo = index + 1;
+        if (line === END) {
+            index += 1;
+            continue;
+        }
+        if (line.startsWith(ENVIRONMENT_ID)) {
+            throw parseError(lineNo, `${ENVIRONMENT_ID} patches are environment-bound and not supported here; regenerate the patch without an Environment ID`);
+        }
+        if (line.startsWith(ADD_FILE)) {
+            const op = parseAddFile(lines, index);
+            ops.push(op.op);
+            index = op.nextIndex;
+            continue;
+        }
+        if (line.startsWith(DELETE_FILE)) {
+            const path = line.slice(DELETE_FILE.length).trim();
+            if (path === '')
+                throw parseError(lineNo, `${DELETE_FILE}requires a file path`);
+            ops.push({ kind: 'delete', path });
+            index += 1;
+            continue;
+        }
+        if (line.startsWith(UPDATE_FILE)) {
+            const op = parseUpdateFile(lines, index);
+            ops.push(op.op);
+            index = op.nextIndex;
+            continue;
+        }
+        throw parseError(lineNo, `unexpected line "${line.slice(0, 48)}"; expected ${ADD_FILE}/${UPDATE_FILE}/${DELETE_FILE} or ${END}`);
+    }
+    if (ops.length === 0)
+        throw parseError(1, 'patch contains no file operations');
+    return { format: 'codex', ops };
+}
+/**
+ * Slice the patch body out of an optional wrapper: returns the text from
+ * `*** Begin Patch` through the LAST `*** End Patch` line (inclusive), or
+ * `null` when the markers are absent.
+ */
+function extractPatchBody(patch) {
+    const normalized = patch.replaceAll('\r\n', '\n');
+    const begin = normalized.indexOf(BEGIN);
+    if (begin < 0)
+        return null;
+    const endMarker = normalized.lastIndexOf(END);
+    if (endMarker < begin)
+        return null;
+    return normalized.slice(begin, endMarker + END.length);
+}
+function parseAddFile(lines, start) {
+    const path = lines[start].slice(ADD_FILE.length).trim();
+    if (path === '')
+        throw parseError(start + 1, `${ADD_FILE}requires a file path`);
+    const content = [];
+    let index = start + 1;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (line.startsWith('+')) {
+            content.push(line.slice(1));
+            index += 1;
+            continue;
+        }
+        if (line === END || line.startsWith('*** '))
+            break;
+        throw parseError(index + 1, `content lines of "${path}" must start with "+"; got "${line.slice(0, 48)}"`);
+    }
+    return { op: { kind: 'add', path, lines: content, trailingNewline: content.length > 0 }, nextIndex: index };
+}
+function parseUpdateFile(lines, start) {
+    const path = lines[start].slice(UPDATE_FILE.length).trim();
+    if (path === '')
+        throw parseError(start + 1, `${UPDATE_FILE}requires a file path`);
+    let index = start + 1;
+    let moveTo;
+    if (lines[index]?.startsWith(MOVE_TO)) {
+        const target = lines[index].slice(MOVE_TO.length).trim();
+        if (target === '')
+            throw parseError(index + 1, `${MOVE_TO}requires a file path`);
+        moveTo = target;
+        index += 1;
+    }
+    const hunks = [];
+    while (index < lines.length) {
+        const line = lines[index];
+        if (line === END)
+            break;
+        if (line.startsWith(UPDATE_FILE) || line.startsWith(ADD_FILE) || line.startsWith(DELETE_FILE))
+            break;
+        if (!line.startsWith('@@')) {
+            throw parseError(index + 1, `expected an "@@" hunk header inside the update of "${path}"; got "${line.slice(0, 48)}"`);
+        }
+        const label = line.slice(2).trim();
+        const parsed = parseCodexHunk(lines, index + 1, path);
+        hunks.push({ contextLabel: label === '' ? undefined : label, lines: parsed.lines, endOfFile: parsed.endOfFile });
+        index = parsed.nextIndex;
+    }
+    if (hunks.length === 0) {
+        // A bare `Update File` + `Move to` without hunks is a pure rename.
+        if (moveTo === undefined)
+            throw parseError(start + 1, `update of "${path}" contains no hunks`);
+    }
+    return { op: { kind: 'update', path, moveTo, hunks }, nextIndex: index };
+}
+function parseCodexHunk(lines, start, path) {
+    const result = [];
+    let endOfFile = false;
+    let index = start;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (line === END_OF_FILE) {
+            endOfFile = true;
+            index += 1;
+            break;
+        }
+        if (line === END)
+            break;
+        if (line.startsWith('@@'))
+            break;
+        if (line.startsWith('*** '))
+            break;
+        const marker = line.charAt(0);
+        const text = line.slice(1);
+        if (marker === ' ')
+            result.push({ kind: 'context', text });
+        else if (marker === '-')
+            result.push({ kind: 'delete', text });
+        else if (marker === '+')
+            result.push({ kind: 'add', text });
+        else if (line === '')
+            result.push({ kind: 'context', text: '' });
+        else
+            throw parseError(index + 1, `hunk lines of "${path}" must start with " ", "-", or "+"; got "${line.slice(0, 48)}"`);
+        index += 1;
+    }
+    if (result.length === 0)
+        throw parseError(start + 1, `hunk of "${path}" is empty`);
+    if (result.every(line => line.kind === 'context')) {
+        throw parseError(start + 1, `hunk of "${path}" contains no changes (context lines only)`);
+    }
+    return { lines: result, endOfFile, nextIndex: index };
+}

package/lib/parse/types.js

@@ -0,0 +1,9 @@
+/**
+ * Unified intermediate representation shared by both patch parsers.
+ *
+ * The unified-diff parser and the Codex `apply_patch` parser both emit
+ * `ParsedPatch`; downstream planning and application see a single shape so
+ * there is exactly one apply path regardless of the input dialect.
+ * @module dsh-patch-edit-plus/parse/types
+ */
+export {};

package/lib/parse/unified.js

@@ -0,0 +1,243 @@
+/**
+ * Git / unified diff parser.
+ *
+ * Produces the shared IR (`ParsedPatch`). Accepts full git diffs (with
+ * `diff --git` headers, mode lines and rename detection) and bare unified
+ * diffs (`---`/`+++` + hunks). Parsing is strict: malformed input raises
+ * `PatchError`('PARSE') with a 1-based line number, never a best-effort guess.
+ * @module dsh-patch-edit-plus/parse/unified
+ */
+import { parseError, unrecognizedPatchError } from '../errors.js';
+/** Normalize CRLF/CR to LF and split into lines. */
+export function normalizeLines(text) {
+    const normalized = text.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+    if (normalized === '')
+        return [];
+    const lines = normalized.split('\n');
+    // A trailing newline yields a final empty element; that is not a line.
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+}
+/** Strip `a/`/`b/` prefixes and quotes from a git header path. */
+function stripPrefix(raw) {
+    let path = raw;
+    if (path.startsWith('"') && path.endsWith('"') && path.length >= 2) {
+        path = path.slice(1, -1).replaceAll('\\"', '"').replaceAll('\\\\', '\\');
+    }
+    if (path.startsWith('a/') || path.startsWith('b/'))
+        path = path.slice(2);
+    return path;
+}
+/** True when the path token means "no file" (add or delete). */
+function isDevNull(path) {
+    return path === '/dev/null' || path === 'a/dev/null' || path === 'b/dev/null';
+}
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+/**
+ * Parse a git/unified diff into the shared IR.
+ * @throws {@link PatchError} code `PARSE` for any malformed or unrecognized input.
+ */
+export function parseUnifiedDiff(patch) {
+    const lines = normalizeLines(patch);
+    if (lines.length === 0)
+        throw unrecognizedPatchError();
+    const sections = [];
+    let current = null;
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        const lineNo = index + 1;
+        if (line.startsWith('diff --git ')) {
+            current = { oldPath: null, newPath: null, newFile: false, deletedFile: false, renameFrom: null, renameTo: null, hunks: [], startLine: lineNo };
+            sections.push(current);
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('--- ')) {
+            if (current === null) {
+                // Bare unified diff without a git header: open an implicit section.
+                current = { oldPath: null, newPath: null, newFile: false, deletedFile: false, renameFrom: null, renameTo: null, hunks: [], startLine: lineNo };
+                sections.push(current);
+            }
+            const token = line.slice(4).trim();
+            current.oldPath = isDevNull(token) ? null : stripPrefix(token);
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            if (current === null)
+                throw parseError(lineNo, '+++ header without a preceding --- header');
+            const token = line.slice(4).trim();
+            current.newPath = isDevNull(token) ? null : stripPrefix(token);
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('new file mode')) {
+            if (current === null)
+                throw parseError(lineNo, 'mode line outside a file section');
+            current.newFile = true;
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('deleted file mode')) {
+            if (current === null)
+                throw parseError(lineNo, 'mode line outside a file section');
+            current.deletedFile = true;
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('rename from ')) {
+            if (current === null)
+                throw parseError(lineNo, 'rename line outside a file section');
+            current.renameFrom = stripPrefix(line.slice(12).trim());
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('rename to ')) {
+            if (current === null)
+                throw parseError(lineNo, 'rename line outside a file section');
+            current.renameTo = stripPrefix(line.slice(10).trim());
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('old mode ') || line.startsWith('new mode ') || line.startsWith('similarity index ')
+            || line.startsWith('dissimilarity index ') || line.startsWith('index ')) {
+            if (current === null)
+                throw parseError(lineNo, `"${line.slice(0, 24)}" outside a file section`);
+            index += 1;
+            continue;
+        }
+        if (line.startsWith('Binary files ') || line === 'GIT binary patch') {
+            throw parseError(lineNo, 'binary patches are not supported; apply the change to the text file instead');
+        }
+        if (line.startsWith('@@')) {
+            if (current === null)
+                throw parseError(lineNo, 'hunk header outside a file section');
+            const hunk = parseHunkHeader(line, lineNo);
+            index += 1;
+            const body = parseHunkBody(lines, index, hunk);
+            index = body.nextIndex;
+            current.hunks.push({ oldStart: hunk.oldStart, lines: body.lines, endOfFile: false, oldNoNewline: body.oldNoNewline, newNoNewline: body.newNoNewline });
+            continue;
+        }
+        // Unknown content: only tolerated as section noise inside a section.
+        if (current === null)
+            throw unrecognizedPatchError();
+        throw parseError(lineNo, `unexpected line "${line.slice(0, 48)}"`);
+    }
+    if (sections.length === 0)
+        throw unrecognizedPatchError();
+    return { format: 'unified', ops: sections.map(toOp) };
+}
+function parseHunkHeader(line, lineNo) {
+    const match = HUNK_HEADER.exec(line);
+    if (match === null)
+        throw parseError(lineNo, `malformed hunk header "${line.slice(0, 48)}"`);
+    const oldStart = Number(match[1]);
+    const oldCount = match[2] === undefined ? 1 : Number(match[2]);
+    const newStart = Number(match[3]);
+    const newCount = match[4] === undefined ? 1 : Number(match[4]);
+    if (!Number.isSafeInteger(oldStart) || !Number.isSafeInteger(newStart)) {
+        throw parseError(lineNo, 'hunk header line numbers out of range');
+    }
+    return { oldStart, oldCount, newStart, newCount };
+}
+function parseHunkBody(lines, start, header) {
+    const result = [];
+    let oldSeen = 0;
+    let newSeen = 0;
+    let oldNoNewline = false;
+    let newNoNewline = false;
+    let index = start;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (oldSeen >= header.oldCount && newSeen >= header.newCount
+            && (line.startsWith('diff --git ') || line.startsWith('@@') || line.startsWith('--- ') || line.startsWith('*** ')))
+            break;
+        if (line.startsWith('\\')) {
+            // "" — applies to the side of the most
+            // recent body line: after `-` it marks the old tail, after `+` the new
+            // tail, after a context line both.
+            if (result.length === 0)
+                throw parseError(index + 1, '\\ "no newline" marker before any hunk line');
+            const previous = result.at(-1);
+            if (previous?.kind === 'delete')
+                oldNoNewline = true;
+            else if (previous?.kind === 'add')
+                newNoNewline = true;
+            else {
+                oldNoNewline = true;
+                newNoNewline = true;
+            }
+            index += 1;
+            continue;
+        }
+        const marker = line.charAt(0);
+        const text = line.slice(1);
+        if (marker === ' ' && (oldSeen < header.oldCount || newSeen < header.newCount)) {
+            result.push({ kind: 'context', text });
+            oldSeen += 1;
+            newSeen += 1;
+        }
+        else if (marker === '-') {
+            result.push({ kind: 'delete', text });
+            oldSeen += 1;
+        }
+        else if (marker === '+') {
+            result.push({ kind: 'add', text });
+            newSeen += 1;
+        }
+        else if (marker === '' && oldSeen < header.oldCount && newSeen < header.newCount) {
+            // A genuinely empty context line whose leading space was stripped.
+            result.push({ kind: 'context', text: '' });
+            oldSeen += 1;
+            newSeen += 1;
+        }
+        else {
+            throw parseError(index + 1, `unexpected hunk line "${line.slice(0, 48)}"`);
+        }
+        index += 1;
+    }
+    if (oldSeen !== header.oldCount || newSeen !== header.newCount) {
+        throw parseError(start + 1, `hunk header counts (old ${header.oldCount}, new ${header.newCount}) do not match the hunk body (old ${oldSeen}, new ${newSeen})`);
+    }
+    if (result.every(line => line.kind === 'context')) {
+        throw parseError(start + 1, 'hunk contains no changes (context lines only)');
+    }
+    return { lines: result, oldNoNewline, newNoNewline, nextIndex: index };
+}
+function assertPlainPath(path, lineNo) {
+    if (path === null)
+        throw parseError(lineNo, 'file section without a usable path');
+    return path;
+}
+/** Convert one parsed file section into an IR operation. */
+function toOp(section) {
+    const headerLine = section.startLine;
+    const oldPath = section.oldPath ?? section.renameFrom;
+    const newPath = section.newPath ?? section.renameTo;
+    if (section.newFile || (section.oldPath === null && section.newPath !== null)) {
+        const path = assertPlainPath(newPath, headerLine);
+        const addLines = [];
+        for (const hunk of section.hunks) {
+            for (const line of hunk.lines) {
+                if (line.kind === 'add')
+                    addLines.push(line.text);
+                else if (line.kind === 'delete')
+                    throw parseError(headerLine, `new-file section for "${path}" contains delete lines`);
+            }
+        }
+        const lastNewNoNewline = section.hunks.at(-1)?.newNoNewline ?? false;
+        return { kind: 'add', path, lines: addLines, trailingNewline: addLines.length === 0 ? false : !lastNewNoNewline };
+    }
+    if (section.deletedFile || (section.newPath === null && section.oldPath !== null)) {
+        const path = assertPlainPath(oldPath, headerLine);
+        return { kind: 'delete', path };
+    }
+    const path = assertPlainPath(oldPath, headerLine);
+    const moveTo = newPath !== null && newPath !== path
+        ? newPath
+        : section.renameTo !== null && section.renameTo !== path ? section.renameTo : undefined;
+    return { kind: 'update', path, moveTo, hunks: section.hunks };
+}

package/lib/register.js

@@ -0,0 +1,60 @@
+/**
+ * Tool registration with three-layer name-conflict protection.
+ *
+ * Layer 1: probe `ctx.tools.get(name)` before building the definition.
+ * Layer 2: `conflictPolicy` — `rename` (default) retries suffixed names,
+ * `skip` logs and loads without the tool, `fail` throws.
+ * Layer 3: `try/catch` around `register()` because get-then-register races.
+ * @module dsh-patch-edit-plus/register
+ */
+import { PatchError } from './errors.js';
+import { buildApplyPatchTool } from './tool.js';
+const MAX_RENAME_ATTEMPTS = 9;
+/**
+ * Resolve an unused tool name and register the frozen definition.
+ * @returns the registration disposer, or `null` when registration was skipped.
+ * @throws {@link PatchError} only under `conflictPolicy: 'fail'`.
+ */
+export function registerApplyPatchTool(ctx, cfg, logger) {
+    const log = logger ?? resolveLogger(ctx);
+    const tools = ctx.tools;
+    const base = cfg.toolName;
+    let resolvedName = base;
+    if (tools.get(resolvedName) !== undefined) {
+        if (cfg.conflictPolicy === 'skip') {
+            log.error?.(`dsh-patch-edit-plus: tool name "${base}" is already registered; conflictPolicy is "skip", so no tool was registered. `);
+            return null;
+        }
+        if (cfg.conflictPolicy === 'fail') {
+            throw new PatchError('CONFLICT', `Tool name "${base}" is already registered. Set a different dsh-patch-edit-plus toolName, or change conflictPolicy to "rename" (default) or "skip".`);
+        }
+        // rename
+        const suffix = cfg.renameSuffix;
+        let found = null;
+        for (let attempt = 1; attempt <= MAX_RENAME_ATTEMPTS && found === null; attempt += 1) {
+            const candidate = attempt === 1 ? `${base}${suffix}` : `${base}${suffix}${attempt}`;
+            if (tools.get(candidate) === undefined)
+                found = candidate;
+        }
+        if (found === null) {
+            throw new PatchError('CONFLICT', `Could not find a free tool name for "${base}" after ${MAX_RENAME_ATTEMPTS} rename attempts. Set an explicit dsh-patch-edit-plus toolName.`);
+        }
+        log.warn?.(`dsh-patch-edit-plus: tool name "${base}" is already registered; registering as "${found}" instead.`);
+        resolvedName = found;
+    }
+    const definition = buildApplyPatchTool(resolvedName, ctx, cfg);
+    try {
+        return tools.register(definition);
+    }
+    catch (error) {
+        if (cfg.conflictPolicy === 'fail')
+            throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        log.error?.(`dsh-patch-edit-plus: registering tool "${resolvedName}" failed (${detail}). The plugin stays loaded without the tool; set a unique toolName to resolve the conflict.`);
+        return null;
+    }
+}
+function resolveLogger(ctx) {
+    const candidate = ctx.logger;
+    return typeof candidate === 'object' && candidate !== null ? candidate : {};
+}

package/lib/shellops.js

@@ -0,0 +1,111 @@
+/**
+ * Shell seam for Delete / Move (the `ctx.fs` contract has no delete/rename).
+ *
+ * Security posture:
+ * - Command templates are CONSTANTS; paths travel only via the environment
+ *   (`DSH_PATCH_SOURCE` / `DSH_PATCH_TARGET`), never interpolated into the
+ *   command string — shell metacharacters in a path cannot inject commands.
+ * - Every run carries a `sandboxPolicy` so sandboxing executors fence it, and
+ *   the reported `ShellSandboxInfo` distinguishes "policy denied" from
+ *   "command failed".
+ * @module dsh-patch-edit-plus/shellops
+ */
+import { PatchError, unsupportedShellError } from './errors.js';
+/** Constant POSIX templates; paths arrive via env, never via interpolation. */
+export const POSIX_REMOVE = 'rm -f -- "$DSH_PATCH_TARGET"';
+export const POSIX_MOVE = 'mv -f -- "$DSH_PATCH_SOURCE" "$DSH_PATCH_TARGET"';
+/** Constant PowerShell templates (Windows default). */
+export const PWSH_REMOVE = 'Remove-Item -LiteralPath $env:DSH_PATCH_TARGET -Force';
+export const PWSH_MOVE = 'Move-Item -LiteralPath $env:DSH_PATCH_SOURCE -Destination $env:DSH_PATCH_TARGET -Force';
+const SHELL_TIMEOUT_MS = 30_000;
+/** Resolve the configured dialect; `auto` picks pwsh on win32, posix elsewhere. */
+export function resolveDialect(cfg) {
+    if (cfg.shellDialect === 'auto')
+        return process.platform === 'win32' ? 'pwsh' : 'posix';
+    return cfg.shellDialect;
+}
+/** The constant delete template for the resolved dialect (config override wins). */
+export function deleteTemplate(cfg) {
+    return cfg.deleteCommand ?? (resolveDialect(cfg) === 'pwsh' ? PWSH_REMOVE : POSIX_REMOVE);
+}
+/** The constant move template for the resolved dialect (config override wins). */
+export function moveTemplate(cfg) {
+    return cfg.moveCommand ?? (resolveDialect(cfg) === 'pwsh' ? PWSH_MOVE : POSIX_MOVE);
+}
+/** Structurally resolve `ctx.shell` without assuming the service is mounted. */
+export function resolveShell(ctx) {
+    try {
+        const shell = ctx.shell;
+        return shell !== undefined && typeof shell.run === 'function' && typeof shell.resolve === 'function' ? shell : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when Delete/Move can run at all under the current configuration. */
+export function shellReady(ctx, cfg) {
+    return cfg.deleteBackend === 'shell' && resolveShell(ctx) !== undefined;
+}
+/** Throw the precise structured UNSUPPORTED error when Delete/Move cannot run. */
+export function assertShellReady(ctx, cfg) {
+    if (cfg.deleteBackend !== 'shell') {
+        throw unsupportedShellError('Delete/Move operations are disabled by configuration (deleteBackend: "none").');
+    }
+    if (resolveShell(ctx) === undefined) {
+        throw unsupportedShellError('Delete/Move operations need a shell capability, but no shell executor is mounted in this session.');
+    }
+}
+/** Remove one file via the sandbox-aware shell. */
+export async function removeFile(ctx, exec, cfg, target, sandboxPolicy) {
+    const shell = requireShell(ctx, cfg);
+    const request = {
+        command: deleteTemplate(cfg),
+        env: { DSH_PATCH_TARGET: ctx.fs.processPath(target) },
+        signal: exec.signal,
+        timeoutMs: SHELL_TIMEOUT_MS,
+        sandboxPolicy,
+    };
+    const result = await runShell(shell, request);
+    interpretResult(result, 'delete', target.displayPath);
+}
+/** Move (rename) one file via the sandbox-aware shell. */
+export async function moveFile(ctx, exec, cfg, source, target, sandboxPolicy) {
+    const shell = requireShell(ctx, cfg);
+    const request = {
+        command: moveTemplate(cfg),
+        env: { DSH_PATCH_SOURCE: ctx.fs.processPath(source), DSH_PATCH_TARGET: ctx.fs.processPath(target) },
+        signal: exec.signal,
+        timeoutMs: SHELL_TIMEOUT_MS,
+        sandboxPolicy,
+    };
+    const result = await runShell(shell, request);
+    interpretResult(result, 'move', `${source.displayPath} -> ${target.displayPath}`);
+}
+function requireShell(ctx, cfg) {
+    assertShellReady(ctx, cfg);
+    return resolveShell(ctx);
+}
+async function runShell(shell, request) {
+    try {
+        return await shell.run(shell.resolve(request));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PatchError('IO', `shell execution failed: ${detail}`);
+    }
+}
+/** Distinguish "sandbox policy denied" from "the command itself failed". */
+function interpretResult(result, verb, subject) {
+    if (result.sandbox?.denied === true) {
+        const mode = result.sandbox.mode ?? 'unknown';
+        throw new PatchError('VALIDATION', `The sandbox denied the ${verb} of "${subject}" (mode: ${mode}). `
+            + 'The path is likely outside the writable workspace. Ask the user for a wider permission preset, or apply the change manually.');
+    }
+    if (result.aborted || result.signal !== null) {
+        throw new PatchError('IO', `The ${verb} of "${subject}" was aborted before it completed.`);
+    }
+    if (result.exitCode !== 0) {
+        const stderrTail = result.stderr.text.trim().split('\n').at(-1) ?? '';
+        throw new PatchError('IO', `The ${verb} of "${subject}" failed with exit code ${result.exitCode ?? 'null'}${stderrTail === '' ? '' : `: ${stderrTail.slice(0, 200)}`}`);
+    }
+}