@adeildo/pi-kit 4.0.0 → 5.0.0

package/src/settings/files.ts

@@ -34,10 +34,17 @@ export function readSettingsFile(path: string): SettingsFile {
 	}
 }
 
-export function writeSettingsFile(path: string, data: SettingsData): void {
+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`, "utf8");
+	writeFileSync(temporary, `${JSON.stringify(data, null, "\t")}\n`, {
+		encoding: "utf8",
+		mode: options.mode,
+	});
 	renameSync(temporary, path);
 }
 
@@ -50,6 +57,20 @@ export function lookup(data: SettingsData, id: string): unknown {
 	return node;
 }
 
+/** Deletes the key, and every object it leaves empty. */
+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();

package/src/settings/setting.ts

@@ -1,13 +1,20 @@
 // A setting is declared next to the feature that reads it. The declaration is plain data plus two
 // helpers, so one handle works against any app.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { Control } from "../control.ts";
 import type { Decoder } from "../decode.ts";
 import type { SettingsStore } from "./store.ts";
 
-/** How a setting shows up on a settings screen. */
+/** The setting's row on the settings screen. */
 export interface SettingUi {
-	group: string;
+	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;
 }
 
 export interface SettingDefinition<T> {
@@ -37,3 +44,13 @@ export function setting<T>(definition: SettingDefinition<T>): Setting<T> {
 	};
 	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/src/settings/store.ts

@@ -2,23 +2,43 @@
 // first layer with a valid one: project (for settings that accept it, in a trusted project),
 // global, default.
 import { formatProblems } from "../decode.ts";
-import { assign, lookup, readSettingsFile, type SettingsData, writeSettingsFile } from "./files.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>>();
-	#values = new Map<string, unknown>();
+	#loaded = new Map<string, Loaded>();
 	#listeners = new Map<string, Set<(value: unknown) => void>>();
-	#loaded = false;
+	#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);
@@ -26,13 +46,25 @@ export class SettingsStore {
 				throw new Error(`two settings are named "${entry.id}"`);
 			this.#known.set(entry.id, entry);
 		}
-		this.#loaded = false;
+		this.#fresh = false;
+	}
+
+	known(): Setting<unknown>[] {
+		return [...this.#known.values()];
 	}
 
+	/** Throws for a setting no feature declared, which would otherwise read its default forever. */
 	get<T>(entry: Setting<T>): T {
-		if (!this.#loaded) this.load(this.#projectPath);
-		// Only `load` writes to #values, and always with a value this setting's decoder produced.
-		return this.#values.has(entry.id) ? (this.#values.get(entry.id) as T) : entry.default;
+		// Only `load` fills #loaded, and always with a value 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 {
@@ -44,24 +76,31 @@ export class SettingsStore {
 		return () => listeners.delete(untyped);
 	}
 
+	/** Lets other stores on the same files read them again. */
+	onWrite(listener: () => void): () => void {
+		this.#writeListeners.add(listener);
+		return () => this.#writeListeners.delete(listener);
+	}
+
 	/** Reads the files again. Pass the project file only when pi trusts the project. */
 	load(projectPath?: string): string[] {
-		this.#loaded = true;
+		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 value = entry.default;
+			let loaded: Loaded = { value: entry.default, layer: "default" };
 
 			const fromGlobal = decodeAt(entry, global.data, this.globalPath, warnings);
-			if (fromGlobal.found) value = fromGlobal.value;
+			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) value = fromProject.value;
+					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`,
@@ -69,7 +108,7 @@ export class SettingsStore {
 				}
 			}
 
-			this.#update(entry, value);
+			this.#update(entry, loaded);
 		}
 
 		return warnings;
@@ -86,25 +125,56 @@ export class SettingsStore {
 	 * default, which would freeze them.
 	 */
 	setAll(entries: readonly (readonly [Setting<unknown>, unknown])[]): string | undefined {
-		const changed = entries.filter(([entry, value]) => !same(this.get(entry), value));
+		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;
 
-		const { data } = readSettingsFile(this.globalPath);
-		for (const [entry, value] of changed) assign(data, entry.id, value);
+		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(this.globalPath, data);
+			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;
 	}
 
-	#update(entry: Setting<unknown>, value: unknown): void {
-		const previous = this.#values.has(entry.id) ? this.#values.get(entry.id) : entry.default;
-		this.#values.set(entry.id, value);
-		if (same(previous, value)) return;
-		for (const listener of this.#listeners.get(entry.id) ?? []) listener(value);
+	#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);
 	}
 }
 

