decorated-pi 0.7.2 → 0.8.0

package/settings.ts

@@ -7,6 +7,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import type { Model } from "@earendil-works/pi-ai";
+import { which } from "./utils/which.js";
 
 const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent");
 const CONFIG_FILE = path.join(CONFIG_DIR, "decorated-pi.json");
@@ -69,15 +70,46 @@ export interface UsageIndexEntry {
   mtime: number;
 }
 
+/** Per-binary dependency override.
+ *
+ *  Keyed by binary name (e.g. "rtk", "wakatime-cli", "gopls",
+ *  "codegraph"). `path` injects an extra search location into which();
+ *  `dontBother` silences missing-dependency notifications for this binary. */
+export interface DependencySettings {
+  /** Absolute path to the binary (file) or a directory to search. Injected
+   *  into which()'s extendPath, so it's tried before $PATH. */
+  path?: string;
+  /** When true, skeleton's missing-dependency notification skips this
+   *  binary. Use for binaries the user doesn't care about. */
+  dontBother?: boolean;
+}
+
+export interface DependencyView extends DependencySettings {
+  /** Runtime-only shadow value: what the resolver actually found.
+   *  Not persisted to decorated-pi.json and not written by /dp-settings. */
+  resolvedPath?: string;
+  /** Runtime-only shadow value: whether the resolver checked/found it. */
+  resolvedState?: "ok" | "missing";
+}
+
 export interface DecoratedPiConfig {
   imageModelKey?: string | null;
   compactModelKey?: string | null;
+  dependencies?: Record<string, DependencySettings>;
   providers?: Record<string, ProviderCache>;
   modules?: ModuleSettings;
   mcpServers?: Record<string, McpServerEntry>;
   usageIndex?: Record<string, UsageIndexEntry>;
 }
 
