@huseynsnmz/pi-suite 0.1.0 → 0.2.0

package/packages/frame/src/kit/app/scope.ts

@@ -0,0 +1,125 @@
+import type { ExtensionAPI, MessageRenderer } from "@earendil-works/pi-coding-agent";
+
+import type { SettingsStore } from "../settings/store.ts";
+import { attributed } from "./attribution.ts";
+import { describe } from "./attribution.ts";
+import type {
+	FeatureScope,
+	ScreenEntry,
+	ScreenGroup,
+	SessionHook,
+	ShutdownHook,
+} from "./feature.ts";
+import { forgetRenderers, keepMessageRenderer, keepToolRenderer } from "./renderers.ts";
+
+export interface Hook<T> {
+	source: string;
+	run: T;
+}
+
+export interface AppState {
+	name: string;
+	pi: ExtensionAPI;
+	settings: SettingsStore;
+	mounted: ReadonlySet<string>;
+	commands: Map<string, string>;
+	starts: Hook<SessionHook>[];
+	shutdowns: Hook<ShutdownHook>[];
+	screen: Map<string, ScreenEntry[]>;
+	screenGroups: Map<string, ScreenGroup[]>;
+	live(): boolean;
+	/** Ends the session from inside a deferral a refused context was found in. */
+	stop(): void;
+	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);
+	forgetRenderers(featureId);
+	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,
+		id: featureId,
+		settings: state.settings,
+		on: attributedOn(state.pi, label),
+		registerCommand(name, options) {
+			const owner = state.commands.get(name);
+			if (owner !== undefined) {
+				state.report(featureId, `/${name} is already registered by ${owner}; skipped`);
+				return;
+			}
+			state.commands.set(name, featureId);
+			state.pi.registerCommand(name, {
+				...options,
+				handler: attributed(`${label}: /${name}`, options.handler),
+			});
+		},
+		registerToolRenderer(resolver) {
+			keepToolRenderer(featureId, resolver);
+			state.pi.registerToolRenderer(resolver);
+		},
+		registerMessageRenderer(customType, renderer) {
+			keepMessageRenderer(featureId, customType, renderer as MessageRenderer);
+			state.pi.registerMessageRenderer(customType, renderer);
+		},
+		defer(run, ms = 0) {
+			// `unref` only keeps a pending timer from holding the process open; the guard at the top
+			// of the callback is what keeps the work from running once the session is over.
+			setTimeout(() => {
+				if (!state.live()) return;
+				try {
+					run();
+				} catch (error) {
+					// The host takes the context away before it announces the shutdown, so `live` is
+					// still true here; its refusal is the only notice that the session is over.
+					if (refusedByHost(error)) {
+						state.stop();
+						return;
+					}
+					state.report(featureId, `deferred work failed: ${describe(error)}`);
+				}
+			}, ms).unref();
+		},
+		onSessionStart: (run) => state.starts.push({ source: featureId, run }),
+		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;
+}
+
+/** Pi's message for a stale context (`dist/core/extensions/runner.js` in 1.4.0). */
+const STALE = "stale after session replacement or reload";
+
+/** A session that ended announces itself by the host refusing its context. */
+function refusedByHost(error: unknown): boolean {
+	return error instanceof Error && error.message.includes(STALE);
+}
+
+type UntypedHandler = (...args: unknown[]) => unknown;
+type UntypedOn = (event: string, handler: UntypedHandler) => () => void;
+
+// pi.on has one overload per event and TypeScript cannot implement an overloaded signature
+// generically, so this is the one place that casts. Callers keep the exact overload types.
+function attributedOn(pi: ExtensionAPI, label: string): ExtensionAPI["on"] {
+	const on = pi.on.bind(pi) as unknown as UntypedOn;
+	const wrapped: UntypedOn = (event, handler) =>
+		on(event, attributed(`${label}: ${event}`, handler));
+	return wrapped as unknown as ExtensionAPI["on"];
+}

package/packages/frame/src/kit/board/model.ts

