@agjs/tsforge 0.1.0

package/src/files/edit.ts

@@ -0,0 +1,193 @@
+import { join } from "node:path";
+import { EDIT_FAIL_REASON } from "./files.constants";
+import type {
+  IEdit,
+  EditResult,
+  IReplacement,
+  EditsResult,
+} from "./files.types";
+
+/**
+ * Apply a str_replace edit. The match must be **exact and unique** — 0 matches
+ * is `not-found`, >1 is `ambiguous` (the model must add surrounding context).
+ * Uniqueness is what makes blind edits safe for a strong, full-file-context model.
+ */
+export async function applyEdit(cwd: string, edit: IEdit): Promise<EditResult> {
+  const path = join(cwd, edit.file);
+  const f = Bun.file(path);
+
+  if (!(await f.exists())) {
+    return { ok: false, file: edit.file, reason: EDIT_FAIL_REASON.missingFile };
+  }
+
+  if (edit.oldString === "") {
+    return { ok: false, file: edit.file, reason: EDIT_FAIL_REASON.notFound };
+  }
+
+  const content = await f.text();
+  const matches = content.split(edit.oldString).length - 1;
+
+  if (matches === 0) {
+    return { ok: false, file: edit.file, reason: EDIT_FAIL_REASON.notFound };
+  }
+
+  if (matches > 1) {
+    return {
+      ok: false,
+      file: edit.file,
+      reason: EDIT_FAIL_REASON.ambiguous,
+      matches,
+    };
+  }
+
+  // Unique match: split/join avoids `$`-pattern interpretation in newString.
+  await Bun.write(path, content.split(edit.oldString).join(edit.newString));
+
+  return { ok: true, file: edit.file };
+}
+
+/**
+ * Apply a SEQUENCE of str_replace edits to one file, ATOMICALLY: each match must
+ * be exact and unique in the content as it stands after the prior replacements;
+ * if any one fails, NOTHING is written and the failing replacement's index +
+ * reason is returned. This lets the model fix the same issue at several spread-
+ * out sites in a single turn (each piece still surgical) instead of a whole-file
+ * rewrite — while the all-or-nothing write keeps a half-applied batch off disk.
+ */
+export async function applyEdits(
+  cwd: string,
+  file: string,
+  edits: readonly IReplacement[]
+): Promise<EditsResult> {
+  const path = join(cwd, file);
+  const f = Bun.file(path);
+
+  if (!(await f.exists())) {
+    return { ok: false, file, index: 0, reason: EDIT_FAIL_REASON.missingFile };
+  }
+
+  if (edits.length === 0) {
+    return { ok: false, file, index: 0, reason: EDIT_FAIL_REASON.notFound };
+  }
+
+  let content = await f.text();
+
+  for (let i = 0; i < edits.length; i += 1) {
+    const replacement = edits[i];
+
+    if (replacement === undefined || replacement.oldString === "") {
+      return { ok: false, file, index: i, reason: EDIT_FAIL_REASON.notFound };
+    }
+
+    const matches = content.split(replacement.oldString).length - 1;
+
+    if (matches === 0) {
+      // Exact match failed — try an indentation-tolerant LINE match (the common
+      // LLM miss: right code, slightly-off leading whitespace). Applies ONLY on a
+      // unique window; never guesses. The gate re-validates as a backstop.
+      const fuzzy = fuzzyLineReplace(
+        content,
+        replacement.oldString,
+        replacement.newString
+      );
+
+      if (fuzzy.matches === 1) {
+        content = fuzzy.text;
+        continue;
+      }
+
+      if (fuzzy.matches > 1) {
+        return {
+          ok: false,
+          file,
+          index: i,
+          reason: EDIT_FAIL_REASON.ambiguous,
+          matches: fuzzy.matches,
+        };
+      }
+
+      return { ok: false, file, index: i, reason: EDIT_FAIL_REASON.notFound };
+    }
+
+    if (matches > 1) {
+      return {
+        ok: false,
+        file,
+        index: i,
+        reason: EDIT_FAIL_REASON.ambiguous,
+        matches,
+      };
+    }
+
+    content = content.split(replacement.oldString).join(replacement.newString);
+  }
+
+  await Bun.write(path, content);
+
+  return { ok: true, file, count: edits.length };
+}
+
+/**
+ * Indentation-tolerant line match: compare `oldString` to `content` line-by-line
+ * ignoring each line's leading/trailing whitespace. Returns the new content with
+ * the matched window replaced by `newString` — but ONLY when exactly one window
+ * matches (`matches === 1`); 0 or >1 leaves content untouched so the caller can
+ * report not-found/ambiguous rather than guess. Line-granular (not char-offset),
+ * which keeps it simple and safe.
+ */
+function fuzzyLineReplace(
+  content: string,
+  oldString: string,
+  newString: string
+): { text: string; matches: number } {
+  const norm = (s: string): string => s.trim();
+  const contentLines = content.split("\n");
+  const oldLines = oldString.split("\n");
+
+  // Drop blank leading/trailing lines (the model often adds a stray newline).
+  while (oldLines.length > 0 && norm(oldLines[0] ?? "") === "") {
+    oldLines.shift();
+  }
+
+  while (
+    oldLines.length > 0 &&
+    norm(oldLines[oldLines.length - 1] ?? "") === ""
+  ) {
+    oldLines.pop();
+  }
+
+  if (oldLines.length === 0) {
+    return { text: content, matches: 0 };
+  }
+
+  const needle = oldLines.map(norm);
+  const starts: number[] = [];
+
+  for (let i = 0; i + needle.length <= contentLines.length; i += 1) {
+    let hit = true;
+
+    for (let j = 0; j < needle.length; j += 1) {
+      if (norm(contentLines[i + j] ?? "") !== needle[j]) {
+        hit = false;
+        break;
+      }
+    }
+
+    if (hit) {
+      starts.push(i);
+    }
+  }
+
+  if (starts.length !== 1) {
+    return { text: content, matches: starts.length };
+  }
+
+  const start = starts[0] ?? 0;
+  const rebuilt = [
+    ...contentLines.slice(0, start),
+    ...newString.split("\n"),
+    ...contentLines.slice(start + needle.length),
+  ];
+
+  return { text: rebuilt.join("\n"), matches: 1 };
+}

