pi-supernova 0.10.2 → 0.11.0

package/src/adapters/read-indexed.js

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {isString} from '../shared/decode.js';
+
+function contained(root, target) {
+  const rel = path.relative(root,target);
+
+  return rel !== '..' && !rel.startsWith('..'+path.sep) && !path.isAbsolute(rel);
+}
+
+function validHintPath(hint) {
+  return isString(hint?.path) && !!hint.path && hint.path.isWellFormed() && !hint.path.includes('\0');
+}
+
+function validHintRange(hint) {
+  return Number.isSafeInteger(hint.startLine) && Number.isSafeInteger(hint.endLine) &&
+    hint.startLine >= 1 && hint.endLine >= hint.startLine && hint.endLine-hint.startLine < 40;
+}
+
+function assertScope(root, scope, target, message) {
+  if (!contained(root,target) || !contained(scope,target)) throw new Error(message);
+}
+
+async function resolveHint(hint, cwd, scope, root, directory) {
+  if (!validHintPath(hint) || !validHintRange(hint)) throw new Error('invalid indexed context range');
+  let target = path.resolve(cwd,hint.path);
+
+  if (!contained(cwd,target) || !contained(scope,target)) {
+    // Providers may spell the same workspace with its realpath. Admit only
+    // that canonical scope, then restore the caller's logical path for reads.
+    assertScope(root,directory,target,'indexed context is outside the requested workspace scope');
+    target = path.resolve(scope,path.relative(directory,target));
+  }
+
+  const real = await fs.realpath(target);
+  assertScope(root,directory,real,'indexed context escapes workspace scope');
+
+  return {path:target,line:hint.startLine,endLine:hint.endLine};
+}
+
+function contextHints(response) {
+  const details = response?.details;
+
+  if (response?.isError || details?.code !== 'OK' || details.timedOut) throw new Error('indexed search incomplete or unavailable; retry or omit indexed:true');
+  const hints = details.contexts;
+
+  if (!Array.isArray(hints) || hints.length > 8) throw new Error('invalid indexed context metadata');
+
+  return {details,hints};
+}
+
+function sourceSelection(candidates, details, cwd) {
+  if (candidates.length === 1 && (!details.truncated || details.contextSelectionComplete === true)) return {status:'found',...candidates[0]};
+
+  return {status:candidates.length ? 'ambiguous' : 'not_found',path:null,line:null,context:candidates.map(c=>({...c,path:path.relative(cwd,c.path)})),message:'Narrow the indexed query or use an explicit path.'};
+}
+
+// Provider metadata is only a locator. The owned reader captures bytes and its
+// CAS baseline itself; rendered text and sourceVersion are never trusted.
+export async function indexedSource(hooks, query, cwd, scope, signal) {
+  if (!hooks.indexedSearch) throw new Error('indexed read requires a callable isearch');
+  signal?.throwIfAborted();
+  const response = await hooks.indexedSearch({query,path:path.relative(cwd,scope)||'.',withContext:true,limit:2,budgetChars:8000});
+  signal?.throwIfAborted();
+  const {details,hints} = contextHints(response);
+  const root = await fs.realpath(cwd), directory = await fs.realpath(scope);
+  const candidates = [];
+
+  for (const hint of hints) candidates.push(await resolveHint(hint,cwd,scope,root,directory));
+
+  return sourceSelection(candidates,details,cwd);
+}

package/src/adapters/read-text.js

