@adeildo/pi-kit 4.1.0 → 5.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@adeildo/pi-kit)](https://www.npmjs.com/package/@adeildo/pi-kit)
 
-What [`@adeildo/pi-ask-permission`](../ask-permission) and [`@adeildo/pi-harness`](../harness) are built on. It's a library, not a Pi package, so installing it adds nothing to Pi. It's on npm because both packages need it at runtime, and its API follows what they need, with no promise to anyone else.
+What [`@adeildo/pi-ask-permission`](../ask-permission) and [`@adeildo/pi-harness`](../harness) are built on. It's a library, not a Pi package. The one thing it adds to Pi is the settings screen. It's on npm because the packages need it at runtime, and its API follows what they need, with no promise to anyone else.
 
 ## An app, and features in it
 
@@ -44,6 +44,7 @@ Each extension a package declares is one app with one or more features. The app'
 | `scope.registerCommand` | `pi.registerCommand`. If another feature in the same app already took the name, this one is skipped with a warning.                                                                                      |
 | `scope.onSessionStart`  | Runs once the session's settings are loaded. Anything that lasts, like a watcher, a server or a child process, starts here and never in `setup`.                                                         |
 | `scope.onShutdown`      | Runs once per session, newest first, even when pi fires `session_shutdown` twice.                                                                                                                        |
+| `scope.screen`          | Rows on the settings screen that are not settings. See below.                                                                                                                                            |
 | `scope.warn`            | Shows a notification when there's a UI and writes to stderr when there isn't. Messages sent before a session starts are held until it does.                                                              |
 | everything else         | The scope **is** the extension API, so `scope.registerTool`, `scope.appendEntry`, `scope.events` and the rest work as they always did.                                                                   |
 
@@ -59,6 +60,39 @@ A setting declared with `project: true` also reads `<project>/.pi/extensions/pi-
 
 A value that fails to decode is ignored, and the warning names the file and the key.
 
+## The settings screen
+
+`Alt+S` or `/harness` opens it. Each feature is a tab, and the rows come from two places.
+
+A setting with a `ui` gets a row:
+
+```ts
+export const cursor = setting({
+	id: "look.frame.cursor",
+	default: "bar",
+	decoder: literal("block", "bar", "underline"),
+	ui: { section: "Editor", label: "Cursor", description: "The editor's cursor." },
+});
+```
+
+The decoder picks the editor. `boolean` is a toggle, `literal` a choice, `integer` a number, `stringList` a list. Set `ui.control` to label the options or add presets.
+
+Anything else goes through `scope.screen`: `value` for session state, `action` for something to run, `info` for a fact.
+
+```ts
+scope.screen.action({
+	id: "judge.test",
+	section: "Judge",
+	label: "Test the judge",
+	description: "Sends one real request.",
+	run: (ctx) => probe(ctx),
+});
+```
+
+A value typed on the screen goes through the same decoder as the file. Feature options `tab` and `sections` set the tab name and the section order.
+
+## Turning a feature off
+
 Every feature also gets `features.<id>.enabled`, which defaults to on. A feature that's off never runs `setup`, so it registers nothing and costs nothing. The change takes effect on the next `/reload`.
 
 ## Events and contracts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adeildo/pi-kit",
-	"version": "4.1.0",
+	"version": "5.1.0",
 	"description": "The app builder, settings and events that pi-harness packages are built on.",
 	"license": "MIT",
 	"author": {
@@ -27,6 +27,7 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
 	}
 }

package/src/app/builder.ts

@@ -4,13 +4,16 @@
 // session, and a feature that fails to set up becomes a warning.
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { boolean } from "../decode.ts";
+import { CHANGED } from "../contracts/screen.ts";
+import { boolean, isObject } from "../decode.ts";
+import { settingsScreen } from "../screen/feature.ts";
 import { globalSettingsPath, projectSettingsPath } from "../settings/files.ts";
 import { type Setting, type SettingsScope, setting } from "../settings/setting.ts";
 import { SettingsStore } from "../settings/store.ts";
 import { describe } from "./attribution.ts";
 import { answerClaims, ownerOf } from "./claim.ts";
 import type { Feature } from "./feature.ts";
+import { serveScreen } from "./host.ts";
 import { type AppState, createScope, type Hook } from "./scope.ts";
 
 export interface App extends SettingsScope {
@@ -48,7 +51,6 @@ export function enabledSetting(feature: Feature): Setting<boolean> {
 		id: `features.${feature.id}.enabled`,
 		default: true,
 		decoder: boolean,
-		ui: { group: "Features", label: feature.id, description: feature.description },
 	});
 }
 
@@ -73,11 +75,31 @@ function mount(pi: ExtensionAPI, options: AppOptions, features: readonly Feature
 		commands: new Map(),
 		starts: [],
 		shutdowns: [],
+		screen: new Map(),
+		screenGroups: new Map(),
 		report: (source, message) => deliver(`${options.name}: ${source}: ${message}`),
 	};
 	const app: App = { name: options.name, settings, has: (id) => mounted.has(id) };
+	const running: Feature[] = [];
 
 	answerClaims(pi, options.name, mounted, () => live);
+	serveScreen({
+		pi,
+		settings,
+		features: () => running,
+		screen: state.screen,
+		screenGroups: state.screenGroups,
+		session: () => session,
+		isLive: () => live,
+	});
+
+	// Every app writes the same files, so a write by one is read again by the others.
+	const store = crypto.randomUUID();
+	settings.onWrite(() => pi.events.emit(CHANGED, { source: store }));
+	pi.events.on(CHANGED, (data) => {
+		if (!live || !isObject(data) || data.source === store) return;
+		for (const line of settings.load(settings.projectPath)) state.report("settings", line);
+	});
 
 	// Registered first, so these run ahead of the features' own handlers.
 	pi.on("session_start", async (_event, ctx) => {
@@ -108,10 +130,9 @@ function mount(pi: ExtensionAPI, options: AppOptions, features: readonly Feature
 		session = undefined;
 	});
 
-	// All the switches first: one read of the file decides what is on, and a feature that is off
-	// still shows up on the settings screen.
+	// All the switches first, so one read of the file decides what is on.
 	const candidates: { feature: Feature; enabled: Setting<boolean> }[] = [];
-	for (const feature of features) {
+	for (const feature of [settingsScreen, ...features]) {
 		if (candidates.some((candidate) => candidate.feature.id === feature.id)) {
 			state.report(feature.id, "was added to this app twice; keeping the first");
 			continue;
@@ -130,13 +151,16 @@ function mount(pi: ExtensionAPI, options: AppOptions, features: readonly Feature
 
 		const owner = ownerOf(pi, feature.id);
 		if (owner !== undefined) {
-			state.report(feature.id, `already loaded by ${owner}, so this copy stays off`);
+			// Every app brings the screen, and one is enough.
+			if (feature !== settingsScreen)
+				state.report(feature.id, `already loaded by ${owner}, so this copy stays off`);
 			continue;
 		}
 
 		try {
 			feature.setup(createScope(state, feature.id));
 			mounted.add(feature.id);
+			running.push(feature);
 		} catch (error) {
 			state.report(feature.id, `failed to set up: ${describe(error)}`);
 		}

package/src/app/feature.ts

@@ -4,6 +4,7 @@ import type {
 	RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
 
+import type { Control, Json } from "../control.ts";
 import type { Setting, SettingsScope } from "../settings/setting.ts";
 import type { SettingsStore } from "../settings/store.ts";
 
@@ -16,6 +17,10 @@ export interface Feature {
 	id: string;
 	/** One line for the settings screen. */
 	description: string;
+	/** The settings tab. Features with the same tab share it. Defaults to the id. */
+	tab?: string;
+	/** Section order on the tab. Sections not listed come after. */
+	sections?: readonly string[];
 	settings?: readonly Setting<unknown>[];
 	/** Registers handlers, commands and providers. Starts nothing: that goes in `onSessionStart`. */
 	setup(scope: FeatureScope): void;
@@ -37,6 +42,52 @@ export interface FeatureScope extends ExtensionAPI, SettingsScope {
 	warn(message: string): void;
 	/** True when this app runs a feature with that id. */
 	has(featureId: string): boolean;
+	readonly screen: ScreenRows;
+}
+
+interface ScreenRow {
+	id: string;
+	section: string;
+	label: string;
+	description: string;
+	/** How deep the row sits under its section. Each step indents two columns. */
+	indent?: number;
+}
+
+export interface ScreenValue extends ScreenRow {
+	control: Control | ((ctx: ExtensionContext) => Control);
+	get(ctx: ExtensionContext): Json;
+	/** Returns why the value was refused. */
+	set(value: Json, ctx: ExtensionContext): string | undefined;
+	/** Where the value applies, when that is not this session. */
+	meta?: string;
+}
+
+export interface ScreenAction extends ScreenRow {
+	text?(ctx: ExtensionContext): string;
+	confirm?: string;
+	/** Returned text opens in the screen. A throw shows as an error. */
+	run(ctx: ExtensionContext): string | undefined | Promise<string | undefined>;
+}
+
+export interface ScreenInfo extends ScreenRow {
+	text(ctx: ExtensionContext): string;
+}
+
+export type ScreenEntry =
+	| ({ kind: "value" } & ScreenValue)
+	| ({ kind: "action" } & ScreenAction)
+	| ({ kind: "info" } & ScreenInfo);
+
+/** Rows a feature builds when the screen opens, for what is only known then. */
+export type ScreenGroup = (ctx: ExtensionContext) => ScreenEntry[];
+
+export interface ScreenRows {
+	value(row: ScreenValue): void;
+	action(row: ScreenAction): void;
+	info(row: ScreenInfo): void;
+	/** One call, many rows: the provider runs every time the screen opens. */
+	rows(provider: ScreenGroup): void;
 }
 
 export function defineFeature(feature: Feature): Feature {

package/src/app/host.ts

@@ -0,0 +1,212 @@
+// Each app answers the screen for the features it runs. A change goes through the setting's own
+// decoder, like a value read from the file.
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+	APPLY,
+	type ApplyRequest,
+	DONE,
+	LIST,
+	type RowView,
+	RUN,
+	type RunDone,
+	type RunRequest,
+	type TabView,
+} from "../contracts/screen.ts";
+import type { Json } from "../control.ts";
+import { formatProblems, isObject } from "../decode.ts";
+import { controlOf, type Setting } from "../settings/setting.ts";
+import type { SettingsStore } from "../settings/store.ts";
+import type { Feature, ScreenEntry, ScreenGroup } from "./feature.ts";
+
+export interface Host {
+	pi: ExtensionAPI;
+	settings: SettingsStore;
+	features: () => readonly Feature[];
+	screen: ReadonlyMap<string, ScreenEntry[]>;
+	/** Rows a feature builds when the screen opens. */
+	screenGroups: ReadonlyMap<string, ScreenGroup[]>;
+	session: () => ExtensionContext | undefined;
+	isLive: () => boolean;
+}
+
+export function serveScreen(host: Host): void {
+	host.pi.events.on(LIST, (data) => {
+		if (!host.isLive() || !isObject(data) || !Array.isArray(data.tabs)) return;
+		const ctx = host.session();
+		for (const feature of host.features()) data.tabs.push(tabOf(host, feature, ctx));
+	});
+
+	host.pi.events.on(APPLY, (data) => {
+		const request = asApply(data);
+		if (request === undefined || !host.isLive()) return;
+		const feature = host.features().find((entry) => entry.id === request.feature);
+		if (feature === undefined) return;
+		request.answer = { error: apply(host, feature, request) };
+	});
+
+	host.pi.events.on(RUN, (data) => {
+		const request = asRun(data);
+		if (request === undefined || !host.isLive()) return;
+		if (!host.features().some((entry) => entry.id === request.feature)) return;
+		const ctx = host.session();
+		const row = findRow(host, request.feature, request.id, ctx);
+		if (row === undefined) return;
+
+		if (row.kind !== "action" || ctx === undefined) {
+			request.answer = { error: "nothing to run" };
+			return;
+		}
+		request.answer = {};
+		const id = request.request;
+		void runAction(row, ctx).then((done) => host.pi.events.emit(DONE, { request: id, ...done }));
+	});
+}
+
+function tabOf(host: Host, feature: Feature, ctx: ExtensionContext | undefined): TabView {
+	const rows: RowView[] = [];
+	for (const entry of feature.settings ?? []) {
+		const row = settingRow(host.settings, feature, entry, ctx);
+		if (row !== undefined) rows.push(row);
+	}
+	if (ctx !== undefined) {
+		for (const entry of entriesOf(host, feature.id, ctx)) rows.push(screenRow(feature, entry, ctx));
+	}
+
+	const sections = [...(feature.sections ?? [])];
+	for (const row of rows) if (!sections.includes(row.section)) sections.push(row.section);
+	return { title: feature.tab ?? capitalize(feature.id), sections, rows };
+}
+
+function settingRow(
+	settings: SettingsStore,
+	feature: Feature,
+	entry: Setting<unknown>,
+	ctx: ExtensionContext | undefined,
+): RowView | undefined {
+	const ui = entry.ui;
+	if (ui === undefined) return undefined;
+
+	const control = controlOf(entry, ctx);
+	const value = toJson(settings.get(entry));
+	const layer = settings.layer(entry);
+	const row: RowView = {
+		feature: feature.id,
+		id: entry.id,
+		kind: control === undefined ? "info" : "setting",
+		section: ui.section,
+		label: ui.label,
+		description: ui.description,
+		value,
+		layer,
+		fallback: toJson(entry.default),
+	};
+	if (control === undefined) row.text = JSON.stringify(value);
+	else row.control = control;
+	if (layer === "project") row.hidden = toJson(settings.hidden(entry));
+	if (ui.restart === true) row.restart = true;
+	return row;
+}
+
+function screenRow(feature: Feature, entry: ScreenEntry, ctx: ExtensionContext): RowView {
+	const row: RowView = {
+		feature: feature.id,
+		id: entry.id,
+		kind: entry.kind,
+		section: entry.section,
+		label: entry.label,
+		description: entry.description,
+	};
+	if (entry.indent !== undefined) row.indent = entry.indent;
+	switch (entry.kind) {
+		case "value":
+			row.control = typeof entry.control === "function" ? entry.control(ctx) : entry.control;
+			row.value = entry.get(ctx);
+			if (entry.meta !== undefined) row.meta = entry.meta;
+			break;
+		case "action": {
+			const text = entry.text?.(ctx);
+			if (text !== undefined) row.text = text;
+			if (entry.confirm !== undefined) row.confirm = entry.confirm;
+			break;
+		}
+		case "info":
+			row.text = entry.text(ctx);
+			break;
+	}
+	return row;
+}
+
+function apply(host: Host, feature: Feature, request: ApplyRequest): string | undefined {
+	const entry = feature.settings?.find((candidate) => candidate.id === request.id);
+	if (entry !== undefined) {
+		if (request.op === "unset") {
+			const layer = host.settings.layer(entry);
+			return layer === "default" ? undefined : host.settings.unset(entry, layer);
+		}
+		const decoded = entry.decoder.decode(request.value, entry.id);
+		if (!decoded.ok) return formatProblems(decoded.problems).join("; ");
+		return host.settings.set(entry, decoded.value);
+	}
+
+	const ctx = host.session();
+	const row = findRow(host, feature.id, request.id, ctx);
+	if (row?.kind !== "value" || ctx === undefined) return "this row cannot change";
+	if (request.op === "unset") return "this row has no default to go back to";
+	return row.set(request.value ?? null, ctx);
+}
+
+/** The rows a feature has at this moment: the ones it declared, then the ones it builds. */
+function entriesOf(host: Host, feature: string, ctx: ExtensionContext): ScreenEntry[] {
+	return [
+		...(host.screen.get(feature) ?? []),
+		...(host.screenGroups.get(feature) ?? []).flatMap((group) => group(ctx)),
+	];
+}
+
+/** An action can sit on a built row too, so the lookup walks the same two places. */
+function findRow(
+	host: Host,
+	feature: string,
+	id: string,
+	ctx: ExtensionContext | undefined,
+): ScreenEntry | undefined {
+	if (ctx === undefined) return host.screen.get(feature)?.find((candidate) => candidate.id === id);
+	return entriesOf(host, feature, ctx).find((candidate) => candidate.id === id);
+}
+
+async function runAction(
+	row: Extract<ScreenEntry, { kind: "action" }>,
+	ctx: ExtensionContext,
+): Promise<Omit<RunDone, "request">> {
+	try {
+		const text = await row.run(ctx);
+		return text === undefined ? {} : { text };
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function asApply(data: unknown): ApplyRequest | undefined {
+	if (!isObject(data) || data.answer !== undefined) return undefined;
+	const { feature, id, op } = data;
+	if (typeof feature !== "string" || typeof id !== "string") return undefined;
+	if (op !== "set" && op !== "unset") return undefined;
+	return data as unknown as ApplyRequest;
+}
+
+function asRun(data: unknown): RunRequest | undefined {
+	if (!isObject(data) || data.answer !== undefined) return undefined;
+	const { feature, id, request } = data;
+	if (typeof feature !== "string" || typeof id !== "string" || typeof request !== "string")
+		return undefined;
+	return data as unknown as RunRequest;
+}
+
+function toJson(value: unknown): Json {
+	return value === undefined ? null : (JSON.parse(JSON.stringify(value)) as Json);
+}
+
+function capitalize(text: string): string {
+	return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/src/app/scope.ts

@@ -2,7 +2,13 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import type { SettingsStore } from "../settings/store.ts";
 import { attributed } from "./attribution.ts";
-import type { FeatureScope, SessionHook, ShutdownHook } from "./feature.ts";
+import type {
+	FeatureScope,
+	ScreenEntry,
+	ScreenGroup,
+	SessionHook,
+	ShutdownHook,
+} from "./feature.ts";
 
 export interface Hook<T> {
 	/** The feature that registered it, named when it fails. */
@@ -20,11 +26,24 @@ export interface AppState {
 	commands: Map<string, string>;
 	starts: Hook<SessionHook>[];
 	shutdowns: Hook<ShutdownHook>[];
+	screen: Map<string, ScreenEntry[]>;
+	screenGroups: Map<string, ScreenGroup[]>;
 	report(source: string, message: string): void;
 }
 
 export function createScope(state: AppState, featureId: string): FeatureScope {
 	const label = `${state.name}: ${featureId}`;
+	const rows: ScreenEntry[] = state.screen.get(featureId) ?? [];
+	state.screen.set(featureId, rows);
+	const groups: ScreenGroup[] = state.screenGroups.get(featureId) ?? [];
+	state.screenGroups.set(featureId, groups);
+	const add = (row: ScreenEntry): void => {
+		if (rows.some((entry) => entry.id === row.id)) {
+			state.report(featureId, `the screen row "${row.id}" was added twice; keeping the first`);
+			return;
+		}
+		rows.push(row);
+	};
 
 	return {
 		...state.pi,
@@ -47,6 +66,12 @@ export function createScope(state: AppState, featureId: string): FeatureScope {
 		onShutdown: (run) => state.shutdowns.push({ source: featureId, run }),
 		warn: (message) => state.report(featureId, message),
 		has: (id) => state.mounted.has(id),
+		screen: {
+			value: (row) => add({ kind: "value", ...row }),
+			action: (row) => add({ kind: "action", ...row }),
+			info: (row) => add({ kind: "info", ...row }),
+			rows: (provider) => void groups.push(provider),
+		},
 	} as FeatureScope;
 }
 

package/src/ask/client.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+	ANSWER,
+	ASK,
+	AVAILABLE,
+	type AskQuestion,
+	type AskRequest,
+	type AskResult,
+	isAskResult,
+} from "../contracts/ask.ts";
+import { isObject } from "../decode.ts";
+
+type Events = ExtensionAPI["events"];
+
+/** True when a feature in this process can draw a question right now. */
+export function canAsk(events: Events): boolean {
+	const probe = { available: false };
+	events.emit(AVAILABLE, probe);
+	return probe.available;
+}
+
+/**
+ * Asks, and resolves with the answer. Check `canAsk` first: with no provider listening, the promise
+ * never settles. A provider that is listening always answers, even when it fails.
+ */
+export function askQuestions(
+	events: Events,
+	questions: readonly AskQuestion[],
+): Promise<AskResult> {
+	const id = crypto.randomUUID();
+	return new Promise((resolve) => {
+		const stop = events.on(ANSWER, (data) => {
+			if (!isObject(data) || data.id !== id) return;
+			stop();
+			resolve(asResult(data.result));
+		});
+		const request: AskRequest = { id, questions: [...questions] };
+		events.emit(ASK, request);
+	});
+}
+
+export function asResult(value: unknown): AskResult {
+	if (!isAskResult(value))
+		return { answers: [], cancelled: true, error: "the answer did not decode" };
+	return value;
+}

package/src/contracts/ask.ts

@@ -0,0 +1,83 @@
+// One dialog for every question. The permission dialog used to ask in its own way, with its own
+// keys; now whoever needs an answer asks here and the questions feature draws it.
+//
+// The bus is synchronous, so a request carries an id and the answer arrives on a second channel,
+// like the screen's `run` does.
+import { isObject } from "../decode.ts";
+
+/** A provider answers this to say it can draw a question right now. */
+export const AVAILABLE = "harness:ask:available";
+export const ASK = "harness:ask";
+export const ANSWER = "harness:ask:answer";
+
+export interface AskOption {
+	label: string;
+	description?: string;
+	/** Shown beside the options while this one is focused. */
+	preview?: string;
+}
+
+export interface AskQuestion {
+	header: string;
+	question: string;
+	options: AskOption[];
+	multiSelect?: boolean;
+	/** A last row for an answer in the user's own words. On unless it is `false`. */
+	typed?: boolean;
+}
+
+export interface AskRequest {
+	id: string;
+	questions: AskQuestion[];
+	answer?: AskResult;
+}
+
+export interface AskNote {
+	option: string;
+	note: string;
+}
+
+export interface AskAnswer {
+	question: string;
+	header: string;
+	picked: string[];
+	typed?: string;
+	notes: AskNote[];
+}
+
+export interface AskResult {
+	answers: AskAnswer[];
+	cancelled: boolean;
+	error?: string;
+}
+
+export interface AnswerEvent {
+	id: string;
+	result: AskResult;
+}
+
+export function isAskResult(value: unknown): value is AskResult {
+	if (!isObject(value)) return false;
+	return Array.isArray(value.answers) && typeof value.cancelled === "boolean";
+}
+
+/** Why a request cannot be used, for a provider reading one from another version. */
+export function decodeAskRequest(value: unknown): string | undefined {
+	if (!isObject(value)) return "not an object";
+	if (typeof value.id !== "string") return "no id";
+	if (!Array.isArray(value.questions)) return "no questions";
+	for (const question of value.questions) {
+		if (!isObject(question)) return "a question is not an object";
+		if (typeof question.header !== "string" || typeof question.question !== "string")
+			return "a question has no header or text";
+		if (!Array.isArray(question.options) || question.options.length === 0)
+			return `"${question.header}" has no options`;
+		if (question.typed !== undefined && typeof question.typed !== "boolean")
+			return `"${question.header}" has a typed flag that is not a boolean`;
+		for (const option of question.options) {
+			if (!isObject(option) || typeof option.label !== "string")
+				return `"${question.header}" has an option with no label`;
+		}
+	}
+	return undefined;
+}