@librechat/agents 3.1.77-dev.1 → 3.1.78-dev.0

package/src/tools/local/editStrategies.ts

@@ -0,0 +1,188 @@
+/**
+ * Single-occurrence string-replacement strategies for `edit_file`.
+ *
+ * The LLM frequently emits an `oldString` whose whitespace, indentation,
+ * or escape sequences are slightly off from the on-disk content. Rather
+ * than failing the call (which forces a re-read + retry round-trip),
+ * we walk a chain of progressively looser matchers, stopping at the
+ * first one that locates exactly one match. The matched on-disk slice
+ * is then literally replaced with `newString` — we never modify
+ * `newString`, only the search.
+ *
+ * Strategies are ordered from strict to lenient so we don't accidentally
+ * over-match a more specific pattern with a looser one. Inspired by
+ * opencode's nine-strategy chain (sst/opencode), trimmed to the four
+ * highest-yield strategies for a first cut. Add more (block-anchor +
+ * Levenshtein, escape-normalized, etc.) as needed.
+ */
+
+export interface EditMatch {
+  /** Strategy name that produced the match, for telemetry/diagnostics. */
+  strategy: string;
+  /** Starting offset in the source. */
+  start: number;
+  /** Ending offset (exclusive). */
+  end: number;
+}
+
+export type EditStrategy = (
+  source: string,
+  oldString: string
+) => EditMatch | null;
+
+const exactStrategy: EditStrategy = (source, oldString) => {
+  if (oldString === '') return null;
+  const first = source.indexOf(oldString);
+  if (first === -1) return null;
+  const second = source.indexOf(oldString, first + oldString.length);
+  if (second !== -1) return null;
+  return { strategy: 'exact', start: first, end: first + oldString.length };
+};
+
+/**
+ * Match per-line, ignoring trailing whitespace differences. Useful for
+ * the very common case where the LLM stripped trailing spaces or added
+ * an extra blank.
+ */
+const lineTrimmedStrategy: EditStrategy = (source, oldString) => {
+  if (oldString === '') return null;
+  const sourceLines = source.split('\n');
+  const oldLines = oldString.split('\n');
+  if (oldLines.length === 0 || oldLines.length > sourceLines.length) {
+    return null;
+  }
+
+  let foundAt = -1;
+  for (let i = 0; i <= sourceLines.length - oldLines.length; i++) {
+    let ok = true;
+    for (let j = 0; j < oldLines.length; j++) {
+      if (sourceLines[i + j].trimEnd() !== oldLines[j].trimEnd()) {
+        ok = false;
+        break;
+      }
+    }
+    if (!ok) continue;
+    if (foundAt !== -1) return null; // multiple matches
+    foundAt = i;
+  }
+  if (foundAt === -1) return null;
+
+  let start = 0;
+  for (let i = 0; i < foundAt; i++) start += sourceLines[i].length + 1;
+  let end = start;
+  for (let i = 0; i < oldLines.length; i++) {
+    end += sourceLines[foundAt + i].length;
+    if (i < oldLines.length - 1) end += 1;
+  }
+  return { strategy: 'line-trimmed', start, end };
+};
+
+/**
+ * Collapse all runs of whitespace to a single space and match. Catches
+ * cases where the LLM normalised tabs to spaces or vice-versa.
+ */
+const whitespaceNormalizedStrategy: EditStrategy = (source, oldString) => {
+  if (oldString === '') return null;
+  const norm = (s: string): string => s.replace(/\s+/g, ' ').trim();
+  const normalizedNeedle = norm(oldString);
+  if (normalizedNeedle === '') return null;
+
+  const sourceLines = source.split('\n');
+  const needleLines = oldString.split('\n');
+  if (needleLines.length > sourceLines.length) return null;
+
+  let foundAt = -1;
+  for (let i = 0; i <= sourceLines.length - needleLines.length; i++) {
+    const candidate = sourceLines
+      .slice(i, i + needleLines.length)
+      .join('\n');
+    if (norm(candidate) !== normalizedNeedle) continue;
+    if (foundAt !== -1) return null;
+    foundAt = i;
+  }
+  if (foundAt === -1) return null;
+
+  let start = 0;
+  for (let i = 0; i < foundAt; i++) start += sourceLines[i].length + 1;
+  let end = start;
+  for (let i = 0; i < needleLines.length; i++) {
+    end += sourceLines[foundAt + i].length;
+    if (i < needleLines.length - 1) end += 1;
+  }
+  return { strategy: 'whitespace-normalized', start, end };
+};
+
+/**
+ * Strip the common leading-indent from each line of the needle and
+ * each candidate window of the source. Catches the very common case
+ * where the LLM omitted the indentation it should have copied.
+ */
+const indentationFlexibleStrategy: EditStrategy = (source, oldString) => {
+  if (oldString === '') return null;
+
+  const stripCommonIndent = (block: string): string => {
+    const lines = block.split('\n');
+    let common = Number.POSITIVE_INFINITY;
+    for (const line of lines) {
+      if (line.trim() === '') continue;
+      const m = /^(\s*)/.exec(line);
+      const indent = m ? m[1].length : 0;
+      if (indent < common) common = indent;
+      if (common === 0) break;
+    }
+    if (!Number.isFinite(common) || common === 0) return block;
+    return lines
+      .map((l) => (l.length >= common ? l.slice(common) : l))
+      .join('\n');
+  };
+
+  const normalizedNeedle = stripCommonIndent(oldString);
+  if (normalizedNeedle === '') return null;
+
+  const sourceLines = source.split('\n');
+  const needleLines = oldString.split('\n');
+  if (needleLines.length > sourceLines.length) return null;
+
+  let foundAt = -1;
+  for (let i = 0; i <= sourceLines.length - needleLines.length; i++) {
+    const window = sourceLines.slice(i, i + needleLines.length).join('\n');
+    if (stripCommonIndent(window) !== normalizedNeedle) continue;
+    if (foundAt !== -1) return null;
+    foundAt = i;
+  }
+  if (foundAt === -1) return null;
+
+  let start = 0;
+  for (let i = 0; i < foundAt; i++) start += sourceLines[i].length + 1;
+  let end = start;
+  for (let i = 0; i < needleLines.length; i++) {
+    end += sourceLines[foundAt + i].length;
+    if (i < needleLines.length - 1) end += 1;
+  }
+  return { strategy: 'indentation-flexible', start, end };
+};
+
+const STRATEGY_CHAIN: EditStrategy[] = [
+  exactStrategy,
+  lineTrimmedStrategy,
+  whitespaceNormalizedStrategy,
+  indentationFlexibleStrategy,
+];
+
+export function locateEdit(source: string, oldString: string): EditMatch | null {
+  for (const strategy of STRATEGY_CHAIN) {
+    const match = strategy(source, oldString);
+    if (match != null) {
+      return match;
+    }
+  }
+  return null;
+}
+
+export function applyEdit(
+  source: string,
+  match: EditMatch,
+  newString: string
+): string {
+  return source.slice(0, match.start) + newString + source.slice(match.end);
+}