@@ -0,0 +1,337 @@
+// A session's board is a fold of its operations, so `/tree` and forks carry it and nothing merges.
+import type { By } from "../contracts/by.ts";
+import { isBy } from "../contracts/by.ts";
+import { isObject } from "../decode.ts";
+
+export type BoardColumn = "backlog" | "todo" | "doing" | "review" | "done" | "dropped";
+
+/** Names the thing, never the reader: `operator` reads "you" only on the operator's screen. */
+export type BoardBlocker = { why: string } & (
+	| { on: "operator" }
+	| { on: "outside" }
+	| { on: "agent"; handle: string }
+);
+
+export interface BoardCard {
+	id: string;
+	title: string;
+	column: BoardColumn;
+	pr?: number;
+	now?: string;
+	blocked?: BoardBlocker;
+	reviewer?: string;
+	result?: string;
+	why?: string;
+	at: number;
+}
+
+export interface BoardDecision {
+	id: string;
+	text: string;
+	by?: By;
+	at: number;
+}
+
+export interface Board {
+	next: number;
+	cards: BoardCard[];
+	decisions: BoardDecision[];
+}
+
+export type BoardOp =
+	| {
+			op: "add";
+			title: string;
+			column?: BoardColumn;
+			pr?: number;
+			blocked?: BoardBlocker;
+			at: number;
+	  }
+	| { op: "move"; id: string; column: BoardColumn; reviewer?: string; result?: string; at: number }
+	| {
+			op: "edit";
+			id: string;
+			title?: string;
+			pr?: number;
+			now?: string;
+			blocked?: BoardBlocker | null;
+			at: number;
+	  }
+	| { op: "drop"; id: string; why: string; at: number }
+	| { op: "decide"; text: string; by?: By; at: number };
+
+export type BoardResult = { ok: true; board: Board } | { ok: false; why: string };
+
+/** Who writes: the agent keeps the board small, the operator may go past the limits. */
+export type BoardWriter = "agent" | "operator";
+
+const IN_PROGRESS = 3;
+const OPEN = 15;
+const TITLE_WORDS = 8;
+const TOO_MANY = 10;
+
+export function emptyBoard(): Board {
+	return { next: 1, cards: [], decisions: [] };
+}
+
+export const BOARD_COLUMNS: readonly {
+	column: BoardColumn;
+	label: string;
+	/** Open cards count toward the cap and the panel. */
+	open: boolean;
+}[] = [
+	{ column: "doing", label: "Doing", open: true },
+	{ column: "review", label: "In review", open: true },
+	{ column: "todo", label: "To do", open: true },
+	{ column: "backlog", label: "Backlog", open: false },
+	{ column: "done", label: "Done", open: false },
+	{ column: "dropped", label: "Dropped", open: false },
+];
+
+const OPEN_COLUMNS: ReadonlySet<BoardColumn> = new Set(
+	BOARD_COLUMNS.filter((one) => one.open).map((one) => one.column),
+);
+
+export function labelOf(column: BoardColumn): string {
+	return BOARD_COLUMNS.find((one) => one.column === column)?.label ?? column;
+}
+
+export function applyBoard(board: Board, op: BoardOp, writer: BoardWriter = "agent"): BoardResult {
+	switch (op.op) {
+		case "add":
+			return add(board, op, writer);
+		case "move":
+			return move(board, op, writer);
+		case "edit":
+			return edit(board, op);
+		case "drop":
+			return drop(board, op);
+		case "decide": {
+			const id = `d${board.next}`;
+			return {
+				ok: true,
+				board: {
+					next: board.next + 1,
+					cards: board.cards,
+					decisions: [
+						...board.decisions,
+						{ id, text: op.text.trim(), ...(op.by === undefined ? {} : { by: op.by }), at: op.at },
+					],
+				},
+			};
+		}
+	}
+}
+
+function add(board: Board, op: Extract<BoardOp, { op: "add" }>, writer: BoardWriter): BoardResult {
+	const title = op.title.trim();
+	const bad = badTitle(title);
+	if (bad !== undefined) return { ok: false, why: bad };
+	if (op.pr !== undefined && board.cards.some((card) => card.pr === op.pr)) {
+		return { ok: false, why: `a card for #${op.pr} already exists` };
+	}
+	const column = op.column ?? "todo";
+	const id = `c${board.next}`;
+	const card: BoardCard = {
+		id,
+		title,
+		column,
+		at: op.at,
+		...(op.pr === undefined ? {} : { pr: op.pr }),
+		...(op.blocked === undefined ? {} : { blocked: op.blocked }),
+	};
+	return guarded(
+		{ next: board.next + 1, cards: [...board.cards, card], decisions: board.decisions },
+		writer,
+	);
+}
+
+function move(
+	board: Board,
+	op: Extract<BoardOp, { op: "move" }>,
+	writer: BoardWriter,
+): BoardResult {
+	const card = board.cards.find((one) => one.id === op.id);
+	if (card === undefined) return { ok: false, why: `no card ${op.id}` };
+	if (op.column === "review" && op.reviewer === undefined)
+		return { ok: false, why: "a card in review needs its reviewer" };
+	if (op.column === "dropped")
+		return { ok: false, why: "a card is dropped with a reason, through drop" };
+	const at = op.at;
+	const next: BoardCard = { ...card, column: op.column, at };
+	// A field belongs to its column; leaving the column clears it, whoever wrote.
+	if (op.column === "doing") next.now = card.now;
+	else delete next.now;
+	if (op.column === "review") next.reviewer = op.reviewer;
+	else delete next.reviewer;
+	if (op.column === "done") next.result = op.result ?? card.result;
+	else delete next.result;
+	// A finished card waits on no one.
+	if (op.column === "done") delete next.blocked;
+	return guarded(
+		{ ...board, cards: board.cards.map((one) => (one.id === card.id ? next : one)) },
+		writer,
+	);
+}
+
+function edit(board: Board, op: Extract<BoardOp, { op: "edit" }>): BoardResult {
+	const card = board.cards.find((one) => one.id === op.id);
+	if (card === undefined) return { ok: false, why: `no card ${op.id}` };
+	const title = op.title?.trim();
+	if (title !== undefined) {
+		const bad = badTitle(title);
+		if (bad !== undefined) return { ok: false, why: bad };
+	}
+	if (op.pr !== undefined && board.cards.some((one) => one.pr === op.pr && one.id !== card.id)) {
+		return { ok: false, why: `a card for #${op.pr} already exists` };
+	}
+	const next: BoardCard = { ...card, at: op.at };
+	if (title !== undefined) next.title = title;
+	if (op.pr !== undefined) next.pr = op.pr;
+	if (op.now !== undefined) next.now = op.now;
+	if (op.blocked === null) delete next.blocked;
+	else if (op.blocked !== undefined) next.blocked = op.blocked;
+	// `now` only means something while the card is being done; the fold enforces it for every writer.
+	if (next.column !== "doing") delete next.now;
+	return {
+		ok: true,
+		board: { ...board, cards: board.cards.map((one) => (one.id === card.id ? next : one)) },
+	};
+}
+
+function drop(board: Board, op: Extract<BoardOp, { op: "drop" }>): BoardResult {
+	const card = board.cards.find((one) => one.id === op.id);
+	if (card === undefined) return { ok: false, why: `no card ${op.id}` };
+	const why = op.why.trim();
+	if (why === "") return { ok: false, why: "a dropped card needs its reason" };
+	const next: BoardCard = { ...card, column: "dropped", why, at: op.at };
+	delete next.now;
+	delete next.reviewer;
+	delete next.result;
+	delete next.blocked;
+	return {
+		ok: true,
+		board: { ...board, cards: board.cards.map((one) => (one.id === card.id ? next : one)) },
+	};
+}
+
+/** A write that would take the board past its limits is refused, whichever operation made it. */
+function guarded(next: Board, writer: BoardWriter): BoardResult {
+	if (writer === "operator") return { ok: true, board: next };
+	const open = next.cards.filter((card) => OPEN_COLUMNS.has(card.column));
+	const doing = open.filter((card) => card.column === "doing");
+	if (open.length > OPEN) {
+		return {
+			ok: false,
+			why: `the board already has ${open.length} open cards; finish, drop or move one to the backlog: ${open.map((card) => card.id).join(", ")}`,
+		};
+	}
+	if (doing.length > IN_PROGRESS) {
+		return {
+			ok: false,
+			why: `there are already ${IN_PROGRESS} cards in progress; finish one first: ${doing.map((card) => card.id).join(", ")}`,
+		};
+	}
+	return { ok: true, board: next };
+}
+
+function badTitle(title: string): string | undefined {
+	const words = title.split(/\s+/).filter((word) => word !== "");
+	if (title === "" || words.length > TITLE_WORDS)
+		return `a title says the result in 1 to ${TITLE_WORDS} words`;
+	return undefined;
+}
+
+/** What other sessions see: the open cards, the backlog as a count, the last three done. */
+export interface BoardView {
+	open: BoardCard[];
+	backlog: number;
+	done: BoardCard[];
+}
+
+export function boardView(board: Board): BoardView {
+	const open = board.cards.filter((card) => OPEN_COLUMNS.has(card.column)).slice(0, OPEN);
+	const backlog = board.cards.filter((card) => card.column === "backlog").length;
+	const done = board.cards.filter((card) => card.column === "done").slice(-3);
+	return { open, backlog, done };
+}
+
+/** Searches deliveries and decisions, at most ten at a time. */
+export function findBoard(
+	board: Board,
+	text: string,
+): { matches: (BoardCard | BoardDecision)[]; more: number } {
+	const needle = text.trim().toLowerCase();
+	if (needle === "") return { matches: [], more: 0 };
+	const cards = board.cards.filter(
+		(card) => card.column === "done" && card.title.toLowerCase().includes(needle),
+	);
+	const decisions = board.decisions.filter((decision) =>
+		decision.text.toLowerCase().includes(needle),
+	);
+	const all = [...cards, ...decisions];
+	return { matches: all.slice(0, TOO_MANY), more: Math.max(0, all.length - TOO_MANY) };
+}
+
+/** The one translation of the blocker: the operator reads "você", a third session reads the operator. */
+export function blockedText(blocker: BoardBlocker, reader: "operator" | "agent"): string {
+	if (blocker.on === "operator") {
+		return `${reader === "operator" ? "você" : "o operador"}: ${blocker.why}`;
+	}
+	if (blocker.on === "outside") return `fora: ${blocker.why}`;
+	const handle = blocker.handle.startsWith("@") ? blocker.handle : `@${blocker.handle}`;
+	return `${handle}: ${blocker.why}`;
+}
+
+export function foldBoard(ops: readonly BoardOp[], writer: BoardWriter = "agent"): Board {
+	let board = emptyBoard();
+	for (const op of ops) {
+		const result = applyBoard(board, op, writer);
+		if (result.ok) board = result.board;
+	}
+	return board;
+}
+
+const COLUMNS: ReadonlySet<string> = new Set(BOARD_COLUMNS.map((one) => one.column));
+
+/** A shape this version cannot read is skipped, never guessed. */
+export function isBoard(value: unknown): value is Board {
+	if (!isObject(value)) return false;
+	const { cards, decisions, next } = value;
+	if (typeof next !== "number" || !Array.isArray(cards) || !Array.isArray(decisions)) return false;
+	return cards.every(isCard) && decisions.every(isDecision);
+}
+
+function isCard(value: unknown): value is BoardCard {
+	if (!isObject(value)) return false;
+	if (
+		typeof value.id !== "string" ||
+		typeof value.title !== "string" ||
+		typeof value.at !== "number"
+	)
+		return false;
+	if (typeof value.column !== "string" || !COLUMNS.has(value.column)) return false;
+	if (value.pr !== undefined && typeof value.pr !== "number") return false;
+	if (value.now !== undefined && typeof value.now !== "string") return false;
+	if (value.reviewer !== undefined && typeof value.reviewer !== "string") return false;
+	if (value.result !== undefined && typeof value.result !== "string") return false;
+	if (value.why !== undefined && typeof value.why !== "string") return false;
+	return value.blocked === undefined || isBlocker(value.blocked);
+}
+
+function isBlocker(value: unknown): value is BoardBlocker {
+	if (!isObject(value) || typeof value.why !== "string") return false;
+	if (value.on === "operator" || value.on === "outside") return true;
+	return value.on === "agent" && typeof value.handle === "string";
+}
+
+function isDecision(value: unknown): value is BoardDecision {
+	if (!isObject(value)) return false;
+	if (
+		typeof value.id !== "string" ||
+		typeof value.text !== "string" ||
+		typeof value.at !== "number"
+	)
+		return false;
+	return value.by === undefined || isBy(value.by);
+}

