pi-supernova 0.8.2 → 0.9.0

package/src/fs/commit.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {fileSignature,sameSignature,textSignature} from './file-io.js';
+
+// realpath() cannot resolve a missing leaf. Canonicalize its nearest existing
+// ancestor so two symlink spellings still share one commit destination.
+async function canonicalNewPath(target) {
+  let ancestor = path.dirname(target);
+
+  for (;;) {
+    try { return path.join(await fs.realpath(ancestor), path.relative(ancestor, target)); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(ancestor);
+
+      if (parent === ancestor) throw error;
+      ancestor = parent;
+    }
+  }
+}
+
+async function resolveExistingFile(logicalPath) {
+  const target = await fs.realpath(logicalPath);
+  const stat = await fs.stat(target);
+
+  if (!stat.isFile()) throw new Error("cannot write to a non-file: " + logicalPath);
+
+  return { target, stat };
+}
+
+export async function resolveCommitTarget(logicalPath) {
+  try {
+    return await resolveExistingFile(logicalPath);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+
+    return { target: await canonicalNewPath(logicalPath), stat: undefined };
+  }
+}
+
+async function collectMissingAncestors(parent) {
+  const missing = [];
+  let probe = parent;
+
+  for (;;) {
+    try { await fs.stat(probe); break; } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      missing.push(probe);
+      probe = path.dirname(probe);
+    }
+  }
+
+  return missing;
+}
+
+async function writeTemporary(entry, content, stat) {
+  try {
+    await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
+  } catch (error) {
+    // Never leak the temporary name: name the destination and the real cause.
+    if (error?.code === "EACCES" || error?.code === "EPERM") throw new Error("permission denied writing " + entry.target + ": the directory or file is not writable");
+    if (error?.code === "EROFS") throw new Error("cannot write " + entry.target + ": the file system is read-only");
+    if (error?.code === "ENOSPC") throw new Error("cannot write " + entry.target + ": no space left on device");
+
+    throw error;
+  }
+
+  if (stat) await fs.chmod(entry.temporary, stat.mode & 0o7777);
+}
+
+async function stageReplacement(entry, content, stat, target) {
+  const replacement = writeTemporary(entry, content, stat);
+  // These touch separate staging files. Settle both before cleanup, even
+  // on failure: Promise.all could leave a late backup after rollback.
+  const staging = [replacement];
+
+  if (stat) staging.push(fs.copyFile(target, entry.backup, fs.constants.COPYFILE_EXCL));
+  const outcomes = await Promise.allSettled(staging);
+  const failure = outcomes.find(outcome => outcome.status === "rejected");
+
+  if (failure) throw failure.reason;
+}
+
+function makeStageEntry(logicalPath, target, content, parent, stat) {
+  const token = ".supernova-" + randomUUID();
+
+  return { logicalPath, target, content, temporary: path.join(parent, token + ".new"), backup: path.join(parent, token + ".bak"), existed: !!stat, replaced: false };
+}
+
+async function recoverReplaced(staged) {
+  const recoveryErrors = [];
+
+  for (const entry of staged.toReversed()) {
+    if (!entry.replaced) continue;
+
+    try {
+      if (entry.existed) await fs.rename(entry.backup, entry.target);
+      else await fs.unlink(entry.target);
+    } catch (err) {
+      // Keep the backup if recovery fails; never delete the remaining original.
+      entry.keepBackup = true;
+      recoveryErrors.push(entry.target + ": " + err.message + " (backup: " + entry.backup + ")");
+    }
+  }
+
+  return recoveryErrors;
+}
+
+async function cleanupStaged(staged, failed, createdDirs) {
+  for (const entry of staged) {
+    // A successful rename consumed the temporary path. These are known
+    // files, so unlink avoids rm's extra type probe; missing files stay benign.
+    if (!entry.replaced) await fs.unlink(entry.temporary).catch(() => {});
+
+    if (entry.existed && !entry.keepBackup) await fs.unlink(entry.backup).catch(() => {});
+  }
+
+  if (failed) for (const dir of createdDirs.toReversed()) await fs.rmdir(dir).catch(() => {});
+}
+
+async function assertExpectedSignature(vfs, logicalPath, target, stat) {
+  if (!vfs.expected.has(logicalPath)) return;
+  const current = stat ? await fileSignature(target, vfs.signal) : null;
+
+  if (!sameSignature(current, vfs.expected.get(logicalPath))) {
+    throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
+  }
+}
+
+async function installStaged(vfs, staged) {
+  for (const entry of staged) {
+    vfs.signal?.throwIfAborted();
+    await fs.rename(entry.temporary, entry.target);
+    entry.replaced = true;
+  }
+
+  for (const entry of staged) {
+    vfs.expected.set(entry.logicalPath, textSignature(entry.content));
+  }
+
+  // Canonical commit destinations must not rewrite established event paths
+  // for newly created files, whose callers supplied a logical cwd spelling.
+  if (staged.length) vfs.onNewFile?.(staged.map(entry => entry.existed ? entry.target : entry.logicalPath));
+}
+
+async function failCommit(vfs, staged, error) {
+  const recoveryErrors = await recoverReplaced(staged);
+  // Keep CAS baselines: a failed commit must not forgive conflicts on files it
+  // never touched. If recovery left disk diverging from a baseline, the next
+  // write to that path fails loudly and forces a re-read instead of silently
+  // re-capturing unknown bytes as the new truth.
+
+  if (recoveryErrors.length) vfs.mutations.recoveryFailed = true;
+
+  if (recoveryErrors.length) vfs.onNewFile?.(null);
+
+  if (recoveryErrors.length) throw new AggregateError([error, ...recoveryErrors.map(message => new Error(message))], "commit failed: " + error.message + "; recovery failed: " + recoveryErrors.join("; "));
+  throw error;
+}
+export {assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged};