package/src/tools/local/index.ts

@@ -0,0 +1,12 @@
+export * from './CompileCheckTool';
+export * from './FileCheckpointer';
+export * from './LocalCodingTools';
+export * from './LocalExecutionEngine';
+export * from './LocalExecutionTools';
+export * from './LocalProgrammaticToolCalling';
+export * from './resolveLocalExecutionTools';
+export * from './attachments';
+export * from './bashAst';
+export * from './editStrategies';
+export * from './syntaxCheck';
+export * from './textEncoding';

package/src/tools/local/resolveLocalExecutionTools.ts

@@ -0,0 +1,208 @@
+import { Constants, CODE_EXECUTION_TOOLS } from '@/common';
+import {
+  createLocalBashExecutionTool,
+  createLocalCodeExecutionTool,
+} from './LocalExecutionTools';
+import {
+  createLocalCodingToolBundle,
+  createLocalCodingToolDefinitions,
+  createLocalCodingTools,
+} from './LocalCodingTools';
+import {
+  createLocalBashProgrammaticToolCallingTool,
+  createLocalProgrammaticToolCallingTool,
+} from './LocalProgrammaticToolCalling';
+import type * as t from '@/types';
+
+type ResolveLocalToolsResult = {
+  toolMap: t.ToolMap;
+  directToolNames: Set<string>;
+  /**
+   * Set when `local.fileCheckpointing === true` AND the auto-bind
+   * coding suite is in use. ToolNode stashes this on the node and
+   * exposes it via `getFileCheckpointer()` so the host can call
+   * `rewind()` after a failed batch. Manual review (finding E)
+   * flagged that the config flag was previously a no-op in the
+   * Run/ToolNode auto-bind path — only direct
+   * `createLocalCodingToolBundle()` callers could access the
+   * checkpointer.
+   */
+  fileCheckpointer?: t.LocalFileCheckpointer;
+};
+
+function shouldUseLocalExecution(config?: t.ToolExecutionConfig): boolean {
+  return config?.engine === 'local';
+}
+
+function shouldIncludeCodingTools(config?: t.ToolExecutionConfig): boolean {
+  return (
+    shouldUseLocalExecution(config) &&
+    config?.local?.includeCodingTools !== false
+  );
+}
+
+function createLocalExecutionTool(
+  name: string,
+  config: t.LocalExecutionConfig
+): t.GenericTool | undefined {
+  switch (name) {
+  case Constants.EXECUTE_CODE:
+    return createLocalCodeExecutionTool(config);
+  case Constants.BASH_TOOL:
+    return createLocalBashExecutionTool({ config });
+  case Constants.PROGRAMMATIC_TOOL_CALLING:
+    return createLocalProgrammaticToolCallingTool(config);
+  case Constants.BASH_PROGRAMMATIC_TOOL_CALLING:
+    return createLocalBashProgrammaticToolCallingTool(config);
+  default:
+    return undefined;
+  }
+}
+
+function mergeToolsByName(
+  baseTools: t.GraphTools | undefined,
+  localTools: t.GenericTool[]
+): t.GraphTools {
+  const orderedTools: t.GenericTool[] = [];
+  const indexByName = new Map<string, number>();
+
+  for (const tool of (baseTools as t.GenericTool[] | undefined) ?? []) {
+    if ('name' in tool && typeof tool.name === 'string') {
+      indexByName.set(tool.name, orderedTools.length);
+    }
+    orderedTools.push(tool);
+  }
+
+  for (const tool of localTools) {
+    const existingIndex = indexByName.get(tool.name);
+    if (existingIndex == null) {
+      indexByName.set(tool.name, orderedTools.length);
+      orderedTools.push(tool);
+      continue;
+    }
+    orderedTools[existingIndex] = tool;
+  }
+
+  return orderedTools;
+}
+
+export function resolveLocalToolsForBinding(args: {
+  tools?: t.GraphTools;
+  toolExecution?: t.ToolExecutionConfig;
+}): t.GraphTools | undefined {
+  if (!shouldUseLocalExecution(args.toolExecution)) {
+    return args.tools;
+  }
+
+  const localConfig = args.toolExecution?.local ?? {};
+  if (shouldIncludeCodingTools(args.toolExecution)) {
+    return mergeToolsByName(args.tools, createLocalCodingTools(localConfig));
+  }
+
+  const replacements = ((args.tools as t.GenericTool[] | undefined) ?? [])
+    .filter(
+      (existingTool): existingTool is t.GenericTool & { name: string } =>
+        'name' in existingTool &&
+        typeof existingTool.name === 'string' &&
+        CODE_EXECUTION_TOOLS.has(existingTool.name)
+    )
+    .map((existingTool) =>
+      createLocalExecutionTool(existingTool.name, localConfig)
+    )
+    .filter((localTool): localTool is t.GenericTool => localTool != null);
+
+  return replacements.length === 0
+    ? args.tools
+    : mergeToolsByName(args.tools, replacements);
+}
+
+export function resolveLocalToolRegistry(args: {
+  toolRegistry?: t.LCToolRegistry;
+  toolExecution?: t.ToolExecutionConfig;
+}): t.LCToolRegistry | undefined {
+  if (!shouldIncludeCodingTools(args.toolExecution)) {
+    return args.toolRegistry;
+  }
+
+  const registry = new Map(args.toolRegistry ?? []);
+  for (const definition of createLocalCodingToolDefinitions()) {
+    registry.set(definition.name, definition);
+  }
+  return registry;
+}
+
+export function resolveLocalExecutionTools(args: {
+  toolMap: t.ToolMap;
+  toolExecution?: t.ToolExecutionConfig;
+  /**
+   * Caller-provided checkpointer that overrides the bundle's
+   * auto-created one. The Graph layer threads a single per-Run
+   * instance so every ToolNode it compiles shares one snapshot
+   * store — without that, a multi-agent graph would each get a
+   * private checkpointer and `Run.rewindFiles()` couldn't reach
+   * any of them.
+   */
+  fileCheckpointer?: t.LocalFileCheckpointer;
+}): ResolveLocalToolsResult {
+  const directToolNames = new Set<string>();
+  if (!shouldUseLocalExecution(args.toolExecution)) {
+    return {
+      toolMap: args.toolMap,
+      directToolNames,
+    };
+  }
+
+  const localConfig = args.toolExecution?.local ?? {};
+  const toolMap = new Map(args.toolMap);
+  let fileCheckpointer: t.LocalFileCheckpointer | undefined;
+
+  if (shouldIncludeCodingTools(args.toolExecution)) {
+    // Use the bundle factory when fileCheckpointing is on so we can
+    // surface the checkpointer back to the caller — without this, the
+    // execution-path tools each captured into a checkpointer that was
+    // immediately discarded, making the public `fileCheckpointing`
+    // config flag a silent no-op outside of direct
+    // `createLocalCodingToolBundle()` use.
+    if (localConfig.fileCheckpointing === true || args.fileCheckpointer != null) {
+      const bundle = createLocalCodingToolBundle(localConfig, {
+        checkpointer: args.fileCheckpointer,
+      });
+      fileCheckpointer = bundle.checkpointer;
+      for (const localTool of bundle.tools) {
+        toolMap.set(localTool.name, localTool);
+        directToolNames.add(localTool.name);
+      }
+    } else {
+      for (const localTool of createLocalCodingTools(localConfig)) {
+        toolMap.set(localTool.name, localTool);
+        directToolNames.add(localTool.name);
+      }
+    }
+  }
+
+  // When the coding-tool bundle was already installed above, it
+  // already created `bash_tool` / `execute_code` / programmatic-tool
+  // variants. Skip re-creating them here — the audit-of-audit (manual
+  // finding #4) flagged that the original loop overwrote those bundle
+  // instances with fresh ones via `createLocalExecutionTool`, wasting
+  // work and (more importantly) replacing tools the bundle had
+  // already wired up with shared state. The CODE_EXECUTION_TOOLS
+  // loop is now only relevant when the host pre-bound a tool with
+  // one of these names (the `toolMap.has(name)` branch) and coding
+  // tools are off.
+  const includeCodingTools = shouldIncludeCodingTools(args.toolExecution);
+  for (const name of CODE_EXECUTION_TOOLS) {
+    if (includeCodingTools) continue;
+    if (!toolMap.has(name)) continue;
+
+    const localTool = createLocalExecutionTool(name, localConfig);
+    if (localTool == null) {
+      continue;
+    }
+
+    toolMap.set(name, localTool);
+    directToolNames.add(name);
+  }
+
+  return { toolMap, directToolNames, fileCheckpointer };
+}

