pi-supernova 0.8.2 → 0.9.1

package/src/contract/read.js

@@ -1,4 +1,4 @@
-import { isString, isObject, isNumber, looksLikePath } from "../shared/decode.js";
+import { errorMessage, isString, isObject, isNumber, looksLikePath } from "../shared/decode.js";
 import { sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
 
 export const SESSION_URI = /^(?:agent|artifact):\/\//i;
@@ -85,12 +85,7 @@ export function normalizeRead(params) {
 }
 
 export function needsProbe(params) {
-  if (isSessionUri(params.path)) return false;
-  if (params.evidence === true) return false;
-  if (isString(params.query)) return false;
-  if (params.outline === true) return false;
-
-  return true;
+  return !(isSessionUri(params.path) || params.evidence === true || isString(params.query) || params.outline === true);
 }
 
 /**
@@ -160,8 +155,6 @@ export const ROUTING_STATUS = "too_large";
 
 const ROUTING_PREFIX = '{"status":"too_large",';
 
-export const ROUTING_KEYS_MAX = 32;
-
 export function isRoutingPayload(value) {
   return isString(value) && value.startsWith(ROUTING_PREFIX);
 }
@@ -171,49 +164,6 @@ function isRoutingObject(parsed) {
     && isNumber(parsed.chars) && (Array.isArray(parsed.keys) || isNumber(parsed.length));
 }
 
-/** Shape of an over-bound JSON document for in-band routing. Throws when text is not JSON. */
-export function buildJsonRouting(rel, text) {
-  const document = JSON.parse(text);
-  const base = { status: ROUTING_STATUS, path: rel, chars: text.length };
-
-  if (Array.isArray(document)) return { ...base, length: document.length };
-
-  if (isObject(document)) {
-    const keys = Object.keys(document);
-
-    return keys.length > ROUTING_KEYS_MAX
-      ? { ...base, keys: keys.slice(0, ROUTING_KEYS_MAX), keysTruncated: true }
-      : { ...base, keys };
-  }
-
-  return base;
-}
-
-export function routingText(routing) {
-  const text = JSON.stringify(routing);
-
-  if (!isRoutingPayload(text)) throw new Error("routing payload must start with the shared marker");
-
-  return text;
-}
-
-/** Shape of one over-budget selection for in-band routing; value is already parsed. */
-export function buildSelectionRouting(rel, selector, value, chars) {
-  const base = { status: ROUTING_STATUS, path: rel, selector, chars };
-
-  if (Array.isArray(value)) return { ...base, length: value.length };
-
-  if (isObject(value)) {
-    const keys = Object.keys(value);
-
-    return keys.length > ROUTING_KEYS_MAX
-      ? { ...base, keys: keys.slice(0, ROUTING_KEYS_MAX), keysTruncated: true }
-      : { ...base, keys };
-  }
-
-  return base;
-}
-
 function decodeByArgs(args, value) {
   return (args.resolve || args.json !== undefined || args.outline || args.evidence) && isString(value);
 }
@@ -230,6 +180,11 @@ export function decodeReadValue(args, value) {
   } catch (error) {
     if (sniffed && !decodeByArgs(args, value)) return value;
 
-    throw new Error("JSON read failed for " + String(args.path ?? args.target ?? "resource") + jsonSelectorNote(args) + ": " + (error instanceof Error ? error.message : String(error)));
+    throw jsonReadError(args, error);
   }
 }
+
+function jsonReadError(args, error) {
+  const target = String(args.path ?? args.target ?? "resource");
+  return new Error("JSON read failed for " + target + jsonSelectorNote(args) + ": " + errorMessage(error));
+}

package/src/fs/check.js

@@ -145,7 +145,7 @@ function consumeLiteral(text, i, stack, prev, rust) {
     if (lifetime && text[end] !== "'") return { end, prev: "value" };
   }
 
-  if (c === '"' || c === "'" || c === "`") return consumeQuoted(text, i, stack);
+  if (['"', "'", "`"].includes(c)) return consumeQuoted(text, i, stack);
 
   if (c !== "/") return null;
 

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;
+}