package/src/fs/diff.js

@@ -18,13 +18,8 @@ export function buildEditDiff(filePath, originalText, oldText, newText) {
     lines.push({ type: "context", lineNum: startLine - 1, text: fileLines[startLine - 2] });
   }
 
-  for (let i = 0; i < oldLines.length; i++) {
-    lines.push({ type: "remove", lineNum: startLine + i, text: oldLines[i] });
-  }
-
-  for (let i = 0; i < newLines.length; i++) {
-    lines.push({ type: "add", lineNum: startLine + i, text: newLines[i] });
-  }
+  appendDiffLines(lines, "remove", oldLines, startLine);
+  appendDiffLines(lines, "add", newLines, startLine);
 
   const afterSourceLine = startLine + oldLines.length;
 
@@ -102,7 +97,7 @@ export function buildPatchDiff(filePath, patchText, relocations = []) {
       continue;
     }
 
-    if (!inHunk || patchLine.startsWith("\\")) continue;
+    if (!inHunk) continue;
     const kind = classifyPatchLine(patchLine);
 
     if (!kind) continue;
@@ -140,13 +135,8 @@ export function buildWriteDiff(filePath, previousText, newText) {
   const maxStoredLines = 64;
   const lines = [];
 
-  for (let i = 0; i < oldLines.length && lines.length < maxStoredLines; i++) {
-    lines.push({ type: "remove", lineNum: i + 1, text: oldLines[i] });
-  }
-
-  for (let i = 0; i < newLines.length && lines.length < maxStoredLines; i++) {
-    lines.push({ type: "add", lineNum: i + 1, text: newLines[i] });
-  }
+  appendDiffLines(lines, "remove", oldLines, 1, maxStoredLines);
+  appendDiffLines(lines, "add", newLines, 1, maxStoredLines);
 
   return {
     path: filePath,
@@ -157,3 +147,9 @@ export function buildWriteDiff(filePath, previousText, newText) {
     lines,
   };
 }
+
+function appendDiffLines(lines, type, text, start, limit = Infinity) {
+  for (let i = 0; i < text.length && lines.length < limit; i++) {
+    lines.push({type, lineNum: start + i, text: text[i]});
+  }
+}

package/src/fs/directory.js

@@ -0,0 +1,79 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {readResult} from '../shared/result.js';
+
+export const MAX_DIRECTORY_ENTRIES = 10000;
+
+export function formatDirectoryEntry(name, type, size = 0) {
+  const sizeSuffix = size ? `, ${size} bytes` : "";
+
+  return `${name}${type === "dir" ? "/" : ""} (${type}${sizeSuffix})`;
+}
+
+export async function formatLsEntry(dirPath, entry) {
+  const isDir = entry.isDirectory();
+  const isSym = entry.isSymbolicLink();
+  const typeLabel = isDir ? "dir" : isSym ? "sym" : "file";
+  let size = 0;
+
+  try {
+    if (!isDir && !isSym) {
+      const st = await fs.stat(path.join(dirPath, entry.name));
+      size = st.size;
+    }
+  } catch {}
+
+  return formatDirectoryEntry(entry.name, typeLabel, size);
+}
+function admitEntry(rows, name, dirPath) {
+  if (!rows.has(name) && rows.size >= MAX_DIRECTORY_ENTRIES) {
+    throw new Error("directory exceeds " + MAX_DIRECTORY_ENTRIES + " entries: " + dirPath + "; read a subdirectory or use bash with a bounded directory parser");
+  }
+}
+
+async function formatDirBatch(dirPath, batch, rows, signal) {
+  const results = await Promise.all(batch.map(entry=>formatLsEntry(dirPath,entry)));
+  signal?.throwIfAborted();
+  for (let i=0;i<batch.length;i++) rows.set(batch[i].name,results[i]);
+}
+
+export function createDirectoryReader(vfs) {
+  function overlayDirRows(dirPath, rows) {
+    for (const file of vfs.getOverlayPaths()) {
+      const relative = path.relative(dirPath,file);
+      if (!relative || relative === ".." || relative.startsWith(".."+path.sep) || path.isAbsolute(relative)) continue;
+      const [name,child] = relative.split(path.sep);
+      admitEntry(rows,name,dirPath);
+      rows.set(name,child === undefined
+        ? formatDirectoryEntry(name,"file",Buffer.byteLength(vfs.getOverlay(file),"utf8"))
+        : formatDirectoryEntry(name,"dir"));
+    }
+  }
+
+  async function diskDirRows(dirPath, rows, signal) {
+    let directory;
+    try { directory = await fs.opendir(dirPath,{bufferSize:128}); }
+    catch (error) { if (error.code === "ENOENT" && rows.size) return; throw error; }
+    let batch = [];
+    // Do not allocate the entire directory first or serialize every stat. Eight
+    // metadata operations overlap; directory handles close on success/error/abort.
+    for await (const entry of directory) {
+      signal?.throwIfAborted();
+      if (rows.has(entry.name)) continue;
+      admitEntry(rows,entry.name,dirPath);
+      rows.set(entry.name,undefined);
+      batch.push(entry);
+      if (batch.length === 8) { await formatDirBatch(dirPath,batch,rows,signal); batch = []; }
+    }
+    await formatDirBatch(dirPath,batch,rows,signal);
+  }
+
+  return async function readDirectory(dirPath, signal) {
+    signal?.throwIfAborted();
+    const rows = new Map();
+    overlayDirRows(dirPath,rows);
+    await diskDirRows(dirPath,rows,signal);
+    const values = [...rows.values()];
+    return readResult(values,{path:dirPath,directory:true,count:rows.size},values.slice(0,20).join("\n"),undefined,()=>values.join("\n"));
+  };
+}

package/src/fs/file-io.js

@@ -0,0 +1,100 @@
+import * as fs from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+
+function textSignature(text) {
+  return { size: Buffer.byteLength(text, "utf8"), sha256: createHash("sha256").update(text, "utf8").digest("hex") };
+}
+
+function sameFileVersion(a, b) {
+  return ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every(key => a[key] === b[key]);
+}
+
+// FileHandle streams with an already-aborted signal can emit a second, unhandled
+// error even after for-await rejects (Node and Bun). Own the bounded reads instead.
+async function* fileChunks(file, signal, maxBytes = Infinity) {
+  const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));
+  let remaining = maxBytes;
+
+  while (remaining > 0) {
+    signal?.throwIfAborted();
+    const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, remaining), null);
+    signal?.throwIfAborted();
+    if (!bytesRead) break;
+    remaining -= bytesRead;
+    // Consumers retaining a chunk must copy it before the next read.
+    yield buffer.subarray(0, bytesRead);
+  }
+}
+
+async function fileSignature(target, signal, observed) {
+  const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+  try {
+    const actual = await file.stat();
+
+    if (!actual.isFile()) throw new Error("read requires a regular file: " + target);
+    if (observed && !sameFileVersion(observed, actual)) throw new Error("file changed while reading: " + target);
+    const hash = createHash("sha256");
+
+    for await (const chunk of fileChunks(file, signal)) hash.update(chunk);
+    const after = await file.stat();
+
+    if (!after.isFile() || !sameFileVersion(actual, after)) throw new Error("file changed while signing: " + target);
+
+    return { size: actual.size, sha256: hash.digest("hex") };
+  } finally {
+    await file.close();
+  }
+}
+
+function sameSignature(a, b) {
+  return a === b || (a !== null && b !== null && a.size === b.size && a.sha256 === b.sha256);
+}
+
+function tooLargeRead(label, maxBytes, target) {
+  return new Error(label + " exceeds " + maxBytes + " bytes" + (target ? ": " + target : "") + "; use a streaming parser through bash");
+}
+
+function overlayOrThrow(overlay, maxBytes, label, target) {
+  if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw tooLargeRead(label, maxBytes, target);
+
+  return overlay;
+}
+
+function assertReadableFile(stat, target) {
+  // Callers are reads, writes, edits and patch application: name the path, not the caller.
+  if (stat.isDirectory()) throw new Error("path is a directory, not a file: " + target);
+
+  if (!stat.isFile()) throw new Error("path is not a regular file: " + target);
+}
+
+async function readLimitedBytes(file, stat, maxBytes, label, signal, overflow = () => tooLargeRead(label, maxBytes)) {
+  if (stat.size > maxBytes) throw overflow();
+  const chunks = [];
+  let size = 0;
+
+  for await (const chunk of fileChunks(file, signal, maxBytes + 1)) {
+    size += chunk.length;
+
+    if (size > maxBytes) throw overflow();
+    chunks.push(Buffer.from(chunk));
+  }
+
+  return Buffer.concat(chunks);
+}
+
+function remapReadError(err, target) {
+  if (err.code === "EISDIR") throw new Error("path is a directory, not a file: " + target);
+
+  if (err.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+  if (err.code === "EACCES" || err.code === "EPERM") throw new Error("permission denied reading " + target + ": check the file mode (for example bash chmod)");
+
+  if (err.code === "ENOENT") {
+    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question; use Promise.allSettled for optional reads to retain successful siblings)');
+    missing.code = "ENOENT";
+    throw missing;
+  }
+
+  throw err;
+}
+export { textSignature, sameFileVersion, fileChunks, fileSignature, sameSignature, tooLargeRead, overlayOrThrow, assertReadableFile, readLimitedBytes, remapReadError };

