@young1lin/dsh-ui-gitworkbench 0.1.5 → 0.1.6

package/lib/patch-model.js

@@ -0,0 +1,223 @@
+/**
+ * A unified diff, parsed so that a SUBSET of it can be emitted back as a patch
+ * `git apply` will accept.
+ *
+ * `diff-model.ts` already parses diffs, but for rendering: `parseRows` throws
+ * the file headers away and keeps only line numbers from the hunk header, which
+ * is everything a reader needs and nothing a patch needs. Re-emitting is the
+ * whole point here, so this model keeps what that one drops.
+ *
+ * The rules for a partial selection are git's own, from `add -p`, and each one
+ * is a statement about the file the patch will be applied to:
+ *
+ *   - a selected `+` line is emitted as `+` — it is being added;
+ *   - an UNSELECTED `+` line is dropped entirely — it is not part of this
+ *     patch, and the target does not have it;
+ *   - a selected `-` line is emitted as `-` — it is being removed;
+ *   - an UNSELECTED `-` line becomes CONTEXT — the target still has that line,
+ *     and claiming otherwise makes the patch fail to apply.
+ *
+ * Those are the rules for a FORWARD apply, where the target holds the patch's
+ * pre-image. A patch meant for `git apply --REVERSE` meets the target holding
+ * the POST-image, so the unselected treatments mirror: an unselected `+` line
+ * becomes context (the target has it) and an unselected `-` line is dropped
+ * (the target does not). Confirmed against git itself: reverse-applying a
+ * forward-style subset to a working tree that also holds another block's
+ * unselected addition fails as "patch does not apply", because the dropped
+ * line is missing from the post-image git is trying to match.
+ *
+ * Both counts are then recomputed from what was actually emitted. That
+ * arithmetic is the reason this module exists as a tested unit: a wrong count
+ * makes `git apply` fail as "corrupt patch", which tells the reader their diff
+ * is broken, when the truth would have been "the file changed under you" —
+ * the message the context check is there to produce.
+ *
+ * Pure: no React, no CSS, no git. `tests/patch-model.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/patch-model
+ */
+/** Take the whole diff. */
+export const selectAll = () => true;
+/** Take none of it — {@link emitPatch} then returns ''. */
+export const selectNone = () => false;
+const HUNK_HEAD = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)$/;
+/**
+ * Parse one file's unified diff.
+ *
+ * @param text - a single file's diff, as `git diff -- <path>` prints it.
+ * @returns the parsed patch, or null when the text carries no hunk at all —
+ *          an empty diff, or a binary one, which says `Binary files … differ`
+ *          and cannot be applied line by line.
+ */
+export function parsePatch(text) {
+    if (text.length === 0)
+        return null;
+    const lines = text.split('\n');
+    const trailingNewline = lines.length > 0 && lines[lines.length - 1] === '';
+    if (trailingNewline)
+        lines.pop();
+    const header = [];
+    const hunks = [];
+    let current = null;
+    const close = () => {
+        if (current === null)
+            return;
+        const [, oldStart, oldCount, newStart, newCount, heading] = current.head;
+        hunks.push({
+            oldStart: Number.parseInt(oldStart, 10),
+            // The unified format allows the count to be omitted when it is 1.
+            oldCount: oldCount === undefined ? 1 : Number.parseInt(oldCount, 10),
+            newStart: Number.parseInt(newStart, 10),
+            newCount: newCount === undefined ? 1 : Number.parseInt(newCount, 10),
+            heading: heading ?? '',
+            oldCountOmitted: oldCount === undefined,
+            newCountOmitted: newCount === undefined,
+            lines: current.lines,
+        });
+        current = null;
+    };
+    for (const line of lines) {
+        const head = HUNK_HEAD.exec(line);
+        if (head !== null) {
+            close();
+            current = { head, lines: [] };
+            continue;
+        }
+        if (current === null) {
+            header.push(line);
+            continue;
+        }
+        if (line.startsWith('\\'))
+            current.lines.push({ kind: 'nonewline', text: '' });
+        else if (line.startsWith('+'))
+            current.lines.push({ kind: 'add', text: line.slice(1) });
+        else if (line.startsWith('-'))
+            current.lines.push({ kind: 'del', text: line.slice(1) });
+        // A context line is ' ' plus content, but git emits a BARE empty line for
+        // an empty one; slicing that would be harmless and reading it as anything
+        // else would drop the line.
+        else
+            current.lines.push({ kind: 'context', text: line.startsWith(' ') ? line.slice(1) : line });
+    }
+    close();
+    if (hunks.length === 0)
+        return null;
+    return { header, hunks, trailingNewline };
+}
+/** Spell a count the way the source spelled it, when that is unambiguous. */
+function count(value, omitted) {
+    return value === 1 && omitted ? '' : `,${value}`;
+}
+/** Apply the selection rules to one hunk's lines. */
+function emitHunkLines(hunk, hunkIndex, isSelected, reverseApply) {
+    const out = [];
+    let oldCount = 0;
+    let newCount = 0;
+    let changed = false;
+    // Whether the line the next `\ No newline` marker would describe survived.
+    let lastKept = false;
+    hunk.lines.forEach((line, lineIndex) => {
+        if (line.kind === 'nonewline') {
+            // The marker describes the line before it. Emitting it after a line that
+            // is no longer in the patch makes git read it as describing a different
+            // line entirely.
+            if (lastKept)
+                out.push('\');
+            return;
+        }
+        if (line.kind === 'context') {
+            out.push(` ${line.text}`);
+            oldCount += 1;
+            newCount += 1;
+            lastKept = true;
+            return;
+        }
+        const selected = isSelected(hunkIndex, lineIndex);
+        if (line.kind === 'add') {
+            // Forward apply: the target does not have an unselected addition, so it
+            // is not part of this patch. Reverse apply: the target DOES have it — it
+            // holds the post-image — so it has to be context or the patch will not
+            // match.
+            if (!selected && !reverseApply) {
+                lastKept = false;
+                return;
+            }
+            if (!selected) {
+                out.push(` ${line.text}`);
+                oldCount += 1;
+                newCount += 1;
+                lastKept = true;
+                return;
+            }
+            out.push(`+${line.text}`);
+            newCount += 1;
+            changed = true;
+            lastKept = true;
+            return;
+        }
+        // A deletion that is not part of this patch still EXISTS in a forward
+        // apply's target (the pre-image), so it is presented as context. A reverse
+        // apply's target never had it, so it is dropped instead.
+        if (!selected) {
+            if (reverseApply) {
+                lastKept = false;
+                return;
+            }
+            out.push(` ${line.text}`);
+            oldCount += 1;
+            newCount += 1;
+            lastKept = true;
+            return;
+        }
+        out.push(`-${line.text}`);
+        oldCount += 1;
+        changed = true;
+        lastKept = true;
+    });
+    return { lines: out, oldCount, newCount, changed };
+}
+/**
+ * Emit the selected part of a patch as text `git apply` will accept.
+ *
+ * A hunk with nothing selected is dropped whole: a hunk of pure context is
+ * valid but pointless, and a patch of nothing but such hunks is a no-op git
+ * would still report as applied.
+ *
+ * The new-side start of each hunk is recomputed by how much the hunks BEFORE
+ * it (in this patch) actually shift the file. Taking one of two added lines
+ * moves everything after it by one, and a header that still claims the
+ * original offset describes a file that will not exist.
+ *
+ * @param file - a parsed patch.
+ * @param isSelected - which changed lines to take.
+ * @param reverseApply - emit for `git apply --reverse`, whose target holds the
+ *          patch's POST-image rather than its pre-image: unselected additions
+ *          become context and unselected deletions are dropped (the mirror of
+ *          the forward rules). Selected lines keep their sign either way.
+ * @returns the patch text, or '' when the selection is empty. The caller must
+ *          treat '' as "nothing to do" and make no git call: a patch with no
+ *          hunks is an error to `git apply`, not a no-op.
+ */
+export function emitPatch(file, isSelected, reverseApply = false) {
+    const body = [];
+    // Set from the first hunk that survives, so a patch starting at hunk 2 keeps
+    // that hunk's own offset rather than inheriting one from hunks left out.
+    let delta = null;
+    file.hunks.forEach((hunk, hunkIndex) => {
+        const emitted = emitHunkLines(hunk, hunkIndex, isSelected, reverseApply);
+        if (!emitted.changed)
+            return;
+        if (delta === null)
+            delta = hunk.newStart - hunk.oldStart;
+        const newStart = hunk.oldStart + delta;
+        const old = count(emitted.oldCount, hunk.oldCountOmitted);
+        const fresh = count(emitted.newCount, hunk.newCountOmitted);
+        body.push(`@@ -${hunk.oldStart}${old} +${newStart}${fresh} @@${hunk.heading}`);
+        body.push(...emitted.lines);
+        delta += emitted.newCount - emitted.oldCount;
+    });
+    if (body.length === 0)
+        return '';
+    const text = [...file.header, ...body].join('\n');
+    return file.trailingNewline ? `${text}\n` : text;
+}

package/lib/side-guard.js

@@ -0,0 +1,55 @@
+/**
+ * The side-by-side diff pane's size guard, as a decision rather than two
+ * scattered comparisons.
+ *
+ * The guard exists for the wire, not the reader: a full-context patch carries
+ * the WHOLE file, so past these caps "a 2 MB patch per click is not a
+ * reasonable wire payload and the side-by-side DOM would be enormous" (the
+ * design spec's own words for why the pane declines).
+ *
+ * Two measurements, because they bound different things:
+ *
+ *   - the TARGET (right-hand) file's byte size and line count — checked
+ *     BEFORE the diff is produced, so declining a pathological file never
+ *     means reading it whole first;
+ *   - the produced diff text itself — checked AFTER, because the target-side
+ *     check has two blind spots the review caught: a file DELETED from the
+ *     working tree has no target to measure while its diff is the entire old
+ *     file as del lines, and a huge LEFT side behind a small target (a 5 MB
+ *     index blob trimmed to 50 lines) passes the target guard while the patch
+ *     still carries the 5 MB old side. Only the diff text sees both.
+ *
+ * Pure: no React, no CSS, no git, no node. `tests/side-guard.test.ts` loads
+ * it directly, defeat cases included.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/side-guard
+ */
+/** Target side past this many bytes is declined. */
+export const SIDE_BYTE_CAP = 2_000_000;
+/** Target side past this many lines is declined. */
+export const SIDE_LINE_CAP = 20_000;
+/** Diff text past this many characters is declined — the guard's own 2 MB
+ *  budget applied to the payload itself, `clipDiff`'s character convention. */
+export const SIDE_DIFF_CHAR_CAP = 2_000_000;
+/**
+ * The before-the-diff half: does the layer's right-hand file already exceed
+ * the guard?
+ *
+ * @param byteLength - the target's size in bytes.
+ * @param lineCount - the target's line count.
+ * @returns true when the pane should decline without producing a diff.
+ */
+export function targetTooLarge(byteLength, lineCount) {
+    return byteLength > SIDE_BYTE_CAP || lineCount > SIDE_LINE_CAP;
+}
+/**
+ * The after-the-diff half: does the patch text itself exceed the guard? This
+ * is what bounds the wire payload when the target measurement cannot — a
+ * deleted working-tree file, or a huge left side behind a small target.
+ *
+ * @param diff - the layer's full-context diff, exactly as it would be returned.
+ * @returns true when the pane should decline instead of shipping it.
+ */
+export function diffTooLarge(diff) {
+    return diff.length > SIDE_DIFF_CHAR_CAP;
+}

package/lib/write-checked.js

@@ -0,0 +1,164 @@
+/**
+ * The `writeChecked` sequence: save the editor's buffer over the working-tree
+ * file it was opened from, refusing when the file moved underneath the editor.
+ *
+ * The sha check is the whole point of this RPC. The drawer shares its
+ * worktrees with an agent that writes the same files, and the poll only says
+ * how fast the drawer *notices* — so the one hard rule is that a write lands
+ * only when the file's blob sha is still the one the editor opened with. A
+ * client that lies about that sha gains nothing: the sha is re-derived from
+ * what git says at the moment of the write, the same never-trust-the-client
+ * shape as `discardFile`'s `expectedEffect`.
+ *
+ * `expectedSha === ''` means "the file did not exist when I opened it" (a
+ * buffer opened on a file deleted meanwhile), and is accepted only while the
+ * file is still absent. The not-exist/hash-failure distinction is made
+ * explicitly, with a filesystem stat: a spawn error must surface as a failed
+ * save, never masquerade as "exists with a different sha" — that would look
+ * like the stale case while silently skipping the guard's real work.
+ *
+ * The sequence's every branch lives here rather than in `index.ts`, because
+ * `index.ts` extends the RPC service class and imports its dsh peers as values
+ * — vitest cannot load it. Everything git- or filesystem-shaped is injected
+ * (`WriteCheckedIo`), which is also what lets the git-backed tests drive this
+ * exact code with a real git in a temp repo.
+ *
+ * There is deliberately no `writeFile(path, content)` without the sha check
+ * anywhere in this plugin, and none may be added: an unchecked write is a
+ * clobber-a-concurrent-agent primitive.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/write-checked
+ */
+import { randomBytes } from 'node:crypto';
+import { renameWithRetry } from './atomic-json.js';
+import { resolveInside } from './fs-remove.js';
+import { decodesAsUtf8, isSafePathArg } from './git-ops.js';
+/**
+ * Run one checked write end to end. Never throws: every failure, including an
+ * IO failure, is a result the RPC can carry back as a sentence.
+ *
+ * The order of the steps is the contract: the path lock, then the sha as git
+ * reads it RIGHT NOW, then the refusal before anything is staged, then the
+ * atomic write, and only then the sha the next save will be checked against.
+ */
+export async function runWriteChecked(io, cwd, path, text, expectedSha) {
+    try {
+        return await writeChecked(io, cwd, path, text, expectedSha);
+    }
+    catch (error) {
+        // Nothing may throw across the RPC boundary: a failed helper is a failed
+        // save with a message, not a broken call.
+        return { ok: false, failure: 'unknown', error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function writeChecked(io, cwd, path, text, expectedSha) {
+    if (typeof path !== 'string' || !isSafePathArg(path)) {
+        return { ok: false, failure: 'invalid', error: `unsafe path argument: ${JSON.stringify(path)}` };
+    }
+    if (typeof text !== 'string' || typeof expectedSha !== 'string') {
+        return { ok: false, failure: 'invalid', error: 'text and expectedSha must be strings' };
+    }
+    // The path lock every filesystem write in this plugin passes — the same
+    // `resolveInside`, not a second one. It throws on traversal spellings and on
+    // anything resolving outside the worktree.
+    let target;
+    try {
+        target = resolveInside(cwd, path);
+    }
+    catch (error) {
+        return { ok: false, failure: 'invalid', error: error instanceof Error ? error.message : String(error) };
+    }
+    // Encoding before anything else, because it is a permanent property of the
+    // file rather than a race. The buffer reached the browser as a UTF-8 decode
+    // of these bytes; for a file in any other encoding that decode was LOSSY,
+    // and writing the result back replaces every non-ASCII byte in the file —
+    // including the lines nobody edited. The client withholds the editor for
+    // such a file, and this refuses the write regardless, because a client's
+    // word is not what this RPC trusts.
+    let current;
+    const present = await io.exists(target);
+    if (present) {
+        let bytes;
+        try {
+            bytes = await io.readBytes(target);
+        }
+        catch (error) {
+            return {
+                ok: false, failure: 'unknown',
+                error: `could not read ${path} to check its encoding: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        if (!decodesAsUtf8(bytes)) {
+            return { ok: false, failure: 'invalid', error: notUtf8Message(path) };
+        }
+    }
+    // The sha as git reads it now. Absent is '', by stat rather than by reading
+    // a spawn failure into it; a file that IS there but will not hash is a
+    // failed save, never a stale one.
+    if (!present) {
+        current = '';
+    }
+    else {
+        const hashed = await io.git(cwd, ['hash-object', '--', path]);
+        if (hashed.exitCode !== 0) {
+            return {
+                ok: false, failure: 'unknown',
+                error: `git hash-object failed (exit ${hashed.exitCode}) for ${path}${hashed.stderr.length > 0 ? `: ${hashed.stderr}` : ''}`,
+            };
+        }
+        current = hashed.stdout.trim();
+    }
+    if (current !== expectedSha) {
+        return { ok: false, failure: 'stale', error: staleMessage(path, expectedSha, current) };
+    }
+    // Atomic write: stage the bytes beside the target (same directory, so the
+    // rename stays inside one filesystem), then rename over it with the shared
+    // Windows-EPERM retry. The buffer is written as bytes exactly as received —
+    // no newline translation anywhere in this path.
+    const tmp = `${target}.gwtmp-${randomBytes(6).toString('hex')}`;
+    try {
+        await io.writeBytes(tmp, Buffer.from(text, 'utf8'));
+        await renameWithRetry(io.rename, io.delay, tmp, target);
+    }
+    catch (error) {
+        // The write did not land; the temp must not linger in the tree as a
+        // phantom untracked file. Cleanup must never mask the result it follows.
+        await io.remove(tmp).catch(() => { });
+        return {
+            ok: false, failure: 'unknown',
+            error: `could not write ${path}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // The sha the NEXT save is checked against, read back from the file that is
+    // now on disk.
+    const after = await io.git(cwd, ['hash-object', '--', path]);
+    if (after.exitCode !== 0) {
+        return {
+            ok: false, failure: 'unknown',
+            error: `${path} was written but its new sha could not be read (exit ${after.exitCode})${after.stderr.length > 0 ? `: ${after.stderr}` : ''}`,
+        };
+    }
+    return { ok: true, sha: after.stdout.trim() };
+}
+/**
+ * Why an encoding refusal happened, in the reader's terms. It names the path
+ * for the same reason the stale message does — the banner sits under a file
+ * tab the reader may already have switched away from.
+ */
+function notUtf8Message(path) {
+    return `${path} is not UTF-8, so editing it here would rewrite every non-ASCII byte; nothing was written`;
+}
+/**
+ * Why the save was refused, in the reader's terms: which way the file moved.
+ * Every spelling names the path, because the banner this lands in sits under a
+ * file tab the reader may already have switched away from.
+ */
+function staleMessage(path, expectedSha, current) {
+    if (expectedSha === '') {
+        return `${path} was created while you were editing it; nothing was written`;
+    }
+    if (current === '') {
+        return `${path} was deleted while you were editing it; nothing was written`;
+    }
+    return `${path} changed while you were editing it; nothing was written`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@young1lin/dsh-ui-gitworkbench",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Out-of-tree dsh web UI plugin: a session-header git workbench chip opening a drawer with the file tree, per-file diff, history, compare, staging, commit, and sync (fetch/pull/push).",
   "type": "module",
   "main": "lib/index.js",
@@ -82,6 +82,12 @@
     "vitest": "^4.1.10"
   },
   "dependencies": {
+    "@codemirror/commands": "6.11.0",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/merge": "6.12.2",
+    "@codemirror/search": "6.7.1",
+    "@codemirror/state": "6.7.1",
+    "@codemirror/view": "6.43.9",
     "@shikijs/langs": "4.3.1",
     "shiki": "4.3.1"
   }

package/src/apply-blocks.ts

@@ -0,0 +1,215 @@
+/**
+ * The `applyBlocks` sequence: turn "these hunk lines of this block" into a git
+ * index or working-tree mutation.
+ *
+ * The client sends a SELECTION, never patch text — a patch is a file-addressing
+ * format, and accepting one from the browser would be a write primitive with a
+ * path argument. So the host re-fetches the layer's diff itself, proves the
+ * client is describing the same snapshot (sha1 of the fetched text must equal
+ * the `diffSha` the pane rendered), and only then emits and applies.
+ *
+ * The sequence's every branch lives here rather than in `index.ts`, because
+ * `index.ts` extends the RPC service class and imports its dsh peers as values
+ * — vitest cannot load it. Everything git- or filesystem-shaped is injected
+ * (`ApplyBlocksIo`), which is also what lets the git-backed tests drive this
+ * exact code with a real git in a temp repo instead of a mock of it.
+ *
+ * Nothing here builds a destructive command: the whole vocabulary is
+ * `git apply`, forward into the index (`--cached`) or reverse out of the index
+ * or the working tree (`--reverse`). The one argv that carries file content is
+ * the host-written tmpfile, never a client string; the client's `path` is
+ * checked with `isSafePathArg` and reaches git only inside the layer-diff
+ * fetch, behind `--`, as every other pathspec in this plugin is.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/apply-blocks
+ */
+
+import { createHash } from 'node:crypto'
+
+import { classifyFailure, isSafePathArg, type OpFailure } from './git-ops.js'
+import { emitPatch, parsePatch, type LineSelector } from './patch-model.js'
+
+/**
+ * Whether a mode applies its patch with `--reverse`, which decides the
+ * emission rules: a reverse apply's target holds the patch's post-image (the
+ * index for `unstage`, the working tree for `discard`), so unselected lines
+ * must be presented the post-image sees them — `emitPatch`'s third argument.
+ */
+function appliesInReverse(mode: string): boolean {
+  return mode !== 'stage'
+}
+
+/** The three block mutations, in the client's vocabulary. */
+export type ApplyMode = 'stage' | 'unstage' | 'discard'
+
+/** One git run, in the shape `index.ts`'s `git()` helper already returns. */
+export interface GitRun {
+  readonly stdout: string
+  readonly exitCode: number
+  readonly stderr: string
+}
+
+/** The result of one `applyBlocks` call — `GitOpResult`, structurally. */
+export interface ApplyBlocksResult {
+  readonly ok: boolean
+  readonly failure?: OpFailure
+  readonly error?: string
+}
+
+/**
+ * Everything the sequence needs from its host, as injected dependencies.
+ *
+ * `index.ts` binds its own `git()` spawn helper, the layer-diff fetch it shares
+ * with `fileSides`, and the tmpfile pair; the tests bind a real git in a temp
+ * repo and a patch file inside it. Either way the decisions below are the same
+ * code — there is no second implementation to fall out of step with.
+ */
+export interface ApplyBlocksIo {
+  /** Run git in `cwd`. Must not throw — report through `exitCode`/`stderr`. */
+  readonly git: (cwd: string, argv: readonly string[]) => Promise<GitRun>
+  /** The layer's full-context diff — the exact fetch `fileSides` serves. */
+  readonly layerDiff: (path: string, layer: string) => Promise<string>
+  /** Write patch text where git can read it; returns the path. */
+  readonly writePatch: (text: string) => Promise<string>
+  /** Delete what `writePatch` produced. Called from a `finally`. */
+  readonly dropPatch: (path: string) => Promise<void>
+}
+
+/**
+ * The mode/layer matrix as argv: which `git apply` spelling carries each
+ * mutation, and the one layer each is valid on.
+ *
+ * @returns the argv head for the mode, or null when the pair is not one the
+ *          design defines — the caller reports it, never guesses a near one.
+ */
+export function applyArgvFor(mode: string, layer: string): readonly string[] | null {
+  if (mode === 'stage' && layer === 'unstaged') return ['apply', '--cached']
+  if (mode === 'unstage' && layer === 'staged') return ['apply', '--cached', '--reverse']
+  if (mode === 'discard' && layer === 'unstaged') return ['apply', '--reverse']
+  return null
+}
+
+/**
+ * sha1 of a string, hex — the `diffSha` contract.
+ *
+ * This was a private helper of `index.ts` until the checker needed to be the
+ * same code as the producer: `fileSides` stamps the diff it returns and
+ * `applyBlocks` re-derives the stamp over its own fresh fetch, and the two ends
+ * of that comparison must be one function or the comparison means nothing.
+ */
+export function sha1Hex(text: string): string {
+  return createHash('sha1').update(text, 'utf8').digest('hex')
+}
+
+/**
+ * The selector `emitPatch` takes for a block's line indices: a hunk line is
+ * selected iff its index appears in `lines`.
+ *
+ * The indices are positional into the one hunk's `lines` — the same array
+ * `side-rows.blockLines` read client-side. Only integers ≥ 0 count: `lines`
+ * crosses the RPC boundary untyped, and a stray string or float selecting
+ * nothing is the safe direction (an empty selection is a no-op, not an error).
+ */
+export function lineSelector(lines: readonly number[]): LineSelector {
+  const list = Array.isArray(lines) ? lines : []
+  const wanted = new Set(list.filter(line => Number.isInteger(line) && line >= 0))
+  return (_hunkIndex: number, lineIndex: number) => wanted.has(lineIndex)
+}
+
+/**
+ * Run one block mutation end to end. Never throws: every failure, including an
+ * IO failure, is a result the RPC can carry back as a sentence.
+ *
+ * The order of the steps is the contract: the stale check before anything is
+ * emitted, the multi-hunk guard before anything is applied, `--check` before
+ * the apply that matters, and the tmpfile deleted whichever way it ends.
+ */
+export async function runApplyBlocks(
+  io: ApplyBlocksIo,
+  cwd: string,
+  path: string,
+  layer: string,
+  diffSha: string,
+  lines: readonly number[],
+  mode: string,
+): Promise<ApplyBlocksResult> {
+  try {
+    return await applyBlocksChecked(io, cwd, path, layer, diffSha, lines, mode)
+  } catch (error) {
+    // Nothing may throw across the RPC boundary: a failed helper is a failed
+    // operation with a message, not a broken call.
+    return { ok: false, failure: 'unknown', error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+async function applyBlocksChecked(
+  io: ApplyBlocksIo,
+  cwd: string,
+  path: string,
+  layer: string,
+  diffSha: string,
+  lines: readonly number[],
+  mode: string,
+): Promise<ApplyBlocksResult> {
+  if (typeof path !== 'string' || !isSafePathArg(path)) {
+    return { ok: false, failure: 'invalid', error: `unsafe path argument: ${JSON.stringify(path)}` }
+  }
+  const argv = applyArgvFor(mode, layer)
+  if (argv === null) {
+    return { ok: false, failure: 'invalid', error: `cannot ${String(mode)} a block on the ${String(layer)} layer` }
+  }
+
+  // The stale check. The selection's line indices have meaning only against
+  // the exact diff the pane rendered; a file that changed since makes them
+  // point at different lines, so nothing is emitted, let alone applied.
+  const diff = await io.layerDiff(path, layer)
+  if (sha1Hex(diff) !== diffSha) {
+    return { ok: false, failure: 'stale', error: `${path} changed since the diff was loaded; nothing was applied` }
+  }
+
+  const file = parsePatch(diff)
+  // No hunk at all (empty or binary diff, with a sha that matches): there is
+  // nothing to select, which is the empty selection's no-op, not an error.
+  if (file === null) return { ok: true }
+  // Hunk line indices restart per hunk, so "line 1" of a two-hunk diff names a
+  // line in EACH hunk. Full context produces one hunk; anything else must be
+  // refused whole rather than applied to the wrong lines.
+  if (file.hunks.length > 1) {
+    return {
+      ok: false, failure: 'invalid',
+      error: `the diff for ${path} carries ${file.hunks.length} hunks; block operations need the single full-context hunk`,
+    }
+  }
+
+  const patch = emitPatch(file, lineSelector(lines), appliesInReverse(mode))
+  // An empty selection is not an error, and `git apply` rejects a patch with
+  // no hunks — so "nothing selected" must never reach git at all.
+  if (patch.length === 0) return { ok: true }
+
+  // The patch travels by tmpfile (`git()` spawns with `stdin: 'ignore'`), as
+  // the LAST argument of the apply spelling chosen above. Deleted in the
+  // finally whatever happens, so a refusal never litters the temp dir.
+  const patchFile = await io.writePatch(patch)
+  try {
+    const check = await io.git(cwd, [...argv, '--check', patchFile])
+    if (check.exitCode !== 0) return refusal(check)
+    const applied = await io.git(cwd, [...argv, patchFile])
+    if (applied.exitCode !== 0) return refusal(applied)
+    return { ok: true }
+  } finally {
+    await io.dropPatch(patchFile).catch(() => {
+      // Cleanup must never mask the result it follows; a tmpfile that is
+      // already gone has done its job.
+    })
+  }
+}
+
+/** A refused apply: git's own message verbatim, classified for the banner. */
+function refusal(run: GitRun): ApplyBlocksResult {
+  const failure = classifyFailure(run.exitCode, run.stderr, run.stdout)
+  const error = (run.stderr || run.stdout).trim().slice(-1000)
+  // `classifyFailure` answers null only for a zero exit, which is not a
+  // refusal and cannot reach here. The key is omitted rather than sent as
+  // null anyway, because the gateway's payloads carry no empty fields.
+  return failure === null ? { ok: false, error } : { ok: false, failure, error }
+}