package/src/testing.ts

@@ -5,17 +5,31 @@ import { join } from "node:path";
 
 import {
 	createEventBus,
+	createSyntheticSourceInfo,
 	type EntryRenderer,
 	type EventBus,
 	type ExtensionAPI,
 	type ExtensionContext,
 	type RegisteredCommand,
 	type ToolDefinition,
+	type ToolInfo,
 } from "@earendil-works/pi-coding-agent";
 
-import type { FeatureScope } from "./app/feature.ts";
+import type { FeatureScope, ScreenEntry, ScreenGroup } from "./app/feature.ts";
 import { SettingsStore } from "./settings/store.ts";
 
+/** A tool as `getAllTools` reports it, with the fields the callers read. */
+export function toolInfo(name: string, extra: Partial<ToolInfo> = {}): ToolInfo {
+	return {
+		name,
+		description: "",
+		parameters: { type: "object" } as ToolInfo["parameters"],
+		exposure: "direct",
+		sourceInfo: createSyntheticSourceInfo(`<test:${name}>`, { source: "test" }),
+		...extra,
+	};
+}
+
 export type FakeHandler = (event: unknown, ctx: ExtensionContext) => unknown;
 type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
 
@@ -25,6 +39,8 @@ export interface FakePi {
 	commands: Map<string, CommandOptions>;
 	shortcuts: string[];
 	tools: ToolDefinition[];
+	/** Every registered tool, as `getAllTools` reports it. */
+	allTools: ToolInfo[];
 	providers: { name: string; config: unknown }[];
 	renderers: Map<string, EntryRenderer>;
 	entries: { customType: string; data: unknown }[];
@@ -43,6 +59,7 @@ export function fakePi(bus: EventBus = createEventBus()): FakePi {
 		commands,
 		shortcuts: [],
 		tools: [],
+		allTools: [],
 		providers: [],
 		renderers: new Map(),
 		entries: [],
@@ -67,6 +84,7 @@ export function fakePi(bus: EventBus = createEventBus()): FakePi {
 		registerCommand: (name: string, options: CommandOptions) => void commands.set(name, options),
 		registerShortcut: (shortcut: unknown) => void fake.shortcuts.push(String(shortcut)),
 		registerTool: (tool: ToolDefinition) => void fake.tools.push(tool),
+		getAllTools: () => fake.allTools,
 		registerProvider: (name: unknown, config?: unknown) =>
 			void fake.providers.push({ name: String(name), config }),
 		registerEntryRenderer: (customType: string, renderer: EntryRenderer) =>
@@ -85,6 +103,10 @@ export interface FakeScopeOptions {
 	/** Collects what the feature warned about. */
 	notes?: string[];
 	settingsPath?: string;
+	/** Collects the rows the feature adds to the settings screen. */
+	screen?: ScreenEntry[];
+	/** Collects the row providers, for the screen to run. */
+	screenGroups?: ScreenGroup[];
 }
 
 /**
@@ -95,6 +117,8 @@ export interface FakeScopeOptions {
 export function fakeScope(options: FakeScopeOptions = {}): FeatureScope {
 	const fake = options.pi ?? fakePi();
 	const notes = options.notes ?? [];
+	const rows = options.screen ?? [];
+	const groups = options.screenGroups ?? [];
 	const settings = new SettingsStore(
 		options.settingsPath ?? join(tmpdir(), `pi-kit-scope-${process.pid}-${Math.random()}.json`),
 	);
@@ -109,6 +133,12 @@ export function fakeScope(options: FakeScopeOptions = {}): FeatureScope {
 		onShutdown: (run) => void fake.pi.on("session_shutdown", () => run()),
 		warn: (message) => void notes.push(message),
 		has: () => false,
+		screen: {
+			value: (row) => void rows.push({ kind: "value", ...row }),
+			action: (row) => void rows.push({ kind: "action", ...row }),
+			info: (row) => void rows.push({ kind: "info", ...row }),
+			rows: (provider) => void groups.push(provider),
+		},
 	};
 }