package/src/fs/glob.js

@@ -0,0 +1,54 @@
+const REGEX_SPECIAL = /[.+^${}()|\\]/g;
+
+/** Translate one glob token at index i → [regexSource, nextIndex]. */
+function globToken(glob, i) {
+  const ch = glob[i];
+
+  if (ch === "*" && glob[i + 1] === "*") {
+    const slashAfter = glob[i + 2] === "/";
+
+    return [slashAfter ? "(?:.*/)?" : ".*", i + (slashAfter ? 3 : 2)];
+  }
+
+  if (ch === "*") return ["[^/]*", i + 1];
+
+  if (ch === "?") return ["[^/]", i + 1];
+
+  if (ch === "{" || ch === "[") return globGroup(glob, i, ch);
+
+  return [ch.replace(REGEX_SPECIAL, "\\$&"), i + 1];
+}
+
+/** {a,b} alternation or [..] class starting at i. */
+function globGroup(glob, i, open) {
+  const close = open === "{" ? "}" : "]";
+  const end = glob.indexOf(close, i);
+
+  if (end < 0) throw new SyntaxError("unclosed " + open + " in glob");
+  const inner = glob.slice(i + 1, end);
+  const source = open === "{"
+    ? "(?:" + inner.split(",").map(globBody).join("|") + ")"
+    : "[" + (inner.startsWith("!") ? "^" + inner.slice(1) : inner) + "]";
+
+  return [source, end + 1];
+}
+
+function globBody(glob) {
+  let source = "";
+  let i = 0;
+
+  while (i < glob.length) {
+    const [piece, next] = globToken(glob, i);
+    source += piece;
+    i = next;
+  }
+
+  return source;
+}
+
+/** gitignore-style glob (rg -g) → RegExp over a "/"-separated relative path. No slash ⇒ basename match anywhere. */
+export function globToRegExp(glob) {
+  const body = globBody(glob);
+
+  return new RegExp(glob.includes("/") ? "^" + body + "$" : "(?:^|/)" + body + "$");
+}

