@svilupp/hash-edit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+type NewlineStyle = "lf" | "crlf" | "cr" | "none";
+type ReplaceOp = {
+    op: "replace";
+    line: number;
+    hash: string;
+    lines: string[];
+    end_line?: number;
+    end_hash?: string;
+};
+type InsertBeforeOp = {
+    op: "insert_before";
+    line: number;
+    hash: string;
+    lines: string[];
+};
+type InsertAfterOp = {
+    op: "insert_after";
+    line: number;
+    hash: string;
+    lines: string[];
+};
+type DeleteOp = {
+    op: "delete";
+    line: number;
+    hash: string;
+    end_line?: number;
+    end_hash?: string;
+};
+type EditOp = ReplaceOp | InsertBeforeOp | InsertAfterOp | DeleteOp;
+type ReadResult = {
+    path: string;
+    version: string;
+    encoding: string;
+    bom: boolean;
+    newline: NewlineStyle;
+    has_final_newline: boolean;
+    hash_length: number;
+    total_lines: number;
+    start_line: number;
+    end_line: number;
+    lines: string[];
+};
+type EditResult = {
+    path: string;
+    version_before: string;
+    version_after: string;
+    applied: number;
+    first_changed_line: number | null;
+    encoding: string;
+    bom: boolean;
+    newline: NewlineStyle;
+    has_final_newline: boolean;
+    total_lines: number;
+};
+type WriteResult = {
+    path: string;
+    version_after: string;
+    created: boolean;
+    encoding: string;
+    bom: boolean;
+    newline: NewlineStyle;
+    has_final_newline: boolean;
+    total_lines: number;
+};
+declare class HashEditError extends Error {
+}
+declare class PathEscapeError extends HashEditError {
+}
+declare class MixedNewlineError extends HashEditError {
+}
+declare class FileEncodingError extends HashEditError {
+}
+declare class InvalidOperationError extends HashEditError {
+}
+declare class VersionConflictError extends HashEditError {
+    path: string;
+    expected: string | null;
+    actual: string;
+    constructor(path: string, expected: string | null, actual: string);
+}
+declare class AnchorMismatchError extends HashEditError {
+    mismatches: Array<{
+        line: number;
+        expected: string;
+        actual: string;
+    }>;
+    constructor(message: string, mismatches: Array<{
+        line: number;
+        expected: string;
+        actual: string;
+    }>);
+}
+declare function computeLineHash(lineNumber: number, text: string, hashLength?: number): string;
+declare function renderLine(lineNumber: number, text: string, hashLength?: number): string;
+declare function renderLines(lines: string[], startLine?: number, hashLength?: number): string[];
+declare function stripRenderPrefixes(lines: string[]): string[];
+declare class HashEditHarness {
+    #private;
+    constructor(root?: string, options?: {
+        default_encoding?: string;
+        hash_length?: number;
+    });
+    resolvePath(path: string): string;
+    read(path: string, options?: {
+        start_line?: number;
+        end_line?: number;
+    }): Promise<ReadResult>;
+    edit(path: string, ops: EditOp | EditOp[], options: {
+        expected_version: string;
+    }): Promise<EditResult>;
+    write(path: string, text: string, options?: {
+        expected_version?: string;
+    }): Promise<WriteResult>;
+    private readSnapshot;
+    private writeSnapshot;
+}
+
+export { AnchorMismatchError, type DeleteOp, type EditOp, type EditResult, FileEncodingError, HashEditError, HashEditHarness, type InsertAfterOp, type InsertBeforeOp, InvalidOperationError, MixedNewlineError, type NewlineStyle, PathEscapeError, type ReadResult, type ReplaceOp, VersionConflictError, type WriteResult, computeLineHash, renderLine, renderLines, stripRenderPrefixes };

package/dist/index.js

