@young1lin/dsh-ui-gitworkbench 0.1.4 → 0.1.6

package/src/patch-model.ts

@@ -0,0 +1,267 @@
+/**
+ * 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
+ */
+
+/** One line of a hunk, with its marker stripped. */
+export interface PatchLine {
+  readonly kind: 'add' | 'del' | 'context' | 'nonewline'
+  /** Line content without the leading marker. `nonewline` carries ''. */
+  readonly text: string
+}
+
+/** One hunk, with the header numbers as the source stated them. */
+export interface Hunk {
+  readonly oldStart: number
+  readonly oldCount: number
+  readonly newStart: number
+  readonly newCount: number
+  /** Whatever followed the closing `@@`, kept verbatim (git puts the enclosing
+   *  function there). Empty when the source had none. */
+  readonly heading: string
+  /** Whether the source wrote `@@ -1 @@` rather than `@@ -1,1 @@`. The unified
+   *  format allows a count of 1 to be omitted and git's own output does omit
+   *  it, so re-emitting the other spelling would make a full selection differ
+   *  from its input for no reason. Only consulted when the emitted count is
+   *  itself 1 — a count of 3 is never ambiguous. */
+  readonly oldCountOmitted: boolean
+  readonly newCountOmitted: boolean
+  readonly lines: readonly PatchLine[]
+}
+
+/** One file's patch: the headers `git apply` needs, plus its hunks. */
+export interface FilePatch {
+  /** `diff --git` through `+++`, verbatim and in order. */
+  readonly header: readonly string[]
+  readonly hunks: readonly Hunk[]
+  /** Whether the source text ended with a newline, so a round trip can too. */
+  readonly trailingNewline: boolean
+}
+
+/**
+ * Whether one changed line is part of the patch being built.
+ * Called only for `add` and `del` lines; context is never optional.
+ */
+export type LineSelector = (hunkIndex: number, lineIndex: number) => boolean
+
+/** Take the whole diff. */
+export const selectAll: LineSelector = () => true
+/** Take none of it — {@link emitPatch} then returns ''. */
+export const selectNone: LineSelector = () => 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: string): FilePatch | null {
+  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: string[] = []
+  const hunks: Hunk[] = []
+  let current: { head: RegExpExecArray; lines: PatchLine[] } | null = null
+
+  const close = (): void => {
+    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: number, omitted: boolean): string {
+  return value === 1 && omitted ? '' : `,${value}`
+}
+
+interface Emitted {
+  readonly lines: readonly string[]
+  readonly oldCount: number
+  readonly newCount: number
+  readonly changed: boolean
+}
+
+/** Apply the selection rules to one hunk's lines. */
+function emitHunkLines(hunk: Hunk, hunkIndex: number, isSelected: LineSelector, reverseApply: boolean): Emitted {
+  const out: string[] = []
+  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: FilePatch, isSelected: LineSelector, reverseApply = false): string {
+  const body: string[] = []
+  // 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: number | null = 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/src/side-guard.ts

@@ -0,0 +1,58 @@
+/**
+ * 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: number, lineCount: number): boolean {
+  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: string): boolean {
+  return diff.length > SIDE_DIFF_CHAR_CAP
+}

package/src/write-checked.ts

@@ -0,0 +1,223 @@
+/**
+ * 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, type OpFailure } from './git-ops.js'
+import type { GitRun } from './apply-blocks.js'
+
+/**
+ * `gitWorkbench/writeChecked`'s answer. Optional fields obey the gateway's
+ * JSON rule: success emits `ok` and `sha` and omits `failure`/`error`
+ * entirely; failure omits `sha`.
+ */
+export interface WriteResult {
+  readonly ok: boolean
+  /** Present only on failure; `stale` is the sha refusal this RPC exists for. */
+  readonly failure?: OpFailure
+  /** A sentence for the user; names the file on the stale path. */
+  readonly error?: string
+  /** The file's blob sha after a successful write, for the next save. */
+  readonly sha?: string
+}
+
+/**
+ * Everything the sequence needs from its host, as injected dependencies.
+ *
+ * `index.ts` binds its own `git()` spawn helper and the fs/promises calls; the
+ * tests bind a real git in a temp repo and the real filesystem. Either way the
+ * decisions below are the same code — there is no second implementation to
+ * fall out of step with.
+ */
+export interface WriteCheckedIo {
+  /** Run git in `cwd`. Must not throw — report through `exitCode`/`stderr`. */
+  readonly git: (cwd: string, argv: readonly string[]) => Promise<GitRun>
+  /** Whether the path exists on disk (the explicit not-exist check). */
+  readonly exists: (path: string) => Promise<boolean>
+  /** The file's raw bytes, for the encoding check. Throws if unreadable. */
+  readonly readBytes: (path: string) => Promise<Buffer>
+  /** Write whole bytes to a path — the buffer as-is, LF, no translation. */
+  readonly writeBytes: (path: string, bytes: Uint8Array) => Promise<void>
+  /** Renames a path over another; retried by {@link renameWithRetry}. */
+  readonly rename: (from: string, to: string) => Promise<void>
+  /** Best-effort temp cleanup; a file already gone is a success. */
+  readonly remove: (path: string) => Promise<void>
+  /** Waits the given milliseconds — the rename retry backoff. */
+  readonly delay: (ms: number) => Promise<void>
+}
+
+/**
+ * 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: WriteCheckedIo,
+  cwd: string,
+  path: string,
+  text: string,
+  expectedSha: string,
+): Promise<WriteResult> {
+  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: WriteCheckedIo,
+  cwd: string,
+  path: string,
+  text: string,
+  expectedSha: string,
+): Promise<WriteResult> {
+  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: string
+  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: string
+  const present = await io.exists(target)
+  if (present) {
+    let bytes: Buffer
+    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: string): string {
+  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: string, expectedSha: string, current: string): string {
+  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`
+}