@@ -18,38 +18,51 @@ export function createTextReader(ctx, readWindow) {
   async function loadText(targetPath, params, query, signal) {
     const explicit = isNumber(params.offset) || isNumber(params.limit);
     const windowed = explicit && params.complete !== true && !isString(params.about) && !isString(query);
+
     if (!windowed) {
       // Whole reads hash the bytes already loaded. Do not read once for a window
       // and open/hash the entire file a second time just to return the same text.
       return {text:await vfs.read(targetPath,{maxBytes:TEXT_MAX_BYTES}),windowed:false};
     }
+
     const start = isNumber(params.offset) ? Math.max(1,Math.floor(params.offset)) : 1;
     const count = isNumber(params.limit) ? Math.max(0,Math.floor(params.limit)) : undefined;
     const window = await readWindow(targetPath,start,count,TEXT_MAX_BYTES,signal);
+
     if (!window.satisfied) throw new Error("read window exceeds " + TEXT_MAX_BYTES + " bytes: " + targetPath + "; request fewer lines or use a bounded parser through bash");
+
     return {text:window.text,windowed:true,windowWhole:window.whole};
   }
 
   async function maybeOutline(cwd, rel, targetPath, text, params, entry) {
     if (!isString(params.about)) return null;
-    const outline = entry && outlineFile(entry,rel,params.about,outlineOptions(params,await referenceFinder(cwd,targetPath),config));
+    // Focused text has no declarations and cannot use lexical caller hints.
+    // Do not make this file-local read wait for unrelated workspace discovery.
+    const references = entry && WorkspaceIndex.spansOf(entry).length ? await referenceFinder(cwd,targetPath) : null;
+    const outline = entry && outlineFile(entry,rel,params.about,outlineOptions(params,references,config));
+
     if (!outline) return null;
     recordOutlineOrigins(ledger,rel,outline.text);
+
     return readResult(outline.text,{path:targetPath,outline:true,expanded:outline.expanded,declarations:outline.declarations});
   }
 
   function resolveSpan(entry, sourceLine, query, params) {
     if (!params.resolve || !isString(query) || !entry) return {offset:params.offset,limit:params.limit,viewComplete:undefined};
     const span=pickSpan(WorkspaceIndex.spansOf(entry),{line:sourceLine,name:query});
+
     if (!span) return {offset:params.offset,limit:params.limit,viewComplete:undefined};
     const spanLines=span.end-span.start+1;
     const limit=isNumber(params.limit) ? Math.min(params.limit,spanLines) : spanLines;
+
     return {offset:span.start,limit,viewComplete:limit>=spanLines};
   }
 
   function textFileResult(rel,targetPath,loaded,span,sliced,firstLine,explicit) {
-    const lines=sliced.length<=LARGE_FILE_BYTES ? sourceLines(sliced) : null;
+    const lines=ledger.window!==0 && sliced.length<=LARGE_FILE_BYTES ? sourceLines(sliced) : null;
+
     if (lines) ledger.recordOrigin(rel,firstLine,lines,explicit);
+
     return readResult(sliced,{path:targetPath,firstLine,lastLine:firstLine+(lines?.length ?? contentLineInfo(sliced).count)-1,
       sourceChars:sliced.length,complete:loaded.windowed ? loaded.windowWhole : sliced===loaded.text,viewComplete:span.viewComplete});
   }
@@ -60,12 +73,16 @@ export function createTextReader(ctx, readWindow) {
     index.touch(rel);
     const entry=needsSourceIndex(params,query) ? WorkspaceIndex.fromText(targetPath,loaded.text) : null;
     const outlined=await maybeOutline(getCwd(),rel,targetPath,loaded.text,params,entry);
+
     if (outlined) return outlined;
     const span=resolveSpan(entry,sourceLine,query,params);
     const firstLine=isNumber(span.offset) ? Math.max(1,Math.floor(span.offset)) : 1;
     const sliced=loaded.windowed ? loaded.text : sliceLinesRaw(loaded.text,span.offset,span.limit);
+
     if (params.complete===true && sliced!==loaded.text) throw new Error("complete:true requires the whole file; remove offset/limit for " + rel);
+
     return textFileResult(rel,targetPath,loaded,span,sliced,firstLine,explicit);
   }
+
   return readTextFile;
 }

package/src/adapters/read.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
-import { readResult, asReadResult, READ_VALUE, READ_BYTES, MAX_READ_VALUE_BYTES } from "../shared/result.js";
+import { readResult, asReadResult, READ_VALUE, READ_BYTES, READ_FILES, MAX_READ_VALUE_BYTES } from "../shared/result.js";
 import { extractStructuralSurface } from "../context/surface.js";
 import { executeSnap, tokenizeQuery } from "../context/snap.js";
 import { selectEvidence } from "../context/evidence.js";
@@ -16,6 +16,7 @@ import { projectJson } from "./read-json.js";
 import { createImageReader } from "./read-image.js";
 import { createTextReader } from "./read-text.js";
 import { createFocusedReader } from "./read-focus.js";
