@adeildo/pi-kit 4.0.0 → 5.0.0

package/src/contracts/screen.ts

@@ -0,0 +1,71 @@
+// In the harness every piece is an extension of its own, so the screen asks them over pi.events.
+// The bus is synchronous: an app answers by writing on the payload, like the claim.
+import type { Control, Json } from "../control.ts";
+import type { Layer } from "../settings/store.ts";
+
+export const LIST = "harness:screen:list";
+export const APPLY = "harness:screen:apply";
+export const RUN = "harness:screen:run";
+export const DONE = "harness:screen:done";
+export const CHANGED = "harness:settings:changed";
+
+export type RowKind = "setting" | "value" | "action" | "info";
+
+export interface RowView {
+	feature: string;
+	id: string;
+	kind: RowKind;
+	section: string;
+	label: string;
+	description: string;
+	control?: Control;
+	value?: Json;
+	text?: string;
+	confirm?: string;
+	/** How deep the row sits under its section. Each step indents two columns. */
+	indent?: number;
+	/** Where a value row applies, when that is not this session. */
+	meta?: string;
+	layer?: Layer;
+	fallback?: Json;
+	/** The global value a project value hides. */
+	hidden?: Json;
+	restart?: boolean;
+}
+
+export interface TabView {
+	title: string;
+	sections: string[];
+	rows: RowView[];
+}
+
+export interface ListRequest {
+	tabs: TabView[];
+}
+
+/** `unset` drops the value that wins, so the one below shows. */
+export interface ApplyRequest {
+	feature: string;
+	id: string;
+	op: "set" | "unset";
+	value?: Json;
+	answer?: { error?: string };
+}
+
+export interface RunRequest {
+	feature: string;
+	id: string;
+	request: string;
+	answer?: { error?: string };
+}
+
+export interface RunDone {
+	request: string;
+	text?: string;
+	error?: string;
+}
+
+export interface Changed {
+	/** The store that wrote, so it skips its own write. */
+	source: string;
+}

package/src/control.ts

