dsh-patch-edit-plus 0.1.0

package/lib/tool.js

@@ -0,0 +1,208 @@
+/**
+ * The single model-facing `apply_patch` tool definition.
+ *
+ * The description carries an explicit routing guide so the model reaches for
+ * the native `edit` tool on cheap single-point changes instead of paying for
+ * a patch, and reserves `apply_patch` for large-file small edits, cross-file
+ * batch edits, creation, deletion and renames.
+ * @module dsh-patch-edit-plus/tool
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { PatchError, codexDisabledError, limitError, unifiedDisabledError } from './errors.js';
+import { detectFormat } from './detect.js';
+import { parseCodexPatch } from './parse/codex.js';
+import { parseUnifiedDiff } from './parse/unified.js';
+import { buildPlan } from './apply/plan.js';
+import { applyPatch, verifyPatch } from './apply/engine.js';
+const ROUTING_GUIDE = [
+    'When to use which editing tool:',
+    '- Single small change in ONE already-read file: prefer the native edit tool (cheaper than a patch).',
+    '- apply_patch is the right choice when: (a) a SMALL change sits inside a LARGE file (a patch avoids echoing the whole file), '
+        + '(b) the same call must change MANY files at once (batch), (c) a new file with substantial content is created, '
+        + '(d) a file is deleted or renamed, or (e) several disjoint spots in one file change at once.',
+    '- Do not use apply_patch for trivial one-line single-file edits when the native edit tool is available.',
+].join('\n');
+/**
+ * Build the (frozen) tool definition. The tool name is passed in resolved
+ * form so registration-side rename avoidance can mint variant names.
+ */
+export function buildApplyPatchTool(toolName, ctx, cfg) {
+    const styles = [
+        cfg.allowUnifiedDiff ? 'git/unified diff (default)' : null,
+        cfg.allowCodexPatch ? 'Codex apply_patch syntax' : null,
+    ].filter(style => style !== null).join(' and ');
+    const definition = defineTool({
+        name: toolName,
+        description: `Apply a patch-style change to one or more text files, all-or-nothing: every hunk is verified against current file content first, and nothing is written unless the whole patch applies. Accepts ${styles}. `
+            + 'Add, update (multi-hunk), delete and move/rename operations are supported. Pass dryRun: true to validate without writing.\n' + ROUTING_GUIDE,
+        parameters: {
+            patch: { type: 'string', required: true, description: 'The full patch text in an accepted style.' },
+            dryRun: { type: 'boolean', description: 'Validate the patch and report what would change, without writing.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    format: { type: 'string', required: true, enum: ['unified', 'codex'] },
+                    applied: { type: 'boolean', required: true },
+                    summary: { type: 'string', required: true },
+                    files: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                path: { type: 'string', required: true },
+                                action: { type: 'string', required: true, enum: ['added', 'modified', 'deleted'] },
+                                from: { type: 'string', description: 'Original path when the file was moved or renamed.' },
+                            },
+                        },
+                    },
+                    stats: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: true,
+                        properties: {
+                            files: { type: 'number', required: true },
+                            added: { type: 'number', required: true },
+                            removed: { type: 'number', required: true },
+                        },
+                    },
+                    wallTimeMs: { type: 'number', required: true },
+                    diffs: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                path: { type: 'string', required: true },
+                                oldText: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
+                                newText: { type: 'string', required: true },
+                                truncated: { type: 'boolean', description: 'Diff content dropped because it exceeded maxDiffBytes.' },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: formatResultText(value) }],
+            presentationMeta: (_args, value) => ({ diffs: value.diffs }),
+        },
+        async execute(args, exec) {
+            const start = Date.now();
+            const patch = args.patch;
+            if (typeof patch !== 'string' || patch.trim() === '') {
+                throw new PatchError('VALIDATION', 'parameter "patch" must be a non-empty string containing the patch text');
+            }
+            if (patch.length > cfg.maxPatchBytes) {
+                throw limitError('patch size in bytes', patch.length, cfg.maxPatchBytes);
+            }
+            const format = detectFormat(patch);
+            if (format === 'codex' && !cfg.allowCodexPatch)
+                throw codexDisabledError();
+            if (format === 'unified' && !cfg.allowUnifiedDiff)
+                throw unifiedDisabledError();
+            const parsed = format === 'codex' ? parseCodexPatch(patch) : parseUnifiedDiff(patch);
+            const dryRun = typeof args.dryRun === 'boolean'
+                ? args.dryRun
+                : cfg.dryRunByDefault;
+            const plan = await buildPlan(ctx, exec, parsed, cfg);
+            const changes = await verifyPatch(ctx, exec, plan, cfg);
+            if (!dryRun) {
+                const sandboxPolicy = undefined;
+                await applyPatch(ctx, exec, changes, cfg, sandboxPolicy);
+            }
+            return buildResult(format, !dryRun, changes, cfg, Date.now() - start);
+        },
+        presentCall: (args) => ({
+            card: 'generic',
+            title: 'Apply patch',
+            kind: 'other',
+            rawInput: args.patch,
+        }),
+        presentResult: (_args, result) => {
+            if (result.isError)
+                return undefined;
+            const diffs = extractDiffs(result.meta);
+            if (diffs.length === 0)
+                return { card: 'generic', title: 'Applied patch' };
+            return { card: 'diff', title: 'Applied patch', diffs };
+        },
+    });
+    return Object.freeze(definition);
+}
+/** Narrow the persisted presentation meta back to diffs (nested dispatch has no meta). */
+function extractDiffs(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return [];
+    const candidate = meta.diffs;
+    if (!Array.isArray(candidate))
+        return [];
+    const diffs = candidate.filter((item) => typeof item === 'object' && item !== null
+        && typeof item.path === 'string'
+        && typeof item.newText === 'string');
+    return diffs;
+}
+/** Build the canonical result value (grouped Codex-style + capped diffs). */
+function buildResult(format, applied, changes, cfg, wallTimeMs) {
+    const files = [];
+    let added = 0;
+    let removed = 0;
+    const diffs = [];
+    for (const change of changes) {
+        const { op } = change.entry;
+        if (op.kind === 'add') {
+            added += op.lines.length;
+            files.push({ path: op.path, action: 'added' });
+            diffs.push(cappedDiff(op.path, null, change.after ?? '', cfg.maxDiffBytes));
+            continue;
+        }
+        if (op.kind === 'delete') {
+            removed += change.before === null ? 0 : change.before.split('\n').length;
+            files.push({ path: op.path, action: 'deleted' });
+            diffs.push(cappedDiff(op.path, change.before ?? '', '', cfg.maxDiffBytes));
+            continue;
+        }
+        const moved = change.entry.moveToTarget !== undefined;
+        files.push(moved
+            ? { path: op.moveTo ?? op.path, action: 'modified', from: op.path }
+            : { path: op.path, action: 'modified' });
+        if (change.before !== null && change.after !== null && !(moved && change.after === change.before)) {
+            for (const hunk of op.hunks) {
+                added += hunk.lines.filter(line => line.kind === 'add').length;
+                removed += hunk.lines.filter(line => line.kind === 'delete').length;
+            }
+            diffs.push(cappedDiff(moved ? op.moveTo ?? op.path : op.path, change.before, change.after, cfg.maxDiffBytes));
+        }
+    }
+    const groups = (action) => files.filter(file => file.action === action);
+    const verb = applied ? 'Applied patch' : 'Dry run: the patch applies cleanly';
+    const summary = `${verb}: ${files.length} file(s), ${groups('added').length} added, ${groups('modified').length} modified, ${groups('deleted').length} deleted, +${added} -${removed} lines`;
+    return { format, applied, summary, files, stats: { files: files.length, added, removed }, wallTimeMs, diffs };
+}
+/** Cap one file diff: over the limit the contents are emptied and the entry marked truncated. */
+function cappedDiff(path, oldText, newText, maxDiffBytes) {
+    if (oldText === null && newText === '')
+        return { path, oldText: null, newText: '' };
+    const size = (oldText?.length ?? 0) + newText.length;
+    if (size > maxDiffBytes)
+        return { path, oldText: null, newText: '', truncated: true };
+    return { path, oldText, newText };
+}
+/** Model-facing text: grouped added → modified → deleted listing. */
+export function formatResultText(value) {
+    const lines = [value.summary];
+    const group = (action, letter) => {
+        for (const file of value.files.filter(f => f.action === action)) {
+            lines.push(`${letter} ${file.path}${file.from !== undefined ? ` (from ${file.from})` : ''}`);
+        }
+    };
+    group('added', 'A');
+    group('modified', 'M');
+    group('deleted', 'D');
+    if (!value.applied)
+        lines.push('Nothing was written (dry run).');
+    return lines.join('\n');
+}

