@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/extensions/board/transport/router.ts

@@ -0,0 +1,91 @@
+/**
+ * The board page's router: one request in, one response out, and every policy the
+ * served surface obeys decided here.
+ *
+ * The page reads. It cannot change a card, so what is left to decide is the `Host`
+ * allowlist, the token in the URL, and which reads exist — a method that would write is
+ * refused by the method list before a handler is reached. The guards themselves are
+ * `lib/http`'s — this module only decides the order and the sentences.
+ *
+ * Nothing here knows what a board is. The snapshot arrives as `view()` and the document
+ * as `page()`, both supplied by `page.ts`, so this file can be tested with a fake store
+ * and no server.
+ */
+
+import {
+	envelopeRefusal,
+	eventHeaders,
+	jsonError,
+	jsonResponse,
+	pageHeaders,
+	parseRequestUrl,
+	scriptHeaders,
+	type ServeResponse,
+} from "../../../lib/http/index.ts";
+import type { BoardView } from "../../../lib/board/view.ts";
+import { THEME_JS, THEME_JS_PATH } from "../../../lib/web/index.ts";
+import type { PageView } from "../view/page.ts";
+
+/**
+ * The methods this surface serves: the two reads and the stream.
+ *
+ * `PAGE_METHODS` also carries `POST`, because a page that writes needs it. This one does
+ * not, so a write is refused by the envelope — before the token is even read — and the
+ * `Allow` header says the truth about what a browser can do here.
+ */
+const METHODS: readonly string[] = ["GET", "HEAD"];
+
+/** Everything the router needs from the running page. */
+export interface BoardRouterContext {
+	/** Whether a token is this page's. */
+	read: (given: string | null) => boolean;
+	/** The names this server answers to. */
+	hosts: () => readonly string[];
+	/** The document for one tab. */
+	page: (view: PageView) => Promise<string>;
+	/** The client script. */
+	script: string;
+	/** The snapshot the page renders, and the body of `/api/board`. */
+	view: () => Promise<BoardView>;
+}
+
+/** The cheap liveness route: a probe reads this, and never the snapshot. */
+export const PING_PATH = "/api/ping";
+
+/**
+ * Handle one request. `method`, `rawUrl`, and `headers` are the raw HTTP values.
+ */
+export async function handleBoardRequest(
+	ctx: BoardRouterContext,
+	method: string,
+	rawUrl: string,
+	headers: Record<string, string | string[] | undefined> = {},
+): Promise<ServeResponse> {
+	const envelope = envelopeRefusal({ method, headers, hosts: ctx.hosts(), allowed: METHODS });
+	if (envelope) return envelope;
+
+	const parsed = parseRequestUrl(rawUrl);
+	if (!parsed) return jsonError(400, "Malformed request URL.");
+	const { pathname, search } = parsed;
+
+	if (pathname === THEME_JS_PATH) return { status: 200, headers: scriptHeaders(), body: THEME_JS };
+	if (pathname === "/app.js") return { status: 200, headers: scriptHeaders(), body: ctx.script };
+
+	if (!ctx.read(search.get("token"))) return jsonError(403, "Invalid or missing token.");
+
+	// The liveness answer, and nothing else: a session deciding whether this page is alive
+	// must not pay for the snapshot, which is a store read and a roster read on the same
+	// event loop the probe is racing.
+	if (pathname === PING_PATH) return jsonResponse(200, { ok: true });
+	if (pathname === "/api/board") return jsonResponse(200, await ctx.view());
+	if (pathname === "/" || pathname === "/index.html") {
+		return { status: 200, headers: pageHeaders(), body: await ctx.page(viewOf(search.get("view"))) };
+	}
+	if (pathname === "/events") return { status: 200, headers: eventHeaders(), stream: true };
+	return jsonError(404, "That page does not exist.");
+}
+
+/** The tab a `?view=` names; anything else is the board. */
+function viewOf(raw: string | null): PageView {
+	return raw === "team" ? "team" : "board";
+}

