@hienlh/ppm 0.19.12 → 0.20.1

package/src/services/db.service.ts

@@ -6,7 +6,7 @@ import { getPpmDir } from "./ppm-dir.ts";
 import { assertProdDbAccessAllowed } from "./prod-db-guard.ts";
 import { backupDbSync } from "./db-backup/db-backup-sync.ts";
 import { CODEX_DEFAULT_MODEL } from "../types/config.ts";
-export const CURRENT_SCHEMA_VERSION = 45;
+export const CURRENT_SCHEMA_VERSION = 47;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -1078,6 +1078,49 @@ export function runMigrations(database: Database): void {
 
     database.exec(`PRAGMA user_version = 45;`);
   }
+
+  // Nesting this inside the v45 block, as it briefly was, meant it only ran for a database
+  // coming from 44 or below — every install already sitting at 45 skipped it silently and
+  // then read columns that were never added.
+  if (current < 46) {
+    // Anthropic kills the whole refresh-token family a fixed time after the
+    // original grant — rotation does not extend it — so an account that has been
+    // refreshing happily every 7h still dies on a schedule nothing local can see.
+    // Recording when the grant was issued, and what the server says about the
+    // refresh token's own lifetime, is what lets PPM warn before that happens.
+    for (const col of [
+      "granted_at INTEGER",
+      "refresh_expires_at INTEGER",
+      "reauth_required INTEGER NOT NULL DEFAULT 0",
+      "last_refresh_attempt_at INTEGER",
+    ]) {
+      try {
+        database.exec(`ALTER TABLE accounts ADD COLUMN ${col}`);
+      } catch {
+        // Column may already exist
+      }
+    }
+    // Existing rows are deliberately left with granted_at NULL. created_at is the
+    // row's creation, not the grant: an account re-authenticated last week still
+    // carries a created_at from months ago, and backfilling it would render every
+    // healthy account as long past due. NULL reads as "unknown until next sign-in",
+    // which is the truth; reauth_required still catches the death either way.
+    database.exec(`PRAGMA user_version = 46;`);
+  }
+
+  if (current < 47) {
+    // Codex accounts had no way to be switched off. Claude accounts have had `status` since
+    // the beginning, so the chat panel could offer a toggle there and not here — the same
+    // control meaning two different amounts of work depending on which provider you were
+    // looking at.
+    //
+    // Two states, not Claude's three: nothing puts a Codex account into cooldown, and adding
+    // a state no code can currently produce would just be a branch that never runs.
+    //
+    // Defaults to enabled so an upgrade changes nothing about which accounts are in play.
+    try { database.exec(`ALTER TABLE codex_accounts ADD COLUMN status TEXT NOT NULL DEFAULT 'active'`); } catch { /* exists */ }
+    database.exec(`PRAGMA user_version = 47;`);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1967,6 +2010,13 @@ export interface AccountRow {
   last_used_at: number | null;
   profile_json: string | null;
   created_at: number;
+  /** When the current OAuth grant was issued. NULL for rows predating this column. */
+  granted_at: number | null;
+  /** Server-reported refresh-token expiry, when the token endpoint provides one. */
+  refresh_expires_at: number | null;
+  /** Set once the OAuth server rejects the refresh token; only a fresh sign-in clears it. */
+  reauth_required: number;
+  last_refresh_attempt_at: number | null;
 }
 
 export function getAccounts(): AccountRow[] {
@@ -1979,12 +2029,13 @@ export function getAccountById(id: string): AccountRow | null {
 
 export function insertAccount(row: Omit<AccountRow, "created_at">): void {
   getDb().query(
-    `INSERT INTO accounts (id, label, email, access_token, refresh_token, expires_at, status, cooldown_until, priority, total_requests, last_used_at, profile_json)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    `INSERT INTO accounts (id, label, email, access_token, refresh_token, expires_at, status, cooldown_until, priority, total_requests, last_used_at, profile_json, granted_at, refresh_expires_at, reauth_required, last_refresh_attempt_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   ).run(
     row.id, row.label, row.email, row.access_token, row.refresh_token,
     row.expires_at, row.status, row.cooldown_until, row.priority,
     row.total_requests, row.last_used_at, row.profile_json,
+    row.granted_at, row.refresh_expires_at, row.reauth_required, row.last_refresh_attempt_at,
   );
 }
 
@@ -2002,6 +2053,10 @@ export function updateAccount(id: string, updates: Partial<Omit<AccountRow, "id"
   if (updates.total_requests !== undefined) { sets.push("total_requests = ?"); vals.push(updates.total_requests); }
   if (updates.last_used_at !== undefined) { sets.push("last_used_at = ?"); vals.push(updates.last_used_at); }
   if (updates.profile_json !== undefined) { sets.push("profile_json = ?"); vals.push(updates.profile_json); }
+  if (updates.granted_at !== undefined) { sets.push("granted_at = ?"); vals.push(updates.granted_at); }
+  if (updates.refresh_expires_at !== undefined) { sets.push("refresh_expires_at = ?"); vals.push(updates.refresh_expires_at); }
+  if (updates.reauth_required !== undefined) { sets.push("reauth_required = ?"); vals.push(updates.reauth_required); }
+  if (updates.last_refresh_attempt_at !== undefined) { sets.push("last_refresh_attempt_at = ?"); vals.push(updates.last_refresh_attempt_at); }
   if (sets.length === 0) return;
   vals.push(id);
   getDb().query(`UPDATE accounts SET ${sets.join(", ")} WHERE id = ?`).run(...(vals as SQLQueryBindings[]));

package/src/services/extension.service.ts

@@ -1,4 +1,4 @@
-import { resolve } from "node:path";
+import { resolve, dirname } from "node:path";
 import { existsSync } from "node:fs";
 import type { ExtensionManifest, ExtensionInfo, RpcMessage } from "../types/extension.ts";
 import { getExtensions, getExtensionById, insertExtension, updateExtension, deleteExtension, deleteExtensionStorage, getExtensionStorage, setExtensionStorageValue } from "./db.service.ts";
@@ -8,6 +8,58 @@ import { parseManifest, discoverManifests, discoverBundledManifests } from "./ex
 import { installExtension, removeExtension, devLinkExtension, ensureExtensionsDir } from "./extension-installer.ts";
 import { registerVscodeCompatHandlers } from "./extension-rpc-handlers.ts";
 import { getPpmDir } from "./ppm-dir.ts";
+import { isCompiledBinary } from "./autostart-generator.ts";
+
+/**
+ * Where the bundled `packages/ext-*` extensions live on disk.
+ *
+ * They are loaded as source by the extension host, so they ship *beside* the install rather
+ * than inside it. Walking up from `import.meta.dir` finds them when PPM runs from source, but
+ * a compiled binary reports `/$bunfs/root` — its embedded filesystem — and the same walk lands
+ * on `/packages`, an absolute path at the filesystem root that cannot exist. Every bundled
+ * extension then vanished with no error and no log line: the panel simply said none were
+ * installed. Fall back to the directory holding the executable (`<install>/dist/ppm` →
+ * `<install>/packages`).
+ */
+export function bundledExtensionsDir(
+  moduleDir: string = import.meta.dir,
+  execPath: string = process.execPath,
+): string {
+  const fromSource = resolve(moduleDir, "../../packages");
+  if (existsSync(fromSource)) return fromSource;
+  return resolve(dirname(execPath), "../packages");
+}
+
+/**
+ * How to name the extension host worker so Bun will actually load it.
+ *
+ * Neither form works in both modes, which is why this is a branch and not a constant:
+ *
+ * - `new URL("./extension-host-worker.ts", import.meta.url)` is right from source — it is
+ *   anchored to this module, so it survives the service's `WorkingDirectory=~/.ppm`. From a
+ *   compiled binary it yields `file:///$bunfs/root/...`, the embedded filesystem, and Bun
+ *   refuses to resolve a worker entry point there: the Worker fails to build and dies at once.
+ *   `ensureWorker` only null-checks, so every later activation posts to the corpse and reports
+ *   `Worker has been terminated`.
+ * - A relative specifier is right when compiled — but it resolves against the directory of the
+ *   build's *main entry point* (`src/index.ts`), not against this module, so it reads
+ *   `./services/...` rather than `./`. Verified at cwd `/`, `~/.ppm` and the binary's own
+ *   directory; every other spelling tried (`./extension-host-worker.ts`, `src/services/...`,
+ *   the `/$bunfs/` path) is refused. From source the same specifier resolves against cwd, so
+ *   it breaks the moment cwd is not this directory, which for the service it never is.
+ *
+ * The worker also has to be a second entry point of `bun build --compile` (see the `build`
+ * script) — a worker referenced only through `new URL` is not pulled into the binary.
+ *
+ * Compiling this way also keeps the worker's own imports (`@ppm/vscode-compat`) inside the
+ * bundle, where loading it off disk would have to resolve them through `node_modules` — which
+ * a worker spawned from a compiled binary does not do.
+ */
+export function extensionHostWorkerSpec(compiled: boolean = isCompiledBinary()): string {
+  return compiled
+    ? "./services/extension-host-worker.ts"
+    : new URL("./extension-host-worker.ts", import.meta.url).href;
+}
 
 class ExtensionService {
   private worker: Worker | null = null;
@@ -24,8 +76,7 @@ class ExtensionService {
   private ensureWorker(): { worker: Worker; rpc: RpcChannel } {
     if (this.worker && this.rpc) return { worker: this.worker, rpc: this.rpc };
 
-    const workerPath = new URL("./extension-host-worker.ts", import.meta.url).href;
-    this.worker = new Worker(workerPath, { type: "module" });
+    this.worker = new Worker(extensionHostWorkerSpec(), { type: "module" });
     this.rpc = new RpcChannel((msg) => this.worker!.postMessage(msg));
 
     this.rpc.onRequest("storage:set", async (params) => {
@@ -73,8 +124,7 @@ class ExtensionService {
     ensureExtensionsDir(resolve(getPpmDir(), "extensions"));
 
     // Discover bundled extensions from packages/ext-*
-    const bundledDir = resolve(import.meta.dir, "../../packages");
-    const bundled = await discoverBundledManifests(bundledDir);
+    const bundled = await discoverBundledManifests(bundledExtensionsDir());
     for (const m of bundled) {
       this.extensionPaths.set(m.id, m._dir);
       this.bundledIds.add(m.id);

package/src/services/git-blame/blame-porcelain.ts

@@ -0,0 +1,89 @@
+/**
+ * Parser for `git blame --porcelain`.
+ *
+ * The porcelain format emits a commit's full header only the *first* time that
+ * commit is seen; every later line from it carries just the sha, an optional
+ * `previous`/`filename`, and the content. So headers accumulate into a map and
+ * lines reference it by sha. `--line-porcelain` would repeat every header and
+ * roughly triple the output for no extra information.
+ */
+import { isUncommittedHash, type BlameCommitInfo, type BlameLine, type BlameResult } from "../../shared/blame.ts";
+
+function stripAngles(value: string): string {
+  return value.replace(/^</, "").replace(/>$/, "");
+}
+
+export function parseBlamePorcelain(stdout: string): BlameResult {
+  const commits: Record<string, BlameCommitInfo> = {};
+  const lines: BlameLine[] = [];
+
+  // Split on \n only: a content line may legitimately end with \r (a CRLF
+  // file), and that \r belongs to the file, not to the porcelain framing.
+  let current: BlameCommitInfo | null = null;
+  let finalLine = 0;
+  let origLine = 0;
+
+  for (const raw of stdout.split("\n")) {
+    if (raw === "") continue;
+
+    // A content line is the only kind that starts with a tab, and it closes the
+    // record — the next header line begins a new one.
+    if (raw.startsWith("\t")) {
+      if (current) lines.push({ hash: current.hash, finalLine, origLine });
+      current = null;
+      continue;
+    }
+
+    const header = /^([0-9a-f]{40})\s+(\d+)\s+(\d+)(?:\s+(\d+))?$/.exec(raw);
+    if (header) {
+      const hash = header[1]!;
+      origLine = Number(header[2]);
+      finalLine = Number(header[3]);
+      let info = commits[hash];
+      if (!info) {
+        info = {
+          hash,
+          author: isUncommittedHash(hash) ? "You" : "",
+          authorMail: "",
+          authorTime: 0,
+          summary: isUncommittedHash(hash) ? "Uncommitted changes" : "",
+        };
+        commits[hash] = info;
+      }
+      current = info;
+      continue;
+    }
+
+    if (!current) continue;
+
+    const sep = raw.indexOf(" ");
+    const key = sep === -1 ? raw : raw.slice(0, sep);
+    const value = sep === -1 ? "" : raw.slice(sep + 1);
+
+    switch (key) {
+      case "author":
+        if (value) current.author = value;
+        break;
+      case "author-mail":
+        current.authorMail = stripAngles(value);
+        break;
+      case "author-time":
+        current.authorTime = Number(value) || 0;
+        break;
+      case "summary":
+        if (value) current.summary = value;
+        break;
+      case "filename":
+        current.filename = value;
+        break;
+      case "previous":
+        // "previous <sha> <path>" — only the sha is useful here.
+        current.previous = value.split(" ")[0];
+        break;
+      default:
+        break;
+    }
+  }
+
+  return { lines, commits };
+}

package/src/services/git-blame/git-blame.service.ts

@@ -0,0 +1,90 @@
+/**
+ * `git blame` for the editor's inline annotation.
+ *
+ * One call blames the whole file — running it per line would be a process per
+ * cursor move. The result is small (a line table plus one record per distinct
+ * commit) and the frontend indexes into it as the cursor moves.
+ */
+import simpleGit from "simple-git";
+import { parseBlamePorcelain } from "./blame-porcelain.ts";
+import type { BlameResult } from "../../shared/blame.ts";
+
+/**
+ * Reject a path that is absolute, escapes the repository, or could be read as
+ * an option. Callers pass paths straight from the browser.
+ *
+ * Deliberately no `node:path` normalisation: on Windows that would rewrite the
+ * separators git expects, and the check is about the string git receives.
+ */
+export function assertSafeFilePath(filePath: string): string {
+  if (!filePath || filePath.startsWith("-") || filePath.startsWith("/") || /[\x00-\x1f\x7f]/.test(filePath)) {
+    throw new Error(`Invalid file path: "${filePath}"`);
+  }
+  let depth = 0;
+  for (const segment of filePath.split(/[\\/]+/)) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      depth--;
+      if (depth < 0) throw new Error(`File path escapes the repository: "${filePath}"`);
+      continue;
+    }
+    depth++;
+  }
+  return filePath;
+}
+
+/**
+ * Reject a revision that could be read as an option or as a range.
+ *
+ * A revision reaches git as its own argv word, so shell metacharacters are not
+ * the hazard here — the two that actually change what the command means are a
+ * leading dash (`--reverse`) and the range syntaxes (`a..b`).
+ *
+ * `~` and `^` stay allowed on purpose: `HEAD~1` and `main^` are exactly the
+ * revisions the diff viewer asks for. The rest of the character class is what
+ * `git check-ref-format` forbids in a refname anyway.
+ */
+export function assertSafeRev(rev: string): string {
+  if (
+    !rev ||
+    rev.startsWith("-") ||
+    rev.includes("..") ||
+    /[\x00-\x1f\x7f:?*[\]\\ ]/.test(rev)
+  ) {
+    throw new Error(`Invalid revision: "${rev}"`);
+  }
+  return rev;
+}
+
+class GitBlameService {
+  /**
+   * Blame every line of `filePath`, in the working tree or as it stood at `rev`.
+   *
+   * `rev` is what makes blame work inside the diff viewer: each side of a diff
+   * is the file at a different revision, so blaming the working tree for the
+   * left-hand pane would name the wrong commits.
+   *
+   * Returns null when there is nothing to blame — the file is untracked, or did
+   * not exist at that revision. Both are ordinary states the UI shows as "no
+   * annotation" rather than an error.
+   */
+  async blameFile(projectPath: string, filePath: string, rev?: string): Promise<BlameResult | null> {
+    assertSafeFilePath(filePath);
+    const git = simpleGit(projectPath);
+    // `-w` ignores whitespace-only changes, so a reformat does not claim every
+    // line. `--` separates the path from the options for good.
+    const args = ["blame", "--porcelain", "-w"];
+    if (rev) args.push(assertSafeRev(rev));
+    args.push("--", filePath);
+
+    try {
+      return parseBlamePorcelain(await git.raw(args));
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      if (/no such path|does not have|is outside repository|no such file/i.test(message)) return null;
+      throw e;
+    }
+  }
+}
+
+export const gitBlameService = new GitBlameService();

package/src/services/git-hunks/git-hunks.service.ts

@@ -0,0 +1,264 @@
+/**
+ * Staging, unstaging and discarding at hunk / line granularity.
+ *
+ * Each operation is a patch fed to `git apply` on stdin. `simple-git` has no
+ * stdin door, so these spawn git directly.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { DiffHunk } from "./unified-diff.ts";
+import {
+  buildPatch, hunkFingerprint, parseUnifiedDiff, resolveRequestedHunks, selectionFromRequest,
+} from "./unified-diff.ts";
+
+export type HunkScope = "worktree" | "index";
+
+export interface HunkRequest {
+  /** Where the hunk sat in the list the client was given. A hint, not the key. */
+  hunk: number;
+  /**
+   * `hunkFingerprint` of the hunk the user actually ticked. This is what the
+   * selection is resolved by, so a file that moved on cannot be silently staged
+   * from a different diff than the one on screen.
+   */
+  id: string;
+  /** Line indexes within the hunk; omitted means the whole hunk. */
+  lines?: number[];
+}
+
+/** A hunk as the browser receives it: UTF-8 text plus its content address. */
+export type ListedHunk = DiffHunk & { id: string };
+
+export interface FileHunks {
+  filePath: string;
+  scope: HunkScope;
+  hunks: ListedHunk[];
+  binary: boolean;
+}
+
+interface GitResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Spawn git and hand back its output byte-for-byte.
+ *
+ * Two things here are load-bearing and neither is visible in review.
+ *
+ * Chunks are collected as `Buffer` and decoded **once**. Decoding each chunk as
+ * it arrives (`stdout += c.toString()`) splits any multi-byte sequence that
+ * straddles a chunk boundary into two invalid halves, which become U+FFFD — and
+ * because a patch built from that text still *applies*, the corruption lands in
+ * the index with no error anywhere. Measured on a 2 MB all-Japanese diff: 43
+ * mangled lines.
+ *
+ * The decode is **latin1**, not utf8, so it is a lossless byte round-trip: the
+ * patch written back to `git apply` is the bytes git gave us, whatever the
+ * file's encoding actually is (a Latin-1 file could not be hunk-staged at all
+ * before). Everything the parser looks at — `@@`, `+`, `-`, `\` — is ASCII and
+ * reads the same either way. Only text leaving for the browser is turned back
+ * into UTF-8, by `toDisplay` below.
+ */
+function runGit(
+  projectPath: string,
+  args: string[],
+  options: { stdin?: Buffer; env?: Record<string, string> } = {},
+): Promise<GitResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd: projectPath,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...options.env },
+    });
+
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout.on("data", (c: Buffer) => { stdout.push(c); });
+    child.stderr.on("data", (c: Buffer) => { stderr.push(c); });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({
+      stdout: Buffer.concat(stdout).toString("latin1"),
+      // stderr only ever becomes a message for a human, so it is decoded the
+      // way a human expects to read it.
+      stderr: Buffer.concat(stderr).toString("utf8"),
+      exitCode: code ?? 0,
+    }));
+
+    if (options.stdin !== undefined) {
+      child.stdin.end(options.stdin);
+    } else {
+      child.stdin.end();
+    }
+  });
+}
+
+/** Undo `runGit`'s latin1 decode, for text on its way to the browser. */
+function toDisplay(text: string): string {
+  return Buffer.from(text, "latin1").toString("utf8");
+}
+
+/**
+ * Reject a path that is absolute, escapes the repository, or could be read as
+ * an option. Callers pass paths straight from the browser.
+ */
+function assertSafeFilePath(filePath: string): string {
+  if (!filePath || filePath.startsWith("-") || filePath.startsWith("/") || /[\x00-\x1f\x7f]/.test(filePath)) {
+    throw new Error(`Invalid file path: "${filePath}"`);
+  }
+  let depth = 0;
+  for (const segment of filePath.split(/[\\/]+/)) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      depth--;
+      if (depth < 0) throw new Error(`File path escapes the repository: "${filePath}"`);
+      continue;
+    }
+    depth++;
+  }
+  return filePath;
+}
+
+class GitHunksService {
+  /** Is the file untracked? Hunk staging needs it in the index first. */
+  private async isUntracked(projectPath: string, filePath: string): Promise<boolean> {
+    const res = await runGit(projectPath, ["ls-files", "--error-unmatch", "--", filePath]);
+    return res.exitCode !== 0;
+  }
+
+  /**
+   * An index git may write to, for a file it has never seen.
+   *
+   * A `git diff` needs something to compare against, which for an untracked
+   * file is what `git add -N` provides. That is a write, and every caller here
+   * is describing a file rather than changing one: doing it to the user's index
+   * turns `?? file` into `A file` behind their back, on nothing more than
+   * opening a dialog, and the exit code went unread so a failure showed up as
+   * "no changes" instead. It goes into a throwaway index instead — git reads the
+   * same config and the same `.gitattributes`, normalises line endings the same
+   * way and produces the same bytes, while the real index is never opened for
+   * writing. `git apply --cached` needs no entry of its own to add a new file,
+   * so staging still lands in the real index.
+   */
+  private async scratchIndexFor(projectPath: string, filePath: string): Promise<string | null> {
+    if (!await this.isUntracked(projectPath, filePath)) return null;
+    const dir = await mkdtemp(join(tmpdir(), "ppm-hunk-index-"));
+    const env = { GIT_INDEX_FILE: join(dir, "index") };
+    const added = await runGit(projectPath, ["add", "-N", "--", filePath], { env });
+    if (added.exitCode !== 0) {
+      await rm(dir, { recursive: true, force: true });
+      throw new Error(
+        added.stderr.trim() || `git could not read "${filePath}" (exit ${added.exitCode}).`,
+      );
+    }
+    return dir;
+  }
+
+  /**
+   * `--no-renames` is not a formatting preference.
+   *
+   * With rename detection on, a staged `git mv` makes `git diff --cached` emit a
+   * *rename patch*, and `git apply --cached --reverse` on one of those rewrites
+   * index entries instead of lines: unstaging a single hunk left `D a.txt`
+   * staged and `b.txt` untracked, one commit away from losing the file's
+   * history. Forcing the content form keeps every patch here a patch about
+   * lines in one path.
+   */
+  private async rawDiff(projectPath: string, filePath: string, scope: HunkScope): Promise<string> {
+    const scratch = scope === "worktree" ? await this.scratchIndexFor(projectPath, filePath) : null;
+    try {
+      const args = ["diff", "--no-color", "--no-ext-diff", "--no-renames"];
+      if (scope === "index") args.push("--cached");
+      args.push("--", filePath);
+      const res = await runGit(projectPath, args, {
+        env: scratch ? { GIT_INDEX_FILE: join(scratch, "index") } : undefined,
+      });
+      if (res.exitCode !== 0) {
+        throw new Error(res.stderr.trim() || `git diff exited with ${res.exitCode}`);
+      }
+      // Belt and braces: a future flag or a repository config that reintroduces
+      // rename headers must fail loudly rather than reach `git apply --reverse`.
+      if (/^rename (from|to) /m.test(res.stdout)) {
+        throw new Error("This file was renamed — stage or unstage it whole rather than by hunk.");
+      }
+      return res.stdout;
+    } finally {
+      if (scratch) await rm(scratch, { recursive: true, force: true });
+    }
+  }
+
+  /**
+   * The hunks the UI shows, each carrying the content address it must send back.
+   *
+   * Fingerprints are taken from the byte-exact text and the *text* is then
+   * converted for display, so what the client echoes identifies the bytes
+   * rather than a lossy rendering of them.
+   */
+  async getHunks(projectPath: string, filePath: string, scope: HunkScope): Promise<FileHunks> {
+    assertSafeFilePath(filePath);
+    const parsed = parseUnifiedDiff(await this.rawDiff(projectPath, filePath, scope));
+    const hunks: ListedHunk[] = parsed.hunks.map((hunk) => ({
+      ...hunk,
+      id: hunkFingerprint(hunk),
+      heading: toDisplay(hunk.heading),
+      lines: hunk.lines.map((line) => ({ ...line, text: toDisplay(line.text) })),
+    }));
+    return { filePath, scope, hunks, binary: parsed.binary };
+  }
+
+  private async applySelection(
+    projectPath: string,
+    filePath: string,
+    scope: HunkScope,
+    requested: HunkRequest[],
+    apply: { cached: boolean; reverse: boolean },
+  ): Promise<void> {
+    assertSafeFilePath(filePath);
+    if (requested.length === 0) throw new Error("No hunks were selected.");
+
+    const parsed = parseUnifiedDiff(await this.rawDiff(projectPath, filePath, scope));
+    if (parsed.binary) throw new Error("A binary file cannot be staged by hunk — stage the whole file.");
+    if (parsed.hunks.length === 0) throw new Error("This file has no changes to apply.");
+
+    // The client's indexes describe the diff it was *shown*; this diff was read
+    // again just now. Resolving by content is what makes the two the same list
+    // — or refuses. `git apply` cannot be the guard here, because the patch is
+    // built from this fresh parse and therefore always applies cleanly.
+    const selection = selectionFromRequest(parsed, resolveRequestedHunks(parsed, requested));
+    const patch = buildPatch(parsed, selection, { reverse: apply.reverse });
+    if (!patch) throw new Error("The selection contains no actual change.");
+
+    // Default three lines of context, no `--unidiff-zero`.
+    const args = ["apply"];
+    if (apply.cached) args.push("--cached");
+    if (apply.reverse) args.push("--reverse");
+    args.push("-");
+
+    const res = await runGit(projectPath, args, { stdin: Buffer.from(patch, "latin1") });
+    if (res.exitCode !== 0) {
+      throw new Error(
+        res.stderr.trim() ||
+        `git could not apply the patch (exit ${res.exitCode}).`,
+      );
+    }
+  }
+
+  /** Move the selected worktree changes into the index. */
+  async stage(projectPath: string, filePath: string, hunks: HunkRequest[]): Promise<void> {
+    await this.applySelection(projectPath, filePath, "worktree", hunks, { cached: true, reverse: false });
+  }
+
+  /** Take the selected staged changes back out of the index. */
+  async unstage(projectPath: string, filePath: string, hunks: HunkRequest[]): Promise<void> {
+    await this.applySelection(projectPath, filePath, "index", hunks, { cached: true, reverse: true });
+  }
+
+  /** Throw away the selected worktree changes. Not recoverable. */
+  async discard(projectPath: string, filePath: string, hunks: HunkRequest[]): Promise<void> {
+    await this.applySelection(projectPath, filePath, "worktree", hunks, { cached: false, reverse: true });
+  }
+}
+
+export const gitHunksService = new GitHunksService();