pi-posthorse 0.10.2 → 0.10.4

package/src/notes.ts

@@ -1,6 +1,5 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
-import { readdir, realpath, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, normalize, sep } from "node:path";
+import { dirname } from "node:path";
 import { setImmediate } from "node:timers/promises";
 import {
 	formatSize,
@@ -12,13 +11,15 @@ import { Type } from "typebox";
 import { toolCards } from "../ui.ts";
 import {
 	MAX_PAGE_CHARS,
-	isRecord,
 	requireValue,
 	textResult,
 	type PolicyContext,
 	type TextResult,
 } from "./contracts.ts";
 import { isBinaryFile, notesDir, publishFile, readText } from "./files.ts";
+import { notePath, scopeDirectory } from "./note-scopes.ts";
+import type { NoteCall, NotesStore, SessionNotes } from "./note-store.ts";
+import { NoteDiscovery, noteLabel } from "./note-discovery.ts";
 import { excerpt, excerptAround } from "./message-text.ts";
 import type { PageAccess } from "./paging.ts";
 
@@ -28,135 +29,54 @@ export type NotesParams = {
 	readonly content?: string;
 	readonly query?: string;
 	readonly offset?: number;
+	readonly scope?: string;
 };
-type NoteFile = { readonly path: string; readonly size: number; readonly mtimeMs: number };
 type NoteHits = { readonly rows: string[]; readonly more: boolean; readonly skipped: number };
 /** Paged operations take a fresh policy snapshot after their filesystem awaits. */
 type NotesAccess = {
 	readonly host: () => PolicyContext;
 	readonly pages: PageAccess;
 	readonly signal: AbortSignal | undefined;
+	readonly call: NoteCall;
+	readonly discovery: NoteDiscovery;
 };
 /** Larger files are logs or evidence rather than notes; reading them would dominate a search. */
 const SEARCH_FILE_BYTES = 1024 * 1024;
 /** Overlapping reads cut a full search of a 212,000-file notes tree from 39 s to 14 s. */
 const SEARCH_BATCH = 16;
-/**
- * Maximum explicit `stat` calls overlapped per batch. On a 212,751-note tree, 16, 64 and 256 took
- * equal time within host noise. The walk enters one folder at a time, so this bounds our pending
- * `stat` calls at any depth. On filesystems that report unknown entry types, Node 24's
- * `readdir({ withFileTypes: true })` also issues its own `lstat` for every entry at once.
- */
-const WALK_BATCH = 64;
 /** Formatting all 212,751 rows of one listing at once stalled Pi for 156-163 ms. */
 const FORMAT_BATCH = 10_000;
 /** Search rescans up to the requested offset, so this also caps the matches one call keeps. */
 const SEARCH_OFFSET_LIMIT = 1_000_000;
-function safeJoin(dir: string, path: string): string {
-	const relative = normalize(path.replace(/^[/\\]+/, ""));
-	if (relative === ".." || relative.startsWith(`..${sep}`) || isAbsolute(relative)) {
-		throw new Error(`Invalid path "${path}": must stay inside the notes directory.`);
-	}
-	return join(dir, relative);
-}
-/** Like `statSync(path, { throwIfNoEntry: false })`: an entry deleted mid-walk is skipped. */
-async function statIfPresent(path: string) {
-	try {
-		return await stat(path);
-	} catch (error) {
-		if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
-			return;
-		}
-		throw error;
-	}
-}
-/** A folder's present entries in listing order. */
-async function* folderEntries(directory: string, signal: AbortSignal | undefined) {
-	const entries = await readdir(directory, { withFileTypes: true });
-	let start = 0;
-	while (start < entries.length) {
-		signal?.throwIfAborted();
-		const batch = entries.slice(start, start + WALK_BATCH);
-		const firstFolder = batch.findIndex(
-			(entry) => entry.isDirectory() || entry.isSymbolicLink(),
-		);
-		const paths = batch
-			.slice(0, firstFolder === -1 ? batch.length : firstFolder + 1)
-			.map((entry) => join(directory, entry.name));
-		// Stats overlap only up to the next entry that may be a folder.
-		// oxlint-disable-next-line no-await-in-loop
-		const infos = await Promise.all(paths.map(statIfPresent));
-		for (const [index, path] of paths.entries()) {
-			start += 1;
-			const info = infos[index];
-			if (info !== undefined) {
-				yield { path, info };
-			}
-			if (info?.isDirectory() === true) {
-				// Stat later entries only after this folder's subtree is walked, discarding any
-				// already taken, so entries removed meanwhile are skipped.
-				break;
-			}
-		}
-	}
-}
-/** Files depth-first in directory-listing order, yielding between filesystem calls. */
-async function walk(
-	directory: string,
-	signal: AbortSignal | undefined,
-	ancestors: readonly string[] = [],
-): Promise<NoteFile[]> {
-	signal?.throwIfAborted();
-	const root = await realpath(directory);
-	if (ancestors.includes(root)) {
-		return [];
-	}
-	const next = [...ancestors, root];
-	const files: NoteFile[] = [];
-	for await (const { path, info } of folderEntries(directory, signal)) {
-		if (info.isDirectory()) {
-			for (const file of await walk(path, signal, next)) {
-				files.push(file);
-			}
-		} else {
-			files.push({ path, size: info.size, mtimeMs: info.mtimeMs });
-		}
-	}
-	return files;
-}
-async function notesUnder(target: string, signal: AbortSignal | undefined): Promise<NoteFile[]> {
-	const info = await statIfPresent(target);
-	signal?.throwIfAborted();
-	if (info === undefined) {
-		return [];
-	}
-	const files = info.isDirectory()
-		? await walk(target, signal)
-		: [{ path: target, size: info.size, mtimeMs: info.mtimeMs }];
-	signal?.throwIfAborted();
-	return files.sort((a, b) => b.mtimeMs - a.mtimeMs);
-}
 async function listNotes(
-	dir: string,
+	session: SessionNotes,
 	params: NotesParams,
 	access: NotesAccess,
 ): Promise<TextResult> {
 	const { host, pages, signal } = access;
 	const folder = params.path;
-	const target = folder === undefined || folder === "" ? dir : safeJoin(dir, folder);
-	const files = await notesUnder(target, signal);
+	const inventory = await access.discovery.list(session, {
+		path: folder,
+		scope: params.scope,
+		signal,
+	});
+	const { files } = inventory;
+	const dir =
+		params.scope === undefined
+			? session.directory
+			: scopeDirectory(await session.selectScope(params.scope));
 	const rows: string[] = [];
 	for (let start = 0; start < files.length; start += FORMAT_BATCH) {
 		// Pi gets an event-loop turn before each batch of rows.
-		// oxlint-disable-next-line no-await-in-loop
 		await setImmediate();
 		signal?.throwIfAborted();
 		for (const file of files.slice(start, start + FORMAT_BATCH)) {
 			rows.push(
-				`${file.path.slice(dir.length + 1)}  ${formatSize(file.size)}  ${new Date(file.mtimeMs).toISOString().slice(0, 16)}Z`,
+				`${noteLabel(file, session, inventory.labeled)}  ${formatSize(file.size)}  ${new Date(file.mtimeMs).toISOString().slice(0, 16)}Z`,
 			);
 		}
 	}
+	rows.push(...inventory.notices);
 	return pages.notes(host(), {
 		rows,
 		offset: params.offset ?? 0,
@@ -166,19 +86,20 @@ async function listNotes(
 	});
 }
 async function readNote(
-	dir: string,
+	session: SessionNotes,
 	params: NotesParams,
 	access: NotesAccess,
 ): Promise<TextResult> {
 	const { pages } = access;
 	const relative = requireValue(params.path, "path", params.op);
-	const path = safeJoin(dir, relative);
+	const target = await session.read(relative, { scope: params.scope, signal: access.signal });
+	const path = target.path;
 	const info = statSync(path, { throwIfNoEntry: false });
 	if (info === undefined) {
 		throw new Error(`No note at ${relative}. Use op "list" to see available notes.`);
 	}
 	if (info.isDirectory()) {
-		return listNotes(dir, params, access);
+		return listNotes(session, { ...params, scope: scopeDirectory(target.address) }, access);
 	}
 	if (await isBinaryFile(path)) {
 		throw new Error(
@@ -190,7 +111,9 @@ async function readNote(
 	if (offset > 0 && offset >= text.length) {
 		throw new Error(`Offset ${offset} is past the end of ${relative} (${text.length} chars).`);
 	}
-	const header = `File: ${path}\n`;
+	const header = target.writable
+		? `File: ${path}\n`
+		: `Read-only live reference: notes read ${JSON.stringify({ scope: scopeDirectory(target.address), path: target.address.path })}\n`;
 	const host = access.host();
 	const chars = pages.size(host, { offset }) - header.length;
 	if (chars <= 0) {
@@ -204,6 +127,7 @@ async function readNote(
 		end < text.length
 			? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]`
 			: "";
+	session.record([{ ...target.address, kind: "read" }], access.call);
 	return pages.result(`${header}${text.slice(offset, end)}${more}`, [], {
 		kind: "note-read",
 		headerLength: header.length,
@@ -213,36 +137,64 @@ async function readNote(
 	});
 }
 async function writeNote(
-	dir: string,
+	session: SessionNotes,
 	params: NotesParams,
-	signal?: AbortSignal,
+	access: NotesAccess,
 ): Promise<TextResult> {
 	const relative = requireValue(params.path, "path", params.op);
 	const content = params.content;
 	if (content === undefined) {
 		throw new Error('"content" is required for op "write" (use "" to clear a note).');
 	}
-	const path = safeJoin(dir, relative);
-	mkdirSync(dirname(path), { recursive: true });
-	await withFileMutationQueue(path, () => publishFile(path, content, signal));
+	const path = notePath(session.binding, relative);
+	await withFileMutationQueue(path, async () => {
+		await session.prepareWrite();
+		mkdirSync(dirname(path), { recursive: true });
+		await publishFile(path, content, access.signal);
+		session.record(
+			[
+				{
+					root: session.binding.root,
+					scope: session.binding.scope,
+					path: relative,
+					kind: content === "" ? "clear" : "write",
+				},
+			],
+			access.call,
+		);
+	});
 	return textResult(`Wrote ${path}`, [], { kind: "note-write" });
 }
 async function appendNote(
-	dir: string,
+	session: SessionNotes,
 	params: NotesParams,
-	signal?: AbortSignal,
+	access: NotesAccess,
 ): Promise<TextResult> {
 	const relative = requireValue(params.path, "path", params.op);
 	const content = requireValue(params.content, "content", params.op);
-	const path = safeJoin(dir, relative);
-	mkdirSync(dirname(path), { recursive: true });
+	const path = notePath(session.binding, relative);
 	await withFileMutationQueue(path, async () => {
-		signal?.throwIfAborted();
+		access.signal?.throwIfAborted();
+		await session.adopt(relative, access.call);
+		access.signal?.throwIfAborted();
+		await session.prepareWrite();
+		mkdirSync(dirname(path), { recursive: true });
 		const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
 		const separator = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
 		// One O_APPEND write keeps records separate across processes. A racing
 		// unterminated write can at worst introduce an extra blank separator.
 		appendFileSync(path, `${separator}${content.replace(/\n?$/, "\n")}`);
+		session.record(
+			[
+				{
+					root: session.binding.root,
+					scope: session.binding.scope,
+					path: relative,
+					kind: "write",
+				},
+			],
+			access.call,
+		);
 	});
 	return textResult(`Appended to ${path}`, [], { kind: "note-append" });
 }
@@ -261,12 +213,14 @@ function matchingLines(name: string, text: string, query: string): string[] {
 }
 /** Matches in newest-first note order, stopping once they pass `limit` characters. */
 async function noteHits(
-	dir: string,
+	session: SessionNotes,
 	query: string,
-	limit: number,
-	signal?: AbortSignal,
+	options: { readonly limit: number; readonly scope: string | undefined },
+	access: NotesAccess,
 ): Promise<NoteHits> {
-	const notes = await notesUnder(dir, signal);
+	const { signal } = access;
+	const inventory = await access.discovery.list(session, { scope: options.scope, signal });
+	const notes = inventory.files;
 	const rows: string[] = [];
 	let length = -1;
 	let skipped = 0;
@@ -274,16 +228,15 @@ async function noteHits(
 		// A batch of notes over 1 MiB reads nothing that would notice cancellation.
 		signal?.throwIfAborted();
 		// Batches keep note order, so a search stops within one batch of the page limit.
-		// oxlint-disable-next-line no-await-in-loop
 		const batch = await Promise.all(
 			notes
 				.slice(start, start + SEARCH_BATCH)
-				.map(async ({ path, size }) =>
-					size > SEARCH_FILE_BYTES
+				.map(async (note) =>
+					note.size > SEARCH_FILE_BYTES
 						? undefined
 						: matchingLines(
-								path.slice(dir.length + 1),
-								(await readText(path, signal)) ?? "",
+								noteLabel(note, session, inventory.labeled),
+								(await readText(note.path, signal)) ?? "",
 								query,
 							),
 				),
@@ -292,15 +245,15 @@ async function noteHits(
 		for (const row of batch.flatMap((found) => found ?? [])) {
 			rows.push(row);
 			length += row.length + 1;
-			if (length > limit) {
+			if (length > options.limit) {
 				return { rows, more: true, skipped };
 			}
 		}
 	}
-	return { rows, more: false, skipped };
+	return { rows: [...rows, ...inventory.notices], more: false, skipped };
 }
 async function searchNotes(
-	dir: string,
+	session: SessionNotes,
 	params: NotesParams,
 	access: NotesAccess,
 ): Promise<TextResult> {
@@ -313,7 +266,12 @@ async function searchNotes(
 			`Notes search pages end before offset ${SEARCH_OFFSET_LIMIT}; search for something more specific.`,
 		);
 	}
-	const hits = await noteHits(dir, query.toLowerCase(), offset + MAX_PAGE_CHARS, access.signal);
+	const hits = await noteHits(
+		session,
+		query.toLowerCase(),
+		{ limit: offset + MAX_PAGE_CHARS, scope: params.scope },
+		access,
+	);
 	const skipped = hits.skipped === 1 ? "1 note" : `${hits.skipped} notes`;
 	return pages.notes(host(), {
 		rows: hits.rows,
@@ -328,14 +286,16 @@ export function registerNotes(
 	pi: ExtensionAPI,
 	policy: (ctx: ExtensionContext) => PolicyContext,
 	pages: PageAccess,
+	store: NotesStore,
 ): void {
+	const discovery = new NoteDiscovery();
 	pi.registerTool({
 		name: "notes",
 		label: "Notes",
 		...toolCards("notes"),
 		description:
-			"Durable notes shared across Git worktrees and context resets. Ops: list (newest first, size/date; optional folder), read, search (case-insensitive text), write (replace; empty clears), append (one newline-terminated record). list/read/search are paged; continue with the returned offset. list shows the absolute notes directory; read shows the absolute file path. Prefer available file-editing tools for changed sections of one concise current-state note; write for creation or substantial restructuring. Link fuller evidence instead of copying them.",
-		promptSnippet: "save and recall durable state that survives context resets",
+			"Durable notes across Git worktrees and context resets. Forks own private copies of selected-branch notes. Ops: list (newest first, size/date; optional folder), read, search (case-insensitive text), write (replace; empty clears), append (one newline-terminated record). list/search discover project-wide notes with scope selectors; use scope for read-only comparisons or a single-scope view. Omit scope for current notes and live references. list/read/search are paged; continue with the returned offset. list shows the current writable directory; current-file reads show an editable path, foreign reads a read-only reference. Edit the returned current path for small changes. A blocked foreign edit may have created a private copy: read that copy before retrying. Append adopts unowned references without losing their text. Keep one concise current-state note and link fuller evidence.",
+		promptSnippet: "save and recall durable state with private notes for forks",
 		parameters: Type.Object({
 			op: Type.Union(
 				[
@@ -350,6 +310,12 @@ export function registerNotes(
 			path: Type.Optional(
 				Type.String({ description: "Note or folder path relative to the notes directory" }),
 			),
+			scope: Type.Optional(
+				Type.String({
+					description:
+						"Absolute scope selector from list/search; only for read/list/search. Omit for current notes and project-wide discovery.",
+				}),
+			),
 			content: Type.Optional(
 				Type.String({ description: "Full file content (write) or text to add (append)" }),
 			),
@@ -364,21 +330,36 @@ export function registerNotes(
 			),
 		}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(_id, params, signal, _onUpdate, ctx) {
-			const dir = notesDir(ctx.cwd);
-			const access: NotesAccess = { host: () => policy(ctx), pages, signal };
+			// Migrate newly returned legacy package notes without changing this session’s binding.
+			notesDir(ctx.cwd);
+			const session = await store.get(ctx);
+			if (params.scope !== undefined && (params.op === "write" || params.op === "append")) {
+				throw new Error(
+					"scope is only valid for read/list/search; writes use this session’s notes scope.",
+				);
+			}
+			const access: NotesAccess = {
+				host: () => policy(ctx),
+				pages,
+				signal,
+				call: session.call(_id),
+				discovery,
+			};
 			switch (params.op) {
 				case "list":
-					return listNotes(dir, params, access);
+					return listNotes(session, params, access);
 				case "read":
-					return readNote(dir, params, access);
+					return params.path === "."
+						? listNotes(session, params, access)
+						: readNote(session, params, access);
 				case "write":
-					return writeNote(dir, params, signal);
+					return writeNote(session, params, access);
 				case "append":
-					return appendNote(dir, params, signal);
+					return appendNote(session, params, access);
 				case "search":
-					return searchNotes(dir, params, access);
+					return searchNotes(session, params, access);
 			}
 		},
 	});

package/src/paging.ts

@@ -14,8 +14,8 @@ import {
 export type PageRequest = {
 	readonly offset: number;
 	readonly imageCount?: number;
-	readonly cursor?: string;
-	readonly imageOffset?: number;
+	readonly cursor?: string | undefined;
+	readonly imageOffset?: number | undefined;
 };
 export type NotesPage = {
 	readonly rows: readonly string[];