package/extensions/board/transport/server.ts

@@ -0,0 +1,138 @@
+/**
+ * The board page's server: one loopback listener, the snapshot pushed to every
+ * attached tab, and the idle grace that closes the page when the last one leaves.
+ *
+ * `lib/http` owns the socket — binding, the body cap, the SSE head, and the
+ * idempotent close — so this module owns only the board's own decisions: when a
+ * frame is pushed (only when a card's revision moved), who receives it, and what
+ * stops the ticker.
+ */
+
+import {
+	type EventSink,
+	LOOPBACK_HOSTS,
+	type LoopbackServer,
+	mintToken,
+	serveLoopback,
+	tokenMatches,
+} from "../../../lib/http/index.ts";
+import type { IdleReason } from "../../../lib/http/sink.ts";
+import { defaultInterval, type RepeatTimer } from "../../../lib/timer.ts";
+import type { BoardView } from "../../../lib/board/view.ts";
+import type { PageView } from "../view/page.ts";
+import { type BoardRouterContext, handleBoardRequest } from "./router.ts";
+
+/** How often the page is offered a frame; a frame is sent only when the signature moved. */
+export const PUSH_MS = 1_000;
+
+/** Largest request body the page accepts: a card and a note are small. */
+export const MAX_BODY_BYTES = 64 * 1_024;
+
+/** What the page is built from. The lifecycle (`page.ts`) supplies all of it. */
+export interface BoardServerOptions {
+	/** Ports tried in order: the session's remembered port, then an OS-chosen one. */
+	ports: readonly number[];
+	/** The page's token; minted here when the caller has none, so the note carries one. */
+	token?: string;
+	page: (view: PageView) => Promise<string>;
+	script: string;
+	view: () => Promise<BoardView>;
+	/** Called when the page went idle: no tab ever opened, or the last one left. */
+	onIdle?: (reason: IdleReason) => void;
+	/** Grace after the last stream leaves; 0 or absent waits for `close()`. */
+	idleMs?: number;
+	/** Grace for a page no tab ever attached to; absent leaves the server open. */
+	firstIdleMs?: number;
+	/** The interval seam, so a test drives the ticker instead of waiting. */
+	interval?: RepeatTimer;
+}
+
+/** A running page. */
+export interface BoardServer {
+	port: number;
+	/** The URL for this page: one address, because there is one thing a page may do. */
+	url: string;
+	/** How many tabs are attached, which is what `/board status` reports. */
+	watchers: () => number;
+	/** The signature of the last frame pushed, so a caller can tell it is live. */
+	pushed: () => string;
+	close: () => Promise<void>;
+}
+
+export async function createBoardServer(options: BoardServerOptions): Promise<BoardServer> {
+	const token = options.token ?? mintToken();
+	const clients = new Set<EventSink>();
+	const interval = options.interval ?? defaultInterval;
+	let pushed = "";
+
+	const ctx: BoardRouterContext = {
+		read: (given) => tokenMatches(token, given ?? ""),
+		hosts: () => LOOPBACK_HOSTS,
+		page: options.page,
+		script: options.script,
+		view: options.view,
+	};
+
+	const push = async (): Promise<void> => {
+		if (clients.size === 0) return;
+		const view = await options.view();
+		// A frame is a snapshot, so sending one that says nothing new costs the page a
+		// parse and every reader a flicker. The signature is what changes.
+		if (view.sig === pushed) return;
+		pushed = view.sig;
+		const frame = `data: ${JSON.stringify(view)}\n\n`;
+		for (const sink of clients) sink.write(frame);
+	};
+
+	const server: LoopbackServer = await serveLoopback({
+		ports: options.ports,
+		maxBodyBytes: MAX_BODY_BYTES,
+		...(options.idleMs === undefined || options.onIdle === undefined
+			? {}
+			: {
+					idle: {
+						ms: options.idleMs,
+						...(options.firstIdleMs === undefined ? {} : { firstMs: options.firstIdleMs }),
+						onIdle: options.onIdle,
+					},
+				}),
+		async handler(request) {
+			const result = await handleBoardRequest(ctx, request.method, request.url, request.headers);
+			if (!result.stream) return { result };
+			return {
+				result,
+				openSink(sink) {
+					clients.add(sink);
+					// A tab that just attached gets the current frame without waiting for a
+					// card to change — otherwise a quiet board looks like a dead page.
+					void options.view().then((view) => {
+						pushed = view.sig;
+						sink.write(`data: ${JSON.stringify(view)}\n\n`);
+					});
+					return () => {
+						clients.delete(sink);
+					};
+				},
+			};
+		},
+	});
+
+	const stopTicker = interval(PUSH_MS, () => void push());
+	let closed = false;
+	const close = async (): Promise<void> => {
+		if (closed) return;
+		closed = true;
+		stopTicker();
+		for (const sink of clients) sink.end();
+		clients.clear();
+		await server.close();
+	};
+
+	return {
+		port: server.port,
+		url: `http://127.0.0.1:${server.port}/?token=${token}`,
+		watchers: () => clients.size,
+		pushed: () => pushed,
+		close,
+	};
+}