package/src/fs/json-size.js

@@ -0,0 +1,54 @@
+const JSON_TWO_BYTE = new Set([0x22, 0x5c, 8, 9, 10, 12, 13]);
+
+function jsonAsciiWidth(c) {
+  if (JSON_TWO_BYTE.has(c)) return 2;
+
+  if (c < 32) return 6;
+
+  return 1;
+}
+
+function jsonUnitWidth(s, i) {
+  const c = s.charCodeAt(i);
+
+  if (c >= 0xD800 && c <= 0xDBFF && i + 1 < s.length) {
+    const d = s.charCodeAt(i + 1);
+
+    if (d >= 0xDC00 && d <= 0xDFFF) return { add: 2, skip: 2 };
+
+    return { add: 6, skip: 1 };
+  }
+
+  if (c >= 0xD800 && c <= 0xDFFF) return { add: 6, skip: 1 };
+
+  return { add: jsonAsciiWidth(c), skip: 1 };
+}
+
+/** UTF-16 length of JSON.stringify(s) for a string, without allocating the JSON. */
+export function jsonStringLength(s) {
+  let n = 2;
+
+  for (let i = 0; i < s.length; ) {
+    const unit = jsonUnitWidth(s, i);
+    n += unit.add;
+    i += unit.skip;
+  }
+
+  return n;
+}
+
+/** Largest prefix whose JSON.stringify length is <= limit. */
+export function maxJsonStringPrefix(s, limit) {
+  let used = 2;
+  let i = 0;
+
+  while (i < s.length) {
+    const unit = jsonUnitWidth(s, i);
+
+    if (used + unit.add > limit) break;
+    used += unit.add;
+    i += unit.skip;
+  }
+
+  return i;
+}