package/src/tools/local/syntaxCheck.ts

@@ -0,0 +1,243 @@
+/**
+ * Per-file syntax check used by `edit_file` / `write_file` to surface
+ * obvious errors immediately after the write — strictly cheaper than
+ * full LSP integration and catches the bulk of "you broke the file"
+ * regressions a vision-less agent loop would otherwise miss until
+ * the next call.
+ *
+ * Each checker is a tiny shell-out (or in-process function) keyed on
+ * file extension. Failures are returned as a single short message;
+ * the wiring layer decides whether to append it to the tool result
+ * advisorily (`auto`) or to throw and force the model to react
+ * (`strict`).
+ *
+ * We deliberately do NOT cover TypeScript here because per-file `tsc`
+ * is slow and per-file syntax (without type info) misses most TS
+ * errors anyway. Use the project-level `compile_check` tool for that.
+ */
+
+import { extname } from 'path';
+import type * as t from '@/types';
+import {
+  getSpawn,
+  getWorkspaceFS,
+  spawnLocalProcess,
+} from './LocalExecutionEngine';
+
+export type SyntaxCheckOutcome =
+  | { ok: true }
+  | { ok: false; checker: string; output: string };
+
+export type SyntaxChecker = (
+  path: string,
+  config: t.LocalExecutionConfig
+) => Promise<SyntaxCheckOutcome>;
+
+/**
+ * Per-backend availability cache for the post-edit syntax-check probe
+ * tools (node, python3, bash). Keyed on the *effective spawn backend*
+ * — see `getSpawn(config)` in LocalExecutionEngine — so a Run that
+ * probes node over Node's child_process can't poison a subsequent Run
+ * whose `local.exec.spawn` routes elsewhere (a remote sandbox might
+ * have python but not node, etc.).
+ *
+ * Mirrors the same fix that landed for the ripgrep cache in
+ * `LocalCodingTools.ts` after the first round of Codex review.
+ * WeakMap keying lets disposed backends GC their entry; the test
+ * reset hook re-creates the map.
+ */
+type ProbeKind = 'hasNode' | 'hasPython' | 'hasBash';
+type ProbeCache = Partial<Record<ProbeKind, Promise<boolean>>>;
+
+// Per-backend × per-env cache. Codex P2 #40 — keying by spawn
+// backend alone misses env-driven availability changes (e.g. PATH
+// loses node between Runs that share the same backend). Same fix
+// shape as the ripgrep cache (Codex P1 #34).
+let probeCacheByBackend = new WeakMap<
+  t.LocalSpawn,
+  Map<string, ProbeCache>
+>();
+
+function envCacheKey(env: NodeJS.ProcessEnv | undefined): string {
+  if (env == null) return '';
+  const sorted: Record<string, string | undefined> = {};
+  for (const k of Object.keys(env).sort()) {
+    sorted[k] = env[k];
+  }
+  return JSON.stringify(sorted);
+}
+
+function cacheFor(
+  config: t.LocalExecutionConfig
+): ProbeCache {
+  const backend = getSpawn(config);
+  let envMap = probeCacheByBackend.get(backend);
+  if (envMap == null) {
+    envMap = new Map();
+    probeCacheByBackend.set(backend, envMap);
+  }
+  const envKey = envCacheKey(config.env);
+  let entry = envMap.get(envKey);
+  if (entry == null) {
+    entry = {};
+    envMap.set(envKey, entry);
+  }
+  return entry;
+}
+
+async function probe(
+  command: string,
+  args: string[],
+  cached: ProbeKind,
+  config: t.LocalExecutionConfig
+): Promise<boolean> {
+  const entry = cacheFor(config);
+  let probePromise = entry[cached];
+  if (probePromise == null) {
+    probePromise = spawnLocalProcess(
+      command,
+      args,
+      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+      { internal: true }
+    )
+      .then((result) => result != null && result.exitCode === 0)
+      .catch(() => false);
+    entry[cached] = probePromise;
+  }
+  return probePromise;
+}
+
+/**
+ * Test-only reset hook. Clears the per-backend probe cache so tests
+ * can swap in mocked spawn backends and reprobe deterministically.
+ *
+ * @internal Not part of the public SDK surface.
+ */
+export function _resetSyntaxCheckProbeCacheForTests(): void {
+  probeCacheByBackend = new WeakMap();
+}
+
+const jsCheck: SyntaxChecker = async (path, config) => {
+  if (!(await probe('node', ['--version'], 'hasNode', config))) {
+    return { ok: true };
+  }
+  const result = await spawnLocalProcess(
+    'node',
+    ['--check', path],
+    { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+    { internal: true }
+  );
+  if (result.exitCode === 0) return { ok: true };
+  return {
+    ok: false,
+    checker: 'node --check',
+    output: result.stderr.trim() || result.stdout.trim() || 'syntax error',
+  };
+};
+
+const pythonCheck: SyntaxChecker = async (path, config) => {
+  if (!(await probe('python3', ['--version'], 'hasPython', config))) {
+    return { ok: true };
+  }
+  const program =
+    'import py_compile, sys\n' +
+    'try:\n' +
+    '  py_compile.compile(sys.argv[1], doraise=True)\n' +
+    'except py_compile.PyCompileError as e:\n' +
+    '  print(e.msg.strip(), file=sys.stderr)\n' +
+    '  sys.exit(1)\n';
+  const result = await spawnLocalProcess(
+    'python3',
+    ['-c', program, path],
+    { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+    { internal: true }
+  );
+  if (result.exitCode === 0) return { ok: true };
+  return {
+    ok: false,
+    checker: 'py_compile',
+    output: result.stderr.trim() || result.stdout.trim() || 'syntax error',
+  };
+};
+
+const jsonCheck: SyntaxChecker = async (path, config) => {
+  // Route through the configured WorkspaceFS so a Run with a custom
+  // `local.exec.fs` (in-memory or remote engine) validates the same
+  // file the write_file/edit_file path actually wrote — pre-fix this
+  // read went to the host fs and either silently passed (no host
+  // file → catch returns undefined → ok: true) or read a different
+  // file with the same absolute path. Codex P1 #24.
+  const fs = getWorkspaceFS(config);
+  const raw = await fs.readFile(path, 'utf8').catch(() => undefined);
+  if (raw == null) return { ok: true };
+  try {
+    JSON.parse(raw);
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      checker: 'JSON.parse',
+      output: (err as Error).message,
+    };
+  }
+};
+
+const bashCheck: SyntaxChecker = async (path, config) => {
+  if (!(await probe('bash', ['--version'], 'hasBash', config))) {
+    return { ok: true };
+  }
+  const result = await spawnLocalProcess(
+    'bash',
+    ['-n', path],
+    { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+    { internal: true }
+  );
+  if (result.exitCode === 0) return { ok: true };
+  return {
+    ok: false,
+    checker: 'bash -n',
+    output: result.stderr.trim() || result.stdout.trim() || 'syntax error',
+  };
+};
+
+const CHECKERS_BY_EXT: Record<string, SyntaxChecker> = {
+  '.js': jsCheck,
+  '.mjs': jsCheck,
+  '.cjs': jsCheck,
+  '.jsx': jsCheck,
+  '.py': pythonCheck,
+  '.pyw': pythonCheck,
+  '.json': jsonCheck,
+  '.sh': bashCheck,
+  '.bash': bashCheck,
+};
+
+/**
+ * Run the post-edit syntax check for `absolutePath`. Returns
+ * `null` when no checker matches the extension (most files), or a
+ * `SyntaxCheckOutcome`.
+ *
+ * Truncates `output` to `maxOutputChars` (default 4096) so a
+ * 10MB-of-errors transpiler dump can't blow the model context.
+ */
+export async function runPostEditSyntaxCheck(
+  absolutePath: string,
+  config: t.LocalExecutionConfig
+): Promise<SyntaxCheckOutcome | null> {
+  const ext = extname(absolutePath).toLowerCase();
+  const checker = (CHECKERS_BY_EXT as Record<string, SyntaxChecker | undefined>)[ext];
+  if (checker == null) return null;
+  try {
+    const result = await checker(absolutePath, config);
+    if (!result.ok) {
+      return {
+        ok: false,
+        checker: result.checker,
+        output: result.output.slice(0, 4096),
+      };
+    }
+    return result;
+  } catch {
+    return null;
+  }
+}

package/src/tools/local/textEncoding.ts

@@ -0,0 +1,37 @@
+/**
+ * BOM and line-ending preservation helpers for the local engine's
+ * file-mutating tools. We never *introduce* a BOM or change line
+ * endings — only preserve what was already on disk so a Windows-
+ * checked-in source file stays CRLF and a UTF-8-with-BOM JSON file
+ * keeps its BOM after an edit.
+ *
+ * Inspired by opencode's `Bom` helper. Trimmed to the cases that
+ * actually matter for editing source code (UTF-8 BOM only;
+ * UTF-16/UTF-32 are out of scope).
+ */
+
+const UTF8_BOM = '';
+
+export interface EncodedFile {
+  /** File contents with BOM stripped. */
+  text: string;
+  /** Whether the on-disk file started with a UTF-8 BOM. */
+  hasBom: boolean;
+  /** Detected newline style. CRLF wins if any CRLF is present. */
+  newline: '\n' | '\r\n';
+}
+
+export function decodeFile(raw: string): EncodedFile {
+  const hasBom = raw.startsWith(UTF8_BOM);
+  const stripped = hasBom ? raw.slice(1) : raw;
+  const newline = stripped.includes('\r\n') ? '\r\n' : '\n';
+  // Internally we always work in LF; encode() restores CRLF on write.
+  const lf = newline === '\r\n' ? stripped.replace(/\r\n/g, '\n') : stripped;
+  return { text: lf, hasBom, newline };
+}
+
+export function encodeFile(text: string, encoding: EncodedFile): string {
+  const out =
+    encoding.newline === '\r\n' ? text.replace(/\n/g, '\r\n') : text;
+  return encoding.hasBom ? `${UTF8_BOM}${out}` : out;
+}