package/extensions/board/types.ts

@@ -0,0 +1,121 @@
+/**
+ * The shapes the `board` tool registers and reports.
+ *
+ * `details` is the result's state: the card an action produced, the cards a list
+ * read, the rollup when it was asked for, and — on a refusal — the card as it was,
+ * so a retry starts from the truth rather than from what the model thought it
+ * knew. The renderer and the tool share these types, and nothing else.
+ */
+
+import type { Card } from "../../lib/board/card.ts";
+import type { Actor } from "../../lib/board/rules.ts";
+import type { RoundSummary } from "../../lib/board/round.ts";
+
+/** The tool's name. One extension registers it, so it stays here. */
+export const BOARD_TOOL = "board";
+
+/** The actions the tool accepts, in the order the description lists them. */
+export const BOARD_ACTIONS = [
+	"list",
+	"add",
+	"claim",
+	"release",
+	"reclaim",
+	"move",
+	"note",
+	"plan",
+	"edit",
+	"archive",
+	"drop",
+] as const;
+
+/** One action. */
+export type BoardAction = (typeof BOARD_ACTIONS)[number];
+
+/**
+ * What each verb does, in one sentence.
+ *
+ * The tool description is built from this table and the parameter's `action`
+ * description points at that sentence, so the verbs are stated once. A new action is
+ * a row here and an entry in {@link BOARD_ACTIONS}; `test` holds the two together.
+ */
+export const BOARD_ACTION_DOCS: Record<BoardAction, string> = {
+	list:
+		"shows the board — `status` filters one lane, `mine` only what this session holds, " +
+		"`query` matches a title, a holder, a path hint, the plan, or a note's text, `card` reads that one card " +
+		"instead of the board, and `round` adds the lead's rollup of owners, unassigned, unplanned, blocked, and " +
+		"idle, which always covers the whole board — and a listing that names no lane leaves out the `done` cards, " +
+		"saying how many it left out",
+	add: "creates a `todo` card",
+	claim: "takes one for this session",
+	release: "gives it back",
+	reclaim: "takes it from whoever holds it",
+	move: "changes lane",
+	note: "appends to its history",
+	plan: "records the plan file being executed",
+	edit: "fixes what the card says — title, path hints, priority, and what it waits for",
+	archive:
+		"sets a finished card aside, out of the board and still readable, or every finished card when no `card` is named",
+	drop: "deletes a `todo`, a `done`, or one you hold",
+};
+
+/**
+ * The fields each action acts on: the behaviour, where {@link BOARD_ACTION_DOCS} is prose.
+ *
+ * The parameters are one flat object, so a field is published to every action at once;
+ * that is only harmless while each action reads its own. A call carrying a field its
+ * action never reads is refused against this table, because the alternative is what
+ * `add` did with `dependsOn`: accepted, ignored, and reported as recorded.
+ *
+ * `test` holds the other direction — every parameter but `action` is claimed here — so
+ * a new field cannot be published without an action that acts on it.
+ */
+export const ACTION_FIELDS: Record<BoardAction, readonly string[]> = {
+	list: ["card", "status", "mine", "query", "round", "archived"],
+	add: ["title", "paths", "priority", "note"],
+	claim: ["card"],
+	release: ["card"],
+	reclaim: ["card"],
+	move: ["card", "status", "blockedBy"],
+	note: ["card", "text"],
+	plan: ["card", "path"],
+	edit: ["card", "title", "paths", "priority", "dependsOn"],
+	archive: ["card"],
+	drop: ["card"],
+};
+
+/**
+ * The actions that change the board: everything but a read.
+ *
+ * One definition, read by the tool (does this call need a teammate?) and by plan
+ * mode (may this call run while planning?), so "a read" cannot mean two things.
+ */
+export const BOARD_MUTATING_ACTIONS: ReadonlySet<BoardAction> = new Set(
+	BOARD_ACTIONS.filter((action) => action !== "list"),
+);
+
+/** A result the transcript renders and the page's routes mirror. */
+export interface BoardDetails {
+	action: BoardAction;
+	/** The serving session: the id Pi knows, and the label a card records. */
+	me: Actor;
+	/** The board a `list` read, in lane order. */
+	cards?: Card[];
+	/** The card an action produced, or the one a refusal left untouched. */
+	card?: Card;
+	/** The lead's rollup, only for `list` with `round`. */
+	round?: RoundSummary;
+	/** The id a `drop` removed. */
+	dropped?: string;
+	/** The ids an `archive` set aside, in the order it moved them. */
+	archived?: string[];
+	/** Cards an `archive` sweep could not set aside, and why: a move that changed underneath it. */
+	failed?: Array<{ card: string; error: string }>;
+	/** A refusal's reason, which the renderer draws instead of the details. */
+	error?: string;
+}
+
+/** Whether a value is one of the actions, so an unknown one is a refusal and not a crash. */
+export function normalizeBoardAction(raw: unknown): BoardAction | undefined {
+	return typeof raw === "string" && BOARD_ACTIONS.includes(raw as BoardAction) ? (raw as BoardAction) : undefined;
+}