package/src/files/files.constants.ts

@@ -0,0 +1,11 @@
+/** Why an edit failed to apply (compare against these, never the bare string). */
+export const EDIT_FAIL_REASON = {
+  missingFile: "missing-file",
+  notFound: "not-found",
+  ambiguous: "ambiguous",
+} as const;
+
+/** Why a create failed (compare against this, never the bare string). */
+export const CREATE_FAIL_REASON = {
+  exists: "exists",
+} as const;

package/src/files/files.types.ts

@@ -0,0 +1,81 @@
+import {
+  type EDIT_FAIL_REASON,
+  type CREATE_FAIL_REASON,
+} from "./files.constants";
+
+/** A single targeted edit: replace an exact, unique snippet. */
+export interface IEdit {
+  file: string;
+  oldString: string;
+  newString: string;
+}
+
+export type EditFailReason =
+  (typeof EDIT_FAIL_REASON)[keyof typeof EDIT_FAIL_REASON];
+
+export type EditResult =
+  | { ok: true; file: string }
+  | {
+      ok: false;
+      file: string;
+      reason: EditFailReason;
+      /** Number of matches when ambiguous. */
+      matches?: number;
+    };
+
+/** One replacement within a batched, multi-site edit to a single file. */
+export interface IReplacement {
+  oldString: string;
+  newString: string;
+}
+
+export type EditsResult =
+  | { ok: true; file: string; count: number }
+  | {
+      ok: false;
+      file: string;
+      /** Which replacement in the batch failed (0-based). */
+      index: number;
+      reason: EditFailReason;
+      matches?: number;
+    };
+
+/** Create a brand-new file. */
+export interface ICreateFile {
+  file: string;
+  content: string;
+}
+
+export type CreateFailReason =
+  (typeof CREATE_FAIL_REASON)[keyof typeof CREATE_FAIL_REASON];
+
+export type CreateResult =
+  | { ok: true; file: string }
+  | { ok: false; file: string; reason: CreateFailReason };
+
+/** Hashline edit request: anchored by content hash for stale-anchor recovery. */
+export interface IHashlineEdit {
+  file: string;
+  /** Content hash from the read annotation (¶path#HASH). */
+  hash?: string;
+  /** Raw edit payload: header + ops. */
+  input: string;
+}
+
+export type HashlineFailReason =
+  | "missing-file"
+  | "no-anchor"
+  | "stale-anchor"
+  | "stale-anchor-conflict"
+  | "parse-error"
+  | "out-of-bounds"
+  | "invalid-op";
+
+export type HashlineResult =
+  | { ok: true; file: string; newHash: string }
+  | {
+      ok: false;
+      file: string;
+      reason: HashlineFailReason;
+      suggestions?: string[];
+    };