+import { indexedSource } from "./read-indexed.js";
 
 export function createRead(ctx) {
   const { getCwd, vfs, config, index, ledger, hooks, reads } = ctx;
@@ -29,19 +30,30 @@ export function createRead(ctx) {
     params = { ...params, resolve: params.resolve !== false };
     const cwd = getCwd();
 
+    const pendingPaths = await vfs.getOverlayPaths(searchDir);
+
+    if (params.indexed && pendingPaths.length === 0) {
+      const hint = await indexedSource(hooks, query, cwd, searchDir, signal);
+
+      if (hint.status !== "found") return readResult(hint, {isSnap:true});
+      const opened = await readFile(hint.path, {resolve:true,offset:hint.line,limit:hint.endLine-hint.line+1}, hint.line, relativeSlash(cwd,hint.path), undefined, signal);
+
+      return openedSource({...hint,path:relativeSlash(cwd,hint.path)}, params, opened.content[0], opened.details);
+    }
+
     const includeHidden = path.relative(cwd, searchDir).split(path.sep)
       .some(segment => segment.startsWith(".") && segment.length > 1);
 
     const result = await executeSnap({ query, searchDir, root: cwd, includeHidden,
       pathContext: { frecency: index.frecency, currentFile: index.lastTouched },
-      overlayText: p => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), signal });
+      overlayText: p => vfs.getOverlay(p), pendingPaths, signal });
 
     return openSource(result, params, signal, undefined, query);
   }
 
   async function sourceIsBounded(target, query, params) {
     if (!isString(query) || params.complete === true) return false;
-    const overlay = vfs.getOverlay(target);
+    const overlay = await vfs.getOverlay(target);
 
     if (overlay !== undefined) return Buffer.byteLength(overlay, "utf8") > 512 * 1024;
 
@@ -111,12 +123,13 @@ export function createRead(ctx) {
       raw.isError = true;
     }
 
+    for (const file of raw[READ_FILES] ?? []) state.files.add(file);
     state.sourcePaths[index] = raw.details?.sourcePath;
     await addBatchItem(state,index,raw,onItem);
   }
 
   async function readBatch(params, signal, onItem) {
-    const state = {items:[],sourcePaths:[],errors:Array(params.path.length).fill(null),bytes:0,streamed:false};
+    const state = {items:[],sourcePaths:[],files:new Set(),errors:Array(params.path.length).fill(null),bytes:0,streamed:false};
 
     // Delivery/acknowledgement stays inside the same eight-operation scheduler
     // slot as I/O. A busy guest cannot cause unbounded host/message-queue buffering.
@@ -136,6 +149,8 @@ export function createRead(ctx) {
 
     response.isError = params._independent!==true && state.errors.some(Boolean);
 
+    if (!state.streamed) response[READ_FILES] = [...state.files];
+
     return response;
   }
 
@@ -152,19 +167,47 @@ export function createRead(ctx) {
     params = normalizeRead({ ...params, path: targetParam });
     const existing = needsProbe(params) ? await probeExistingPath(cwd, params.path, vfs) : null;
     const cls = classifyRead(params, existing);
+    const scope = await scopeForRead(params, cwd, cls, signal);
+    const staged = await vfs.getOverlay(scope) !== undefined;
+    const revision = await vfs.readRevision(scope);
+
+    try {
+      const value = await readSingleUnchecked(params, cwd, cls, scope, signal);
+
+      if (!staged) await vfs.assertReadCommitted(revision);
+      const source = value.details;
+
+      // Only the native text reader supplies these fields. JSON documents,
+      // directories, outlines and empty windows are not text-open receipts.
+      if (source?.sourceChars > 0 && isString(source.path) && path.isAbsolute(source.path) && await vfs.getOverlay(source.path) === undefined) value[READ_FILES] = [source.path];
+
+      return value;
+    } finally { vfs.releaseRead(revision); }
+  }
+
+  // Classify once so the observation guard follows the same path/scope as dispatch.
+  async function scopeForRead(params, cwd, cls, signal) {
+    if (cls.kind === "session") return resolveSessionResource(params.path, signal, hooks);
+
+    if (cls.kind === "snap") return cls.existing?.directory ? cls.existing.path : cls.scoped ? resolveReadPath(cwd, params.path) : cwd;
+
+    if (cls.kind === "evidence") return cls.scope ? resolveReadPath(cwd, cls.scope) : cwd;
+
+    return cls.existing?.path ?? (isString(params.path) ? resolveReadPath(cwd, params.path) : cwd);
+  }
+
+  async function readSingleUnchecked(params, cwd, cls, scope, signal) {
+    if (params.indexed && cls.kind !== "snap") throw new Error("indexed:true requires a source query");
     const relOf = hit => relativeSlash(cwd, hit.path);
-    const snapScope = (scoped, hit) => hit?.directory ? hit.path : scoped ? resolveReadPath(cwd, params.path) : cwd;
 
     const kinds = {
       session: async () => {
-        const target = await resolveSessionResource(params.path, signal, hooks);
-
         return params.resolve
-          ? openSource({ status: "found", path: params.path, line: params.offset ?? 1 }, params, signal, target)
-          : readFile(target, params, undefined, params.path, undefined, signal);
+          ? openSource({ status: "found", path: params.path, line: params.offset ?? 1 }, params, signal, scope)
+          : readFile(scope, params, undefined, params.path, undefined, signal);
       },
       evidence: () => evidence({ ...params, query: cls.query, path: cls.scope }, signal),
-      snap: () => sourceRead(cls.query, snapScope(cls.scoped, cls.existing), signal, params),
+      snap: () => sourceRead(cls.query, scope, signal, params),
       outline: () => surface({ path: params.path }, signal),
       focus: () => focusAbout({ rel: relOf(cls.existing), about: cls.about, overlay: cls.existing.overlay, targetPath: cls.existing.path, signal }),
       open: () => openSource({ status: "found", path: relOf(cls.existing), line: params.offset ?? 1 }, params, signal),
@@ -223,7 +266,7 @@ export function createRead(ctx) {
         root: cwd,
         includeHidden,
         overlayText: (p) => vfs.getOverlay(p),
-        pendingPaths: vfs.getOverlayPaths(),
+        pendingPaths: await vfs.getOverlayPaths(cwd),
         signal,
       });
 
@@ -249,7 +292,7 @@ export function createRead(ctx) {
 
       if (signal?.aborted) throw new Error("aborted");
       const searchDir = params?.path ? await resolveWorkspacePath(cwd, params.path, "evidence", true) : cwd;
-      const res = await selectEvidence({ query: params.query, root: cwd, searchDir, index, overlayText: (p) => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), options: evidenceOptions(params) });
+      const res = await selectEvidence({ query: params.query, root: cwd, searchDir, index, overlayText: (p) => vfs.getOverlay(p), pendingPaths: await vfs.getOverlayPaths(searchDir), options: evidenceOptions(params) });
 
       for (const span of res.spans) ledger.recordOrigin(span.path, span.lines[0], span.text.split("\n"));
 
@@ -258,7 +301,8 @@ export function createRead(ctx) {
 
   async function surface(params, signal) {
       const cwd = getCwd();
-      const target = await resolveWorkspacePath(cwd, params?.path, "surface", false);
+      // Outlines are read-only, like text reads; mutations still require workspace admission.
+      const target = resolveReadPath(cwd, params?.path);
 
       if (signal?.aborted) throw new Error("aborted");
       const text = await vfs.read(target, { maxBytes: 2 * 1024 * 1024 });

package/src/adapters/refs.js

@@ -1,4 +1,5 @@
 import { relativeSlash } from "../fs/workspace.js";
+import { overlaySnapshot } from "../context/search-files.js";
 
 export function outlineOptions(params, references, config) {
   const options = { references };
@@ -17,24 +18,33 @@ export function recordOutlineOrigins(ledger, rel, outlineText) {
   }
 }
 
-/** Where else a name appears (declaration line excluded), for outlines and edit results. */
+/** Where else an expanded outline name appears, excluding its own declaration. */
 export function createReferenceFinder(index, vfs) {
   return async function referenceFinder(cwd, targetPath) {
     let files;
 
-    try { files = [...new Set([...await index.files(cwd), ...vfs.getOverlayPaths()])]; }
+    try { files = [...new Set([...await index.files(cwd), ...await vfs.getOverlayPaths(cwd)])]; }
     catch { return () => []; }
 
     if (!index.canScan(files)) return () => [];
+    const overlayText = await overlaySnapshot(files, file => vfs.getOverlay(file));
+    const targetRel = relativeSlash(await vfs.resolvePath(cwd), await vfs.resolvePath(targetPath));
 
-    return (name, excludeLine) => {
+    // Each outline supplies its expanded names together. The row snapshot is
+    // call-local; the existing index still owns file validation and body caching.
+    let rows;
+
+    return (name, excludeLine, names) => {
       if (!name || name.length < 3) return [];
       const escaped = name.replace(/[$]/g, (c) => "\\" + c);
-      const regex = new RegExp("\\b" + escaped + "\\b");
+      // JavaScript identifiers include $, which is not a regex word character.
+      const regex = new RegExp("(?<![\\w$])" + escaped + "(?![\\w$])");
+
+      rows ??= index.grepRows(files, new RegExp("(?<![\\w$])(?:" + names.filter(name => name.length >= 3)
+        .map(name => name.replaceAll("$", "\\$")).join("|") + ")(?![\\w$])"), cwd, overlayText);
 
-      return index
-        .grepRows(files, regex, cwd, file => vfs.getOverlay(file))
-        .filter((r) => !(r.line === excludeLine && r.rel === relativeSlash(cwd, targetPath)))
+      return rows
+        .filter((r) => regex.test(r.text) && !(r.line === excludeLine && r.rel === targetRel))
         .map((r) => r.rel + ":" + r.line);
     };
   };

package/src/adapters/write.js

@@ -50,6 +50,7 @@ export function createWrite(ctx) {
     const unknown = Object.keys(params ?? {}).filter(key => !WRITE_OPTION_KEYS.includes(key));
 
     if (unknown.length) throw new Error("write does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are " + WRITE_OPTION_KEYS.join(", "));
+
     if (!isString(params?.content)) throw new Error("write requires string content");
     assertWriteAppendFlag(params.append);
     assertWriteArtifactsFlag(params.allowReadArtifacts);
@@ -62,21 +63,15 @@ export function createWrite(ctx) {
     return content;
   }
 
-  async function applyAppend(target, content, snap) {
-    const { overlay, existingBytes } = snap;
-
-    if (existingBytes > WRITE_APPEND_MAX_READ_BYTES) throw new Error("append input exceeds " + WRITE_APPEND_MAX_READ_BYTES + " bytes; stream it with bash redirection instead");
-    // Append needs the real content: the diff snapshot may be a lossy decode, and
-    // concatenating that would silently corrupt a non-UTF-8 file.
-    let prevText;
-
-    try { prevText = overlay !== undefined ? overlay : await vfs.read(target, { maxBytes: WRITE_APPEND_MAX_READ_BYTES, preserveRead: true }); }
+  async function readAppendBase(target) {
+    // Append bytes and receipt text share one strict, bounded read. The VFS
+    // supplies staged overlays and preserves any earlier read's CAS baseline.
+    try { return await vfs.read(target, { maxBytes: WRITE_APPEND_MAX_READ_BYTES, label: "append input", preserveRead: true }); }
     catch (error) {
       if (error.code !== "ENOENT") throw error;
-      prevText = "";
-    }
 
-    return { content: prevText + content, prevText, removedLines: undefined };
+      return "";
+    }
   }
 
   async function write(params, signal) {
@@ -85,15 +80,13 @@ export function createWrite(ctx) {
 
       if (signal?.aborted) throw new Error("aborted");
       let content = assertWriteParams(params);
-      const snap = await writeSnapshot(vfs, target, signal);
-      let { previous: prevText, removedLines } = snap;
-
-      if (params.append === true) {
-        const appended = await applyAppend(target, content, snap);
-        content = appended.content;
-        prevText = appended.prevText;
-        removedLines = appended.removedLines;
-      }
+      const appending = params.append === true;
+
+      const { previous: prevText, removedLines } = appending
+        ? { previous: await readAppendBase(target) }
+        : await writeSnapshot(vfs, target, signal);
+
+      if (appending) content = prevText + content;
 
       const { speculative } = await vfs.write(target, content);
       index.touch(relativeSlash(cwd, target));