package/src/fs/lines.js

@@ -0,0 +1,117 @@
+import {isNumber} from '../shared/decode.js';
+
+function totalContentLines(text) {
+  if (text === "") return 1;
+
+  return contentLineInfo(text).count + (text.endsWith("\n") ? 1 : 0);
+}
+
+function emptySliceInfo(text, totalLines) {
+  return { text: "", end: totalLines, total: totalLines, count: 0, eof: true, whole: totalLines === 1 && text === "" };
+}
+
+function sliceWindow(text, startIndex, count, totalLines) {
+  const endExclusive = Math.min(totalLines, startIndex + count);
+  const start = lineStartIndex(text, startIndex + 1);
+  const end = lineEndIndex(text, start, endExclusive - startIndex);
+  let selected = text.slice(start, end);
+  const eof = endExclusive >= totalLines || (endExclusive === totalLines - 1 && text.endsWith("\n"));
+
+  if (endExclusive < totalLines && !selected.endsWith("\n")) selected += "\n";
+
+  return { text: selected, end: endExclusive, total: totalLines, count: endExclusive - startIndex, eof, whole: startIndex === 0 && eof };
+}
+
+export function sliceLinesRawInfo(text, offset, limit) {
+  const totalLines = totalContentLines(text);
+
+  if (!isNumber(offset) && !isNumber(limit)) {
+    return { text, end: totalLines, total: totalLines, count: totalLines, eof: true, whole: true };
+  }
+
+  const startIndex = (isNumber(offset) ? Math.max(1, Math.floor(offset)) : 1) - 1;
+  const count = isNumber(limit) ? Math.max(0, Math.floor(limit)) : totalLines;
+
+  if (count === 0 || startIndex >= totalLines) return emptySliceInfo(text, totalLines);
+
+  return sliceWindow(text, startIndex, count, totalLines);
+}
+
+/** Read-window slicing preserves the selected lines' own line ending. */
+export function sliceLinesRaw(text, offset, limit) {
+  return sliceLinesRawInfo(text, offset, limit).text;
+}
+
+export function sourceLines(content) {
+  const raw = content.split("\n");
+
+  if (raw.at(-1) === "") raw.pop();
+
+  return raw;
+}
+
+export function lineNumberAt(content, index) {
+  let line = 1;
+
+  for (let i = 0; i < index; i++) if (content.charCodeAt(i) === 10) line++;
+
+  return line;
+}
+
+export function formatNumberedLine(n, text) {
+  return String(n).padStart(5) + " " + text;
+}
+
+export function numberedPreview(content, cap = EDIT_PREVIEW_LINES) {
+  const { count, preview } = contentLineInfo(content, cap);
+
+  if (count === 0) return "0 lines";
+  const body = preview.map((line, i) => formatNumberedLine(i + 1, line)).join("\n");
+  const suffix = count + " lines total";
+
+  return body + "\n" + suffix;
+}
+
+export function lineStartIndex(content, line) {
+  return lineEndIndex(content, 0, line - 1);
+}
+
+export function lineEndIndex(content, startIndex, lineCount) {
+  let index = startIndex;
+
+  for (let i = 0; i < lineCount; i++) {
+    const next = content.indexOf("\n", index);
+
+    if (next < 0) return content.length;
+    index = next + 1;
+  }
+
+  return index;
+}
+
+export function lineTextRange(content, line) {
+  const start = lineStartIndex(content, line);
+
+  return { start, end: lineEndIndex(content, start, 1) };
+}
+
+export function contentLineInfo(text, previewLimit = 0) {
+  if (text === "") return { count: 0, preview: [], newlines: 0 };
+  const preview = [];
+  let count = 0;
+  let start = 0;
+
+  do {
+    const newline = text.indexOf("\n", start);
+    const end = newline < 0 ? text.length : newline;
+
+    if (preview.length < previewLimit) preview.push(text.slice(start, end).replace(/\r$/, ""));
+    count++;
+    if (newline < 0) break;
+    start = newline + 1;
+  } while (start < text.length);
+
+  return { count, preview, newlines: count - Number(!text.endsWith("\n")) };
+}
+
+export const EDIT_PREVIEW_LINES = 16;