+/** Runtime view = real config plus in-memory shadow fields. The shadow has
+ *  the same top-level shape as config, but may enrich selected leaves with
+ *  runtime-only data. It is never persisted and /dp-settings writes only the
+ *  real config through setter functions. */
+export interface DecoratedPiConfigView extends Omit<DecoratedPiConfig, "dependencies"> {
+  dependencies?: Record<string, DependencyView>;
+}
+
 export function loadConfig(): DecoratedPiConfig {
   try {
     if (fs.existsSync(CONFIG_FILE)) {
@@ -99,6 +131,11 @@ export function saveConfig(config: Partial<DecoratedPiConfig>) {
   fs.writeFileSync(CONFIG_FILE, JSON.stringify({ ...current, ...config }, null, 2), "utf-8");
 }
 
+// Runtime-only shadow for the whole config. It mirrors DecoratedPiConfig's
+// top-level shape but is never persisted; runtime modules update it, and
+// /dp-settings reads the merged view for display only.
+const configShadow: DecoratedPiConfigView = {};
+
 // ─── 辅助 ──────────────────────────────────────────────────────────────────
 
 export function formatModelKey(m: Model<any>): string {
@@ -165,6 +202,77 @@ export function getCompactModelKey(): string | null {
   return loadConfig().compactModelKey ?? null;
 }
 
+/** Look up a binary's configured path override. Returns null when not set. */
+export function getDependencyPath(name: string): string | null {
+  return loadConfig().dependencies?.[name]?.path ?? null;
+}
+
+/** Whether missing-dependency notifications are silenced for this binary. */
+export function isDontBother(name: string): boolean {
+  return loadConfig().dependencies?.[name]?.dontBother === true;
+}
+
+export function getConfigView(): DecoratedPiConfigView {
+  const real = loadConfig();
+  const dependencyNames = new Set([
+    ...Object.keys(real.dependencies ?? {}),
+    ...Object.keys(configShadow.dependencies ?? {}),
+  ]);
+  const dependencies: Record<string, DependencyView> = {};
+  for (const name of dependencyNames) {
+    dependencies[name] = {
+      ...(real.dependencies?.[name] ?? {}),
+      ...(configShadow.dependencies?.[name] ?? {}),
+    };
+  }
+  return {
+    ...real,
+    ...configShadow,
+    dependencies: Object.keys(dependencies).length ? dependencies : undefined,
+  };
+}
+
+export function getDependencyView(name: string): DependencyView {
+  return getConfigView().dependencies?.[name] ?? {};
+}
+
+export function listDependencyViewNames(extraNames: string[] = []): string[] {
+  return [...new Set([
+    ...extraNames,
+    ...Object.keys(getConfigView().dependencies ?? {}),
+  ])].sort();
+}
+
+export function recordDependencyResolution(name: string, resolvedPath: string | null): void {
+  if (!configShadow.dependencies) configShadow.dependencies = {};
+  configShadow.dependencies[name] = {
+    ...(configShadow.dependencies[name] ?? {}),
+    ...(resolvedPath
+      ? { resolvedState: "ok" as const, resolvedPath }
+      : { resolvedState: "missing" as const, resolvedPath: undefined }),
+  };
+}
+
+/** Resolve a binary using dependency config plus caller-specific search
+ *  locations. Modules call this at startup/runtime; it records a shadow
+ *  view for /dp-settings but does not persist anything.
+ *
+ *  Order:
+ *    1. dependencies[name].path (file or directory)
+ *    2. opts.extendPath entries (file or directory)
+ *    3. $PATH
+ */
+export function resolveDependency(name: string, opts?: { extendPath?: string[] }): string | null {
+  const override = getDependencyPath(name);
+  const extendPath = [
+    ...(override ? [override] : []),
+    ...(opts?.extendPath ?? []),
+  ];
+  const resolved = which(name, { extendPath });
+  recordDependencyResolution(name, resolved);
+  return resolved;
+}
+
 // ─── Setter ─────────────────────────────────────────────────────────────────
 
 export function setImageModelKey(key: string | null) {
@@ -175,6 +283,47 @@ export function setCompactModelKey(key: string | null) {
   saveConfig({ compactModelKey: key });
 }
 
+/** Set or clear a binary's path override. Pass null to remove the path.
+ *  Preserves any dontBother flag on the same entry (精准修改不覆盖). */
+export function setDependencyPath(name: string, path: string | null) {
+  const current = loadConfig();
+  const deps = { ...(current.dependencies ?? {}) };
+  const existing = deps[name] ?? {};
+  if (path === null) {
+    const { path: _drop, ...rest } = existing;
+    if (Object.keys(rest).length === 0) {
+      delete deps[name];
+    } else {
+      deps[name] = rest;
+    }
+  } else {
+    deps[name] = { ...existing, path };
+  }
+  // Path edits are config writes; invalidate runtime-only resolution for
+  // this binary so /dp-settings never shows a stale pre-edit shadow path.
+  if (configShadow.dependencies?.[name]) delete configShadow.dependencies[name];
+  saveConfig({ dependencies: deps });
+}
+
+/** Set or clear a binary's dontBother flag. Pass false to re-enable
+ *  missing-dependency notifications. Preserves any path override. */
+export function setDontBother(name: string, dontBother: boolean) {
+  const current = loadConfig();
+  const deps = { ...(current.dependencies ?? {}) };
+  const existing = deps[name] ?? {};
+  if (dontBother) {
+    deps[name] = { ...existing, dontBother: true };
+  } else {
+    const { dontBother: _drop, ...rest } = existing;
+    if (Object.keys(rest).length === 0) {
+      delete deps[name];
+    } else {
+      deps[name] = rest;
+    }
+  }
+  saveConfig({ dependencies: deps });
+}
+
 // ─── Module Switches ──────────────────────────────────────────────────────────
 
 const DEFAULT_MODULES: Required<ModuleSettings> = {
@@ -321,14 +470,23 @@ export function getAllModuleSettings(): Required<ModuleSettings> {
  * reload is actually necessary.
  */
 let loadedModuleSnapshot: Required<ModuleSettings> | null = null;
+let loadedDependenciesSnapshot: Record<string, DependencySettings> | null = null;
 
 export function captureModuleSnapshot(): void {
   loadedModuleSnapshot = getAllModuleSettings();
+  loadedDependenciesSnapshot = loadConfig().dependencies ?? {};
 }
 
 export function moduleSnapshotChanged(): boolean {
   if (!loadedModuleSnapshot) return true;
-  return JSON.stringify(loadedModuleSnapshot) !== JSON.stringify(getAllModuleSettings());
+  if (JSON.stringify(loadedModuleSnapshot) !== JSON.stringify(getAllModuleSettings())) return true;
+  // Dependencies changes don't strictly require reload (which() reads the
+  // config file on every call), but prompt for consistency — the user
+  // might be mid-session and expect the new path to be picked up by hooks
+  // that captured the binary path at startup (rtk/wakatime).
+  const currentDeps = loadConfig().dependencies ?? {};
+  if (JSON.stringify(loadedDependenciesSnapshot) !== JSON.stringify(currentDeps)) return true;
+  return false;
 }
 
 // ─── Usage index (增量同步元数据) ─────────────────────────────────────────────

package/tools/ask/index.ts

@@ -17,11 +17,8 @@ const askQuestionSchema = Type.Object({
     { description: "text = free input, single = one option, multi = many options" },
   ),
   question: Type.String({ description: "Question text shown to the user." }),
-  options: Type.Optional(Type.Array(Type.String(), { description: "Options for single or multi choice." })),
+  options: Type.Optional(Type.Array(Type.String(), { description: "Options for single or multi choice. Each option MUST be a plain string (not an object). Example: [\"选项A\", \"选项B\", \"选项C\"]. The user picks by index; do NOT pass {id,text} objects." })),
   default: Type.Optional(Type.String({ description: "Default answer. For multi, comma-separated values." })),
-  allowCustom: Type.Optional(Type.Boolean({
-    description: "For single/multi: append an \"Other\" row that toggles into a free-text input. Lets the user enter a custom answer not in the preset list.",
-  })),
 });
 
 function formatAnswer(q: AskQuestion, value: string | string[]): string {

package/tools/lsp/servers.ts

@@ -2,9 +2,9 @@
  * LSP Server Config — language detection, server commands, workspace roots.
  */
 import { existsSync, readdirSync, type Dirent } from "node:fs";
-import { spawnSync } from "node:child_process";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 import type { DependencyStatus } from "../../hooks/skeleton.js";
+import { getDependencyPath, resolveDependency } from "../../settings.js";
 
 // ─── File extension → language mapping ────────────────────────────────────
 
@@ -97,6 +97,16 @@ export function listSupportedLanguages(): string[] {
   return Object.keys(LANGUAGE_SERVERS).sort();
 }
 
+/** Unique binary names used by builtin LSP servers. Used by the
+ *  /dp-settings Dependencies UI to know which binaries are configurable. */
+export function listLspBinaryNames(): string[] {
+  const seen = new Set<string>();
+  for (const lang of Object.keys(LANGUAGE_SERVERS)) {
+    seen.add(LANGUAGE_SERVERS[lang].command);
+  }
+  return [...seen].sort();
+}
+
 export function getServerConfig(
   language: string,
   cwd = process.cwd(),
@@ -104,6 +114,12 @@ export function getServerConfig(
   const base = LANGUAGE_SERVERS[language];
   if (!base) return undefined;
 
+  const override = getDependencyPath(base.command);
+  if (override) {
+    const resolvedOverride = resolveDependency(base.command, { extendPath: [] });
+    return { ...base, command: resolvedOverride ?? override, is_project_local: false };
+  }
+
   const resolved = resolveLocalBinary(base.command, cwd);
   return { ...base, command: resolved.command, is_project_local: resolved.is_project_local };
 }
@@ -147,14 +163,16 @@ export function collectLspDependencyStatuses(cwd: string): DependencyStatus[] {
   const statuses: DependencyStatus[] = [];
   const seen = new Set<string>();
   for (const language of listSupportedLanguages()) {
-    const cfg = getServerConfig(language, cwd);
-    if (!cfg || seen.has(cfg.command)) continue;
-    seen.add(cfg.command);
+    const base = LANGUAGE_SERVERS[language];
+    if (!base || seen.has(base.command)) continue;
+    seen.add(base.command);
+    const path = resolveLspBinary(base.command, cwd);
     statuses.push({
       module: "lsp",
-      label: cfg.command,
-      state: commandExists(cfg.command) ? "ok" : "missing",
-      detail: cfg.install_hint,
+      label: base.command,
+      state: path ? "ok" : "missing",
+      detail: base.install_hint,
+      path: path ?? undefined,
     });
   }
   return statuses;
@@ -174,14 +192,12 @@ export function findWorkspaceRoot(
 
 // ─── Internal helpers ─────────────────────────────────────────────────────
 
-function commandExists(command: string): boolean {
-  if (isAbsolute(command) || command.includes("/") || command.includes("\\")) {
-    return existsSync(command);
-  }
-  const result = process.platform === "win32"
-    ? spawnSync("where", [command], { encoding: "utf-8" })
-    : spawnSync(process.env.SHELL || "sh", ["-lc", `command -v '${command.replace(/'/g, `'"'"'`)}'`], { encoding: "utf-8" });
-  return result.status === 0;
+export function lspDependencyExtendPath(cwd = process.cwd()): string[] {
+  return [...ancestorDirs(cwd)].map((dir) => join(dir, "node_modules", ".bin"));
+}
+
+export function resolveLspBinary(command: string, cwd = process.cwd()): string | null {
+  return resolveDependency(command, { extendPath: lspDependencyExtendPath(cwd) });
 }
 
 function resolveLocalBinary(

package/tools/mcp/config.ts

@@ -15,11 +15,11 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { spawnSync } from "node:child_process";
-import { isModuleEnabled } from "../../settings.js";
+import { isModuleEnabled, resolveDependency } from "../../settings.js";
 import type { DependencyStatus } from "../../hooks/skeleton.js";
 import { BUILTIN_MCP_SERVERS } from "./builtin/index.js";
 
+
 export { BUILTIN_MCP_SERVERS } from "./builtin/index.js";
 
 export interface McpServerConfig {
@@ -33,6 +33,8 @@ export interface McpServerConfig {
   source: "builtin" | "global" | "project";
   /** Optional predicate: return false if this server cannot be used in the given project. */
   canUseInProject?: (cwd: string) => boolean;
+  /** Binary/config key before dependency path resolution. */
+  dependencyName?: string;
 }
 
 function globalMcpJsonPath(): string {
@@ -217,33 +219,50 @@ export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
     }
   }
 
-  return [...byName.values()].filter((s) => s.url || s.command);
+  return [...byName.values()]
+    .filter((s) => s.url || s.command)
+    .map((s) => {
+      // Apply user-configured binary path override (dependencies[cmd].path)
+      // last, so it wins over builtin/global/project configs. Only applies
+      // to servers that use a command (not URL-based servers).
+      if (!s.command) return s;
+      const dependencyName = s.command;
+      const resolved = resolveMcpBinary(dependencyName);
+      return { ...s, dependencyName, command: resolved ?? s.command };
+    });
+}
+
+/** Unique binary names used by builtin MCP servers that have a `command`
+ *  (URL-based servers are excluded — they don't need a binary). */
+export function listMcpBinaryNames(): string[] {
+  const seen = new Set<string>();
+  for (const s of BUILTIN_MCP_SERVERS) {
+    if (s.command) seen.add(s.command);
+  }
+  return [...seen].sort();
 }
 
 export function collectMcpDependencyStatuses(cwd: string): DependencyStatus[] {
   const seen = new Set<string>();
   const statuses: DependencyStatus[] = [];
   for (const cfg of resolveMcpConfigs(cwd)) {
-    if (!cfg.enabled || !cfg.command || seen.has(cfg.command)) continue;
-    seen.add(cfg.command);
+    const depName = cfg.dependencyName ?? cfg.command;
+    if (!cfg.enabled || !cfg.command || !depName || seen.has(depName)) continue;
+    seen.add(depName);
+    const resolved = resolveMcpBinary(depName);
     statuses.push({
       module: `mcp:${cfg.name}`,
-      label: cfg.command,
-      state: commandExists(cfg.command) ? "ok" : "missing",
+      label: depName,
+      state: resolved ? "ok" : "missing",
       detail: `Install the MCP server command for \"${cfg.name}\" or update its config.`,
+      path: resolved ?? undefined,
     });
   }
   return statuses;
 }
 
-function commandExists(command: string): boolean {
-  if (path.isAbsolute(command) || command.includes("/") || command.includes("\\")) {
-    return fs.existsSync(command);
-  }
-  const result = process.platform === "win32"
-    ? spawnSync("where", [command], { encoding: "utf-8" })
-    : spawnSync(process.env.SHELL || "sh", ["-lc", `command -v '${command.replace(/'/g, `'"'"'`)}'`], { encoding: "utf-8" });
-  return result.status === 0;
+export function resolveMcpBinary(command: string): string | null {
+  return resolveDependency(command);
 }
 
 function readMcpJsonSafe(filePath: string): Record<string, any> | null {

package/tools/patch/core.ts

@@ -11,7 +11,12 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as fsPromises from "node:fs/promises";
+import {
+  detectFileEncoding,
+  readFileDecoded,
+  writeFileEncoded,
+  type FileEncoding,
+} from "./encoding.js";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -63,6 +68,12 @@ export interface ReplacementInfo {
   oldLines: string[];
   /** The new lines that replaced them */
   newLines: string[];
+  /** Verbatim normalized replacement text (for byte-faithful writeback). */
+  newStr?: string;
+  /** Offset in normalized content where the matched region starts (writeback). */
+  normStart?: number;
+  /** Offset one past the matched region in normalized content (writeback). */
+  normEnd?: number;
   /** Optional anchor text (first line only, for hunk display) */
   anchor?: string;
   /** Anchor was provided but not found, and patch fell back to global old_str search */
@@ -156,13 +167,20 @@ function applyOverwrite(
   content: string,
   result: PatchResult,
 ): void {
-  const oldContent = fs.existsSync(absPath) ? fs.readFileSync(absPath, "utf8") : "";
+  // Detect encoding from the existing file so we round-trip in the same
+  // bytes. New files default to UTF-8 (no BOM).
+  const enc: FileEncoding | null = fs.existsSync(absPath)
+    ? detectFileEncoding(absPath)
+    : null;
+  const oldContent = enc ? readFileDecoded(absPath, enc) : "";
 
   // Write to temp file in the same directory (same filesystem → mv is atomic)
   ensureParentDir(absPath);
   const dir = path.dirname(absPath);
   const tmpName = path.join(dir, `.pi-patch-${randomId()}.tmp`);
-  fs.writeFileSync(tmpName, content, "utf8");
+  // Overwrite semantics: write exactly what the caller passed, in the
+  // detected encoding (UTF-8 for new files).
+  writeFileEncoded(tmpName, content, enc ?? { encoding: "utf-8", hasBOM: false, isUtf8: true });
   fs.renameSync(tmpName, absPath);
 
   if (oldContent) {
@@ -287,8 +305,8 @@ async function applyEdits(
     throw new ApplyError(`Cannot patch directory: ${displayPath}`);
   }
 
-  const rawContent = fs.readFileSync(absPath, "utf8");
-  const lineEnding = detectLineEnding(rawContent);
+  const enc = detectFileEncoding(absPath);
+  const rawContent = readFileDecoded(absPath, enc);
   const originalContent = normalizeLineEndings(rawContent);
 
   // Precompute line offsets for the original file (used throughout)
@@ -349,6 +367,8 @@ async function applyEdits(
 
       const oldStartLine = lineAtOffset(lineOffsets, matchIdx - cumulativeOffset);
       const oldEndLine = lineAtOffset(lineOffsets, matchIdx - cumulativeOffset + oldNorm.length - 1);
+      const normStart = matchIdx - cumulativeOffset;
+      const normEnd = normStart + oldNorm.length;
 
       content =
         content.substring(0, matchIdx) +
@@ -364,6 +384,9 @@ async function applyEdits(
         newEndLine: 0,
         oldLines: oldNorm.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === "")),
         newLines: newNorm.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === "")),
+        newStr: newNorm,
+        normStart,
+        normEnd,
         anchor: displayAnchor ? displayAnchor.split("\n")[0] : undefined,
         anchorMissing,
       });
@@ -392,12 +415,18 @@ async function applyEdits(
       result.diff = fileDiff;
     }
 
-    const finalContent = restoreLineEndings(content, lineEnding);
-    if (lineEnding === "\r\n" && rawContent.includes("\r\n")) {
-      result.warnings.push(`${displayPath}: CRLF line endings were normalized to LF during editing.`);
-    }
+    const finalContent = spliceOntoRaw(
+      rawContent,
+      cleanReplacements
+        .map((r) => ({
+          normStart: r.normStart ?? 0,
+          normEnd: r.normEnd ?? 0,
+          newStr: r.newStr ?? r.newLines.join("\n"),
+        }))
+        .sort((a, b) => a.normStart - b.normStart),
+    );
 
-    fs.writeFileSync(absPath, finalContent, "utf8");
+    writeFileEncoded(absPath, finalContent, enc);
     result.modified.push(displayPath);
     result.replacements.set(displayPath, cleanReplacements);
     return;
@@ -495,14 +524,16 @@ async function applyEdits(
     result.diff = fileDiff;
   }
 
-  // Restore line endings
-  const finalContent = restoreLineEndings(content, lineEnding);
-
-  if (lineEnding === "\r\n" && rawContent.includes("\r\n")) {
-    result.warnings.push(`${displayPath}: CRLF line endings were normalized to LF during editing.`);
-  }
+  const finalContent = spliceOntoRaw(
+    rawContent,
+    sorted.map((p) => ({
+      normStart: p.matchIdx,
+      normEnd: p.matchIdx + p.oldNorm.length,
+      newStr: p.newNorm,
+    })),
+  );
 
-  fs.writeFileSync(absPath, finalContent, "utf8");
+  writeFileEncoded(absPath, finalContent, enc);
   result.modified.push(displayPath);
   result.replacements.set(displayPath, replacements);
 }
@@ -541,7 +572,8 @@ export async function computePatchPreview(
         return { error: "File not found" };
       }
 
-      const rawContent = await fsPromises.readFile(absPath, "utf8");
+      const enc = detectFileEncoding(absPath);
+      const rawContent = readFileDecoded(absPath, enc);
     const lineOffsets = buildLineOffsets(rawContent);
     const totalLines = lineOffsets.length - 1;
     let content = normalizeLineEndings(rawContent);
@@ -1053,16 +1085,68 @@ function ensureParentDir(absPath: string): void {
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
-function detectLineEnding(content: string): string {
-  return content.includes("\r\n") ? "\r\n" : "\n";
-}
-
 function normalizeLineEndings(text: string): string {
   return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
 
-function restoreLineEndings(text: string, ending: string): string {
-  return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+/** A replacement expressed in coordinates of the normalized (\n-only) content,
+ *  paired with the exact new_str to drop in. Used by spliceOntoRaw to rebuild
+ *  the file byte-for-byte on the original rawContent. */
+interface RawSplice {
+  /** Offset in the normalized content where the matched text starts. */
+  normStart: number;
+  /** Offset in the normalized content one past the matched text. */
+  normEnd: number;
+  /** Verbatim replacement text (already normalized to \n). */
+  newStr: string;
+}
+
+/** Map every index of the normalized content to its offset in rawContent.
+ *  The two strings differ only by `\r` bytes (CRLF→LF normalization removed
+ *  them), so we walk both in lockstep. O(n). */
+function buildNormToRawMap(raw: string, norm: string): Int32Array {
+  const map = new Int32Array(norm.length + 1);
+  let ri = 0;
+  for (let ni = 0; ni <= norm.length; ni++) {
+    // Skip any `\r` in raw that the normalization folded into `\n`.
+    // norm[ni] corresponds to raw[ri]; when norm advances past a `\n` that
+    // came from `\r\n`, raw must skip the `\r` first.
+    if (ni < norm.length) {
+      map[ni] = ri;
+      const ch = norm.charCodeAt(ni);
+      const rawCh = raw.charCodeAt(ri);
+      if (ch === 10 /* \n */ && rawCh === 13 /* \r */) {
+        // raw had \r\n; advance past \r then \n
+        ri += 2;
+      } else {
+        ri += 1;
+      }
+    } else {
+      map[ni] = raw.length;
+    }
+  }
+  return map;
+}
+
+/** Rebuild the file on top of the original rawContent: untouched regions keep
+ *  their original bytes (including CRLF / mixed endings), edited regions get
+ *  the verbatim newStr the caller supplied. Splices must be sorted by
+ *  normStart and non-overlapping. */
+function spliceOntoRaw(rawContent: string, splices: RawSplice[]): string {
+  if (splices.length === 0) return rawContent;
+  const norm = normalizeLineEndings(rawContent);
+  const map = buildNormToRawMap(rawContent, norm);
+  let out = "";
+  let rawCursor = 0;
+  for (const s of splices) {
+    const rawStart = map[s.normStart] ?? 0;
+    const rawEnd = map[s.normEnd] ?? rawContent.length;
+    if (rawStart > rawCursor) out += rawContent.substring(rawCursor, rawStart);
+    out += s.newStr;
+    rawCursor = rawEnd;
+  }
+  if (rawCursor < rawContent.length) out += rawContent.substring(rawCursor);
+  return out;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1203,6 +1287,9 @@ function collapseSequentialReplacements(
         newEndLine: merged.oldStartLine + next.newLines.length - 1,
         oldLines: merged.oldLines,
         newLines: next.newLines,
+        newStr: next.newStr,
+        normStart: merged.normStart,
+        normEnd: merged.normEnd,
         anchor: undefined,
         anchorMissing: merged.anchorMissing || next.anchorMissing,
       };
@@ -1530,4 +1617,6 @@ export const __patchCoreTest = {
   truncate,
   collapseSequentialReplacements,
   generateReplacementDiff,
+  spliceOntoRaw,
+  buildNormToRawMap,
 };