package/extensions/board/view/client.ts

@@ -0,0 +1,51 @@
+/**
+ * The client bundle: the modules that paint, round up, open a card, bind keys, and
+ * follow the frame stream, plus the kit's own theme toggle and the two dialog scripts,
+ * and the one entry point that starts them.
+ *
+ * Served as one string, because a page that opens six requests before it can paint
+ * is a page that looks broken for a moment. Nothing here is typed — no compiler sees
+ * a template string — so the split is by job and the class-contract test reads the
+ * result: `render.ts` paints, `team.ts` draws the round, `dialog.ts` opens one card,
+ * `keys.ts` binds, and `live.ts` owns the tabs and the stream.
+ *
+ * Load order is a dependency: `team` takes helpers from `render`, and `live` starts
+ * last, after every `board.*` handler it wires exists.
+ */
+
+import { MATCHES_QUERY_JS } from "../../../lib/board/card.ts";
+import { CLIENT_RUNTIME_JS } from "../../../lib/web/index.ts";
+import { PLURAL_JS } from "../../../lib/board/round-text.ts";
+import { FORMAT_AGE_JS } from "../../../lib/format.ts";
+import { namesScript, TAB_TITLE_JS, THEME_TOGGLE_JS, dialogScript, keysDialogScript } from "../../../lib/web/index.ts";
+import { BOARD_CLASS } from "./names.ts";
+import { BOARD_DIALOG_JS } from "./dialog.ts";
+import { BOARD_KEYS_JS } from "./keys.ts";
+import { BOARD_LIVE_JS } from "./live.ts";
+import { renderJs } from "./render.ts";
+import { BOARD_TEAM_JS } from "./team.ts";
+
+/**
+ * The whole client, in load order: paint, round, the card dialog, keys, wiring, start.
+ *
+ * Four rules cross the boundary as source — the count's wording, the tab title's
+ * shape, what a `query` matches, and how an age reads: the browser has no import graph,
+ * and a second copy of any of them is exactly what this bundle is not allowed to hold.
+ */
+export const BOARD_CLIENT_JS = `${namesScript(BOARD_CLASS)}
+${renderJs({ plural: PLURAL_JS, tabTitle: TAB_TITLE_JS, matches: MATCHES_QUERY_JS, age: FORMAT_AGE_JS, runtime: CLIENT_RUNTIME_JS })}
+${BOARD_TEAM_JS}
+${BOARD_DIALOG_JS}
+${BOARD_KEYS_JS}
+${BOARD_LIVE_JS}
+${THEME_TOGGLE_JS}
+${dialogScript({ dialogId: "board-card-dialog", closeId: "card-dialog-close", globalName: "bfCard" })}
+${keysDialogScript("keys-open")}
+(function () {
+  "use strict";
+  var board = window.bfBoard;
+  if (!board) return;
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", function () { board.start(); });
+  else board.start();
+})();
+`;

