@huseynsnmz/pi-suite 0.1.0 → 0.2.0

package/packages/frame/src/kit/settings/files.ts

@@ -0,0 +1,90 @@
+// Every app shares the settings files, so a write keeps every key it does not know.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { isObject } from "../decode.ts";
+
+export type SettingsData = Record<string, unknown>;
+
+export interface SettingsFile {
+	data: SettingsData;
+	warnings: string[];
+}
+
+export function globalSettingsPath(): string {
+	return join(getAgentDir(), "extensions", "pi-harness", "settings.json");
+}
+
+export function projectSettingsPath(cwd: string): string {
+	return join(cwd, CONFIG_DIR_NAME, "extensions", "pi-harness", "settings.json");
+}
+
+export function readSettingsFile(path: string): SettingsFile {
+	try {
+		const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (isObject(data)) return { data, warnings: [] };
+		return { data: {}, warnings: [`${path}: must contain a JSON object; using the defaults`] };
+	} catch (error) {
+		// A missing file is a fresh start, not a warning.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { data: {}, warnings: [] };
+		const reason = error instanceof Error ? error.message : String(error);
+		return { data: {}, warnings: [`${path}: could not be read (${reason}); using the defaults`] };
+	}
+}
+
+export function writeSettingsFile(
+	path: string,
+	data: SettingsData,
+	options: { mode?: number } = {},
+): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, `${JSON.stringify(data, null, "\t")}\n`, {
+		encoding: "utf8",
+		mode: options.mode,
+	});
+	renameSync(temporary, path);
+}
+
+export function lookup(data: SettingsData, id: string): unknown {
+	let node: unknown = data;
+	for (const key of id.split(".")) {
+		if (!isObject(node)) return undefined;
+		node = node[key];
+	}
+	return node;
+}
+
+export function remove(data: SettingsData, id: string): void {
+	const [key, ...rest] = id.split(".");
+	if (key === undefined || !(key in data)) return;
+	if (rest.length === 0) {
+		delete data[key];
+		return;
+	}
+	const child = data[key];
+	if (!isObject(child)) return;
+	remove(child, rest.join("."));
+	if (Object.keys(child).length === 0) delete data[key];
+}
+
+export function assign(data: SettingsData, id: string, value: unknown): void {
+	const keys = id.split(".");
+	const last = keys.pop();
+	if (last === undefined) return;
+
+	let node = data;
+	for (const key of keys) {
+		const next = node[key];
+		if (isObject(next)) {
+			node = next;
+			continue;
+		}
+		const created: SettingsData = {};
+		node[key] = created;
+		node = created;
+	}
+	node[last] = value;
+}

package/packages/frame/src/kit/settings/setting.ts

@@ -0,0 +1,57 @@
+// Declared next to the feature that reads it; one handle works against any app.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { Preview } from "../contracts/screen.ts";
+import type { Control } from "../control.ts";
+import type { Decoder } from "../decode.ts";
+import type { SettingsStore } from "./store.ts";
+
+export interface SettingUi {
+	section: string;
+	label: string;
+	description: string;
+	/** Overrides the decoder's. A function runs each time the screen opens. */
+	control?: Control | ((ctx: ExtensionContext) => Control);
+	/** Applies only after `/reload`. */
+	restart?: boolean;
+	/** What a value looks like, drawn under the list while the setting or a value is selected. */
+	preview?: Preview;
+}
+
+export interface SettingDefinition<T> {
+	/** Dotted path, like `subscription.claudeCodeVersion`. */
+	id: string;
+	default: T;
+	decoder: Decoder<T>;
+	/** Once pi trusts the project. */
+	project?: boolean;
+	ui?: SettingUi;
+}
+
+export interface SettingsScope {
+	readonly settings: SettingsStore;
+}
+
+export interface Setting<T> extends SettingDefinition<T> {
+	get(scope: SettingsScope): T;
+	listen(scope: SettingsScope, listener: (value: T) => void): () => void;
+}
+
+export function setting<T>(definition: SettingDefinition<T>): Setting<T> {
+	const handle: Setting<T> = {
+		...definition,
+		get: (scope) => scope.settings.get(handle),
+		listen: (scope, listener) => scope.settings.listen(handle, listener),
+	};
+	return handle;
+}
+
+export function controlOf(
+	entry: Setting<unknown>,
+	ctx: ExtensionContext | undefined,
+): Control | undefined {
+	const declared = entry.ui?.control;
+	if (typeof declared === "function")
+		return ctx === undefined ? entry.decoder.control : declared(ctx);
+	return declared ?? entry.decoder.control;
+}

