dsh-hashline-edit 0.2.1 → 0.2.2

package/src/fs-lifecycle.ts

@@ -1,201 +0,0 @@
-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/host-utils.ts

@@ -1,224 +0,0 @@
-/**
- * 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

@@ -1,39 +0,0 @@
-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;