package/lib/types/apply/engine.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Two-phase atomic application engine.
+ *
+ * Phase 1 (verify) reads every target and computes the full in-memory result;
+ * ANY failure aborts the whole patch with zero bytes written. Phase 2 (apply)
+ * only writes what verify already validated.
+ * @module dsh-patch-edit-plus/apply/engine
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { ResolvedConfig } from '../config.js';
+import type { Hunk } from '../parse/types.js';
+import { consumedLines } from './seek.js';
+import type { PlannedEntry, PlannedPatch } from './plan.js';
+/** One verified, ready-to-write change. */
+export interface VerifiedChange {
+    entry: PlannedEntry;
+    /** Original content; `null` for adds. */
+    before: string | null;
+    /** Computed new content; `null` for deletes. */
+    after: string | null;
+}
+/**
+ * Verify the whole patch: read every file, locate every hunk, compute every
+ * result. Throws on the first failure — nothing has been written.
+ */
+export declare function verifyPatch(ctx: Context, exec: ToolRunContext, plan: PlannedPatch, cfg: ResolvedConfig): Promise<VerifiedChange[]>;
+/** Apply phase: writes only — verify already settled every decision. */
+export declare function applyPatch(ctx: Context, exec: ToolRunContext, changes: readonly VerifiedChange[], cfg: ResolvedConfig, sandboxPolicy: SandboxExecutionPolicy | undefined): Promise<void>;
+/** Pure-move entries (update with moveTo and no hunks) skip the write. */
+export declare function isPureMove(change: VerifiedChange): boolean;
+/**
+ * Apply hunks to raw file content with newline fidelity: CRLF files are
+ * normalized for matching and written back in their original style; the
+ * trailing-newline state of the file tail is preserved exactly.
+ */
+export declare function applyHunksToContent(path: string, before: string, hunks: readonly Hunk[]): string;
+export { consumedLines };

