pi-posthorse 0.10.2 → 0.10.4

package/src/note-snapshots.ts

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import {
+	copyFile,
+	lstat,
+	mkdir,
+	mkdtemp,
+	open,
+	readFile,
+	rename,
+	rm,
+	stat,
+	utimes,
+	writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "./contracts.ts";
+import { publishFile } from "./files.ts";
+import {
+	notePath,
+	parseBinding,
+	sameOwner,
+	scopeDirectory,
+	type ForkBinding,
+	type NoteAddress,
+	type NoteBinding,
+	type NoteIdentity,
+	type NoteSeed,
+} from "./note-scopes.ts";
+
+export function fileIdentity(info: NoteIdentity): NoteIdentity {
+	return {
+		size: info.size,
+		mtimeMs: info.mtimeMs,
+		ctimeMs: info.ctimeMs,
+		ino: info.ino,
+		dev: info.dev,
+	};
+}
+export function sameIdentity(left: NoteIdentity, right: NoteIdentity): boolean {
+	return (
+		left.size === right.size &&
+		left.mtimeMs === right.mtimeMs &&
+		left.ctimeMs === right.ctimeMs &&
+		left.ino === right.ino &&
+		left.dev === right.dev
+	);
+}
+export async function fileDigest(path: string, signal?: AbortSignal): Promise<string> {
+	const file = await open(path, "r");
+	try {
+		const hash = createHash("sha256");
+		for await (const chunk of file.createReadStream({ autoClose: false })) {
+			signal?.throwIfAborted();
+			const bytes: unknown = chunk;
+			if (!(bytes instanceof Uint8Array)) {
+				throw new TypeError("Expected binary file data.");
+			}
+			hash.update(bytes);
+		}
+		return hash.digest("hex");
+	} finally {
+		await file.close();
+	}
+}
+export async function readManifest(directory: string): Promise<ForkBinding | undefined> {
+	try {
+		const raw: unknown = JSON.parse(
+			await readFile(join(dirname(directory), "manifest.json"), "utf8"),
+		);
+		const binding = parseBinding(raw);
+		return binding?.kind === "fork" && scopeDirectory(binding) === directory
+			? binding
+			: undefined;
+	} catch (error) {
+		if (
+			error instanceof SyntaxError ||
+			(isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+		) {
+			return;
+		}
+		throw error;
+	}
+}
+export type SnapshotNote = {
+	readonly path: string;
+	readonly source: NoteAddress;
+	readonly lineage: NoteAddress;
+	readonly anchors: readonly string[];
+};
+async function copyNote(note: SnapshotNote, destination: string): Promise<NoteSeed> {
+	const source = notePath(note.source, note.source.path);
+	const before = await stat(source);
+	await mkdir(dirname(destination), { recursive: true });
+	await copyFile(source, destination, constants.COPYFILE_EXCL);
+	const after = await stat(source);
+	if (!sameIdentity(before, after)) {
+		throw new Error(`Source note changed during snapshot: ${source}. Retry initialization.`);
+	}
+	await utimes(destination, before.atimeMs / 1000, before.mtimeMs / 1000);
+	const digest = await fileDigest(destination);
+	return { ...note, digest, identity: fileIdentity(await stat(destination)) };
+}
+/** Publication is the ownership boundary. An existing unrelated directory is never overwritten. */
+export async function snapshot(
+	binding: ForkBinding,
+	notes: readonly SnapshotNote[],
+): Promise<ForkBinding> {
+	const directory = scopeDirectory(binding);
+	const existing = await readManifest(directory);
+	if (existing !== undefined && sameOwner(existing.owner, binding.owner)) {
+		return existing;
+	}
+	const container = dirname(directory);
+	if (
+		await lstat(container).catch((error: unknown) => {
+			if (isRecord(error) && error.code === "ENOENT") {
+				return;
+			}
+			throw error;
+		})
+	) {
+		throw new Error(`Incomplete notes snapshot: preserving unexpected data at ${container}.`);
+	}
+	if (notes.length === 0) {
+		return binding;
+	}
+	await mkdir(dirname(container), { recursive: true });
+	const stage = await mkdtemp(join(dirname(container), ".staging-"));
+	try {
+		const seeds: NoteSeed[] = [];
+		for (const note of notes) {
+			// Keep each file's identity and digest paired with the bytes actually copied.
+			seeds.push(await copyNote(note, notePath({ root: stage, scope: "notes" }, note.path)));
+		}
+		const complete: ForkBinding = { ...binding, seeds };
+		await writeFile(join(stage, "manifest.json"), JSON.stringify(complete), { flag: "wx" });
+		await rename(stage, container);
+		return complete;
+	} catch (error) {
+		throw new Error(
+			`Incomplete notes snapshot for ${directory}: ${error instanceof Error ? error.message : String(error)}`,
+			{ cause: error },
+		);
+	} finally {
+		await rm(stage, { recursive: true, force: true });
+	}
+}
+/** Called inside the destination's native mutation queue, never queues that path recursively. */
+export async function adoptNote(binding: NoteBinding, note: SnapshotNote): Promise<NoteSeed> {
+	return copyNote(note, notePath(binding, note.path));
+}
+/** Empty initialized scopes publish their manifest when the first note is created. */
+export async function ensureManifest(binding: NoteBinding): Promise<void> {
+	if (binding.kind !== "fork") {
+		return;
+	}
+	const path = join(dirname(scopeDirectory(binding)), "manifest.json");
+	await mkdir(dirname(path), { recursive: true });
+	try {
+		await writeFile(path, JSON.stringify(binding), { flag: "wx" });
+	} catch (error) {
+		if (!isRecord(error) || error.code !== "EEXIST") {
+			throw error;
+		}
+		const existing = await readManifest(scopeDirectory(binding));
+		if (existing === undefined || !sameOwner(existing.owner, binding.owner)) {
+			throw new Error(`Preserving unexpected notes manifest at ${path}.`, { cause: error });
+		}
+	}
+}
+
+export async function saveAdoption(binding: NoteBinding, seed: NoteSeed): Promise<void> {
+	if (binding.kind !== "fork") {
+		return;
+	}
+	const path = join(dirname(scopeDirectory(binding)), "manifest.json");
+	await withFileMutationQueue(path, async () => {
+		await ensureManifest(binding);
+		const previous = (await readManifest(scopeDirectory(binding))) ?? binding;
+		const seeds = [...previous.seeds.filter((item) => item.path !== seed.path), seed];
+		await publishFile(path, JSON.stringify({ ...previous, seeds }));
+	});
+}

package/src/note-store.ts

@@ -0,0 +1,278 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+	withFileMutationQueue,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { EntryLike, ProjectedEntry } from "./contracts.ts";
+import { notesDir } from "./files.ts";
+import { adoptNote, ensureManifest, readManifest, saveAdoption } from "./note-snapshots.ts";
+import {
+	loadNotesBinding,
+	resolveReference,
+	sourceEntries,
+	type NoteSource,
+} from "./note-provenance.ts";
+import {
+	NOTES_BINDING,
+	NOTES_TOUCH,
+	bindingsOf,
+	canonicalPath,
+	inside,
+	notePath,
+	noteRelative,
+	ownedPaths,
+	sameOwner,
+	sameScope,
+	scopeDirectory,
+	type NoteAddress,
+	type NoteBinding,
+	type NoteScope,
+	type NoteTouchRecord,
+} from "./note-scopes.ts";
+import type { NotesRecovery } from "./note-evidence.ts";
+
+type NotesManager = ExtensionContext["sessionManager"];
+export type NoteCall = { readonly id: string; readonly rootId: string };
+export type NoteRead = {
+	readonly address: NoteAddress;
+	readonly path: string;
+	readonly writable: boolean;
+};
+export class SessionNotes {
+	readonly #pi: ExtensionAPI;
+	readonly binding: NoteBinding;
+	readonly #manager: NotesManager;
+	readonly #source: NoteSource;
+	readonly #owned: Set<string>;
+	readonly scopes: readonly NoteScope[];
+	readonly #calls = new Map<string, string>();
+	readonly #revisions = new Map<string, number>();
+	constructor(pi: ExtensionAPI, binding: NoteBinding, manager: NotesManager, source: NoteSource) {
+		this.#pi = pi;
+		this.binding = binding;
+		this.#manager = manager;
+		this.#source = source;
+		this.#owned = ownedPaths(binding, manager.getEntries());
+		this.scopes = [
+			binding,
+			{ root: binding.root, scope: "" },
+			...(binding.kind === "fork" && binding.source !== null ? [binding.source] : []),
+			...bindingsOf([...manager.getEntries(), ...source.entries]),
+		];
+	}
+	get directory(): string {
+		return scopeDirectory(this.binding);
+	}
+	get branch(): readonly EntryLike[] {
+		return this.#manager.getBranch();
+	}
+	get projection(): readonly ProjectedEntry[] {
+		return this.#manager.buildSessionProjection().entries;
+	}
+	revision(path: string): number {
+		return this.#revisions.get(canonicalPath(path)) ?? 0;
+	}
+	get recovery(): NotesRecovery {
+		return { binding: this.binding, entries: this.#manager.getEntries() };
+	}
+	startCall(id: string, parent: string | undefined): NoteCall {
+		const rootId = parent === undefined ? id : (this.#calls.get(parent) ?? parent);
+		this.#calls.set(id, rootId);
+		return { id, rootId };
+	}
+	finishCall(id: string): void {
+		this.#calls.delete(id);
+	}
+	call(id: string): NoteCall {
+		return { id, rootId: this.#calls.get(id) ?? id };
+	}
+	owns(path: string): boolean {
+		return (
+			this.binding.kind === "project" ||
+			this.#owned.has(path) ||
+			existsSync(notePath(this.binding, path))
+		);
+	}
+	record(files: NoteTouchRecord["files"], call: NoteCall): void {
+		if (files.length === 0) {
+			return;
+		}
+		for (const file of files) {
+			if (file.kind !== "read" && sameScope(file, this.binding)) {
+				this.#owned.add(file.path);
+				const path = canonicalPath(notePath(file, file.path));
+				this.#revisions.set(path, this.revision(path) + 1);
+			}
+		}
+		this.#pi.appendEntry(NOTES_TOUCH, {
+			version: 1,
+			owner: this.binding.owner,
+			scope: { root: this.binding.root, scope: this.binding.scope },
+			rootToolCallId: call.rootId,
+			toolCallId: call.id,
+			files,
+		} satisfies NoteTouchRecord);
+	}
+	async selectScope(selector: string): Promise<NoteScope> {
+		const directory = canonicalPath(selector);
+		const known = this.scopes.find(
+			(scope) => canonicalPath(scopeDirectory(scope)) === directory,
+		);
+		if (known !== undefined) {
+			return known;
+		}
+		const manifest = await readManifest(directory);
+		if (
+			manifest !== undefined &&
+			manifest.root === this.binding.root &&
+			inside(join(this.binding.root, ".forks"), directory)
+		) {
+			return manifest;
+		}
+		throw new Error(
+			`Unknown notes scope ${selector}. Copy a scope selector from notes list/search.`,
+		);
+	}
+	async #reference(path: string, signal?: AbortSignal): Promise<NoteAddress | undefined> {
+		if (this.binding.kind !== "fork" || this.binding.source === null) {
+			return;
+		}
+		const entries = [
+			...this.#manager.getEntries(),
+			...this.#source.entries,
+			...(await sourceEntries(this.#source.file, signal)),
+		];
+		return resolveReference(this.binding.source, path, entries);
+	}
+	async read(
+		path: string,
+		options: {
+			readonly scope?: string | undefined;
+			readonly signal?: AbortSignal | undefined;
+		} = {},
+	): Promise<NoteRead> {
+		const relative = noteRelative(path);
+		if (options.scope !== undefined) {
+			const scope = await this.selectScope(options.scope);
+			return {
+				address: { ...scope, path: relative },
+				path: notePath(scope, relative),
+				writable: sameScope(scope, this.binding),
+			};
+		}
+		const reference = this.owns(relative)
+			? undefined
+			: await this.#reference(relative, options.signal);
+		const address = reference ?? {
+			root: this.binding.root,
+			scope: this.binding.scope,
+			path: relative,
+		};
+		return { address, path: notePath(address, relative), writable: reference === undefined };
+	}
+	async adopt(path: string, call: NoteCall): Promise<boolean> {
+		const relative = noteRelative(path);
+		if (this.owns(relative)) {
+			return false;
+		}
+		const source = await this.#reference(relative);
+		if (source === undefined) {
+			return false;
+		}
+		const seed = await adoptNote(this.binding, {
+			path: relative,
+			source,
+			lineage: source,
+			anchors: [],
+		});
+		this.record(
+			[
+				{
+					root: this.binding.root,
+					scope: this.binding.scope,
+					path: relative,
+					kind: "adopt",
+					seed,
+				},
+			],
+			call,
+		);
+		try {
+			await saveAdoption(this.binding, seed);
+		} catch (error) {
+			throw new Error(
+				`Private copy created at ${notePath(this.binding, relative)}; source not edited, but its adoption manifest could not be saved. Read the private copy before retrying.`,
+				{ cause: error },
+			);
+		}
+		return true;
+	}
+	async prepareWrite(): Promise<void> {
+		await ensureManifest(this.binding);
+	}
+	async guardReference(path: string, call: NoteCall): Promise<string> {
+		const destination = notePath(this.binding, path);
+		const copied = await withFileMutationQueue(destination, () => this.adopt(path, call));
+		return copied
+			? `Private copy created at ${destination}; the source was not edited. Read the private copy, then retry the edit on that path.`
+			: `This session writes only ${this.directory}. Read ${destination}, then retry there; the foreign path was not edited.`;
+	}
+}
+function sessionKey(ctx: ExtensionContext): string {
+	const header = ctx.sessionManager.getHeader();
+	if (header === null) {
+		throw new Error("Pi session header is required for notes.");
+	}
+	return `${header.id}\0${header.timestamp}`;
+}
+export type NotesStore = {
+	readonly get: (ctx: ExtensionContext) => Promise<SessionNotes>;
+	readonly roots: () => readonly string[];
+	readonly recovery: (ctx: ExtensionContext) => NotesRecovery | undefined;
+};
+export function createNotesStore(pi: ExtensionAPI): NotesStore {
+	const sessions = new Map<string, Promise<SessionNotes>>();
+	const ready = new Map<string, SessionNotes>();
+	const roots = new Set<string>();
+	const get = (ctx: ExtensionContext): Promise<SessionNotes> => {
+		const key = sessionKey(ctx);
+		const existing = sessions.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		const bindings = bindingsOf(ctx.sessionManager.getEntries());
+		const header = ctx.sessionManager.getHeader();
+		const root =
+			bindings.findLast((binding) => header !== null && sameOwner(binding.owner, header))
+				?.root ?? canonicalPath(notesDir(ctx.cwd));
+		roots.add(root);
+		for (const binding of bindings) {
+			roots.add(binding.root);
+		}
+		const initialized = loadNotesBinding(ctx.sessionManager, root)
+			.then(({ binding, source, created }) => {
+				if (created) {
+					pi.appendEntry(NOTES_BINDING, binding);
+				}
+				const session = new SessionNotes(pi, binding, ctx.sessionManager, source);
+				for (const scope of session.scopes) {
+					roots.add(scope.root);
+				}
+				ready.set(key, session);
+				return session;
+			})
+			.catch((error: unknown) => {
+				sessions.delete(key);
+				throw error;
+			});
+		sessions.set(key, initialized);
+		return initialized;
+	};
+	return {
+		get,
+		roots: () => [...roots],
+		recovery: (ctx: ExtensionContext) => ready.get(sessionKey(ctx))?.recovery,
+	};
+}

package/src/note-tool-effects.ts

@@ -0,0 +1,190 @@
+import { isRecord, optionalString, unknownArray } from "./contracts.ts";
+
+export type NoteAction =
+	| "read"
+	| "write"
+	| "clear"
+	| "append"
+	| "edit"
+	| "create"
+	| "create-empty"
+	| "delete";
+export type NoteOperation = {
+	readonly path: string;
+	readonly action: NoteAction;
+	readonly scope?: string | undefined;
+};
+export function bareToolName(name: string | undefined): string {
+	const cut = Math.max(name?.lastIndexOf(":") ?? -1, name?.lastIndexOf("/") ?? -1);
+	return name?.slice(cut + 1) ?? "";
+}
+function patchOperations(input: unknown): NoteOperation[] {
+	if (typeof input !== "string") {
+		return [];
+	}
+	const operations: NoteOperation[] = [];
+	for (const match of input.matchAll(
+		/^\*\*\* (Update File|Add File|Delete File|Move to): ([^\r\n]+)$/gmu,
+	)) {
+		const path = match[2];
+		if (path === undefined) {
+			continue;
+		}
+		if (match[1] === "Move to") {
+			const previous = operations.pop();
+			if (previous !== undefined) {
+				operations.push({ ...previous, action: "delete" });
+			}
+		}
+		let action: NoteAction = "create";
+		if (match[1] === "Update File") {
+			action = "edit";
+		} else if (match[1] === "Delete File") {
+			action = "delete";
+		}
+		operations.push({ path, action });
+	}
+	return operations;
+}
+function batchOperations(tool: string, files: unknown): NoteOperation[] {
+	return (unknownArray(files) ?? []).flatMap<NoteOperation>((file) => {
+		if (!isRecord(file) || typeof file.path !== "string") {
+			return [];
+		}
+		if (tool === "replace_text") {
+			return [{ path: file.path, action: "edit" }];
+		}
+		if (file.mode === "create") {
+			return [{ path: file.path, action: file.content === "" ? "create-empty" : "create" }];
+		}
+		return [{ path: file.path, action: file.content === "" ? "clear" : "write" }];
+	});
+}
+function notesAction(args: Readonly<Record<string, unknown>>): NoteAction | undefined {
+	switch (args.op) {
+		case "write":
+			return args.content === "" ? "clear" : "write";
+		case "append":
+		case "read":
+			return args.op;
+		default:
+			return;
+	}
+}
+function singleOperation(tool: string, args: Readonly<Record<string, unknown>>): NoteOperation[] {
+	const path = optionalString(args.path);
+	if (path === undefined) {
+		return [];
+	}
+	switch (tool) {
+		case "notes": {
+			const action = notesAction(args);
+			return action === undefined
+				? []
+				: [{ path, action, scope: optionalString(args.scope) }];
+		}
+		case "read":
+		case "edit":
+			return [{ path, action: tool }];
+		case "write":
+			return [{ path, action: args.content === "" ? "clear" : "write" }];
+		default:
+			return [];
+	}
+}
+export function noteOperations(tool: string, input: unknown): NoteOperation[] {
+	const args = isRecord(input) ? input : {};
+	if (args.preview === true || tool === "preview_patch") {
+		return [];
+	}
+	switch (tool) {
+		case "apply_patch":
+			return patchOperations(typeof input === "string" ? input : args.input);
+		case "write_files":
+		case "replace_text":
+			return batchOperations(tool, args.files);
+		default:
+			return singleOperation(tool, args);
+	}
+}
+export function noteOperationKind(
+	action: NoteAction,
+): "read" | "full-write" | "partial-write" | "clear" {
+	switch (action) {
+		case "read":
+			return "read";
+		case "write":
+		case "create":
+			return "full-write";
+		case "edit":
+		case "append":
+			return "partial-write";
+		case "clear":
+		case "create-empty":
+		case "delete":
+			return "clear";
+	}
+}
+function committedAction(
+	file: unknown,
+	operation: NoteOperation | undefined,
+	path: string,
+): NoteAction {
+	if (!isRecord(file)) {
+		return operation?.action ?? "edit";
+	}
+	// modifiedFiles is path-qualified; a partly committed move can still have status "failed".
+	if (file.operation === "delete" || (file.operation === "move" && file.path === path)) {
+		return "delete";
+	}
+	if (file.bytesAfter === 0) {
+		return "clear";
+	}
+	return operation?.action ?? "edit";
+}
+function committedOperations(
+	details: Readonly<Record<string, unknown>>,
+	operations: readonly NoteOperation[],
+): NoteOperation[] | undefined {
+	const modified = unknownArray(details.modifiedFiles);
+	if (modified === undefined) {
+		return;
+	}
+	const files = unknownArray(details.files) ?? [];
+	return modified.flatMap((path) => {
+		if (typeof path !== "string") {
+			return [];
+		}
+		const file = files.find(
+			(value) => isRecord(value) && (value.path === path || value.moveTo === path),
+		);
+		const action = committedAction(
+			file,
+			operations.find((operation) => operation.path === path),
+			path,
+		);
+		return [{ path, action }];
+	});
+}
+/** pi-apply-edits reports committed paths even when a later publication failed. */
+export function verifiedNoteOperations(
+	tool: string,
+	input: unknown,
+	result: {
+		readonly isError: boolean;
+		readonly details: unknown;
+	},
+): NoteOperation[] {
+	const operations = noteOperations(tool, input);
+	const details = isRecord(result.details) ? result.details : undefined;
+	if (details?.preview === true) {
+		return [];
+	}
+	if (details !== undefined && ["replace_text", "write_files", "apply_patch"].includes(tool)) {
+		const committed = committedOperations(details, operations);
+		if (committed !== undefined) {
+			return committed;
+		}
+	}
+	return result.isError ? [] : operations;
+}