dsh-hashline-edit 0.2.2 → 0.2.3

package/src/fs-lifecycle.ts

@@ -0,0 +1,201 @@
+import { lstat, mkdir, realpath, rename, rm, rmdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { DomainError } from "./domain-errors.js";
+import { reportDiagnostic } from "./diagnostics.js";
+import { resolveTarget } from "./fs-write.js";
+import { errCode } from "./utils.js";
+
+/**
+ * Filesystem primitives for apply_patch's file lifecycle: classify, create directories, delete a
+ * regular file and rename one. Every entry point resolves through {@link resolveTarget}, the same
+ * symlink-resolving boundary every read/write uses, so a lifecycle action can never escape it.
+ *
+ * These are primitives, not a second write engine: file CONTENTS still go through writeAtomic;
+ * this module only owns namespace operations that writeAtomic deliberately does not express.
+ *
+ * @module dsh-hashline-edit/fs-lifecycle
+ */
+
+/** The physical kind of a path as the file layer sees it (symlinks resolved first). */
+export type PathKind = "file" | "directory" | "other" | "absent";
+
+/** Classify one path through the file layer's symlink-resolving boundary. */
+export async function pathKind(path: string): Promise<PathKind> {
+  const targetPath = await resolveTarget(path);
+  try {
+    const info = await lstat(targetPath);
+    if (info.isSymbolicLink()) return "other";
+    if (info.isFile()) return "file";
+    if (info.isDirectory()) return "directory";
+    return "other";
+  } catch (error: unknown) {
+    if (errCode(error) === "ENOENT") return "absent";
+    throw error;
+  }
+}
+
+/**
+ * True when `path` resolves inside `root` once every existing symlink/junction component is
+ * followed. A missing tail is checked against its nearest existing ancestor: an Add File under a
+ * junction ancestor therefore fails before mkdir can create anything outside the workspace.
+ */
+export async function isPathWithinWorkspace(root: string, path: string): Promise<boolean> {
+  const absolutePath = resolve(path);
+  const { root: fsRoot } = parse(absolutePath);
+  let cursor = fsRoot;
+  for (const part of absolutePath
+    .slice(fsRoot.length)
+    .split(sep)
+    .filter((value) => value.length > 0)) {
+    cursor = join(cursor, part);
+    try {
+      const info = await lstat(cursor);
+      if (info.isSymbolicLink()) return false;
+      // WHY: Windows junctions are reparse points that some Node builds do not classify as
+      // WHY: symlinks; a realpath that differs from the lexical path proves a link component.
+      if ((await realpath(cursor)) !== cursor) return false;
+    } catch (error: unknown) {
+      if (errCode(error) === "ENOENT") break;
+      throw error;
+    }
+  }
+  const rootReal = await realpath(resolve(root));
+  let ancestor = absolutePath;
+  for (;;) {
+    try {
+      const real = await realpath(ancestor);
+      const rel = relative(rootReal, real);
+      return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    } catch (error: unknown) {
+      if (errCode(error) !== "ENOENT") throw error;
+      const parent = dirname(ancestor);
+      if (parent === ancestor) return false;
+      ancestor = parent;
+    }
+  }
+}
+
+/** Throw the E_PATCH_SYNTAX boundary refusal for one escaping lifecycle path. */
+export async function assertPathWithinWorkspace(root: string, path: string): Promise<void> {
+  if (!(await isPathWithinWorkspace(root, path))) {
+    throw new DomainError("E_PATCH_SYNTAX", {
+      message: `path escapes the workspace through a symlink or junction: ${path}`,
+      path,
+    });
+  }
+}
+
+/** Create one directory (and missing parents), through the symlink-resolving boundary. */
+export async function mkdirp(path: string, workspaceRoot?: string): Promise<void> {
+  if (path.includes("\0")) {
+    throw new DomainError("E_INTERNAL_INVARIANT", { message: "Path contains null byte." });
+  }
+  if (workspaceRoot !== undefined) await assertPathWithinWorkspace(workspaceRoot, path);
+  const targetPath = await resolveTarget(path);
+  await mkdir(targetPath, { recursive: true });
+  if (workspaceRoot !== undefined) await assertPathWithinWorkspace(workspaceRoot, path);
+}
+
+/**
+ * Delete one regular file. Deliberately NOT recursive: a lifecycle delete targets a file, and a
+ * directory at the same path is a caller bug that must surface, never be removed wholesale.
+ */
+export async function removeFile(path: string, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
+  const targetPath = await resolveTarget(path);
+  const kind = await pathKind(targetPath);
+  if (kind === "absent") {
+    const error = new Error(
+      "ENOENT: no such file or directory, unlink '" + targetPath + "'",
+    ) as NodeJS.ErrnoException;
+    error.code = "ENOENT";
+    throw error;
+  }
+  if (kind !== "file") {
+    throw new DomainError("E_INTERNAL_INVARIANT", {
+      message: "Refusing to delete a non-file lifecycle target: " + path,
+    });
+  }
+  await rm(targetPath, { force: false });
+}
+
+/**
+ * Rename one regular file, creating the destination parent first. The destination must not exist:
+ * a move never clobbers another file (spec §6: target-exists is a rejection, not an overwrite).
+ */
+export async function renameFile(
+  from: string,
+  to: string,
+  signal?: AbortSignal,
+  workspaceRoot?: string,
+): Promise<void> {
+  signal?.throwIfAborted();
+  if (workspaceRoot !== undefined) {
+    await assertPathWithinWorkspace(workspaceRoot, from);
+    await assertPathWithinWorkspace(workspaceRoot, to);
+  }
+  const fromPath = await resolveTarget(from);
+  const toPath = await resolveTarget(to);
+  const destinationKind = await pathKind(toPath);
+  if (destinationKind !== "absent") {
+    const error = new Error(
+      "EEXIST: file already exists, rename '" + fromPath + "' -> '" + toPath + "'",
+    ) as NodeJS.ErrnoException;
+    error.code = "EEXIST";
+    throw error;
+  }
+  await mkdirp(dirname(toPath), workspaceRoot);
+  if (workspaceRoot !== undefined) await assertPathWithinWorkspace(workspaceRoot, to);
+  await rename(fromPath, toPath);
+}
+
+/**
+ * The directories on the way to `path` that do not exist yet, OUTERMOST FIRST. Captured before a
+ * lifecycle add writes, so an undo removes exactly the directories the add created and no others.
+ */
+export async function missingAncestorDirs(path: string): Promise<string[]> {
+  const targetPath = await resolveTarget(path);
+  const missing: string[] = [];
+  let cursor = dirname(targetPath);
+  const { root } = parse(cursor);
+  while (cursor !== root) {
+    try {
+      const info = await lstat(cursor);
+      if (info.isDirectory()) break;
+      break;
+    } catch (error: unknown) {
+      if (errCode(error) !== "ENOENT") throw error;
+      missing.unshift(cursor);
+      cursor = dirname(cursor);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Best-effort removal of directories a lifecycle add created, deepest first. Returns the removed
+ * paths. A directory that is no longer empty (an outside writer put something there) is kept.
+ */
+export async function pruneEmptyDirs(dirs: readonly string[]): Promise<string[]> {
+  const removed: string[] = [];
+  for (const dir of [...dirs].sort((a, b) => b.length - a.length)) {
+    try {
+      await rmdir(dir);
+      removed.push(dir);
+    } catch (error: unknown) {
+      const code = errCode(error);
+      if (
+        code === "ENOENT" ||
+        code === "ENOTEMPTY" ||
+        code === "EEXIST" ||
+        code === "EPERM" ||
+        code === "EISDIR" ||
+        code === "ENOTDIR"
+      ) {
+        continue;
+      }
+      reportDiagnostic("fs-lifecycle", "failed to prune a lifecycle-created directory:", error);
+    }
+  }
+  return removed;
+}

package/src/hash-store.ts

@@ -156,7 +156,16 @@ function openDb(storePath: string, budget?: BusyBudget): OpenedDb {
 const MIGRATION_COLUMNS = {
   cut_intent: { direction: "TEXT" },
   file_snapshots: { stat_key: "TEXT" },
-  file_undo: { snapshot_hash: "TEXT", transaction_id: "TEXT", raw_pre: "TEXT" },
+  file_undo: {
+    snapshot_hash: "TEXT",
+    transaction_id: "TEXT",
+    raw_pre: "TEXT",
+    lifecycle: "TEXT",
+    from_path: "TEXT",
+    to_path: "TEXT",
+    raw_post: "TEXT",
+    created_dirs: "TEXT",
+  },
   served: { retired: "TEXT", canons: "TEXT", snapshotId: "TEXT" },
   undo: { result_content: "TEXT NOT NULL DEFAULT ''" },
 } as const;
@@ -625,6 +634,14 @@ export function ensureFileUndoSchema(db: DatabaseSync): void {
   addColumnIfMissing(db, "file_undo", "snapshot_hash");
   addColumnIfMissing(db, "file_undo", "transaction_id");
   addColumnIfMissing(db, "file_undo", "raw_pre");
+  // WHY: apply_patch lifecycle rows are still edit-shaped rows: one file_undo row per member,
+  // WHY: one shared transaction id. These columns only widen what a row can describe — an
+  // WHY: existing row (all NULL) stays an ordinary edit, so the addition is back-compatible.
+  addColumnIfMissing(db, "file_undo", "lifecycle");
+  addColumnIfMissing(db, "file_undo", "from_path");
+  addColumnIfMissing(db, "file_undo", "to_path");
+  addColumnIfMissing(db, "file_undo", "raw_post");
+  addColumnIfMissing(db, "file_undo", "created_dirs");
   // WHY: versions the persisted anchor set — existing rows keep 0 (never current),
   // WHY: so a pre-bump store is refused, not migrated, on first open after upgrade.
   // WHY: `canon_version` (pre-rename builds) is renamed in place, preserving stamped values.

package/src/hashline/alphabet.ts

@@ -3,9 +3,10 @@
  *
  * WHY an environment variable rather than a settings-file key: `alphabet.ts` is a zero-import leaf
  * and every shape, regex, bitset and capacity constant below is derived at module load, so the
- * width can only be a process-wide, load-time value. Switching it changes every served anchor; the
- * persisted store stays safe because the anchor generation (`hash-identity.ts`) folds the width in,
- * so a switch is a hard generation miss (re-read), never a cross-width hit.
+ * width can only be a process-wide, load-time value. The build bakes it via esbuild `define`
+ * (`__ANCHOR_WIDTH__`), so a shipped bundle carries a literal and never reads the environment; the
+ * anchor generation (`hash-identity.ts`) folds the width in, so a width switch is a hard generation
+ * miss (re-read), never a cross-width hit.
  */
 export const ANCHOR_WIDTH_ENV_VAR = "PI_BETTER_EDIT_ANCHOR_WIDTH";
 
@@ -31,10 +32,9 @@ export function resolveAnchorWidth(env: Record<string, string | undefined>): num
 }
 
 /**
- * Build-time bake hook. The dsh/pi builds pass esbuild `define: __ANCHOR_WIDTH__ = <width>` so the
- * shipped bundle carries a literal width and NEVER consults the environment at runtime. When there
- * is no define (vitest / an unbundled dev import), the `typeof` guard falls back to the resolver
- * below, keeping the zero-import leaf usable in tests without a build step.
+ * Build-time bake hook. The dsh build passes esbuild `define: __ANCHOR_WIDTH__ = <width>` so the
+ * shipped bundle carries a literal width and NEVER consults the environment at runtime. Without a
+ * define (vitest / an unbundled dev import) the `typeof` guard falls back to the resolver above.
  */
 declare const __ANCHOR_WIDTH__: number | undefined;
 

package/src/hashline/hash-identity.ts

@@ -112,23 +112,28 @@ export const HASH_PROBE_STRIDE = ALPHA.length ** 2 + ALPHA.length + 1;
 export const CANON_VERSION = 3;
 
 /**
- * The file-scoped anchor-derivation generation (issue #20, ADR-0031; ADR-0020 for the width axis).
+ * ANCHOR_GENERATION 1 (issue #20, ADR-0031): the file-scoped anchor-derivation generation.
  * It covers exactly: (1) the width (`HASH_LEN`, `ALPHA`, `HASH_SPACE`/`USABLE_HASH_SPACE`);
  * (2) the (path, content) seeding (`fileBaseIndex` seeds xxh32 with the canonical absolute path,
  * `contentBaseIndex` is the explicit content-only fallback); (3) the all-digit reservation
  * (`DIGIT_CHARS`/`RESERVED_HASH_SPELLINGS`/`RESERVED_BITS` pre-marked in allocation); (4) the probe
  * stride (`HASH_PROBE_STRIDE`, coprime with both spaces). Bump it whenever any of those change.
  *
- * WHY it is a function of the width now: the width is a runtime switch (default 4, optional 3), so a
- * width change MUST flip the generation or a store written at one width could be read at another.
- * Width 4 stays generation 1 — the original persisted generation — so existing stores keep their
- * anchors across this change; width 3 gets generation 2, and any future width gets `100 + width`.
- *
- * WHY: single owner of the anchor-generation value — anchor-bearing artifacts (the undo/snapshot
+ * WHY: single owner of the anchor-generation literal — anchor-bearing artifacts (the undo/snapshot
  * generation gate and the open-time sweep) read this axis only, never `CANON_VERSION`; the snapshot
  * cache key carries both (`${CANON_VERSION}:${ANCHOR_GENERATION}:${checksum}`), so a canon-only change
  * misses the cache without invalidating anchor state while a generation change invalidates both.
  */
+/**
+ * The file-scoped anchor-derivation generation. It covers the width (`HASH_LEN`, `ALPHA`,
+ * `HASH_SPACE`/`USABLE_HASH_SPACE`), the (path, content) seeding, the all-digit reservation and the
+ * probe stride. Bump it whenever any of those change.
+ *
+ * WHY it is a function of the width: the width is a build-time switch (ADR-0020: default 4, optional
+ * 3), so a width change MUST flip the generation or a store written at one width could be read at
+ * another. Width 4 stays generation 1 — the original persisted generation — so existing stores keep
+ * their anchors; width 3 gets generation 2, and any future width gets `100 + width`.
+ */
 export function anchorGenerationFor(width: number): number {
   return width === 4 ? 1 : width === 3 ? 2 : 100 + width;
 }

package/src/host-utils.ts

@@ -0,0 +1,224 @@
+/**
+ * Host-neutral utilities the hashline core needs from the historical pi runtime.
+ *
+ * WHY: the dsh plugin ships without the pi agent package. Three core modules used
+ * to import small utility functions from `@earendil-works/pi-coding-agent`:
+ * `src/file-content/preview.ts` and `src/file-content/served-header.ts` use
+ * `formatSize` / `truncateHead` / `DEFAULT_MAX_LINES` / `DEFAULT_MAX_BYTES`
+ * to render read pages, and `src/mutation-queue.ts` uses
+ * `withFileMutationQueue` to serialize same-file mutations for the cut
+ * transaction and its correlated undo. This module owns that surface as plain
+ * host-neutral code; `dsh/host-compat.ts` re-exports it for the dsh bundle.
+ *
+ * @module dsh-hashline-edit/host-utils
+ */
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+/** Retained line budget, matching pi's `DEFAULT_MAX_LINES`. */
+export const DEFAULT_MAX_LINES = 2000;
+
+/** Retained byte budget, matching pi's `DEFAULT_MAX_BYTES` (50KB). */
+export const DEFAULT_MAX_BYTES = 50 * 1024;
+
+/** The truncation report the core's read page renders. */
+export interface TruncationResult {
+  /** The truncated content. */
+  content: string;
+  /** Whether truncation occurred. */
+  truncated: boolean;
+  /** Which limit was hit: `"lines"`, `"bytes"`, or `null` when nothing was cut. */
+  truncatedBy: "lines" | "bytes" | null;
+  /** Total number of lines in the original content. */
+  totalLines: number;
+  /** Total number of bytes in the original content. */
+  totalBytes: number;
+  /** Number of complete lines in the truncated output. */
+  outputLines: number;
+  /** Number of bytes in the truncated output. */
+  outputBytes: number;
+  /** Whether the last line was partially truncated (tail truncation only). */
+  lastLinePartial: boolean;
+  /** Whether the first line exceeded the byte limit (head truncation only). */
+  firstLineExceedsLimit: boolean;
+  /** The line limit that was applied. */
+  maxLines: number;
+  /** The byte limit that was applied. */
+  maxBytes: number;
+}
+
+/** The two independent limits a truncation call applies. */
+export interface TruncationOptions {
+  /** Maximum number of lines; defaults to {@link DEFAULT_MAX_LINES}. */
+  maxLines?: number;
+  /** Maximum number of bytes; defaults to {@link DEFAULT_MAX_BYTES}. */
+  maxBytes?: number;
+}
+
+/** Split content into lines for counting, dropping the empty tail of a trailing newline. */
+function splitLinesForCounting(content: string): string[] {
+  if (content.length === 0) return [];
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines;
+}
+
+/**
+ * Format bytes as a human-readable size (`512B`, `1.5KB`, `2.0MB`).
+ * @param bytes - the byte count to render.
+ * @returns the pi-compatible size label.
+ */
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * Truncate content from the head (keep the first N lines / bytes).
+ *
+ * WHY: the read page's oversize and truncation warnings must agree with the pi
+ * implementation the rest of the contract was written against, so this is a
+ * faithful port including its two edge rules: complete lines only, and an
+ * over-long first line yields empty content with `firstLineExceedsLimit`.
+ * @param content - the text to truncate.
+ * @param options - the line and byte limits.
+ * @returns the truncation report.
+ */
+export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
+  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const totalBytes = Buffer.byteLength(content, "utf-8");
+  const lines = splitLinesForCounting(content);
+  const totalLines = lines.length;
+
+  if (totalLines <= maxLines && totalBytes <= maxBytes) {
+    return {
+      content,
+      truncated: false,
+      truncatedBy: null,
+      totalLines,
+      totalBytes,
+      outputLines: totalLines,
+      outputBytes: totalBytes,
+      lastLinePartial: false,
+      firstLineExceedsLimit: false,
+      maxLines,
+      maxBytes,
+    };
+  }
+
+  const firstLineBytes = Buffer.byteLength(lines[0] ?? "", "utf-8");
+  if (firstLineBytes > maxBytes) {
+    return {
+      content: "",
+      truncated: true,
+      truncatedBy: "bytes",
+      totalLines,
+      totalBytes,
+      outputLines: 0,
+      outputBytes: 0,
+      lastLinePartial: false,
+      firstLineExceedsLimit: true,
+      maxLines,
+      maxBytes,
+    };
+  }
+
+  const outputLinesArr: string[] = [];
+  let outputBytesCount = 0;
+  let truncatedBy: "lines" | "bytes" = "lines";
+  for (let index = 0; index < lines.length && index < maxLines; index += 1) {
+    const line = lines[index] ?? "";
+    const lineBytes = Buffer.byteLength(line, "utf-8") + (index > 0 ? 1 : 0);
+    if (outputBytesCount + lineBytes > maxBytes) {
+      truncatedBy = "bytes";
+      break;
+    }
+    outputLinesArr.push(line);
+    outputBytesCount += lineBytes;
+  }
+  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+    truncatedBy = "lines";
+  }
+
+  const outputContent = outputLinesArr.join("\n");
+  return {
+    content: outputContent,
+    truncated: true,
+    truncatedBy,
+    totalLines,
+    totalBytes,
+    outputLines: outputLinesArr.length,
+    outputBytes: Buffer.byteLength(outputContent, "utf-8"),
+    lastLinePartial: false,
+    firstLineExceedsLimit: false,
+    maxLines,
+    maxBytes,
+  };
+}
+
+/** The per-path queue tails; an entry exists only while a mutation holds or awaits it. */
+const fileMutationQueues = new Map<string, Promise<void>>();
+
+/** WHY: queue registration itself must be serialized so two callers cannot adopt the same tail. */
+let registrationQueue: Promise<void> = Promise.resolve();
+
+/** Whether a realpath failure means "no such path" (the queue then keys by the resolved path). */
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+/** Key a mutation by the canonical path, falling back to the resolved path for missing files. */
+async function getMutationQueueKey(filePath: string): Promise<string> {
+  const resolvedPath = resolve(filePath);
+  try {
+    return await realpath(resolvedPath);
+  } catch (error) {
+    if (isMissingPathError(error)) return resolvedPath;
+    throw error;
+  }
+}
+
+/**
+ * Serialize file mutation operations that target the same file; different files still run
+ * in parallel. A faithful port of pi's queue so the core's cut transaction keeps its
+ * lock ordering guarantees under the dsh host.
+ * @param filePath - the file the mutation targets.
+ * @param run - the critical section to run once the path is free.
+ * @returns the critical section's result.
+ */
+export async function withFileMutationQueue<T>(
+  filePath: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  const registration = registrationQueue.then(async () => {
+    const key = await getMutationQueueKey(filePath);
+    const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
+    let releaseNext: () => void = () => {};
+    const nextQueue = new Promise<void>((resolveQueue) => {
+      releaseNext = resolveQueue;
+    });
+    const chainedQueue = currentQueue.then(() => nextQueue);
+    fileMutationQueues.set(key, chainedQueue);
+    return { key, currentQueue, chainedQueue, releaseNext };
+  });
+  registrationQueue = registration.then(
+    () => undefined,
+    () => undefined,
+  );
+
+  const { key, currentQueue, chainedQueue, releaseNext } = await registration;
+  await currentQueue;
+  try {
+    return await run();
+  } finally {
+    releaseNext();
+    if (fileMutationQueues.get(key) === chainedQueue) fileMutationQueues.delete(key);
+  }
+}

package/src/mutation-engine/edit-request.ts

@@ -0,0 +1,39 @@
+import type { EditPlacement } from "../hashline/resolve.js";
+
+/** The internal payload vocabulary the mutation engine consumes; no wire schema lives here. */
+type SpanRef = {
+  anchor_from: string;
+  anchor_to: string;
+  file?: string;
+  mode: "copy" | "cut";
+};
+
+type EditMode = "general" | "literal";
+
+type Placement = "in-place" | "before" | "after";
+
+export type DesiredContent =
+  | { kind: "literal"; text: string }
+  | { kind: "reference"; span: SpanRef; mode: "copy" | "cut" }
+  | { kind: "empty" };
+
+export type NormalizedEditItem = {
+  target: { anchor_from: string; anchor_to: string };
+  at: Placement;
+  payload: DesiredContent;
+  file?: string;
+};
+
+export type NormalizedEditRequest = {
+  file: string;
+  edits: NormalizedEditItem[];
+  mode?: EditMode;
+};
+
+// WHY: the engine seam's placement union must stay mutually assignable with the hashline resolver's
+// WHY: EditPlacement; this assertion fails typecheck if either side drifts.
+const _placementAgreement: [
+  Placement extends EditPlacement ? true : never,
+  EditPlacement extends Placement ? true : never,
+] = [true, true];
+void _placementAgreement;