package/packages/frame/src/kit/settings/store.ts

@@ -0,0 +1,192 @@
+// A value comes from the first layer that has a valid one: project (when allowed and trusted), global, default.
+import { formatProblems } from "../decode.ts";
+import {
+	assign,
+	lookup,
+	readSettingsFile,
+	remove,
+	type SettingsData,
+	writeSettingsFile,
+} from "./files.ts";
+import type { Setting } from "./setting.ts";
+
+export type Layer = "default" | "global" | "project";
+
+type Found<T> = { found: true; value: T } | { found: false };
+
+interface Loaded {
+	value: unknown;
+	layer: Layer;
+	global?: unknown;
+}
+
+export class SettingsStore {
+	readonly globalPath: string;
+	#projectPath: string | undefined;
+	#known = new Map<string, Setting<unknown>>();
+	#loaded = new Map<string, Loaded>();
+	#listeners = new Map<string, Set<(value: unknown) => void>>();
+	#writeListeners = new Set<() => void>();
+	#fresh = false;
+
+	constructor(globalPath: string) {
+		this.globalPath = globalPath;
+	}
+
+	get projectPath(): string | undefined {
+		return this.#projectPath;
+	}
+
+	register(settings: readonly Setting<unknown>[]): void {
+		for (const entry of settings) {
+			const known = this.#known.get(entry.id);
+			if (known !== undefined && known !== entry)
+				throw new Error(`two settings are named "${entry.id}"`);
+			this.#known.set(entry.id, entry);
+		}
+		this.#fresh = false;
+	}
+
+	known(): Setting<unknown>[] {
+		return [...this.#known.values()];
+	}
+
+	/** Throws for an undeclared setting, which would otherwise read its default forever. */
+	get<T>(entry: Setting<T>): T {
+		// `load` fills #loaded only with values this setting's decoder produced.
+		return this.#read(entry).value as T;
+	}
+
+	layer(entry: Setting<unknown>): Layer {
+		return this.#read(entry).layer;
+	}
+
+	hidden(entry: Setting<unknown>): unknown {
+		return this.#read(entry).global;
+	}
+
+	listen<T>(entry: Setting<T>, listener: (value: T) => void): () => void {
+		const listeners = this.#listeners.get(entry.id) ?? new Set();
+		this.#listeners.set(entry.id, listeners);
+		// Every value given to a listener came from this setting's decoder.
+		const untyped = listener as (value: unknown) => void;
+		listeners.add(untyped);
+		return () => listeners.delete(untyped);
+	}
+
+	onWrite(listener: () => void): () => void {
+		this.#writeListeners.add(listener);
+		return () => this.#writeListeners.delete(listener);
+	}
+
+	/** Pass the project file only when pi trusts the project. */
+	load(projectPath?: string): string[] {
+		this.#fresh = true;
+		this.#projectPath = projectPath;
+		const global = readSettingsFile(this.globalPath);
+		const project = projectPath === undefined ? undefined : readSettingsFile(projectPath);
+		const warnings = [...global.warnings, ...(project?.warnings ?? [])];
+
+		for (const entry of this.#known.values()) {
+			let loaded: Loaded = { value: entry.default, layer: "default" };
+
+			const fromGlobal = decodeAt(entry, global.data, this.globalPath, warnings);
+			if (fromGlobal.found) loaded = { value: fromGlobal.value, layer: "global" };
+
+			if (project !== undefined && projectPath !== undefined) {
+				if (entry.project) {
+					const fromProject = decodeAt(entry, project.data, projectPath, warnings);
+					if (fromProject.found)
+						loaded = { value: fromProject.value, layer: "project", global: loaded.value };
+				} else if (lookup(project.data, entry.id) !== undefined) {
+					warnings.push(
+						`${projectPath}: ${entry.id}: only the global settings file can set this; ignored`,
+					);
+				}
+			}
+
+			this.#update(entry, loaded);
+		}
+
+		return warnings;
+	}
+
+	/** Keeps the rest of the file. Returns an error message on failure. */
+	set<T>(entry: Setting<T>, value: T): string | undefined {
+		return this.setAll([[entry, value]]);
+	}
+
+	/** A value equal to the current one is not written, so the file never freezes a default. */
+	setAll(entries: readonly (readonly [Setting<unknown>, unknown])[]): string | undefined {
+		for (const [entry] of entries) this.#assertKnown(entry);
+		const changed = entries.filter(([entry, value]) => !same(this.#globalOf(entry), value));
+		if (changed.length === 0) return undefined;
+
+		return this.#edit(this.globalPath, (data) => {
+			for (const [entry, value] of changed) assign(data, entry.id, value);
+		});
+	}
+
+	unset(entry: Setting<unknown>, layer: Exclude<Layer, "default">): string | undefined {
+		this.#assertKnown(entry);
+		const path = layer === "global" ? this.globalPath : this.#projectPath;
+		if (path === undefined) return "no trusted project to change";
+		return this.#edit(path, (data) => remove(data, entry.id));
+	}
+
+	#edit(path: string, change: (data: SettingsData) => void): string | undefined {
+		const { data } = readSettingsFile(path);
+		change(data);
+		try {
+			writeSettingsFile(path, data);
+		} catch (error) {
+			return error instanceof Error ? error.message : String(error);
+		}
+		this.load(this.#projectPath);
+		for (const listener of this.#writeListeners) listener();
+		return undefined;
+	}
+
+	#globalOf(entry: Setting<unknown>): unknown {
+		const loaded = this.#read(entry);
+		return loaded.layer === "project" ? loaded.global : loaded.value;
+	}
+
+	#read(entry: Setting<unknown>): Loaded {
+		this.#assertKnown(entry);
+		if (!this.#fresh) this.load(this.#projectPath);
+		return this.#loaded.get(entry.id) ?? { value: entry.default, layer: "default" };
+	}
+
+	#assertKnown(entry: Setting<unknown>): void {
+		if (this.#known.get(entry.id) !== entry)
+			throw new Error(`the setting "${entry.id}" was not declared by any feature of this app`);
+	}
+
+	#update(entry: Setting<unknown>, loaded: Loaded): void {
+		const previous = this.#loaded.get(entry.id)?.value ?? entry.default;
+		this.#loaded.set(entry.id, loaded);
+		if (same(previous, loaded.value)) return;
+		for (const listener of this.#listeners.get(entry.id) ?? []) listener(loaded.value);
+	}
+}
+
+function decodeAt<T>(
+	entry: Setting<T>,
+	data: SettingsData,
+	path: string,
+	warnings: string[],
+): Found<T> {
+	const input = lookup(data, entry.id);
+	if (input === undefined) return { found: false };
+
+	const result = entry.decoder.decode(input, entry.id);
+	const suffix = result.ok ? "" : "; ignored";
+	for (const line of formatProblems(result.problems)) warnings.push(`${path}: ${line}${suffix}`);
+	return result.ok ? { found: true, value: result.value } : { found: false };
+}
+
+/** Decoders build new objects on every read, so values compare by content. */
+function same(left: unknown, right: unknown): boolean {
+	return JSON.stringify(left) === JSON.stringify(right);
+}

package/packages/frame/src/kit/sources/file.ts

@@ -0,0 +1,129 @@
+// A session read from its file on this machine. Read-only: no questions, queue or way in.
+import {
+	calculateContextTokens,
+	type ExtensionAPI,
+	type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+	askSource,
+	type SessionSummary,
+	type SessionSource,
+	type SourceAddress,
+} from "../contracts/sources.ts";
+import { HOST } from "../events/log.ts";
+import { FileTail, followFile, type FileRecord, type TailItem } from "./follow.ts";
+
+export interface FileSourceOptions {
+	/** Milliseconds between polls when the directory watch stays quiet. */
+	every?: number;
+}
+
+export function sourceFor(
+	events: ExtensionAPI["events"],
+	address: SourceAddress,
+	options: FileSourceOptions = {},
+): SessionSource | undefined {
+	const provided = askSource(events, address);
+	if (provided !== undefined) return provided;
+	if (address.machine !== HOST || address.file === undefined) return undefined;
+	return fileSource(address.file, options);
+}
+
+export function fileSource(path: string, options: FileSourceOptions = {}): SessionSource {
+	return {
+		open() {
+			const fold = new Fold();
+			for (const item of new FileTail(path).poll()) fold.apply(item);
+			const summary = fold.snapshot();
+			if (summary === undefined) return Promise.reject(new Error(`no session in ${path} yet`));
+			return Promise.resolve(summary);
+		},
+		follow(after, on) {
+			const fold = new Fold();
+			let waiting = after?.entry;
+			// A cursor with nothing this source reads, such as a newer one, is unknown.
+			if (after !== undefined && waiting === undefined) on({ kind: "reset" });
+			let sent = "";
+			return followFile(
+				path,
+				(items) => {
+					if (items[0]?.kind === "reset") {
+						fold.reset();
+						on({ kind: "reset" });
+					}
+					let entries = items.flatMap((item) => fold.apply(item));
+					if (waiting !== undefined) {
+						const at = entries.findIndex((entry) => entry.id === waiting);
+						// The first read holds the whole file, so a cursor it lacks is unknown to the file.
+						if (at === -1) on({ kind: "reset" });
+						entries = entries.slice(at + 1);
+						waiting = undefined;
+					}
+					for (const entry of entries) on({ kind: "entry", entry });
+					const summary = fold.snapshot();
+					const text = JSON.stringify(summary);
+					if (summary === undefined || text === sent) return;
+					sent = text;
+					on({ kind: "summary", summary });
+				},
+				{ every: options.every },
+			);
+		},
+	};
+}
+
+class Fold {
+	#header: { session: string; cwd: string } | undefined;
+	#rest: Omit<SessionSummary, "session" | "machine" | "cwd"> = {};
+
+	reset(): void {
+		this.#header = undefined;
+		this.#rest = {};
+	}
+
+	apply(item: TailItem): SessionEntry[] {
+		if (item.kind === "reset") return [];
+		const record = item.record;
+		if (record.type === "session") {
+			if (typeof record.cwd === "string") this.#header = { session: record.id, cwd: record.cwd };
+			return [];
+		}
+		if (!isEntry(record)) return [];
+		this.#rest = { ...this.#rest, ...changes(record), leafId: record.id };
+		return [record];
+	}
+
+	snapshot(): SessionSummary | undefined {
+		if (this.#header === undefined) return undefined;
+		return { ...this.#header, machine: HOST, ...this.#rest };
+	}
+}
+
+function changes(entry: SessionEntry): Partial<SessionSummary> {
+	switch (entry.type) {
+		case "session_info":
+			return { name: entry.name };
+		case "model_change":
+			return { model: { provider: entry.provider, id: entry.modelId } };
+		case "thinking_level_change":
+			return { thinkingLevel: entry.thinkingLevel };
+		case "compaction":
+			// Pi does not know the context size again until the next answer.
+			return { context: undefined };
+		case "message": {
+			const message = entry.message;
+			if (message.role !== "assistant") return {};
+			const model = { provider: message.provider, id: message.model };
+			if (message.stopReason === "aborted" || message.stopReason === "error") return { model };
+			const tokens = calculateContextTokens(message.usage);
+			return tokens > 0 ? { model, context: { tokens } } : { model };
+		}
+		default:
+			return {};
+	}
+}
+
+function isEntry(record: FileRecord): record is FileRecord & SessionEntry {
+	return typeof record.type === "string" && "parentId" in record;
+}

package/packages/frame/src/kit/sources/follow.ts

@@ -0,0 +1,155 @@
+// Follows a JSONL file of records with an `id`. Pi rewrites the whole file when it migrates it, so a
+// rewrite is detected and read again without repeating a record. Imports only `node:*`.
+import { closeSync, fstatSync, openSync, readSync, watch } from "node:fs";
+import { dirname } from "node:path";
+
+export interface FollowState {
+	/** Always at the end of a line. */
+	offset: number;
+	lastId: string | undefined;
+	ino: number;
+	size: number;
+	/** A rewrite can keep the size, but not the modification time. */
+	mtimeMs: number;
+}
+
+export interface FileRecord {
+	id: string;
+	[field: string]: unknown;
+}
+
+/** `reset`: the file was rewritten; drop what came before. */
+export type TailItem = { kind: "record"; record: FileRecord } | { kind: "reset" };
+
+const START: FollowState = { offset: 0, lastId: undefined, ino: 0, size: 0, mtimeMs: 0 };
+
+export class FileTail {
+	readonly #path: string;
+	#state: FollowState;
+
+	constructor(path: string, from: FollowState = START) {
+		this.#path = path;
+		this.#state = { ...from };
+	}
+
+	get state(): FollowState {
+		return { ...this.#state };
+	}
+
+	/** A file that does not exist yet gives nothing. */
+	poll(): TailItem[] {
+		let fd: number;
+		try {
+			fd = openSync(this.#path, "r");
+		} catch {
+			return [];
+		}
+		try {
+			return this.#read(fd);
+		} finally {
+			closeSync(fd);
+		}
+	}
+
+	#read(fd: number): TailItem[] {
+		const { ino, size, mtimeMs } = fstatSync(fd);
+		const state = this.#state;
+		if (ino === state.ino && size === state.size && mtimeMs === state.mtimeMs) return [];
+		const rewritten =
+			(state.ino !== 0 && ino !== state.ino) ||
+			size < state.offset ||
+			(state.offset > 0 && idEndingAt(fd, state.offset) !== state.lastId);
+		const skipTo = rewritten ? state.lastId : undefined;
+		const from = rewritten ? 0 : state.offset;
+		const { records, end } = readLines(fd, from, size);
+		this.#state = {
+			offset: end,
+			lastId: records.at(-1)?.id ?? (rewritten ? undefined : state.lastId),
+			ino,
+			size,
+			mtimeMs,
+		};
+		if (skipTo === undefined) return records.map(asItem);
+		const seen = records.findIndex((record) => record.id === skipTo);
+		if (seen === -1) return [{ kind: "reset" }, ...records.map(asItem)];
+		return records.slice(seen + 1).map(asItem);
+	}
+}
+
+/** `every` is the poll behind the directory watch, which some filesystems never fire. */
+export function followFile(
+	path: string,
+	on: (items: TailItem[]) => void,
+	options: { from?: FollowState; every?: number } = {},
+): () => void {
+	const tail = new FileTail(path, options.from);
+	let stopped = false;
+	function check(): void {
+		if (stopped) return;
+		const items = tail.poll();
+		if (items.length > 0) on(items);
+	}
+	const poll = setInterval(check, options.every ?? 1_000);
+	poll.unref();
+	const watcher = watchFolder(dirname(path), check);
+	check();
+	return () => {
+		stopped = true;
+		clearInterval(poll);
+		watcher?.close();
+	};
+}
+
+function watchFolder(folder: string, changed: () => void): { close(): void } | undefined {
+	try {
+		const watcher = watch(folder, changed);
+		watcher.on("error", () => {});
+		return watcher;
+	} catch {
+		return undefined;
+	}
+}
+
+function asItem(record: FileRecord): TailItem {
+	return { kind: "record", record };
+}
+
+function readLines(fd: number, from: number, size: number): { records: FileRecord[]; end: number } {
+	if (size <= from) return { records: [], end: from };
+	const buffer = Buffer.alloc(size - from);
+	readSync(fd, buffer, 0, buffer.length, from);
+	const last = buffer.lastIndexOf(0x0a);
+	if (last === -1) return { records: [], end: from };
+	const records = buffer
+		.subarray(0, last)
+		.toString("utf8")
+		.split("\n")
+		.flatMap((line) => recordOf(line));
+	return { records, end: from + last + 1 };
+}
+
+/** Reads back only as far as that line starts. */
+function idEndingAt(fd: number, offset: number): string | undefined {
+	for (let window = 4_096; ; window *= 2) {
+		const start = Math.max(0, offset - window);
+		const buffer = Buffer.alloc(offset - start);
+		readSync(fd, buffer, 0, buffer.length, start);
+		if (buffer.at(-1) !== 0x0a) return undefined;
+		const before = buffer.lastIndexOf(0x0a, buffer.length - 2);
+		if (before !== -1 || start === 0) {
+			return recordOf(buffer.subarray(before + 1, -1).toString("utf8"))[0]?.id;
+		}
+	}
+}
+
+function recordOf(line: string): FileRecord[] {
+	if (line.trim() === "") return [];
+	try {
+		const value: unknown = JSON.parse(line);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
+		if (!("id" in value) || typeof value.id !== "string") return [];
+		return [value as FileRecord];
+	} catch {
+		return [];
+	}
+}