@@ -0,0 +1,407 @@
+// src/index.ts
+import { createHash, randomUUID } from "crypto";
+import { realpathSync } from "fs";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { basename, dirname, isAbsolute, join as joinPath, relative, resolve } from "path";
+var DEFAULT_ENCODING = "utf-8";
+var DEFAULT_HASH_LENGTH = 2;
+var UTF8_BOM = Buffer.from([239, 187, 191]);
+var PREFIX_RE = /^\s*\d+:[0-9a-f]{2,}\|/;
+var HashEditError = class extends Error {
+};
+var PathEscapeError = class extends HashEditError {
+};
+var MixedNewlineError = class extends HashEditError {
+};
+var FileEncodingError = class extends HashEditError {
+};
+var InvalidOperationError = class extends HashEditError {
+};
+var VersionConflictError = class extends HashEditError {
+  path;
+  expected;
+  actual;
+  constructor(path, expected, actual) {
+    const message = expected === null ? `${path} already exists. read() first and pass expected_version to overwrite safely.` : `Version conflict for ${path}: expected ${expected}, actual ${actual}. Re-read the file first.`;
+    super(message);
+    this.path = path;
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
+var AnchorMismatchError = class extends HashEditError {
+  mismatches;
+  constructor(message, mismatches) {
+    super(message);
+    this.mismatches = mismatches;
+  }
+};
+function newlineSeparator(style) {
+  if (style === "lf") return "\n";
+  if (style === "crlf") return "\r\n";
+  if (style === "cr") return "\r";
+  return "\n";
+}
+function detectNewlineStyle(text) {
+  const matches = text.match(/\r\n|\n|\r/g) ?? [];
+  const unique = new Set(matches);
+  if (unique.size > 1) {
+    throw new MixedNewlineError(`Mixed newline styles detected: ${Array.from(unique).join(", ")}`);
+  }
+  if (matches.length === 0) {
+    return { newline: "none", has_final_newline: false, lines: text === "" ? [] : [text] };
+  }
+  const separator = matches[0] ?? "\n";
+  const newline = separator === "\n" ? "lf" : separator === "\r\n" ? "crlf" : "cr";
+  const has_final_newline = text.endsWith(separator);
+  const split = text.split(separator);
+  const lines = has_final_newline ? split.slice(0, -1) : split;
+  return { newline, has_final_newline, lines };
+}
+function joinText(lines, newline, hasFinalNewline) {
+  if (lines.length === 0) return "";
+  const separator = newlineSeparator(newline);
+  let text = lines.join(separator);
+  if (hasFinalNewline) text += separator;
+  return text;
+}
+function versionForBytes(data) {
+  return createHash("blake2s256").update(data).digest("hex").slice(0, 32);
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function computeLineHash(lineNumber, text, hashLength = DEFAULT_HASH_LENGTH) {
+  if (hashLength < 2) throw new Error("hashLength must be >= 2");
+  const normalized = text.replace(/\r/g, "").replace(/[ \t]+$/u, "");
+  const material = /[\p{L}\p{N}]/u.test(normalized) ? normalized : `${lineNumber}\0${normalized}`;
+  return createHash("blake2s256").update(material, DEFAULT_ENCODING).digest("hex").slice(0, hashLength);
+}
+function renderLine(lineNumber, text, hashLength = DEFAULT_HASH_LENGTH) {
+  return `${lineNumber}:${computeLineHash(lineNumber, text, hashLength)}|${text}`;
+}
+function renderLines(lines, startLine = 1, hashLength = DEFAULT_HASH_LENGTH) {
+  return lines.map((line, index) => renderLine(startLine + index, line, hashLength));
+}
+function stripRenderPrefixes(lines) {
+  const nonEmpty = lines.filter((line) => line !== "");
+  if (nonEmpty.length > 0 && nonEmpty.every((line) => PREFIX_RE.test(line))) {
+    return lines.map((line) => line.replace(PREFIX_RE, ""));
+  }
+  return [...lines];
+}
+function mismatchMessage(path, lines, hashLength, mismatches) {
+  const displayLines = /* @__PURE__ */ new Set();
+  for (const mismatch of mismatches) {
+    for (let line = Math.max(1, mismatch.line - 2); line <= Math.min(lines.length, mismatch.line + 2); line += 1) {
+      displayLines.add(line);
+    }
+  }
+  const rendered = [
+    `Anchors are stale in ${path}. Re-read the file and use the updated rendered lines below.`
+  ];
+  if (displayLines.size === 0) return rendered.join("\n");
+  rendered.push("");
+  const mismatchSet = new Set(mismatches.map((mismatch) => mismatch.line));
+  let previous = -1;
+  for (const lineNumber of [...displayLines].sort((left, right) => left - right)) {
+    if (previous !== -1 && lineNumber > previous + 1) {
+      rendered.push("    ...");
+    }
+    const prefix = mismatchSet.has(lineNumber) ? ">>> " : "    ";
+    rendered.push(prefix + renderLine(lineNumber, lines[lineNumber - 1] ?? "", hashLength));
+    previous = lineNumber;
+  }
+  return rendered.join("\n");
+}
+var HashEditHarness = class {
+  #root;
+  #resolvedRoot;
+  #encoding;
+  #hashLength;
+  constructor(root = ".", options = {}) {
+    this.#root = resolve(root);
+    this.#resolvedRoot = resolveExistingPath(this.#root);
+    this.#encoding = options.default_encoding ?? DEFAULT_ENCODING;
+    this.#hashLength = options.hash_length ?? DEFAULT_HASH_LENGTH;
+  }
+  resolvePath(path) {
+    const absolute = resolve(this.#root, path);
+    const resolved = resolveExistingPath(absolute);
+    const rel = relative(this.#resolvedRoot, resolved);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw new PathEscapeError(`${path} escapes root ${this.#root}`);
+    }
+    return resolved;
+  }
+  async read(path, options = {}) {
+    const resolved = this.resolvePath(path);
+    const snapshot = await this.readSnapshot(resolved);
+    if (snapshot.lines.length === 0) {
+      return {
+        path: snapshot.path,
+        version: snapshot.version,
+        encoding: snapshot.encoding,
+        bom: snapshot.bom,
+        newline: snapshot.newline,
+        has_final_newline: snapshot.has_final_newline,
+        hash_length: this.#hashLength,
+        total_lines: 0,
+        start_line: 0,
+        end_line: 0,
+        lines: []
+      };
+    }
+    const startLine = options.start_line ?? 1;
+    const endLine = options.end_line ?? snapshot.lines.length;
+    if (startLine < 1 || endLine < startLine || endLine > snapshot.lines.length) {
+      throw new InvalidOperationError(
+        `Invalid read window for ${snapshot.path}: start_line=${startLine}, end_line=${endLine}, total_lines=${snapshot.lines.length}`
+      );
+    }
+    return {
+      path: snapshot.path,
+      version: snapshot.version,
+      encoding: snapshot.encoding,
+      bom: snapshot.bom,
+      newline: snapshot.newline,
+      has_final_newline: snapshot.has_final_newline,
+      hash_length: this.#hashLength,
+      total_lines: snapshot.lines.length,
+      start_line: startLine,
+      end_line: endLine,
+      lines: renderLines(snapshot.lines.slice(startLine - 1, endLine), startLine, this.#hashLength)
+    };
+  }
+  async edit(path, ops, options) {
+    const resolved = this.resolvePath(path);
+    const snapshot = await this.readSnapshot(resolved);
+    if (options.expected_version !== snapshot.version) {
+      throw new VersionConflictError(snapshot.path, options.expected_version, snapshot.version);
+    }
+    const operations = Array.isArray(ops) ? [...ops] : [ops];
+    if (operations.length === 0) {
+      throw new InvalidOperationError("edit() requires at least one operation");
+    }
+    const lines = [...snapshot.lines];
+    const mismatches = [];
+    const validateAnchor = (line, expectedHash) => {
+      if (line < 1 || line > lines.length) {
+        throw new InvalidOperationError(
+          `Line ${line} is out of range for ${snapshot.path} (total_lines=${lines.length})`
+        );
+      }
+      const actual = computeLineHash(line, lines[line - 1] ?? "", this.#hashLength);
+      if (actual !== expectedHash) {
+        mismatches.push({ line, expected: expectedHash, actual });
+      }
+    };
+    for (const operation of operations) {
+      validateAnchor(operation.line, operation.hash);
+      if ("end_line" in operation && operation.end_line !== void 0) {
+        if (!operation.end_hash) {
+          throw new InvalidOperationError("Range edits require end_hash");
+        }
+        validateAnchor(operation.end_line, operation.end_hash);
+        if (operation.end_line < operation.line) {
+          throw new InvalidOperationError("end_line must be >= line");
+        }
+      }
+    }
+    if (mismatches.length > 0) {
+      throw new AnchorMismatchError(
+        mismatchMessage(snapshot.path, lines, this.#hashLength, mismatches),
+        mismatches
+      );
+    }
+    const sortKey = (operation) => {
+      const lineNumber = "end_line" in operation && operation.end_line !== void 0 ? operation.end_line : operation.line;
+      const precedence = { replace: 0, delete: 0, insert_after: 1, insert_before: 2 }[operation.op];
+      return [-lineNumber, precedence];
+    };
+    let firstChangedLine = null;
+    for (const operation of [...operations].sort((left, right) => {
+      const [leftLine, leftPrec] = sortKey(left);
+      const [rightLine, rightPrec] = sortKey(right);
+      return leftLine - rightLine || leftPrec - rightPrec;
+    })) {
+      if (operation.op === "replace") {
+        const replacement = stripRenderPrefixes([...operation.lines]);
+        const endLine = operation.end_line ?? operation.line;
+        const current = lines.slice(operation.line - 1, endLine);
+        if (current.length === replacement.length && current.every((line, index) => line === replacement[index])) {
+          throw new InvalidOperationError(
+            `No changes made to ${snapshot.path}. Replacement for ${operation.line}:${operation.hash} is identical.`
+          );
+        }
+        lines.splice(operation.line - 1, endLine - operation.line + 1, ...replacement);
+        firstChangedLine = firstChangedLine === null ? operation.line : Math.min(firstChangedLine, operation.line);
+      } else if (operation.op === "delete") {
+        const endLine = operation.end_line ?? operation.line;
+        lines.splice(operation.line - 1, endLine - operation.line + 1);
+        firstChangedLine = firstChangedLine === null ? operation.line : Math.min(firstChangedLine, operation.line);
+      } else if (operation.op === "insert_before") {
+        const inserted = stripRenderPrefixes([...operation.lines]);
+        const payload = inserted.length === 0 ? [""] : inserted;
+        lines.splice(operation.line - 1, 0, ...payload);
+        firstChangedLine = firstChangedLine === null ? operation.line : Math.min(firstChangedLine, operation.line);
+      } else {
+        const inserted = stripRenderPrefixes([...operation.lines]);
+        const payload = inserted.length === 0 ? [""] : inserted;
+        lines.splice(operation.line, 0, ...payload);
+        const insertionLine = operation.line + 1;
+        firstChangedLine = firstChangedLine === null ? insertionLine : Math.min(firstChangedLine, insertionLine);
+      }
+    }
+    const versionAfter = await this.writeSnapshot(resolved, {
+      lines,
+      bom: snapshot.bom,
+      newline: snapshot.newline,
+      has_final_newline: snapshot.has_final_newline
+    });
+    return {
+      path: snapshot.path,
+      version_before: snapshot.version,
+      version_after: versionAfter,
+      applied: operations.length,
+      first_changed_line: firstChangedLine,
+      encoding: snapshot.encoding,
+      bom: snapshot.bom,
+      newline: snapshot.newline,
+      has_final_newline: snapshot.has_final_newline,
+      total_lines: lines.length
+    };
+  }
+  async write(path, text, options = {}) {
+    const resolved = this.resolvePath(path);
+    const created = !await pathExists(resolved);
+    const input = detectNewlineStyle(text);
+    let bom = false;
+    let newline = input.newline;
+    let versionAfter;
+    if (created) {
+      versionAfter = await this.writeSnapshot(resolved, {
+        lines: input.lines,
+        bom: false,
+        newline: input.newline,
+        has_final_newline: input.has_final_newline
+      });
+    } else {
+      const snapshot = await this.readSnapshot(resolved);
+      if ((options.expected_version ?? null) !== snapshot.version) {
+        throw new VersionConflictError(
+          snapshot.path,
+          options.expected_version ?? null,
+          snapshot.version
+        );
+      }
+      bom = snapshot.bom;
+      newline = snapshot.newline === "none" ? input.newline : snapshot.newline;
+      versionAfter = await this.writeSnapshot(resolved, {
+        lines: input.lines,
+        bom,
+        newline,
+        has_final_newline: input.has_final_newline
+      });
+    }
+    return {
+      path: relative(this.#root, resolved),
+      version_after: versionAfter,
+      created,
+      encoding: this.#encoding,
+      bom,
+      newline,
+      has_final_newline: input.has_final_newline,
+      total_lines: input.lines.length
+    };
+  }
+  async readSnapshot(path) {
+    const raw = Buffer.from(await readFile(path));
+    const version = versionForBytes(raw);
+    const bom = raw.subarray(0, UTF8_BOM.length).equals(UTF8_BOM);
+    const payload = bom ? raw.subarray(UTF8_BOM.length) : raw;
+    let text;
+    try {
+      text = new TextDecoder(this.#encoding, { fatal: true }).decode(payload);
+    } catch (error) {
+      throw new FileEncodingError(`${relative(this.#root, path)} is not valid ${this.#encoding}`, {
+        cause: error
+      });
+    }
+    const parsed = detectNewlineStyle(text);
+    return {
+      path: relative(this.#root, path),
+      version,
+      encoding: this.#encoding,
+      bom,
+      newline: parsed.newline,
+      has_final_newline: parsed.has_final_newline,
+      lines: parsed.lines
+    };
+  }
+  async writeSnapshot(path, options) {
+    await mkdir(dirname(path), { recursive: true });
+    const text = joinText(options.lines, options.newline, options.has_final_newline);
+    let payload = Buffer.from(text, this.#encoding);
+    if (options.bom) {
+      payload = Buffer.concat([UTF8_BOM, payload]);
+    }
+    const tempPath = `${path}.${randomUUID()}.tmp`;
+    let mode;
+    try {
+      mode = (await stat(path)).mode;
+    } catch {
+    }
+    try {
+      await writeFile(tempPath, payload);
+      if (mode !== void 0) {
+        await chmod(tempPath, mode);
+      }
+      await rename(tempPath, path);
+    } finally {
+      await rm(tempPath, { force: true });
+    }
+    return versionForBytes(payload);
+  }
+};
+function resolveExistingPath(path) {
+  const missingSegments = [];
+  let current = path;
+  while (true) {
+    try {
+      const resolved = realpathSync.native(current);
+      const suffix = [...missingSegments].reverse();
+      return missingSegments.length === 0 ? resolved : joinPath(resolved, ...suffix);
+    } catch (error) {
+      const candidate = error;
+      if (candidate.code !== "ENOENT") {
+        throw candidate;
+      }
+      const parent = dirname(current);
+      if (parent === current) {
+        return joinPath(current, ...[...missingSegments].reverse());
+      }
+      missingSegments.push(basename(current));
+      current = parent;
+    }
+  }
+}
+export {
+  AnchorMismatchError,
+  FileEncodingError,
+  HashEditError,
+  HashEditHarness,
+  InvalidOperationError,
+  MixedNewlineError,
+  PathEscapeError,
+  VersionConflictError,
+  computeLineHash,
+  renderLine,
+  renderLines,
+  stripRenderPrefixes
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@svilupp/hash-edit",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Minimal AI-agent file read/edit/write tools with line-hash anchors",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src", "LICENSE"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "lint:oxlint": "oxlint --tsconfig tsconfig.json -c .oxlintrc.json src/",
+    "format": "biome format --write src/ tests/",
+    "check": "bun run lint && bun run typecheck && bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^24.7.2",
+    "bun-types": "^1.3.10",
+    "oxlint": "^1.56.0",
+    "oxlint-tsgolint": "^0.17.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.0"
+  }
+}