package/src/fs/read-window.js

@@ -0,0 +1,74 @@
+import * as fs from "node:fs/promises";
+import { decodeUtf8Strict, decodeUtf8Window } from "../shared/utf8.js";
+import { sliceLinesRawInfo } from "./lines.js";
+import { fileChunks, remapReadError } from "./file-io.js";
+
+/** Advance through newline-delimited bytes without decoding or retaining skipped data. */
+function advanceLines(bytes, start, remaining) {
+  while (remaining > 0) {
+    const newline = bytes.indexOf(10, start);
+    if (newline < 0) return { offset: bytes.length, remaining };
+    start = newline + 1;
+    remaining--;
+  }
+  return { offset: start, remaining };
+}
+
+async function scanWindow(file, stat, startLine, lineCount, maxBytes, signal) {
+  const scan = { parts: [], collected: 0, startByte: undefined, endByte: undefined };
+  let skip = startLine - 1, take = lineCount ?? Infinity, position = 0;
+  for await (const chunk of fileChunks(file, signal, stat.size)) {
+    const head = advanceLines(chunk, 0, skip);
+    skip = head.remaining;
+    const start = position;
+    position += chunk.length;
+    if (skip) continue;
+    scan.startByte ??= start + head.offset;
+    const tail = advanceLines(chunk, head.offset, take);
+    take = tail.remaining;
+    if (take === 0) scan.endByte = start + tail.offset;
+    const end = Math.min(tail.offset, head.offset + maxBytes + 1 - scan.collected);
+    if (end > head.offset) {
+      scan.parts.push(Buffer.from(chunk.subarray(head.offset, end)));
+      scan.collected += end - head.offset;
+    }
+    if (take === 0 || scan.collected > maxBytes) break;
+  }
+  return scan;
+}
+
+function overlayWindow(overlay, startLine, lineCount) {
+  const window = sliceLinesRawInfo(overlay, startLine, lineCount);
+  const satisfied = lineCount === undefined || lineCount === 0 || window.text === "" || window.count >= lineCount || window.eof;
+  return { text: window.text, satisfied, whole: window.whole };
+}
+
+async function openReadFile(target) {
+  try { return await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0)); }
+  catch (error) { remapReadError(error, target); }
+}
+
+export function createWindowReader(vfs) {
+  return async function readWindow(target, startLine, lineCount, maxBytes, signal) {
+    const overlay = vfs.getOverlay(target);
+    if (overlay !== undefined) {
+      const window = overlayWindow(overlay,startLine,lineCount);
+      window.satisfied &&= Buffer.byteLength(window.text,"utf8") <= maxBytes;
+      return window;
+    }
+    const file = await openReadFile(target);
+    try {
+      const stat = await file.stat();
+      if (!stat.isFile()) throw new Error("read requires a regular file: " + target);
+      if (lineCount === 0) return { text: "", satisfied: true, whole: stat.size === 0 };
+      const scan = await scanWindow(file, stat, startLine, lineCount, maxBytes, signal);
+      if (scan.startByte === undefined) return { text: "", satisfied: true, whole: stat.size === 0 };
+      const bytes = Buffer.concat(scan.parts, scan.collected);
+      const end = scan.startByte + scan.collected;
+      const eof = end >= stat.size;
+      const text = eof ? decodeUtf8Strict(bytes, target) : decodeUtf8Window(bytes);
+      await vfs.recordExpected(target, stat);
+      return { text, satisfied: end >= scan.endByte || eof, whole: startLine === 1 && scan.startByte === 0 && eof };
+    } finally { await file.close(); }
+  };
+}