package/src/files/hashline-format.ts

@@ -0,0 +1,110 @@
+/**
+ * Hashline format constants and pure functions. Single source of truth for
+ * read/edit annotation format, hash computation, and display helpers.
+ * Adapts oh-my-pi's hashline primitives for tsforge (no block-edits,
+ * lenient parse, 3-way merge recovery).
+ */
+
+/** File-section header prefix. */
+export const HL_HEADER_SIGIL = "¶";
+
+/** Hash separator in header: `¶path#HASH`. */
+export const HL_HASH_SEP = "#";
+
+/** Line-number / content separator: `N:text`. */
+export const HL_LINE_SEP = ":";
+
+/** Replacement/deletion/insert operation keywords. */
+export const HL_OP_REPLACE = "replace";
+export const HL_OP_DELETE = "delete";
+export const HL_OP_INSERT = "insert";
+
+/** Position keywords for insert. */
+export const HL_POS_BEFORE = "before";
+export const HL_POS_AFTER = "after";
+
+/** Payload line prefix. */
+export const HL_PAYLOAD_PREFIX = "+";
+
+/** Range separator: N..M. */
+export const HL_RANGE_SEP = "..";
+
+/** Length of the hex hash (4 hex chars = 16 bits). */
+export const HL_HASH_LENGTH = 4;
+
+/**
+ * Normalize text for hashing: strip trailing [ \t\r] from every line
+ * (before \n or EOF) so CRLF and display-trimmed content hash identically.
+ */
+function normalizeForHash(text: string): string {
+  return text.replace(/[ \t\r]+(?=\n|$)/g, "");
+}
+
+/**
+ * Compute the content-derived hash tag for a file's normalized text.
+ * 4-hex-uppercase fingerprint using xxHash32 (fast, collision-free for
+ * practical file sizes). Same tag mints on every read of byte-identical content.
+ */
+export function computeFileHash(text: string): string {
+  const normalized = normalizeForHash(text);
+  const hash32 = Bun.hash.xxHash32(normalized, 0);
+  const low16 = hash32 & 0xffff;
+
+  return low16.toString(16).padStart(HL_HASH_LENGTH, "0").toUpperCase();
+}
+
+/**
+ * Format a read-annotation header: `¶path#HASH`.
+ */
+export function formatHashHeader(filePath: string, hash: string): string {
+  return `${HL_HEADER_SIGIL}${filePath}${HL_HASH_SEP}${hash}`;
+}
+
+/**
+ * Format a numbered line: `N:text`.
+ */
+export function formatNumberedLine(lineNum: number, text: string): string {
+  return `${lineNum}${HL_LINE_SEP}${text}`;
+}
+
+/**
+ * Parse a read-annotation header. Extracts path and hash from `¶path#HASH`.
+ * Returns null if the line is not a valid header.
+ */
+export function parseHashHeader(
+  line: string
+): { path: string; hash: string } | null {
+  if (!line.startsWith(HL_HEADER_SIGIL)) {
+    return null;
+  }
+
+  const body = line.slice(HL_HEADER_SIGIL.length);
+  const sepIdx = body.lastIndexOf(HL_HASH_SEP);
+
+  if (sepIdx === -1) {
+    return null;
+  }
+
+  const path = body.slice(0, sepIdx);
+  const hash = body.slice(sepIdx + 1);
+
+  if (path.length === 0 || !isValidHash(hash)) {
+    return null;
+  }
+
+  return { path, hash };
+}
+
+/**
+ * Check if a string is a valid 4-hex hash.
+ */
+export function isValidHash(hash: string): boolean {
+  return /^[0-9A-F]{4}$/i.test(hash);
+}
+
+/**
+ * Normalize a hash to uppercase for comparison.
+ */
+export function normalizeHash(hash: string): string {
+  return hash.toUpperCase();
+}