@henryqw/pi-herdr-btw 1.0.1

package/internal/config.ts

@@ -0,0 +1,253 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const TOOL_MODES = ["inherit", "all", "read-only", "none"] as const;
+export type BtwToolMode = (typeof TOOL_MODES)[number];
+export type BtwSplit = "right" | "down";
+
+export type BtwConfig = {
+	autoSubmit: boolean;
+	tools: BtwToolMode;
+	split: BtwSplit;
+};
+
+const CONFIG_LOCK_STALE_MS = 30_000;
+const CONFIG_LOCK_WAIT_MS = 10_000;
+const CONFIG_LOCK_RETRY_MS = 25;
+
+export const DEFAULT_CONFIG: Readonly<BtwConfig> = Object.freeze({
+	autoSubmit: false,
+	tools: "inherit",
+	split: "right",
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function parseConfig(value: unknown): BtwConfig {
+	if (!isRecord(value)) throw new Error("/btw config must be a JSON object");
+	const allowedKeys = new Set(["autoSubmit", "tools", "split"]);
+	for (const key of Object.keys(value)) {
+		if (!allowedKeys.has(key)) throw new Error(`unknown config key: ${key}`);
+	}
+
+	const config = { ...DEFAULT_CONFIG };
+	if ("autoSubmit" in value) {
+		if (typeof value.autoSubmit !== "boolean") throw new Error("autoSubmit must be true or false");
+		config.autoSubmit = value.autoSubmit;
+	}
+	if ("tools" in value) {
+		if (!TOOL_MODES.includes(value.tools as BtwToolMode)) {
+			throw new Error("tools must be inherit, all, read-only, or none");
+		}
+		config.tools = value.tools as BtwToolMode;
+	}
+	if ("split" in value) {
+		if (value.split !== "right" && value.split !== "down") {
+			throw new Error("split must be right or down");
+		}
+		config.split = value.split;
+	}
+	return config;
+}
+
+export function formatConfig(config: BtwConfig): string {
+	return [
+		`auto-submit: ${config.autoSubmit ? "on" : "off"}`,
+		`tools: ${config.tools}`,
+		`split: ${config.split}`,
+	].join(" · ");
+}
+
+export const CONFIG_COMMAND_USAGE =
+	"/btw config [auto-submit on|off | tools inherit|all|read-only|none | split right|down | reset]";
+
+export type ConfigCommandResult = {
+	action: "show" | "save" | "reset";
+	config: BtwConfig;
+};
+
+export function applyConfigCommand(current: BtwConfig, input: string): ConfigCommandResult {
+	const trimmed = input.trim();
+	if (!trimmed || trimmed === "show") return { action: "show", config: current };
+	if (trimmed === "reset") return { action: "reset", config: { ...DEFAULT_CONFIG } };
+
+	const [key, value, ...extra] = trimmed.split(/\s+/);
+	if (!key || !value || extra.length > 0) throw new Error(CONFIG_COMMAND_USAGE);
+	const config = { ...current };
+
+	switch (key) {
+		case "auto-submit":
+			if (value !== "on" && value !== "off") throw new Error(CONFIG_COMMAND_USAGE);
+			config.autoSubmit = value === "on";
+			break;
+		case "tools":
+			if (!TOOL_MODES.includes(value as BtwToolMode)) {
+				throw new Error(CONFIG_COMMAND_USAGE);
+			}
+			config.tools = value as BtwToolMode;
+			break;
+		case "split":
+			if (value !== "right" && value !== "down") throw new Error(CONFIG_COMMAND_USAGE);
+			config.split = value;
+			break;
+		default:
+			throw new Error(CONFIG_COMMAND_USAGE);
+	}
+
+	return { action: "save", config };
+}
+
+const configPath = () => join(getAgentDir(), "config", "pi-herdr-btw.json");
+
+export class ConfigStore {
+	readonly path: string;
+
+	constructor(path = configPath()) {
+		this.path = path;
+	}
+
+	async load(): Promise<BtwConfig> {
+		try {
+			return parseConfig(JSON.parse(await readFile(this.path, "utf8")));
+		} catch (error) {
+			if (error && typeof error === "object" && (error as NodeJS.ErrnoException).code === "ENOENT") {
+				return { ...DEFAULT_CONFIG };
+			}
+			throw error;
+		}
+	}
+
+	async save(config: BtwConfig): Promise<void> {
+		const validated = parseConfig(config);
+		await this.withLock(() => this.saveUnlocked(validated));
+	}
+
+	async update(mutator: (config: BtwConfig) => BtwConfig): Promise<BtwConfig> {
+		return this.withLock(async () => {
+			const next = parseConfig(mutator(await this.load()));
+			await this.saveUnlocked(next);
+			return next;
+		});
+	}
+
+	async reset(): Promise<BtwConfig> {
+		return this.withLock(async () => {
+			await rm(this.path, { force: true });
+			return { ...DEFAULT_CONFIG };
+		});
+	}
+
+	private async saveUnlocked(validated: BtwConfig): Promise<void> {
+		const directory = dirname(this.path);
+		await mkdir(directory, { recursive: true, mode: 0o700 });
+		const temporaryPath = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await writeFile(temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, {
+				encoding: "utf8",
+				flag: "wx",
+				mode: 0o600,
+			});
+			await chmod(temporaryPath, 0o600);
+			await rename(temporaryPath, this.path);
+		} catch (error) {
+			await rm(temporaryPath, { force: true }).catch(() => undefined);
+			throw error;
+		}
+	}
+
+	private async withLock<T>(operation: () => Promise<T>): Promise<T> {
+		const release = await this.acquireLock();
+		try {
+			return await operation();
+		} finally {
+			await release();
+		}
+	}
+
+	private async acquireLock(): Promise<() => Promise<void>> {
+		const lockPath = `${this.path}.lock`;
+		await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+		const token = randomUUID();
+		const ownerPath = join(lockPath, `owner-${token}`);
+		const deadline = Date.now() + CONFIG_LOCK_WAIT_MS;
+
+		while (true) {
+			try {
+				await mkdir(lockPath, { mode: 0o700 });
+				try {
+					await writeFile(ownerPath, token, { encoding: "utf8", flag: "wx", mode: 0o600 });
+				} catch (error) {
+					await rm(ownerPath, { force: true }).catch(() => undefined);
+					await rmdir(lockPath).catch(() => undefined);
+					throw error;
+				}
+				return async () => {
+					if ((await readFile(ownerPath, "utf8").catch(() => undefined)) !== token) return;
+					try {
+						await rm(ownerPath);
+					} catch (error) {
+						const code = error && typeof error === "object" ? (error as NodeJS.ErrnoException).code : undefined;
+						if (code === "ENOENT") return;
+						throw error;
+					}
+					await rmdir(lockPath).catch((error) => {
+						const code = error && typeof error === "object" ? (error as NodeJS.ErrnoException).code : undefined;
+						if (code !== "ENOENT" && code !== "ENOTEMPTY") throw error;
+					});
+				};
+			} catch (error) {
+				if (!error || typeof error !== "object" || (error as NodeJS.ErrnoException).code !== "EEXIST") {
+					throw error;
+				}
+				const info = await lstat(lockPath).catch(() => undefined);
+				if (!info || Date.now() - info.mtimeMs > CONFIG_LOCK_STALE_MS) {
+					if (!info) continue;
+					const ownerName = await this.readOwnerName(lockPath);
+					const currentInfo = await lstat(lockPath).catch(() => undefined);
+					const currentOwnerName = await this.readOwnerName(lockPath);
+					if (
+						!currentInfo ||
+						currentInfo.dev !== info.dev ||
+						currentInfo.ino !== info.ino ||
+						currentInfo.ctimeMs !== info.ctimeMs ||
+						currentOwnerName !== ownerName
+					) {
+						continue;
+					}
+					// Remove only observed owner's unique entry. Only the process that
+					// removes that entry may remove lockPath; this prevents a stale
+					// reclaimer from deleting a replacement created in between.
+					if (!ownerName) {
+						if (Date.now() >= deadline) throw new Error(`Timed out waiting for config lock: ${this.path}`);
+						await new Promise((resolve) => setTimeout(resolve, CONFIG_LOCK_RETRY_MS));
+						continue;
+					}
+					try {
+						await rm(join(lockPath, ownerName));
+					} catch (error) {
+						const code = error && typeof error === "object" ? (error as NodeJS.ErrnoException).code : undefined;
+						if (code === "ENOENT") continue;
+						throw error;
+					}
+					await rmdir(lockPath).catch((error) => {
+						const code = error && typeof error === "object" ? (error as NodeJS.ErrnoException).code : undefined;
+						if (code !== "ENOENT" && code !== "ENOTEMPTY") throw error;
+					});
+					continue;
+				}
+				if (Date.now() >= deadline) throw new Error(`Timed out waiting for config lock: ${this.path}`);
+				await new Promise((resolve) => setTimeout(resolve, CONFIG_LOCK_RETRY_MS));
+			}
+		}
+	}
+
+	private async readOwnerName(lockPath: string): Promise<string | undefined> {
+		const entries = await readdir(lockPath, { withFileTypes: true }).catch(() => []);
+		const owners = entries.filter((entry) => entry.isFile() && entry.name.startsWith("owner-"));
+		return owners.length === 1 ? owners[0]?.name : undefined;
+	}
+}

package/internal/context-store.ts

@@ -0,0 +1,287 @@
+import {
+	chmod,
+	lstat,
+	mkdir,
+	mkdtemp,
+	readFile,
+	readdir,
+	realpath,
+	rename,
+	rm,
+	utimes,
+	writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isBtwPayload, type BtwPayload } from "./core.ts";
+import { isMergeRequest, MERGE_REQUEST_FILE, type MergeRequest } from "./merge.ts";
+
+const PAYLOAD_FILE = "payload.json";
+const LAUNCH_PREFIX = "launch-";
+const MAX_MAILBOX_FILE_BYTES = 128 * 1024;
+export const MAX_PAYLOAD_FILE_BYTES = 64 * 1024 * 1024;
+
+export const DEFAULT_STALE_CONTEXT_MS = 24 * 60 * 60 * 1000;
+
+function currentUid(): number | undefined {
+	return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+
+function assertOwnedByCurrentUser(uid: number, path: string): void {
+	const expectedUid = currentUid();
+	if (expectedUid !== undefined && uid !== expectedUid) {
+		throw new Error(`Refusing /btw context path not owned by the current user: ${path}`);
+	}
+}
+
+function assertPrivateMode(mode: number, path: string): void {
+	if (process.platform !== "win32" && (mode & 0o077) !== 0) {
+		throw new Error(`Refusing /btw context path with group or other permissions: ${path}`);
+	}
+}
+
+function isInside(root: string, candidate: string): boolean {
+	const child = relative(root, candidate);
+	return child !== "" && !child.startsWith("..") && !isAbsolute(child);
+}
+
+function isMissing(error: unknown): boolean {
+	return !!error && typeof error === "object" && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+export function defaultContextRoot(): string {
+	const uid = currentUid();
+	return join(tmpdir(), uid === undefined ? "pi-herdr-btw" : `pi-herdr-btw-${uid}`);
+}
+
+export class ContextStore {
+	readonly root: string;
+	private canonicalRoot: string | undefined;
+
+	constructor(root = defaultContextRoot()) {
+		this.root = resolve(root);
+	}
+
+	async create(payload: BtwPayload): Promise<string> {
+		const root = await this.ensureRoot();
+		const serialized = `${JSON.stringify(payload)}\n`;
+		if (Buffer.byteLength(serialized, "utf8") > MAX_PAYLOAD_FILE_BYTES) {
+			throw new Error("Refusing oversized /btw context payload");
+		}
+		const launchDir = await mkdtemp(join(root, LAUNCH_PREFIX));
+		try {
+			await chmod(launchDir, 0o700);
+
+			const payloadPath = join(launchDir, PAYLOAD_FILE);
+			await writeFile(payloadPath, serialized, {
+				encoding: "utf8",
+				flag: "wx",
+				mode: 0o600,
+			});
+			await chmod(payloadPath, 0o600);
+			return payloadPath;
+		} catch (error) {
+			await rm(launchDir, { recursive: true, force: true }).catch(() => undefined);
+			throw error;
+		}
+	}
+
+	async read(payloadPath: string): Promise<BtwPayload> {
+		const canonicalPath = await this.validateLaunchFile(payloadPath, PAYLOAD_FILE);
+		if (!canonicalPath) throw new Error(`Missing /btw context payload: ${payloadPath}`);
+		const parsed: unknown = JSON.parse(await readFile(canonicalPath, "utf8"));
+		if (!isBtwPayload(parsed)) {
+			throw new Error("Invalid or unsupported /btw context payload");
+		}
+		return parsed;
+	}
+
+	/** List payload paths for every launch directory currently in the private root. */
+	async listLaunchPayloadPaths(): Promise<string[]> {
+		const root = await this.ensureRoot();
+		const entries = await readdir(root, { withFileTypes: true });
+		return entries
+			.filter((entry) => entry.isDirectory() && entry.name.startsWith(LAUNCH_PREFIX))
+			.map((entry) => join(root, entry.name, PAYLOAD_FILE));
+	}
+
+	async writeMergeRequest(payloadPath: string, request: MergeRequest): Promise<void> {
+		if (!isMergeRequest(request)) throw new Error("Invalid /btw merge request");
+		await this.writeLaunchFile(payloadPath, MERGE_REQUEST_FILE, request);
+	}
+
+	async readMergeRequest(payloadPath: string): Promise<unknown> {
+		return this.readLaunchFile(payloadPath, MERGE_REQUEST_FILE);
+	}
+
+	/** Keep a launch with a request until its parent consumes it. */
+	async removeIfNoPendingMerge(payloadPath: string): Promise<boolean> {
+		if ((await this.readMergeRequest(payloadPath)) !== undefined) return false;
+		await this.remove(payloadPath);
+		return true;
+	}
+
+	async remove(payloadPath: string): Promise<void> {
+		const launchDir = await this.validateLaunchDir(payloadPath, true);
+		if (launchDir) await rm(launchDir, { recursive: true, force: true });
+	}
+
+	/** Refresh launch liveness without modifying mailbox contents. */
+	async touch(payloadPath: string): Promise<void> {
+		const launchDir = await this.validateLaunchDir(payloadPath, true);
+		if (launchDir) {
+			const now = new Date();
+			await utimes(launchDir, now, now);
+		}
+	}
+
+	async removeStale(
+		maxAgeMs = DEFAULT_STALE_CONTEXT_MS,
+		now = Date.now(),
+	): Promise<void> {
+		const root = await this.ensureRoot();
+		const entries = await readdir(root, { withFileTypes: true });
+		// One unsafe or foreign entry must not abort cleanup of the others.
+		await Promise.allSettled(
+			entries.map(async (entry) => {
+				if (!entry.name.startsWith(LAUNCH_PREFIX) || !entry.isDirectory()) return;
+				const launchDir = join(root, entry.name);
+				const info = await lstat(launchDir).catch(() => undefined);
+				if (!info?.isDirectory() || info.isSymbolicLink()) return;
+				assertOwnedByCurrentUser(info.uid, launchDir);
+				if (info.mtimeMs < now - maxAgeMs) {
+					// A heartbeat may have refreshed this launch after the first stat.
+					const current = await lstat(launchDir).catch(() => undefined);
+					if (
+						!current?.isDirectory() ||
+						current.isSymbolicLink() ||
+						current.dev !== info.dev ||
+						current.ino !== info.ino ||
+						current.ctimeMs !== info.ctimeMs ||
+						current.mtimeMs !== info.mtimeMs
+					) {
+						return;
+					}
+					await rm(launchDir, { recursive: true, force: true });
+				}
+			}),
+		);
+	}
+
+	private async ensureRoot(): Promise<string> {
+		if (this.canonicalRoot) return this.canonicalRoot;
+
+		try {
+			await mkdir(this.root, { mode: 0o700 });
+		} catch (error) {
+			if (!error || typeof error !== "object" || (error as NodeJS.ErrnoException).code !== "EEXIST") {
+				throw error;
+			}
+		}
+
+		const info = await lstat(this.root);
+		if (!info.isDirectory() || info.isSymbolicLink()) {
+			throw new Error(`Refusing unsafe /btw context root: ${this.root}`);
+		}
+		assertOwnedByCurrentUser(info.uid, this.root);
+		await chmod(this.root, 0o700);
+		const canonicalRoot = await realpath(this.root);
+		const canonicalInfo = await lstat(canonicalRoot);
+		assertOwnedByCurrentUser(canonicalInfo.uid, canonicalRoot);
+		assertPrivateMode(canonicalInfo.mode, canonicalRoot);
+		this.canonicalRoot = canonicalRoot;
+		return canonicalRoot;
+	}
+
+	private async writeLaunchFile(payloadPath: string, fileName: string, data: unknown): Promise<void> {
+		const launchDir = await this.validateLaunchDir(payloadPath, false);
+		if (!launchDir) throw new Error(`Missing /btw launch directory: ${payloadPath}`);
+		const targetPath = join(launchDir, fileName);
+		const temporaryPath = join(launchDir, `.${fileName}.${process.pid}.${Date.now()}.tmp`);
+		try {
+			await writeFile(temporaryPath, `${JSON.stringify(data)}\n`, {
+				encoding: "utf8",
+				flag: "wx",
+				mode: 0o600,
+			});
+			await chmod(temporaryPath, 0o600);
+			await rename(temporaryPath, targetPath);
+		} catch (error) {
+			await rm(temporaryPath, { force: true }).catch(() => undefined);
+			throw error;
+		}
+	}
+
+	private async readLaunchFile(payloadPath: string, fileName: string): Promise<unknown> {
+		const canonicalPath = await this.validateLaunchFile(payloadPath, fileName);
+		if (!canonicalPath) return undefined;
+		return JSON.parse(await readFile(canonicalPath, "utf8")) as unknown;
+	}
+
+	private async validateLaunchFile(
+		payloadPath: string,
+		fileName: string,
+	): Promise<string | undefined> {
+		const launchDir = await this.validateLaunchDir(payloadPath, false);
+		if (!launchDir) throw new Error(`Missing /btw context payload: ${payloadPath}`);
+
+		const candidate = join(launchDir, fileName);
+		let info;
+		try {
+			info = await lstat(candidate);
+		} catch (error) {
+			if (fileName !== PAYLOAD_FILE && isMissing(error)) return undefined;
+			throw error;
+		}
+		if (!info.isFile() || info.isSymbolicLink()) {
+			throw new Error(`Refusing unsafe /btw context payload: ${candidate}`);
+		}
+		assertOwnedByCurrentUser(info.uid, candidate);
+		assertPrivateMode(info.mode, candidate);
+		const maxBytes = fileName === PAYLOAD_FILE ? MAX_PAYLOAD_FILE_BYTES : MAX_MAILBOX_FILE_BYTES;
+		if (info.size > maxBytes) {
+			throw new Error(`Refusing oversized /btw mailbox file: ${candidate}`);
+		}
+
+		const canonicalPath = await realpath(candidate);
+		const root = await this.ensureRoot();
+		if (!isInside(root, canonicalPath)) {
+			throw new Error(`Refusing /btw context payload outside the private root: ${payloadPath}`);
+		}
+		return canonicalPath;
+	}
+
+	private async validateLaunchDir(
+		payloadPath: string,
+		allowMissing: boolean,
+	): Promise<string | undefined> {
+		const root = await this.ensureRoot();
+		const absolutePayload = resolve(payloadPath);
+		const launchDir = dirname(absolutePayload);
+		if (basename(absolutePayload) !== PAYLOAD_FILE || !basename(launchDir).startsWith(LAUNCH_PREFIX)) {
+			throw new Error(`Refusing invalid /btw context payload path: ${payloadPath}`);
+		}
+		if (!isInside(root, launchDir)) {
+			throw new Error(`Refusing /btw context payload outside the private root: ${payloadPath}`);
+		}
+
+		let info;
+		try {
+			info = await lstat(launchDir);
+		} catch (error) {
+			if (allowMissing && isMissing(error)) return undefined;
+			throw error;
+		}
+		if (!info.isDirectory() || info.isSymbolicLink()) {
+			throw new Error(`Refusing unsafe /btw launch directory: ${launchDir}`);
+		}
+		assertOwnedByCurrentUser(info.uid, launchDir);
+		assertPrivateMode(info.mode, launchDir);
+
+		const canonicalLaunchDir = await realpath(launchDir);
+		if (!isInside(root, canonicalLaunchDir)) {
+			throw new Error(`Refusing /btw launch directory outside the private root: ${launchDir}`);
+		}
+		return canonicalLaunchDir;
+	}
+}