package/lib/types/apply/plan.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Operation planning: path resolution, workspace containment, symlink policy
+ * and duplicate detection. Pure resolution work — no file content is read
+ * here (the engine's verify stage does that).
+ * @module dsh-patch-edit-plus/apply/plan
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { FsTarget } from '@deepseek-ai/dsh-fs';
+import type { ResolvedConfig } from '../config.js';
+import type { ParsedPatch, PatchOp } from '../parse/types.js';
+/** One planned, fully-resolved operation. */
+export interface PlannedEntry {
+    op: PatchOp;
+    /** Resolved target of `op.path`. */
+    target: FsTarget;
+    /** Resolved move destination, when the operation renames/moves the file. */
+    moveToTarget?: FsTarget;
+}
+/** A fully planned patch: every path resolved and validated, nothing touched. */
+export interface PlannedPatch {
+    format: 'unified' | 'codex';
+    entries: PlannedEntry[];
+}
+/**
+ * Plan a parsed patch against the filesystem backend.
+ * @throws {@link PatchError} on limits, path escapes, symlinks, missing parents or duplicate targets.
+ */
+export declare function buildPlan(ctx: Context, exec: ToolRunContext, parsed: ParsedPatch, cfg: ResolvedConfig): Promise<PlannedPatch>;
+/** True when the operation needs the shell backend (delete or move). */
+export declare function needsShell(op: PatchOp): boolean;

package/lib/types/apply/seek.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Context-line location with three tolerance levels.
+ *
+ * Levels, tried in order over the whole search window (exact matches always
+ * win over trimmed ones): exact equality → `trimEnd` → full `trim`. Only the
+ * context/remove lines participate; add lines are insertions and never
+ * constrain the position.
+ * @module dsh-patch-edit-plus/apply/seek
+ */
+import type { PatchLine } from '../parse/types.js';
+/** Locate `expected` inside `fileLines` starting at `from`. Returns the match index or `null`. */
+export declare function findSequence(fileLines: readonly string[], expected: readonly PatchLine[], from: number, opts?: {
+    endOfFile?: boolean;
+}): number | null;
+/**
+ * Number of old-side lines a hunk consumes at its match position
+ * (context + delete lines).
+ */
+export declare function consumedLines(hunk: {
+    lines: readonly PatchLine[];
+}): number;

package/lib/types/config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Plugin configuration: Schemastery schema + resolved defaults.
+ *
+ * Every knob the tool honors lives here; the tool body only ever reads the
+ * fully-resolved `ResolvedConfig` produced by `resolveConfig`.
+ * @module dsh-patch-edit-plus/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** What to do when the configured tool name is already taken at registration. */
+export type ConflictPolicy = 'rename' | 'skip' | 'fail';
+/** Backend used for Delete/Move operations (`ctx.fs` has no delete/move). */
+export type DeleteBackend = 'shell' | 'none';
+/** Shell command dialect for the constant delete/move templates. */
+export type ShellDialect = 'auto' | 'posix' | 'pwsh';
+/** Deployment-owned configuration. */
+export interface Config {
+    /** Model-facing tool name. Defaults to `apply_patch`. */
+    toolName?: string;
+    /** Behavior when the tool name is already registered. Defaults to `rename`. */
+    conflictPolicy?: ConflictPolicy;
+    /** Suffix appended on rename avoidance. Defaults to `_1`. */
+    renameSuffix?: string;
+    /** Accept git/unified diff patches. Defaults to true. */
+    allowUnifiedDiff?: boolean;
+    /** Accept Codex `apply_patch` syntax. Defaults to false. */
+    allowCodexPatch?: boolean;
+    /** Delete/Move backend. Defaults to `shell`. `none` rejects Delete/Move with a structured error. */
+    deleteBackend?: DeleteBackend;
+    /** Shell dialect for the constant delete/move templates. Defaults to `auto` (pwsh on win32). */
+    shellDialect?: ShellDialect;
+    /** Custom delete command template; paths still arrive only via env `DSH_PATCH_TARGET`. */
+    deleteCommand?: string;
+    /** Custom move command template; paths arrive via env `DSH_PATCH_SOURCE`/`DSH_PATCH_TARGET`. */
+    moveCommand?: string;
+    /** Treat `apply_patch` calls as dry runs unless the call passes `dryRun: false`. Defaults to false. */
+    dryRunByDefault?: boolean;
+    /** Allow patch paths to traverse symbolic links. Defaults to false (symlinks are rejected). */
+    followSymlinks?: boolean;
+    /** Maximum file sections per patch. Defaults to 50. */
+    maxFiles?: number;
+    /** Maximum patch text size in bytes. Defaults to 524288 (512 KiB). */
+    maxPatchBytes?: number;
+    /** Maximum per-file diff size in bytes carried in the result metadata. Defaults to 16384. */
+    maxDiffBytes?: number;
+}
+/** Schemastery schema for Loader defaults and generated configuration docs. */
+export declare const Config: z<Config>;
+/** Fully-resolved configuration used by the tool body. */
+export interface ResolvedConfig {
+    toolName: string;
+    conflictPolicy: ConflictPolicy;
+    renameSuffix: string;
+    allowUnifiedDiff: boolean;
+    allowCodexPatch: boolean;
+    deleteBackend: DeleteBackend;
+    shellDialect: ShellDialect;
+    deleteCommand?: string;
+    moveCommand?: string;
+    dryRunByDefault: boolean;
+    followSymlinks: boolean;
+    maxFiles: number;
+    maxPatchBytes: number;
+    maxDiffBytes: number;
+}
+/** Fill user config with defaults; `undefined`/null entries fall back too. */
+export declare function resolveConfig(config: Config | undefined): ResolvedConfig;

package/lib/types/detect.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Patch format detection.
+ *
+ * Runs BEFORE any parser so a recognized-but-disabled style can produce an
+ * actionable hint instead of a generic parse error (Codex syntax is a strong
+ * prior for GPT-family models; a silent failure traps them in retry loops).
+ * @module dsh-patch-edit-plus/detect
+ */
+export type PatchFormat = 'unified' | 'codex';
+/**
+ * Classify patch text. Order matters: the `*** Begin Patch` sentinel wins
+ * first, then explicit unified-diff markers, then Codex section headers.
+ * @throws {@link PatchError} code `PARSE` (with both syntax examples) when the text matches neither supported syntax.
+ */
+export declare function detectFormat(patch: string): PatchFormat;

package/lib/types/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Error taxonomy and model-facing message builders.
+ *
+ * Every failure surfaces as a `PatchError` with a stable machine code so
+ * retry/permission/UI layers can branch without parsing prose. Messages are
+ * written for the model to self-correct: they carry the concrete file, hunk,
+ * position and excerpt needed to fix the patch (no stacks, no internal paths).
+ * @module dsh-patch-edit-plus/errors
+ */
+/** Stable, machine-routable failure codes for patch application. */
+export type PatchErrorCode = 
+/** The patch text is not a parseable patch in either supported syntax. */
+'PARSE'
+/** The patch conflicts with on-disk state or with itself. */
+ | 'CONFLICT'
+/** Arguments or paths are invalid. */
+ | 'VALIDATION'
+/** Filesystem I/O failed. */
+ | 'IO'
+/** The requested operation is not available under the current configuration. */
+ | 'UNSUPPORTED'
+/** A configured resource limit was exceeded. */
+ | 'LIMIT';
+/** Typed patch failure. */
+export declare class PatchError extends Error {
+    readonly code: PatchErrorCode;
+    constructor(code: PatchErrorCode, message: string);
+}
+/** Syntax examples embedded in "cannot recognize" errors so the model can retry in a valid dialect. */
+export declare const SYNTAX_EXAMPLES: string;
+/** PARSE error for input that matches neither supported syntax. */
+export declare function unrecognizedPatchError(): PatchError;
+/** PARSE error with position information for malformed input. */
+export declare function parseError(lineNo: number, why: string): PatchError;
+/** Structured error when a recognized Codex patch arrives while the style is disabled (actionable, not a parse failure). */
+export declare function codexDisabledError(): PatchError;
+/** Structured error when a unified diff arrives while that style is disabled. */
+export declare function unifiedDisabledError(): PatchError;
+/** CONFLICT error for an Add onto an existing path (Codex semantics). */
+export declare function addExistsError(path: string): PatchError;
+/** CONFLICT error for update/delete of a missing file. */
+export declare function missingFileError(path: string, action: string): PatchError;
+/** CONFLICT error for a Move onto an existing path. */
+export declare function moveTargetExistsError(path: string): PatchError;
+/** CONFLICT error when one resolved file is hit by more than one patch operation. */
+export declare function duplicatePathError(path: string): PatchError;
+/** VALIDATION error for paths escaping the workspace. */
+export declare function pathEscapeError(path: string): PatchError;
+/** VALIDATION error when a symlink is on the patch path (followSymlinks: false). */
+export declare function symlinkRejectedError(path: string, at: string): PatchError;
+/** VALIDATION error when the Add parent directory does not exist (matches the native write tool's behavior). */
+export declare function missingParentError(path: string, parent: string): PatchError;
+/** LIMIT error for exceeding a configured cap. */
+export declare function limitError(what: string, actual: number, limit: number): PatchError;
+/** UNSUPPORTED error when delete/move is disabled or no shell capability exists. */
+export declare function unsupportedShellError(why: string): PatchError;
+interface MismatchInput {
+    /** Display path of the file that failed to locate. */
+    path: string;
+    /** 1-based hunk index within the file section. */
+    hunkIndex: number;
+    /** 1-based line number where the search started. */
+    searchFromLine: number;
+    /** The context/delete lines the hunk expected to find. */
+    expected: string[];
+    /** The file's actual lines around the search origin. */
+    actual: string[];
+    /** True when the hunk carried an `*** End of File` pin. */
+    endOfFile?: boolean;
+}
+/**
+ * Four-element mismatch diagnostic: file + hunk index, search origin, expected
+ * preview, actual excerpt — plus a targeted hint when the expected lines look
+ * like they still carry patch markers (the classic duplicated-prefix mistake).
+ */
+export declare function mismatchMessage(input: MismatchInput): string;
+/** IO error wrapping a backend failure. */
+export declare function ioError(what: string, cause: unknown): PatchError;
+export {};

package/lib/types/fsops.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Filesystem seam: reads plus the official write-intent dance.
+ *
+ * DSH providers NEVER dispatch `fs/*` events — the tool layer is the only
+ * initiator — so a bare `ctx.fs.writeText` would silently bypass the
+ * read-before-write gate. Every write here therefore replicates the official
+ * `write` tool verbatim:
+ * 1. `ctx.waterfall('fs/write-intent', target, exec, () => undefined)`
+ * 2. `ctx.fs.writeText(target, content, intent, exec.signal, sandboxPolicy)`
+ * 3. `ctx.emit('fs/observed', target, { kind: 'present', version }, exec)`
+ * With no policy plugin mounted the waterfall returns `undefined`, which is
+ * itself the correct "unconditional write" probe.
+ * @module dsh-patch-edit-plus/fsops
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { FsInfo, FsTarget, FsWriteOutcome } from '@deepseek-ai/dsh-fs';
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+/**
+ * Write one file through the full intent dance. Must stay byte-for-byte the
+ * official sequence — the verification script asserts it.
+ * @throws {@link PatchError} code `IO` when the backend rejects the write.
+ */
+export declare function writeFile(ctx: Context, exec: ToolRunContext, target: FsTarget, content: string, sandboxPolicy: SandboxExecutionPolicy | undefined): Promise<FsWriteOutcome>;
+/** Read one file's text (whole file). */
+export declare function readFile(ctx: Context, exec: ToolRunContext, target: FsTarget): Promise<string>;
+/** Stat one resolved target; `undefined` when absent. */
+export declare function statFile(ctx: Context, exec: ToolRunContext, target: FsTarget): Promise<FsInfo | undefined>;

package/lib/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * dsh-patch-edit-plus — patch-style file editing for DeepSeek Harness.
+ *
+ * One `apply_patch` tool accepting git/unified diff (default) and Codex
+ * `apply_patch` syntax (opt-in). All-or-nothing application through the
+ * official fs write-intent dance; delete/move through the sandbox-aware
+ * shell. Compatible with DSH 0.1.2-rc.1 through 0.1.5-rc.2: the tool
+ * authoring contract is byte-identical across those versions, so a single
+ * code path serves both; only settings registration needs the dual-API
+ * fallback (`installSection` first, `register` second).
+ *
+ * @module dsh-patch-edit-plus
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+import type { Config as PluginConfig } from './config.js';
+/** Cordis plugin name used by Loader diagnostics. */
+export declare const name = "dsh-patch-edit-plus";
+/** Settings namespace (a plain string literal: valid on every target version). */
+export declare const SETTINGS_NAMESPACE = "patch_edit_plus";
+export { Config };
+/** Register the tool and the settings namespace. Every registration is scoped to this plugin. */
+export declare function apply(ctx: Context, config?: PluginConfig): void;

package/lib/types/parse/codex.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { ParsedPatch } from './types.js';
+/**
+ * Parse a Codex `apply_patch` patch into the shared IR.
+ * @throws {@link PatchError} code `PARSE` for malformed or unrecognized input.
+ */
+export declare function parseCodexPatch(patch: string): ParsedPatch;

package/lib/types/parse/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ */
+/** One line inside an update hunk: keep it (`context`), remove (`delete`) or insert (`add`). */
+export interface PatchLine {
+    kind: 'context' | 'delete' | 'add';
+    text: string;
+}
+/**
+ * One hunk of an update operation. Hunk lines are applied in order at the
+ * position located by context matching (unified hunk headers only accelerate
+ * the search, they never pin it).
+ */
+export interface Hunk {
+    /** Codex `@@ <label>` label, when present. */
+    contextLabel?: string;
+    lines: PatchLine[];
+    /**
+     * Codex `*** End of File` marker: the hunk must land at end-of-file, so the
+     * search window is pinned to the last possible position.
+     */
+    endOfFile: boolean;
+    /** Unified hunk header old-file start line (1-based); a search hint only. */
+    oldStart?: number;
+    /** `\ No newline` marker seen after a `-` (or context) line: the OLD file tail lacks the newline. */
+    oldNoNewline?: boolean;
+    /** `\ No newline` marker seen after a `+` line: the NEW file tail lacks the newline. */
+    newNoNewline?: boolean;
+}
+export type PatchOp = {
+    /** Create a file with the given content. */
+    kind: 'add';
+    path: string;
+    lines: string[];
+    trailingNewline: boolean;
+} | {
+    /** Remove a file (runs through the shell backend). */
+    kind: 'delete';
+    path: string;
+} | {
+    /** Modify a file in place, optionally moving it (rename or Codex Move to). */
+    kind: 'update';
+    path: string;
+    moveTo?: string;
+    hunks: Hunk[];
+};
+/** A fully parsed patch in the shared IR. */
+export interface ParsedPatch {
+    format: 'unified' | 'codex';
+    ops: PatchOp[];
+}
+/** Model-facing action label for one changed file (Codex output semantics). */
+export type FileAction = 'added' | 'modified' | 'deleted';

package/lib/types/parse/unified.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { ParsedPatch } from './types.js';
+/** Normalize CRLF/CR to LF and split into lines. */
+export declare function normalizeLines(text: string): string[];
+/**
+ * Parse a git/unified diff into the shared IR.
+ * @throws {@link PatchError} code `PARSE` for any malformed or unrecognized input.
+ */
+export declare function parseUnifiedDiff(patch: string): ParsedPatch;

package/lib/types/register.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedConfig } from './config.js';
+/** A logger face; falls back to no-ops when the host exposes none. */
+export interface LoggerFace {
+    info?(message: string): void;
+    warn?(message: string): void;
+    error?(message: string): void;
+}
+/**
+ * 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 declare function registerApplyPatchTool(ctx: Context, cfg: ResolvedConfig, logger?: LoggerFace): (() => void) | null;