package/packages/frame/src/kit/contract.ts

@@ -0,0 +1,79 @@
+// State one feature owns and others read over pi.events. The bus is synchronous, so a read is never
+// stale, and a change is announced with the whole value. Values are JSON, decoded on arrival, since
+// the other side may be another version.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { type Decoder, formatProblems, isObject } from "./decode.ts";
+
+export interface EventScope {
+	readonly events: ExtensionAPI["events"];
+	warn(message: string): void;
+}
+
+type KeyArgs<K> = [K] extends [void] ? [] : [key: K];
+
+export interface Contract<T, K extends string | void = void> {
+	readonly channel: string;
+	/** Undefined when nobody provides it, or when the answer does not decode (which warns). */
+	current(scope: EventScope, ...key: KeyArgs<K>): T | undefined;
+	/** An undefined answer leaves the question to another provider. */
+	provide(scope: EventScope, answer: (key: K) => T | undefined): () => void;
+	/** Undefined says there is none any more. */
+	changed(scope: EventScope, value: T | undefined, ...key: KeyArgs<K>): void;
+	onChanged(scope: EventScope, listener: (value: T | undefined, key: K) => void): () => void;
+}
+
+interface Question {
+	key?: unknown;
+	answered?: boolean;
+	value?: unknown;
+}
+
+/** Named `<area>` or `<area>:<what>`, like `tasks` or `calls:ruling`. */
+export function defineContract<T, K extends string | void = void>(
+	name: string,
+	decoder: Decoder<T>,
+): Contract<T, K> {
+	const channel = `harness:${name}`;
+	const changes = `${channel}:changed`;
+
+	function decoded(scope: EventScope, value: unknown, what: string): T | undefined {
+		const result = decoder.decode(value, name);
+		if (result.ok) return result.value;
+		scope.warn(`ignored ${what} ${name}: ${formatProblems(result.problems).join("; ")}`);
+		return undefined;
+	}
+
+	return {
+		channel,
+		current(scope, ...key) {
+			const question: Question = { key: key[0] };
+			scope.events.emit(channel, question);
+			if (question.answered !== true) return undefined;
+			return decoded(scope, question.value, "an answer to");
+		},
+		provide(scope, answer) {
+			return scope.events.on(channel, (data) => {
+				if (!isObject(data) || data.answered === true) return;
+				const value = answer(data.key as K);
+				if (value === undefined) return;
+				data.value = value;
+				data.answered = true;
+			});
+		},
+		changed(scope, value, ...key) {
+			scope.events.emit(changes, { key: key[0], value });
+		},
+		onChanged(scope, listener) {
+			return scope.events.on(changes, (data) => {
+				if (!isObject(data)) return;
+				if (data.value === undefined) {
+					listener(undefined, data.key as K);
+					return;
+				}
+				const value = decoded(scope, data.value, "a change of");
+				if (value !== undefined) listener(value, data.key as K);
+			});
+		},
+	};
+}

