@young1lin/dsh-ui-gitworkbench 0.1.5 → 0.1.7

package/lib/index.js

@@ -76,16 +76,21 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
  * @module @young1lin/dsh-ui-gitworkbench
  */
 import { randomBytes } from 'node:crypto';
-import { mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
+import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { runApplyBlocks, sha1Hex } from './apply-blocks.js';
 import { saveJsonAtomic } from './atomic-json.js';
+import { runWriteChecked } from './write-checked.js';
 import { CommitPayloadCache, cacheKey } from './commit-cache.js';
-import { NETWORK_GRACE_MS, NON_INTERACTIVE_ENV, capBranches, classifyFailure, clipDiff, commitArgv, countBufferLines, fetchArgv, isBinaryPrefix, isNoMergeBaseError, isSafePathArg, parseNameStatus, parseNumstat, parseStatus, parseTracking, pullArgv, pushArgv, stageArgv, unstageArgv, } from './git-ops.js';
+import { NETWORK_GRACE_MS, NON_INTERACTIVE_ENV, capBranches, classifyFailure, clipDiff, commitArgv, countBufferLines, decodesAsUtf8, fetchArgv, isBinaryPrefix, isNoMergeBaseError, isSafePathArg, parseNameStatus, parseNumstat, parseStatus, parseTracking, pullArgv, pushArgv, stageArgv, unstageArgv, } from './git-ops.js';
 import { planFromStatus, } from './discard-ops.js';
+import { parseBlame } from './blame.js';
 import { removePathInside } from './fs-remove.js';
+import { diffTooLarge, targetTooLarge, SIDE_BYTE_CAP, SIDE_LINE_CAP } from './side-guard.js';
+import { IMAGE_BYTE_CAP, sniffImage } from './image-sniff.js';
 import { LOG_FORMAT, parseLog } from './git-log.js';
 import { emptyLogFilter, logFilterArgs } from './log-filter.js';
 import { parseShortlog } from './shortlog.js';
@@ -99,6 +104,9 @@ const UNTRACKED_FILE_BYTE_CAP = 1_000_000;
 const UNTRACKED_TOTAL_CHAR_CAP = 160_000;
 /** Files with a NUL byte in the first 8k are treated as binary. */
 const BINARY_SNIFF_BYTES = 8_000;
+/** Context radius that makes `git diff` emit ONE hunk covering the whole file —
+ *  the artifact the side-by-side view aligns its two columns on. */
+const FULL_CONTEXT = 1_000_000;
 /** Untracked files measured at once. Enough to keep the disk busy, few enough
  *  that a repository with thousands of them cannot exhaust the file table. */
 const UNTRACKED_READ_CONCURRENCY = 16;
@@ -126,6 +134,10 @@ const COMMIT_CACHE_CAPACITY = 32;
 const COMMIT_DIFF_CACHE_CAPACITY = 128;
 /** Abbreviated or full object name — rejects anything that could read as a git option. */
 const COMMIT_HASH = /^[0-9a-fA-F]{4,40}$/;
+/** A `fileImage` answer that carries no picture, only why. */
+function declined(reason, bytes) {
+    return { ok: false, mime: '', kind: '', base64: '', bytes, reason };
+}
 /**
  * Narrow whatever the client sent to a list of path strings.
  *
@@ -144,6 +156,11 @@ let GitWorkbenchService = (() => {
     let _instanceExtraInitializers = [];
     let _stats_decorators;
     let _fileDiff_decorators;
+    let _fileSides_decorators;
+    let _applyBlocks_decorators;
+    let _writeChecked_decorators;
+    let _blame_decorators;
+    let _fileImage_decorators;
     let _commitStats_decorators;
     let _commits_decorators;
     let _authors_decorators;
@@ -169,6 +186,11 @@ let GitWorkbenchService = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _stats_decorators = [Remote('stats')];
             _fileDiff_decorators = [Remote('fileDiff')];
+            _fileSides_decorators = [Remote('fileSides')];
+            _applyBlocks_decorators = [Remote('applyBlocks')];
+            _writeChecked_decorators = [Remote('writeChecked')];
+            _blame_decorators = [Remote('blame')];
+            _fileImage_decorators = [Remote('fileImage')];
             _commitStats_decorators = [Remote('commitStats')];
             _commits_decorators = [Remote('commits')];
             _authors_decorators = [Remote('authors')];
@@ -191,6 +213,11 @@ let GitWorkbenchService = (() => {
             _push_decorators = [Remote('push')];
             __esDecorate(this, null, _stats_decorators, { kind: "method", name: "stats", static: false, private: false, access: { has: obj => "stats" in obj, get: obj => obj.stats }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _fileDiff_decorators, { kind: "method", name: "fileDiff", static: false, private: false, access: { has: obj => "fileDiff" in obj, get: obj => obj.fileDiff }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _fileSides_decorators, { kind: "method", name: "fileSides", static: false, private: false, access: { has: obj => "fileSides" in obj, get: obj => obj.fileSides }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _applyBlocks_decorators, { kind: "method", name: "applyBlocks", static: false, private: false, access: { has: obj => "applyBlocks" in obj, get: obj => obj.applyBlocks }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _writeChecked_decorators, { kind: "method", name: "writeChecked", static: false, private: false, access: { has: obj => "writeChecked" in obj, get: obj => obj.writeChecked }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _blame_decorators, { kind: "method", name: "blame", static: false, private: false, access: { has: obj => "blame" in obj, get: obj => obj.blame }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _fileImage_decorators, { kind: "method", name: "fileImage", static: false, private: false, access: { has: obj => "fileImage" in obj, get: obj => obj.fileImage }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _commitStats_decorators, { kind: "method", name: "commitStats", static: false, private: false, access: { has: obj => "commitStats" in obj, get: obj => obj.commitStats }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _commits_decorators, { kind: "method", name: "commits", static: false, private: false, access: { has: obj => "commits" in obj, get: obj => obj.commits }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _authors_decorators, { kind: "method", name: "authors", static: false, private: false, access: { has: obj => "authors" in obj, get: obj => obj.authors }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -327,7 +354,7 @@ let GitWorkbenchService = (() => {
                     const session = exec.agent?.session;
                     if (session === undefined)
                         return { ok: false, error: 'worktree tools require a calling session' };
-                    return this.worktreeEnter(session.id, session.header.cwd, args?.name, exec.signal);
+                    return this.worktreeEnter(session.id, session.header.cwd ?? '', args?.name, exec.signal);
                 },
                 presentCall: () => ({ card: 'generic', title: 'Enter worktree', kind: 'other' }),
             }));
@@ -356,7 +383,7 @@ let GitWorkbenchService = (() => {
                     const session = exec.agent?.session;
                     if (session === undefined)
                         return { ok: false, error: 'worktree tools require a calling session' };
-                    return this.worktreeStatus(session.id, session.header.cwd, exec.signal);
+                    return this.worktreeStatus(session.id, session.header.cwd ?? '', exec.signal);
                 },
                 presentCall: () => ({ card: 'generic', title: 'Worktree status', kind: 'read' }),
             }));
@@ -474,6 +501,340 @@ let GitWorkbenchService = (() => {
                 return { diff: tracked.stdout };
             return { diff: await untrackedSegment(cwd, path) ?? '' };
         }
+        /**
+         * One layer of one file for the side-by-side diff pane: the layer's
+         * full-context diff, the right-hand text the editor starts from, and the
+         * shas later mutations check against (plain-identifier params; signal last).
+         *
+         * The two layers answer different questions about the same file — `unstaged`
+         * is index→worktree (the editable side), `staged` is HEAD→index (read-only:
+         * editing the index would mean writing a blob with no file behind it) — so
+         * the diff, the target text and the target sha each come from that layer's
+         * own sources. Untracked files have no index entry, so `git diff` reports
+         * nothing for them and the unstaged layer falls back to the synthesized
+         * new-file segment `fileDiff` already uses.
+         *
+         * @param worktreePath - directory to run in; empty falls back to the host cwd.
+         * @param path - repository-relative path, as the drawer lists it.
+         * @param layer - `unstaged` (index→worktree) or `staged` (HEAD→index).
+         * @param signal - abort signal.
+         */
+        async fileSides(worktreePath, path, layer, signal) {
+            if (layer !== 'unstaged' && layer !== 'staged') {
+                throw new Error(`unknown layer "${String(layer)}"; expected 'unstaged' or 'staged'`);
+            }
+            if (typeof path !== 'string' || !isSafePathArg(path)) {
+                throw new Error(`unsafe path argument: ${JSON.stringify(path)}`);
+            }
+            const cwd = this.cwdOf(worktreePath);
+            return layer === 'unstaged'
+                ? await this.unstagedSides(cwd, path, signal)
+                : await this.stagedSides(cwd, path, signal);
+        }
+        /** The unstaged layer: diff index→worktree, target = the working-tree file. */
+        async unstagedSides(cwd, path, signal) {
+            // Size guard first, off the stat rather than a read: declining a file past
+            // the cap must not mean loading a pathological one whole first. Bytes are
+            // all a stat knows; the line half of the guard needs the read below.
+            try {
+                const info = await stat(join(cwd, path));
+                if (info.isFile() && targetTooLarge(info.size, 0))
+                    return { ...emptySides(), tooLarge: true };
+            }
+            catch {
+                // Missing file: deleted in the working tree, which the diff below states.
+            }
+            let bytes = null;
+            try {
+                bytes = await readFile(join(cwd, path));
+            }
+            catch {
+                bytes = null;
+            }
+            if (bytes !== null && isBinaryPrefix(bytes, BINARY_SNIFF_BYTES)) {
+                return { ...emptySides(), binary: true, targetSha: await this.worktreeBlobSha(cwd, path, signal) };
+            }
+            if (bytes !== null && targetTooLarge(bytes.length, countBufferLines(bytes))) {
+                return { ...emptySides(), tooLarge: true };
+            }
+            const diff = await this.layerDiffText(cwd, path, 'unstaged', signal);
+            if (binaryDiffOutput(diff)) {
+                return { ...emptySides(), binary: true, targetSha: await this.worktreeBlobSha(cwd, path, signal) };
+            }
+            // The diff half of the guard, AFTER the artifact exists: the target-side
+            // checks above cannot see a worktree-deleted large file (no target to
+            // measure) or a huge left side behind a small target — but the patch text
+            // carries both, and it is the payload being bounded.
+            if (diffTooLarge(diff))
+                return { ...emptySides(), tooLarge: true };
+            return {
+                diff,
+                diffSha: sha1Hex(diff),
+                targetText: bytes === null ? '' : bytes.toString('utf8'),
+                targetSha: bytes === null ? '' : await this.worktreeBlobSha(cwd, path, signal),
+                binary: false,
+                tooLarge: false,
+                // Only the unstaged layer can report this, and only it needs to: the
+                // editor edits the working tree, and the staged layer is read-only.
+                lossyEncoding: bytes !== null && !decodesAsUtf8(bytes),
+            };
+        }
+        /** The staged layer: diff HEAD→index, target = the index blob. */
+        async stagedSides(cwd, path, signal) {
+            // `:path` resolves the stage-0 index entry: the target text when it exists,
+            // and a failed resolution (no entry) is the empty target, not an error.
+            const shown = await this.git(cwd, ['show', `:${path}`], signal);
+            const sha = (await this.git(cwd, ['rev-parse', '--verify', '--quiet', `:${path}`], signal)).stdout.trim();
+            const targetText = shown.exitCode === 0 ? shown.stdout : '';
+            const targetBytes = Buffer.from(targetText, 'utf8');
+            if (targetText.length > 0 && isBinaryPrefix(targetBytes, BINARY_SNIFF_BYTES)) {
+                return { ...emptySides(), binary: true, targetSha: sha };
+            }
+            if (targetTooLarge(targetBytes.length, countBufferLines(targetBytes))) {
+                return { ...emptySides(), tooLarge: true, targetSha: sha };
+            }
+            const diff = await this.layerDiffText(cwd, path, 'staged', signal);
+            if (binaryDiffOutput(diff)) {
+                return { ...emptySides(), binary: true, targetSha: sha };
+            }
+            // Same reasoning as the unstaged layer's post-diff check: a huge HEAD side
+            // behind a small index target passes the target guard while the patch
+            // still carries the whole old file.
+            if (diffTooLarge(diff)) {
+                return { ...emptySides(), tooLarge: true, targetSha: sha };
+            }
+            return {
+                diff,
+                diffSha: sha1Hex(diff),
+                targetText,
+                targetSha: sha,
+                binary: false,
+                tooLarge: false,
+                lossyEncoding: false,
+            };
+        }
+        /** Blob sha of the working-tree file, '' when git cannot hash it. */
+        async worktreeBlobSha(cwd, path, signal) {
+            const hashed = await this.git(cwd, ['hash-object', '--', path], signal);
+            return hashed.exitCode === 0 ? hashed.stdout.trim() : '';
+        }
+        /**
+         * The layer's full-context diff — the one artifact the side pane aligns its
+         * rows on and `applyBlocks` re-checks its sha against.
+         *
+         * Both callers go through here by design: `fileSides` stamps the text it
+         * returns with {@link sha1Hex} and `applyBlocks` re-derives the stamp over
+         * its own fresh fetch, so the two ends of the stale comparison are over the
+         * SAME text by construction, not by two fetch sites staying in step.
+         */
+        async layerDiffText(cwd, path, layer, signal) {
+            if (layer === 'staged') {
+                return (await this.git(cwd, ['diff', '--cached', `-U${FULL_CONTEXT}`, '--', path], signal)).stdout;
+            }
+            const diff = (await this.git(cwd, ['diff', `-U${FULL_CONTEXT}`, '--', path], signal)).stdout;
+            // Untracked files have no index entry, so `git diff` reports nothing for
+            // them; the synthesized new-file segment is their unstaged diff. The
+            // trailing newline is added here because every diff git prints carries
+            // one: this text is what `applyBlocks` re-emits as a patch file, and a
+            // patch whose last line has no LF is "corrupt patch" to `git apply` —
+            // which is exactly what a real-git drive of the untracked path caught.
+            if (diff.length === 0 && await this.isUntracked(cwd, path, signal)) {
+                const segment = await untrackedSegment(cwd, path, SIDE_BYTE_CAP);
+                return segment === null ? '' : `${segment}\n`;
+            }
+            return diff;
+        }
+        /**
+         * Apply one change block of a side-by-side diff: stage it into the index,
+         * unstage it back out, or roll it back out of the working tree
+         * (plain-identifier params; signal last).
+         *
+         * The client sends a selection — `path`, `layer`, the `diffSha` of the diff
+         * the pane rendered, and the block's hunk-line indices — never patch text.
+         * The sequence itself (stale check, emission, `--check`, apply, tmpfile
+         * cleanup) lives in `apply-blocks.ts`, where vitest can drive it against a
+         * real git; this method only binds the host's git helper, the layer fetch
+         * shared with `fileSides`, and the tmpfile pair. Every failure comes back as
+         * a result — the method never throws across the RPC boundary.
+         *
+         * @param worktreePath - directory to run in; empty falls back to the host cwd.
+         * @param path - repository-relative path, as the drawer lists it.
+         * @param layer - the layer the block was selected on; the mode decides which
+         *                one that may be.
+         * @param diffSha - sha of the diff the pane rendered, re-derived and compared.
+         * @param lines - hunk-line indices of the block, as `side-rows.blockLines`
+         *                produced them client-side.
+         * @param mode - `stage` | `unstage` | `discard`.
+         * @param signal - abort signal.
+         */
+        async applyBlocks(worktreePath, path, layer, diffSha, lines, mode, signal) {
+            const cwd = this.cwdOf(worktreePath);
+            const io = {
+                git: (dir, argv) => this.git(dir, argv, signal),
+                layerDiff: (file, which) => this.layerDiffText(cwd, file, which === 'staged' ? 'staged' : 'unstaged', signal),
+                writePatch: writeTmpPatch,
+                dropPatch: dropTmpPatch,
+            };
+            return runApplyBlocks(io, cwd, path, layer, String(diffSha ?? ''), lines, mode);
+        }
+        /**
+         * Save the side-by-side editor's buffer over the working-tree file it was
+         * opened from — the editable diff's one write (plain-identifier params;
+         * signal last).
+         *
+         * The buffer travels with the blob sha the editor opened with, and the host
+         * re-derives that sha from git at the moment of the write: a file that moved
+         * underneath the editor — an agent's write, another session's save — makes
+         * the save refuse with `failure: 'stale'` and NOTHING is written. The whole
+         * sequence (path lock, sha refusal, atomic temp+rename write, the fresh sha
+         * the next save checks against) lives in `write-checked.ts`, where vitest
+         * drives it against a real git; this method binds the host's git helper and
+         * the filesystem calls, plus the stat that keeps "file absent" from being
+         * read off a hash spawn's failure. Never throws across the RPC boundary.
+         *
+         * This is deliberately NOT a `writeFile(path, content)` primitive: the sha
+         * check and this method are one thing, and no unchecked write RPC exists or
+         * may be added in this plugin.
+         *
+         * @param worktreePath - directory to run in; empty falls back to the host cwd.
+         * @param path - repository-relative path, as the drawer lists it.
+         * @param text - the editor buffer, verbatim; written as bytes (LF as given).
+         * @param expectedSha - the `targetSha` the buffer was opened with ('' when
+         *                     the file did not exist then), or the sha a successful
+         *                     save last returned.
+         * @param signal - abort signal.
+         */
+        async writeChecked(worktreePath, path, text, expectedSha, signal) {
+            const cwd = this.cwdOf(worktreePath);
+            const io = {
+                git: (dir, argv) => this.git(dir, argv, signal),
+                exists: async (p) => {
+                    try {
+                        await stat(p);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+                readBytes: p => readFile(p),
+                writeBytes: async (p, bytes) => { await writeFile(p, bytes); },
+                rename: async (from, to) => { await rename(from, to); },
+                remove: async (p) => { await rm(p, { force: true }); },
+                delay: ms => new Promise(resolve => { setTimeout(resolve, ms); }),
+            };
+            return runWriteChecked(io, cwd, path, typeof text === 'string' ? text : '', typeof expectedSha === 'string' ? expectedSha : '');
+        }
+        /**
+         * One file's provenance, line by line — the side pane's blame gutter
+         * (plain-identifier params; signal last).
+         *
+         * Blames the WORKING TREE file, which is what the reader is looking at and
+         * what IDEA annotates: lines the reader has not committed come back flagged
+         * rather than missing. Read-only, no index or worktree is touched, so this
+         * needs none of the confirmation machinery the write paths carry.
+         *
+         * @param worktreePath - directory to run in; empty falls back to the host cwd.
+         * @param path - repository-relative path, as the drawer lists it.
+         * @param signal - abort signal.
+         */
+        async blame(worktreePath, path, signal) {
+            if (typeof path !== 'string' || !isSafePathArg(path)) {
+                return { lines: [], truncated: false, error: `unsafe path argument: ${JSON.stringify(path)}` };
+            }
+            const cwd = this.cwdOf(worktreePath);
+            // `--` keeps a path that looks like a revision from being read as one, as
+            // every other pathspec in this plugin does.
+            const run = await this.git(cwd, ['blame', '--line-porcelain', '--', path], signal);
+            if (run.exitCode !== 0) {
+                // An untracked file has no blame, and git says so; that message is the
+                // honest thing to show rather than an empty gutter.
+                return { lines: [], truncated: false, error: (run.stderr || run.stdout).trim().slice(-500) };
+            }
+            const all = parseBlame(run.stdout);
+            // The same line cap the side pane declines a file at: past it the gutter
+            // is a payload nobody reads to the end of.
+            if (all.length > SIDE_LINE_CAP)
+                return { lines: all.slice(0, SIDE_LINE_CAP), truncated: true };
+            return { lines: all, truncated: false };
+        }
+        /**
+         * One working-tree file's bytes, when those bytes really are an image.
+         *
+         * The Files tab's fallback for a picture used to be "binary file — no text
+         * diff", which is true and useless: a repository's icons and screenshots are
+         * content, and a browser is already the best image viewer on the machine.
+         *
+         * The EXTENSION does not decide. It cannot: a `.png` is a filename, and a
+         * view that trusted it would hand the browser whatever bytes happened to be
+         * under that name. {@link sniffImage} reads the signature the format's own
+         * specification mandates, and a file that fails it comes back `notImage` so
+         * the client falls back to the ordinary text path — a mislabelled file still
+         * opens, as itself.
+         *
+         * The size check runs off the stat rather than the read, the same way
+         * `fileSides` does it: declining an oversized file must not mean loading it
+         * whole first. Base64 rather than a binary frame because the RPC channel is
+         * JSON; the third it adds is why {@link IMAGE_BYTE_CAP} sits where it does.
+         *
+         * Read-only — nothing is spawned, nothing is written.
+         *
+         * @param worktreePath - directory to run in; empty falls back to the host cwd.
+         * @param path - repository-relative path, as the drawer lists it.
+         * @param signal - abort signal.
+         */
+        async fileImage(worktreePath, path, signal) {
+            if (typeof path !== 'string' || !isSafePathArg(path)) {
+                throw new Error(`unsafe path argument: ${JSON.stringify(path)}`);
+            }
+            const full = join(this.cwdOf(worktreePath), path);
+            let size = 0;
+            try {
+                const info = await stat(full);
+                if (!info.isFile())
+                    return declined('missing', 0);
+                size = info.size;
+            }
+            catch {
+                return declined('missing', 0);
+            }
+            if (size > IMAGE_BYTE_CAP)
+                return declined('tooLarge', size);
+            let bytes;
+            try {
+                bytes = await readFile(full);
+            }
+            catch {
+                return declined('missing', 0);
+            }
+            // Re-checked against the bytes actually read: the stat above is a separate
+            // syscall, and the file can have grown between the two.
+            if (bytes.length > IMAGE_BYTE_CAP)
+                return declined('tooLarge', bytes.length);
+            const found = sniffImage(bytes);
+            if (found === null)
+                return declined('notImage', bytes.length);
+            return {
+                ok: true,
+                mime: found.mime,
+                kind: found.kind,
+                base64: bytes.toString('base64'),
+                bytes: bytes.length,
+                reason: '',
+            };
+        }
+        /**
+         * Whether git has never seen this path: no index entry and no HEAD entry.
+         * Those are the files whose diff has to be synthesized rather than asked of
+         * `git diff`, which reports nothing for them.
+         */
+        async isUntracked(cwd, path, signal) {
+            const listed = await this.git(cwd, ['ls-files', '--', path], signal);
+            if (listed.exitCode !== 0 || listed.stdout.trim().length > 0)
+                return false;
+            const head = await this.git(cwd, ['rev-parse', '--verify', '--quiet', `HEAD:${path}`], signal);
+            return head.exitCode !== 0;
+        }
         /**
          * One commit's change set, in the SAME {@link WorkbenchStats} shape as the working-tree
          * view so the drawer's tree and diff panes render it with no separate code path.
@@ -1286,9 +1647,11 @@ async function measureUntracked(cwd, path) {
  * `/dev/null` as a repo-relative path. Never throws.
  * @param cwd - worktree the path is relative to.
  * @param path - repository-relative file path.
+ * @param byteCap - refuse files larger than this; defaults to the stats
+ *                  payload's budget, which `fileSides` raises to its own.
  * @returns the segment, or null when the file is missing, binary, or oversized.
  */
-async function untrackedSegment(cwd, path) {
+async function untrackedSegment(cwd, path, byteCap = UNTRACKED_FILE_BYTE_CAP) {
     let bytes;
     try {
         bytes = await readFile(join(cwd, path));
@@ -1298,7 +1661,7 @@ async function untrackedSegment(cwd, path) {
     }
     if (isBinaryPrefix(bytes, BINARY_SNIFF_BYTES))
         return null;
-    if (bytes.length > UNTRACKED_FILE_BYTE_CAP)
+    if (bytes.length > byteCap)
         return null;
     const lines = countBufferLines(bytes);
     const text = bytes.toString('utf8');
@@ -1325,6 +1688,37 @@ function randomHex(digits) {
     const bytes = randomBytes(Math.ceil(digits / 2));
     return bytes.toString('hex').slice(0, digits);
 }
+/**
+ * Park patch text where git can read it: a uniquely named file under the OS
+ * temp dir, passed to `git apply` as its last argument.
+ *
+ * `git()` spawns with `stdin: 'ignore'`, so a tmpfile — not a pipe — is how a
+ * patch reaches git without changing that helper, and the temp dir keeps patch
+ * text (which can be a whole file's worth of context) out of the repository.
+ * `apply-blocks.ts` deletes what this wrote from a `finally`, whichever way
+ * the apply ended.
+ */
+async function writeTmpPatch(text) {
+    const file = join(tmpdir(), `gw-apply-${process.pid}-${randomHex(8)}.patch`);
+    await writeFile(file, text, 'utf8');
+    return file;
+}
+/** Remove a tmpfile `writeTmpPatch` made; a file already gone is a success. */
+async function dropTmpPatch(file) {
+    await rm(file, { force: true });
+}
+/** The `fileSides` payload for a file with nothing to show: no diff, no target. */
+function emptySides() {
+    return { diff: '', diffSha: sha1Hex(''), targetText: '', targetSha: '', binary: false, tooLarge: false, lossyEncoding: false };
+}
+/**
+ * Whether a diff git printed says `Binary files … differ` instead of hunks.
+ * The line starts at column 0 — inside a hunk every body line carries a
+ * marker, so a text file that mentions "Binary files" cannot match.
+ */
+function binaryDiffOutput(diff) {
+    return /^Binary files /m.test(diff);
+}
 function emptyStats(worktreePath) {
     return {
         worktreePath, branch: '', ahead: 0, behind: 0, detached: false,