@@ -0,0 +1,59 @@
+// How the settings screen edits a value. Plain JSON, because the screen may live in another package.
+export type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+
+export interface ControlOption {
+	value: Json;
+	label?: string;
+	description?: string;
+}
+
+export type Control =
+	| { type: "toggle" }
+	| { type: "choice"; options: ControlOption[]; custom?: boolean }
+	| { type: "number"; min?: number; max?: number; step?: number; unit?: string; nullable?: boolean }
+	| { type: "text"; multiline?: boolean; presets?: ControlOption[] }
+	| { type: "list"; options?: ControlOption[] };
+
+export function formatValue(control: Control, value: Json | undefined): string {
+	if (value === undefined || value === null) return control.type === "number" ? "none" : "";
+	switch (control.type) {
+		case "toggle":
+			return value === true ? "on" : "off";
+		case "choice":
+			return optionLabel(control.options, value);
+		case "number":
+			return control.unit === undefined ? String(value) : `${value}${control.unit}`;
+		case "text":
+			if (typeof value !== "string") return JSON.stringify(value);
+			if (control.presets !== undefined) {
+				const preset = control.presets.find((option) => option.value === value);
+				if (preset !== undefined) return preset.label ?? String(preset.value);
+				if (value.trim() === "") return "(empty)";
+				return "custom";
+			}
+			return firstLine(value);
+		case "list":
+			if (!Array.isArray(value)) return JSON.stringify(value);
+			if (value.length === 0) return "(none)";
+			return value.map((entry) => optionLabel(control.options ?? [], entry)).join(", ");
+	}
+}
+
+export function optionLabel(options: readonly ControlOption[], value: Json): string {
+	const option = options.find((entry) => sameJson(entry.value, value));
+	return optionText(option ?? { value });
+}
+
+export function optionText(option: ControlOption): string {
+	if (option.label !== undefined) return option.label;
+	return typeof option.value === "string" ? option.value : JSON.stringify(option.value);
+}
+
+export function sameJson(left: unknown, right: unknown): boolean {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function firstLine(text: string): string {
+	const line = text.split("\n")[0] ?? "";
+	return text.includes("\n") ? `${line} …` : line;
+}

package/src/decode.ts

@@ -1,5 +1,8 @@
 // Decoders for everything that comes from outside: settings files and event payloads from other
-// packages. The only module that inspects `typeof`, and no decoder throws.
+// packages. The only module that inspects `typeof`, and no decoder throws. `control` is how the
+// settings screen edits the value.
+import type { Control } from "./control.ts";
+
 export interface Problem {
 	path: string;
 	message: string;
@@ -11,6 +14,7 @@ export type Decoded<T> =
 
 export interface Decoder<T> {
 	decode(input: unknown, path: string): Decoded<T>;
+	control?: Control;
 }
 
 export function pass<T>(value: T, problems: Problem[] = []): Decoded<T> {
@@ -38,12 +42,14 @@ export function isObject(input: unknown): input is Record<string, unknown> {
 }
 
 export const string: Decoder<string> = {
+	control: { type: "text" },
 	decode(input, path) {
 		return typeof input === "string" ? pass(input) : fail(problem(path, "expected a string"));
 	},
 };
 
 export const trimmedString: Decoder<string> = {
+	control: { type: "text" },
 	decode(input, path) {
 		if (typeof input !== "string" || input.trim() === "")
 			return fail(problem(path, "expected a non-empty string"));
@@ -52,12 +58,14 @@ export const trimmedString: Decoder<string> = {
 };
 
 export const boolean: Decoder<boolean> = {
+	control: { type: "toggle" },
 	decode(input, path) {
 		return typeof input === "boolean" ? pass(input) : fail(problem(path, "expected a boolean"));
 	},
 };
 
 export const unit: Decoder<number> = {
+	control: { type: "number", min: 0, max: 1, step: 0.05 },
 	decode(input, path) {
 		if (typeof input !== "number" || !Number.isFinite(input) || input < 0 || input > 1)
 			return fail(problem(path, "expected a number from 0 to 1"));
@@ -66,6 +74,7 @@ export const unit: Decoder<number> = {
 };
 
 export const duration: Decoder<number> = {
+	control: { type: "number", min: 0, step: 500, unit: "ms" },
 	decode(input, path) {
 		if (typeof input !== "number" || !Number.isFinite(input) || input < 0)
 			return fail(problem(path, "expected a non-negative number of milliseconds"));
@@ -76,6 +85,7 @@ export const duration: Decoder<number> = {
 /** A whole number from `min` to `max`, inclusive. */
 export function integer(min: number, max: number): Decoder<number> {
 	return {
+		control: { type: "number", min, max, step: 1 },
 		decode(input, path) {
 			if (typeof input !== "number" || !Number.isInteger(input) || input < min || input > max) {
 				return fail(problem(path, `expected a whole number from ${min} to ${max}`));
@@ -88,6 +98,7 @@ export function integer(min: number, max: number): Decoder<number> {
 /** A string that matches `pattern`, described to the user as `expected`. */
 export function matching(pattern: RegExp, expected: string): Decoder<string> {
 	return {
+		control: { type: "text" },
 		decode(input, path) {
 			if (typeof input === "string" && pattern.test(input)) return pass(input);
 			return fail(problem(path, `expected ${expected}`));
@@ -98,6 +109,7 @@ export function matching(pattern: RegExp, expected: string): Decoder<string> {
 export function literal<const T extends readonly string[]>(...values: T): Decoder<T[number]> {
 	const expected = values.map((value) => `"${value}"`).join(" or ");
 	return {
+		control: { type: "choice", options: values.map((value) => ({ value })) },
 		decode(input, path) {
 			if (typeof input === "string" && (values as readonly string[]).includes(input))
 				return pass(input as T[number]);
@@ -107,7 +119,10 @@ export function literal<const T extends readonly string[]>(...values: T): Decode
 }
 
 export function nullable<T>(inner: Decoder<T>): Decoder<T | null> {
+	const control: Control | undefined =
+		inner.control?.type === "number" ? { ...inner.control, nullable: true } : inner.control;
 	return {
+		control,
 		decode(input, path) {
 			return input === null ? pass(null) : inner.decode(input, path);
 		},
@@ -116,6 +131,7 @@ export function nullable<T>(inner: Decoder<T>): Decoder<T | null> {
 
 export function withDefaultOf<T>(inner: Decoder<T>, fallback: () => T): Decoder<T> {
 	return {
+		control: inner.control,
 		decode(input, path) {
 			if (input === undefined) return pass(fallback());
 			const result = inner.decode(input, path);
@@ -133,6 +149,7 @@ export function stringList(expected: string): Decoder<string[]> {
 	const dropped = "ignored entries that are not non-empty strings";
 
 	return {
+		control: { type: "list" },
 		decode(input, path) {
 			if (!Array.isArray(input)) return fail(problem(path, notAList));
 
@@ -155,6 +172,7 @@ export function stringListOrEmpty(
 ): Decoder<string[]> {
 	const parse = stringList(expected);
 	return {
+		control: parse.control,
 		decode(input, path) {
 			if (input === undefined) return pass([...fallback]);
 			const result = parse.decode(input, path);

package/src/index.ts

@@ -1,7 +1,16 @@
+export { askQuestions, canAsk } from "./ask/client.ts";
 export * from "./app/builder.ts";
 export * from "./app/feature.ts";
+export * from "./contracts/ask.ts";
+export * from "./contracts/screen.ts";
+export * from "./control.ts";
 export * from "./decode.ts";
 export * from "./events.ts";
-export { globalSettingsPath, projectSettingsPath } from "./settings/files.ts";
+export {
+	globalSettingsPath,
+	projectSettingsPath,
+	readSettingsFile,
+	writeSettingsFile,
+} from "./settings/files.ts";
 export * from "./settings/setting.ts";
 export * from "./settings/store.ts";

package/src/screen/client.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+	APPLY,
+	type ApplyRequest,
+	DONE,
+	LIST,
+	type ListRequest,
+	type RowView,
+	RUN,
+	type RunDone,
+	type RunRequest,
+	type TabView,
+} from "../contracts/screen.ts";
+import type { Json } from "../control.ts";
+import { isObject } from "../decode.ts";
+
+type Events = ExtensionAPI["events"];
+
+/** Tabs with the same title, from features of different packages, become one. */
+export function listTabs(events: Events): TabView[] {
+	const request: ListRequest = { tabs: [] };
+	events.emit(LIST, request);
+
+	const merged: TabView[] = [];
+	for (const tab of request.tabs) {
+		if (tab.rows.length === 0) continue;
+		const same = merged.find((entry) => entry.title === tab.title);
+		if (same === undefined) {
+			merged.push({ title: tab.title, sections: [...tab.sections], rows: [...tab.rows] });
+			continue;
+		}
+		for (const section of tab.sections)
+			if (!same.sections.includes(section)) same.sections.push(section);
+		same.rows.push(...tab.rows);
+	}
+	return merged;
+}
+
+/** Returns why the change was refused. */
+export function applyRow(
+	events: Events,
+	row: RowView,
+	op: ApplyRequest["op"],
+	value?: Json,
+): string | undefined {
+	const request: ApplyRequest = { feature: row.feature, id: row.id, op };
+	if (value !== undefined) request.value = value;
+	events.emit(APPLY, request);
+	if (request.answer === undefined) return `${row.feature} is not running`;
+	return request.answer.error;
+}
+
+export function runRow(events: Events, row: RowView): Promise<Omit<RunDone, "request">> {
+	const id = crypto.randomUUID();
+	return new Promise((resolve) => {
+		const stop = events.on(DONE, (data) => {
+			if (!isObject(data) || data.request !== id) return;
+			stop();
+			resolve({
+				...(typeof data.text === "string" ? { text: data.text } : {}),
+				...(typeof data.error === "string" ? { error: data.error } : {}),
+			});
+		});
+
+		const request: RunRequest = { feature: row.feature, id: row.id, request: id };
+		events.emit(RUN, request);
+		const refused =
+			request.answer === undefined ? `${row.feature} is not running` : request.answer.error;
+		if (refused !== undefined) {
+			stop();
+			resolve({ error: refused });
+		}
+	});
+}

package/src/screen/feature.ts

@@ -0,0 +1,61 @@
+// Every app brings this feature, and the claim keeps the first copy.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+
+import type { Feature, FeatureScope } from "../app/feature.ts";
+import { formatValue } from "../control.ts";
+import { applyRow, listTabs } from "./client.ts";
+import { ScreenModel } from "./model.ts";
+import { type ScreenResult, ScreenView } from "./view.ts";
+
+export const settingsScreen: Feature = {
+	id: "settings-screen",
+	description: "One screen for every setting of the harness",
+	setup(scope) {
+		scope.registerCommand("harness", {
+			description: "Settings for every harness piece (also Alt+S)",
+			getArgumentCompletions: (prefix) => {
+				const typed = prefix.trim().toLowerCase();
+				const tabs = listTabs(scope.events).map((tab) => tab.title.toLowerCase());
+				const matches = tabs.filter((tab) => tab.startsWith(typed));
+				return matches.length === 0 ? null : matches.map((tab) => ({ value: tab, label: tab }));
+			},
+			handler: (args, ctx) => openScreen(scope, ctx, args),
+		});
+		scope.registerShortcut(Key.alt("s"), {
+			description: "Settings for every harness piece",
+			handler: (ctx) => openScreen(scope, ctx, ""),
+		});
+	},
+};
+
+async function openScreen(scope: FeatureScope, ctx: ExtensionContext, tab: string): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("the settings screen needs the interactive terminal", "warning");
+		return;
+	}
+	const model = new ScreenModel(listTabs(scope.events));
+	if (tab.trim() !== "") model.openTab(tab);
+
+	// The editor for long text is pi's own, so the screen closes for it and opens where it was.
+	for (;;) {
+		// oxlint-disable-next-line no-await-in-loop -- one screen at a time
+		const result = await ctx.ui.custom<ScreenResult>(
+			(tui, theme, _keybindings, done) =>
+				new ScreenView({ tui, theme, events: scope.events, model, done }),
+			{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left" } },
+		);
+		if (result?.kind !== "edit") return;
+
+		const row = result.row;
+		const current = typeof row.value === "string" ? row.value : "";
+		// oxlint-disable-next-line no-await-in-loop -- the screen waits for the editor
+		const text = await ctx.ui.editor(row.label, current);
+		if (text !== undefined && text !== current) {
+			const error = applyRow(scope.events, row, "set", text);
+			const shown = row.control === undefined ? "" : formatValue(row.control, text);
+			ctx.ui.notify(error ?? `${row.label}: ${shown}`, error === undefined ? "info" : "error");
+		}
+		model.refresh(listTabs(scope.events));
+	}
+}

package/src/screen/model.ts

@@ -0,0 +1,173 @@
+import { fuzzyFilter } from "@earendil-works/pi-tui";
+
+import type { RowView, TabView } from "../contracts/screen.ts";
+
+export type Line = { kind: "heading"; title: string } | { kind: "row"; row: RowView; tab: string };
+
+export interface SectionMark {
+	title: string;
+	active: boolean;
+}
+
+export class ScreenModel {
+	tabs: TabView[];
+	tab = 0;
+	query = "";
+	#cursor: string | undefined;
+
+	constructor(tabs: TabView[]) {
+		this.tabs = tabs;
+		this.#cursor = this.#firstKey();
+	}
+
+	get searching(): boolean {
+		return this.query !== "";
+	}
+
+	/** Keeps the tab and the row under the cursor. */
+	refresh(tabs: TabView[]): void {
+		const title = this.tabs[this.tab]?.title;
+		this.tabs = tabs;
+		const index = tabs.findIndex((entry) => entry.title === title);
+		this.tab = index === -1 ? 0 : index;
+		if (this.#index() === -1) this.#cursor = this.#firstKey();
+	}
+
+	lines(): Line[] {
+		return this.searching ? this.#results() : this.#tabLines();
+	}
+
+	selected(): Extract<Line, { kind: "row" }> | undefined {
+		const line = this.lines()[this.#index()];
+		return line?.kind === "row" ? line : undefined;
+	}
+
+	cursorLine(): number {
+		return this.#index();
+	}
+
+	move(delta: number): void {
+		const rows = this.#rowIndexes();
+		if (rows.length === 0) return;
+		const at = rows.indexOf(this.#index());
+		const next = Math.min(rows.length - 1, Math.max(0, (at === -1 ? 0 : at) + delta));
+		this.#select(rows[next]);
+	}
+
+	moveToEdge(edge: "first" | "last"): void {
+		const rows = this.#rowIndexes();
+		this.#select(edge === "first" ? rows[0] : rows.at(-1));
+	}
+
+	jumpSection(direction: 1 | -1): void {
+		const lines = this.lines();
+		const starts: number[] = [];
+		lines.forEach((line, index) => {
+			if (line.kind === "heading" && lines[index + 1]?.kind === "row") starts.push(index + 1);
+		});
+		if (starts.length === 0) return;
+
+		const at = this.#index();
+		const current = starts.findLastIndex((start) => start <= at);
+		const next = (current + direction + starts.length) % starts.length;
+		this.#select(starts[next]);
+	}
+
+	switchTab(delta: number): void {
+		if (this.searching || this.tabs.length === 0) return;
+		this.tab = (this.tab + delta + this.tabs.length) % this.tabs.length;
+		this.#cursor = this.#firstKey();
+	}
+
+	openTab(title: string): boolean {
+		const wanted = title.trim().toLowerCase();
+		const index = this.tabs.findIndex((entry) => entry.title.toLowerCase().startsWith(wanted));
+		if (index === -1) return false;
+		this.tab = index;
+		this.#cursor = this.#firstKey();
+		return true;
+	}
+
+	setQuery(query: string): void {
+		this.query = query;
+		this.#cursor = this.#firstKey();
+	}
+
+	sections(): SectionMark[] {
+		const lines = this.lines();
+		const at = this.#index();
+		let active = "";
+		lines.forEach((line, index) => {
+			if (line.kind === "heading" && index <= at) active = line.title;
+		});
+		return lines
+			.filter((line): line is Extract<Line, { kind: "heading" }> => line.kind === "heading")
+			.map((line) => ({ title: line.title, active: line.title === active }));
+	}
+
+	#tabLines(): Line[] {
+		const tab = this.tabs[this.tab];
+		if (tab === undefined) return [];
+		const lines: Line[] = [];
+		for (const section of tab.sections) {
+			const rows = tab.rows.filter((row) => row.section === section);
+			if (rows.length === 0) continue;
+			lines.push({ kind: "heading", title: section });
+			for (const row of rows) lines.push({ kind: "row", row, tab: tab.title });
+		}
+		return lines;
+	}
+
+	#results(): Line[] {
+		const all = this.tabs.flatMap((tab) => tab.rows.map((row) => ({ row, tab: tab.title })));
+		// The query picks the rows. The order stays the tab's.
+		const matched = new Set(
+			fuzzyFilter(all, this.query, ({ row, tab }) =>
+				[row.label, row.section, tab, row.id].join(" "),
+			),
+		);
+		const found = all.filter((hit) => matched.has(hit));
+
+		const groups = new Map<string, typeof found>();
+		for (const hit of found) {
+			const title = `${hit.tab} \u203a ${hit.row.section}`;
+			groups.set(title, [...(groups.get(title) ?? []), hit]);
+		}
+		const lines: Line[] = [];
+		for (const [title, hits] of groups) {
+			lines.push({ kind: "heading", title });
+			for (const hit of hits) lines.push({ kind: "row", ...hit });
+		}
+		return lines;
+	}
+
+	#rowIndexes(): number[] {
+		const indexes: number[] = [];
+		this.lines().forEach((line, index) => {
+			if (line.kind === "row") indexes.push(index);
+		});
+		return indexes;
+	}
+
+	#index(): number {
+		if (this.#cursor === undefined) return -1;
+		return this.lines().findIndex(
+			(line) => line.kind === "row" && keyOf(line.row) === this.#cursor,
+		);
+	}
+
+	#select(index: number | undefined): void {
+		if (index === undefined) return;
+		const line = this.lines()[index];
+		if (line?.kind === "row") this.#cursor = keyOf(line.row);
+	}
+
+	#firstKey(): string | undefined {
+		const line = this.lines().find((entry) => entry.kind === "row");
+		return line?.kind === "row" ? keyOf(line.row) : undefined;
+	}
+}
+
+export function keyOf(row: RowView): string {
+	return `${row.feature}\u0000${row.id}`;
+}