package/packages/frame/src/kit/contracts/accounts.ts

@@ -0,0 +1,33 @@
+import { defineContract } from "../contract.ts";
+import { guarded, isObject } from "../decode.ts";
+
+export interface AccountWindow {
+	name: string;
+	/** Percent used of that window, 0..100. */
+	used: number;
+	/** Time left in the window, like `11m`. */
+	resetsIn?: string;
+}
+
+export interface AccountState {
+	provider: string;
+	label: string;
+	windows: AccountWindow[];
+	needsLogin?: boolean;
+}
+
+/** Keyed by provider; nobody answers for a provider with no accounts. */
+export const ACCOUNT = defineContract<AccountState, string>(
+	"accounts:state",
+	guarded(isAccountState, "an account with a provider, a label and windows"),
+);
+
+function isAccountState(value: unknown): value is AccountState {
+	if (!isObject(value) || typeof value.provider !== "string" || typeof value.label !== "string")
+		return false;
+	return Array.isArray(value.windows) && value.windows.every(isWindow);
+}
+
+function isWindow(value: unknown): value is AccountWindow {
+	return isObject(value) && typeof value.name === "string" && typeof value.used === "number";
+}

package/packages/frame/src/kit/contracts/ask.ts

@@ -0,0 +1,120 @@
+// One dialog for every question. The bus is synchronous, so the answer comes on a second channel.
+import { isObject } from "../decode.ts";
+import { GLYPH } from "../ui/glyphs.ts";
+import type { By } from "./by.ts";
+
+export const AVAILABLE = "harness:ask:available";
+export const ASK = "harness:ask";
+export const ANSWER = "harness:ask:answer";
+// Only the asker emits it. A provider whose dialog closes on its own answers `cancelled: true`
+// instead, or the asker waits forever.
+export const CANCEL = "harness:ask.cancel";
+
+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[];
+	/** The asker's own terminal already draws this question, so a provider that draws skips it. */
+	drawn?: true;
+	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 AskReply extends AskResult {
+	by?: By;
+}
+
+export interface AnswerEvent {
+	id: string;
+	/** Without it the answer is logged as from nobody known, never as the terminal. */
+	by?: By;
+	result: AskResult;
+}
+
+export interface AskCancel {
+	id: string;
+	reason: "answered" | "aborted";
+	by?: By;
+}
+
+export function isAskResult(value: unknown): value is AskResult {
+	if (!isObject(value)) return false;
+	return Array.isArray(value.answers) && typeof value.cancelled === "boolean";
+}
+
+export function isAnswered(answer: AskAnswer): boolean {
+	return answer.picked.length > 0 || (answer.typed ?? "").trim() !== "";
+}
+
+export function describeAnswers(answers: readonly AskAnswer[]): string[] {
+	const lines: string[] = [];
+	for (const answer of answers) {
+		lines.push(`- ${answer.header}: "${answer.question}" ${GLYPH.right} ${answerSummary(answer)}`);
+		for (const { option, note } of answer.notes) {
+			const tag = answer.picked.includes(option) ? "" : " (not picked)";
+			lines.push(`  note on "${option}"${tag}: ${note}`);
+		}
+	}
+	return lines;
+}
+
+export function answerSummary(answer: AskAnswer): string {
+	const parts = answer.picked.map((label) => `"${label}"`);
+	const typed = answer.typed?.trim();
+	if (typed) parts.push(`in their words: "${typed}"`);
+	return parts.length === 0 ? "(nothing)" : parts.join(", ");
+}
+
+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)) return `"${question.header}" has no options`;
+		if (question.options.length === 0 && question.typed === false)
+			return `"${question.header}" has no options and no typed row`;
+		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;
+}

package/packages/frame/src/kit/contracts/board.ts

@@ -0,0 +1,6 @@
+// Offered whole, since every reader needs the same state.
+import { isBoard, type Board } from "../board/model.ts";
+import { defineContract } from "../contract.ts";
+import { guarded } from "../decode.ts";
+
+export const BOARD = defineContract<Board>("board", guarded(isBoard, "a board"));