package/extensions/board/view/dialog.ts

@@ -0,0 +1,43 @@
+/**
+ * The card dialog: one card, whole, as a read view.
+ *
+ * Opening, closing, and forgetting which card is open is the whole of it. The page
+ * cannot change a card, so this module has no request, no confirmation, no banner and
+ * no footer actions — the dialogs it used to fill are gone from the document, and the
+ * only way a card changes is a tool.
+ *
+ * The one thing it must not do is leave a stale panel behind: a dialog the kit closed —
+ * `Esc`, a backdrop click, its own close button — forgets `openId`, so the next frame
+ * stops filling something nobody can see.
+ */
+
+export const BOARD_DIALOG_JS = String.raw`(function () {
+  "use strict";
+  var board = window.bfBoard || (window.bfBoard = {});
+
+  /** Fill and open the card dialog. */
+  board.openCard = function (id) {
+    var view = board.view;
+    if (!view) return;
+    var card = board.findCard(view, id);
+    if (!card || !window.bfCard) return;
+    board.openId = id;
+    board.fillDialog(card, view);
+    window.bfCard.open();
+  };
+
+  board.closeCard = function () {
+    if (window.bfCard) window.bfCard.close();
+  };
+
+  board.dialogOpen = function () {
+    return window.bfCard ? window.bfCard.isOpen() : false;
+  };
+
+  var cardDialog = document.getElementById("board-card-dialog");
+  if (cardDialog) {
+    new MutationObserver(function () {
+      if (cardDialog.hidden) board.openId = undefined;
+    }).observe(cardDialog, { attributes: true, attributeFilter: ["hidden"] });
+  }
+})();`;

package/extensions/board/view/keys.ts

