Write reference

type MutationResult = MutationReport & { readonly content: readonly ContentPart[] };

type MutationReport = MutationOk | MutationNoChange | MutationFailure;

// Every variant has these fields.
interface MutationFields {
  tool: "edit" | "write" | "apply_patch";
  changes: readonly FileChange[];
  unchanged: readonly string[];
  notes: readonly Note[];
}

interface MutationOk extends MutationFields {
  status: "ok";
  commit: null;
}

interface MutationNoChange extends MutationFields {
  status: "no-change";
  commit: null;
}

interface MutationFailure extends MutationFields {
  status: "error";
  error: WriteError; // { code, phase, message, data? }
  commit: CommitReport | null;
}

import { memoryFileSystem } from "@better-fs-tools/fs";
import { createEditTool, textOf } from "@better-fs-tools/write";

const edit = createEditTool({
  fs: memoryFileSystem({ files: { "/app.ts": "const a = 1;\nconst b = 2;\n" } }),
});

const result = await edit({
  path: "/app.ts",
  edits: [{ oldText: "const b = 2;", newText: "const b = 3;" }],
});

if (result.status === "error") {
  console.log(result.error.code, result.error.phase, result.error.data);
} else {
  for (const change of result.changes) {
    console.log(change.kind, change.path, change.linesAdded, change.linesRemoved); // update /app.ts 1 1
    console.log(change.matches[0]?.matcher, change.matches[0]?.lines); // exact [2, 2]
  }
}
console.log(textOf(result)); // "Edited /app.ts: 1 replacement at line 2."

const miss = await edit({ path: "/app.ts", edits: [{ oldText: "const c", newText: "x" }] });
if (miss.status === "error") {
  console.log(miss.error.code, miss.error.phase, miss.error.data); // NO_MATCH plan { index: 0 }
}

interface FileChange {
  kind: "create" | "update" | "delete" | "move";
  path: string; // display path. For a move, the destination
  requestedPath: string;
  resolvedPath: string;
  movedFrom: string | null; // display path of a move source
  before: FileVersion | null; // null for a create
  after: FileVersion | null; // null for a delete
  linesAdded: number;
  linesRemoved: number;
  diff: string; // unified diff with a/ and b/ headers
  diffTruncated: boolean; // cut at limits.maxDiffLines
  matches: readonly MatchInfo[]; // edit pairs and patch hunks
  snippets: readonly Snippet[]; // new lines around each change
  userModified: boolean; // an authorizer replaced the content
  createdDirectories: readonly string[]; // resolved paths, outermost first
}

interface FileVersion {
  contentId: string | null; // null with digest: null
  version: string | null; // the backend version. null when the backend gave none
  bytes: number;
}

interface MatchInfo {
  index: number; // zero-based pair or hunk
  matcher: string; // for example "exact" or "normalized"
  fuzzy: boolean;
  lines: readonly [number, number]; // one-based, in the file before the change
  count: number; // more than 1 only with replaceAll
  replaced: readonly (readonly [number, number])[]; // each replacement, in the file after
}

interface Snippet {
  startLine: number; // one-based, in the file after the change
  lines: readonly string[];
}

interface CommitReport {
  rolledBack: boolean; // true when every published step was undone
  files: readonly {
    path: string;
    state: "unchanged" | "committed" | "restored" | "rollback-failed";
    code?: WriteErrorCode;
  }[];
}

interface Note {
  code: string;
  severity: "info" | "warning";
  message: string;
  data?: JsonObject;
}

interface PatchParser {
  readonly id: string;
  parse(text: string): PatchParseOutcome; // synchronous. Must not throw
}

type PatchParseOutcome =
  { ok: true; plan: PatchPlan } | { ok: false; error: { line: number; detail: string } };

interface PatchPlan {
  operations: readonly PatchOperation[];
}

type PatchOperation =
  | { kind: "add"; path: string; content: string; line: number }
  | { kind: "delete"; path: string; line: number }
  | {
      kind: "update";
      path: string;
      moveTo: string | null;
      hunks: readonly PatchHunk[];
      line: number;
    };

interface PatchHunk {
  context: string | null; // the text after "@@ ". null for a bare "@@", or a first hunk with no "@@"
  lines: readonly PatchLine[]; // old lines are " " and "-". New lines are " " and "+"
  endOfFile: boolean; // "*** End of File" closed the hunk
  line: number; // one-based line of the hunk in the patch text
}

interface PatchLine {
  kind: " " | "-" | "+";
  text: string; // the line with no prefix and no line break
}

import { parsePatch } from "@better-fs-tools/write/patch";

const outcome = parsePatch(
  [
    "*** Begin Patch",
    "*** Update File: src/a.ts",
    "@@ function greet",
    "-  return 1;",
    "+  return 2;",
    "*** Delete File: old.txt",
    "*** End Patch",
  ].join("\n"),
);

if (outcome.ok) {
  for (const operation of outcome.plan.operations) {
    console.log(operation.kind, operation.path, operation.line);
  }
  // update src/a.ts 2
  // delete old.txt 6
} else {
  console.log(outcome.error.line, outcome.error.detail);
}

interface WriteRecord extends ReadRecord {
  origin: "write";
  totalsExact: true;
  request: null; // a write record has no read range
}

import {
  defaultPreconditions,
  parseApplyPatchInput,
  parseEditInput,
  parseWriteInput,
  resolveWriteLimits,
  resolveWriteMessages,
} from "@better-fs-tools/write";

const limits = resolveWriteLimits({ maxEdits: 2 });

console.log(parseEditInput({ path: "a.ts", edits: [{ oldText: "a", newText: "b" }] }, limits));
// { tool: "edit", path: "a.ts", edits: [{ oldText: "a", newText: "b", replaceAll: false }] }

try {
  parseEditInput({ path: "a.ts", edits: [] }, limits);
} catch (error) {
  console.log((error as TypeError).message); // "edits must be a non-empty array"
}

console.log(parseWriteInput({ path: "a.ts", content: "x\n" }, limits));
// { tool: "write", path: "a.ts", content: "x\n" }

try {
  parseApplyPatchInput({ patch: " " }, limits);
} catch (error) {
  console.log((error as TypeError).message); // "patch must be a non-empty string"
}

const messages = resolveWriteMessages({
  param: (name) => (name === "oldText" ? "old_string" : name),
});
console.log(messages.param("oldText")); // "old_string"

console.log(defaultPreconditions);
// { requireRead: "existing", partialRead: "edit-only", onStale: "reject" }