@@ -0,0 +1,125 @@
+/**
+ * The board page's keyboard: one table, and the two halves that read it.
+ *
+ * The sheet the user opens with `?` is server-rendered from {@link BOARD_KEYS}, and
+ * the bindings that make those keys work are {@link BOARD_KEYS_JS}, so the key a row
+ * advertises and the key the client listens for sit in one file — the drift this
+ * module exists to prevent, since no type checker sees the bundle.
+ *
+ * The vocabulary is the TUI's where it means the same thing (`j`/`k`, `?`, `Esc`);
+ * `/` and `t` are this page's own. There is no key that changes a card: the page reads.
+ */
+
+import type { KeyHint } from "../../../lib/web/index.ts";
+
+/** One binding: the key or keys, and what pressing it does. */
+export const BOARD_KEYS: readonly KeyHint[] = [
+	{ keys: "/", label: "Filter the cards" },
+	{ keys: ["j", "k"], label: "Next or previous card, or the next card in an open dialog" },
+	{ keys: "Enter", label: "Open the focused card" },
+	{ keys: "t", label: "Switch Board and Team" },
+	{ keys: "Esc", label: "Close a dialog, or clear the filter" },
+	{ keys: "?", label: "This sheet" },
+];
+
+/**
+ * The bindings, as the client sees them.
+ *
+ * Every branch reads `board.` state and calls `board.` handlers that `render.ts`,
+ * `team.ts`, and `live.ts` already published, so this module decides only *which
+ * key* does what. A field with focus keeps its keys: `n` inside the note input types
+ * an `n`.
+ */
+export const BOARD_KEYS_JS = String.raw`(function () {
+  "use strict";
+  var board = window.bfBoard || (window.bfBoard = {});
+
+  /** The render bundle's runtime: one typing test for the whole page. */
+  var typing = board.typing;
+
+  /** The card nodes in reading order, so j/k walk the board as it is drawn. */
+  function cards() {
+    return board.drawnCards();
+  }
+
+  /** Move the open dialog to the next or previous card; false when no dialog is open. */
+  function walk(delta) {
+    if (!board.dialogOpen || !board.dialogOpen()) return false;
+    var drawn = cards();
+    if (drawn.length === 0) return true;
+    // The open card is the one marked open, not the focused node: focus sits on the
+    // dialog's own panel, which is not one of the cards.
+    var at = -1;
+    for (var i = 0; i < drawn.length; i++) {
+      if (drawn[i].getAttribute("data-card") === String(board.openId)) at = i;
+    }
+    var next = at < 0 ? (delta > 0 ? 0 : drawn.length - 1) : (at + delta + drawn.length) % drawn.length;
+    board.openCard(drawn[next].getAttribute("data-card"));
+    return true;
+  }
+
+  /** Move focus to the next or previous drawn card, and say so for a screen reader. */
+  function step(delta) {
+    // An open dialog walks instead of moving focus: the record stays whole, and Esc
+    // still returns to the board where it was.
+    if (walk(delta)) return;
+    var drawn = cards();
+    if (drawn.length === 0) return;
+    var at = drawn.indexOf(document.activeElement);
+    var next = at < 0 ? (delta > 0 ? 0 : drawn.length - 1) : (at + delta + drawn.length) % drawn.length;
+    var button = drawn[next].querySelector(".board-card__title");
+    if (button) button.focus();
+  }
+
+  board.bindKeys = function (doc) {
+    doc.addEventListener("keydown", function (event) {
+      if (event.metaKey || event.ctrlKey || event.altKey) return;
+      var target = event.target;
+      if (event.key === "?" && !typing(target)) {
+        event.preventDefault();
+        board.openKeys();
+        return;
+      }
+      if (event.key === "Escape") {
+        if (board.keysOpen && board.keysOpen()) {
+          board.closeKeys();
+          return;
+        }
+        if (board.dialogOpen && board.dialogOpen()) {
+          board.closeCard();
+          return;
+        }
+        // What is left for Escape is the filter: a field with text loses it, and the field
+        // itself then gives the keyboard back to the page. The keys sheet and the card
+        // dialog are above this, in the order a reader is likely to be inside them.
+        if (board.hasFilter()) {
+          board.clearFilter();
+          if (typing(target)) target.blur();
+          return;
+        }
+        if (typing(target)) {
+          target.blur();
+          return;
+        }
+        return;
+      }
+      if (typing(target)) {
+        if (event.key === "Enter" && target.id === "board-filter") board.applyFilter();
+        return;
+      }
+      if (event.key === "/") {
+        event.preventDefault();
+        board.focusFilter();
+      } else if (event.key === "j") {
+        event.preventDefault();
+        step(1);
+      } else if (event.key === "k") {
+        event.preventDefault();
+        step(-1);
+      } else if (event.key === "t") {
+        event.preventDefault();
+        board.showView(board.viewName() === "team" ? "board" : "team");
+      }
+    });
+  };
+})();`;