@xynogen/pix-todo 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-todo",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Pi tool — durable execution checklist (todo)",
 	"type": "module",
 	"main": "src/index.ts",

package/src/once.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-instance idempotency guard for extension activation.
+ *
+ * pix-core (the meta-package) invokes this package's factory, and a standalone
+ * install makes Pi invoke it again — sometimes against the SAME `pi`. We must
+ * dedupe that. But Pi rebuilds the extension runtime on /new, /resume, /fork,
+ * and /reload, handing the factory a BRAND-NEW `pi`; that must re-register.
+ *
+ * Keying the registry on the `pi` instance satisfies both: same instance =>
+ * skip, new instance => run. The registry lives on globalThis because jiti
+ * (`moduleCache: false`) re-evaluates this module on every load pass, so a
+ * module-scoped WeakMap would not be shared between the aggregator pass and the
+ * standalone pass within a single session.
+ */
+export function once(pi: object, key: string, fn: () => void): void {
+	const g = globalThis as { __pixOnce?: WeakMap<object, Set<string>> };
+	const registry = (g.__pixOnce ??= new WeakMap<object, Set<string>>());
+	let loaded = registry.get(pi);
+	if (!loaded) {
+		loaded = new Set<string>();
+		registry.set(pi, loaded);
+	}
+	if (loaded.has(key)) return;
+	loaded.add(key);
+	fn();
+}

package/src/todo.test.ts

@@ -1,6 +1,14 @@
-import { describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, test } from "bun:test";
 import registerTodo, { renderTodoLines, type TodoItem } from "./todo.ts";
 
+// registerTodo wraps its body in once(pi, "pix-todo") — a per-instance
+// WeakMap guard that dedupes activation across pix-core + a standalone install.
+// Tests re-register a fresh host per case. Clear the registry between tests so
+// that the same pi object can be re-used without cross-test interference.
+beforeEach(() => {
+	delete (globalThis as { __pixOnce?: WeakMap<object, Set<string>> }).__pixOnce;
+});
+
 // Stub theme tags each fragment with its color/bold so assertions can verify
 // which status got which tint, without depending on real ANSI codes.
 const tagTheme = {

package/src/todo.ts

@@ -13,6 +13,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
+import { once } from "./once.ts";
+
 export type TodoStatus = "pending" | "in_progress" | "done" | "blocked";
 
 export interface TodoItem {
@@ -67,152 +69,154 @@ const parseItems = (raw: string): string[] =>
 		.filter(Boolean);
 
 export default function registerTodo(pi: ExtensionAPI): void {
-	let todos: TodoItem[] = [];
-	let nextTodoId = 1;
-
-	function persistTodos() {
-		pi.appendEntry("todo-state", { todos, nextTodoId });
-	}
-
-	function todoSummary(): string {
-		if (!todos.length) return "(no todos)";
-		const done = todos.filter((t) => t.status === "done").length;
-		const lines = todos.map(
-			(t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`,
-		);
-		return `Todos ${done}/${todos.length} done:\n${lines.join("\n")}`;
-	}
-
-	// Durable execution checklist for BUILD mode. Survives context compaction
-	// and session restore. Workflows like plan instruct the model to seed it
-	// from a plan's "Implementation Phases" so it stays anchored to plan.md.
-	pi.registerTool({
-		name: "todo",
-		label: "Todo",
-		description:
-			"Track BUILD-phase execution progress. Durable across context compaction. Actions: list, set (replace all items from newline/numbered text), add, update (change one item's status), clear.",
-		promptSnippet:
-			"todo(action, items?, id?, status?, text?) — action: list|set|add|update|clear. Use to track implementation progress, especially when executing a plan.",
-		promptGuidelines: [
-			"When you start executing a multi-step plan in BUILD mode, seed the todo list with `todo(action:'set', items: <plan Implementation Phases>)`.",
-			"Mark each item in_progress before working it and done when finished via `todo(action:'update', id, status)`.",
-			"Call `todo(action:'list')` to recover your place after long runs or context compaction.",
-		],
-		parameters: Type.Object({
-			action: Type.Union(
-				[
-					Type.Literal("list"),
-					Type.Literal("set"),
-					Type.Literal("add"),
-					Type.Literal("update"),
-					Type.Literal("clear"),
-				],
-				{ description: "Operation to perform" },
-			),
-			items: Type.Optional(
-				Type.String({
-					description:
-						"For set/add: newline-separated or numbered list of todo texts.",
-				}),
-			),
-			id: Type.Optional(
-				Type.Number({ description: "For update: target todo id." }),
-			),
-			status: Type.Optional(
-				Type.Union(
+	once(pi, "pix-todo", () => {
+		let todos: TodoItem[] = [];
+		let nextTodoId = 1;
+
+		function persistTodos() {
+			pi.appendEntry("todo-state", { todos, nextTodoId });
+		}
+
+		function todoSummary(): string {
+			if (!todos.length) return "(no todos)";
+			const done = todos.filter((t) => t.status === "done").length;
+			const lines = todos.map(
+				(t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`,
+			);
+			return `Todos ${done}/${todos.length} done:\n${lines.join("\n")}`;
+		}
+
+		// Durable execution checklist for BUILD mode. Survives context compaction
+		// and session restore. Workflows like plan instruct the model to seed it
+		// from a plan's "Implementation Phases" so it stays anchored to plan.md.
+		pi.registerTool({
+			name: "todo",
+			label: "Todo",
+			description:
+				"Track BUILD-phase execution progress. Durable across context compaction. Actions: list, set (replace all items from newline/numbered text), add, update (change one item's status), clear.",
+			promptSnippet:
+				"todo(action, items?, id?, status?, text?) — action: list|set|add|update|clear. Use to track implementation progress, especially when executing a plan.",
+			promptGuidelines: [
+				"When you start executing a multi-step plan in BUILD mode, seed the todo list with `todo(action:'set', items: <plan Implementation Phases>)`.",
+				"Mark each item in_progress before working it and done when finished via `todo(action:'update', id, status)`.",
+				"Call `todo(action:'list')` to recover your place after long runs or context compaction.",
+			],
+			parameters: Type.Object({
+				action: Type.Union(
 					[
-						Type.Literal("pending"),
-						Type.Literal("in_progress"),
-						Type.Literal("done"),
-						Type.Literal("blocked"),
+						Type.Literal("list"),
+						Type.Literal("set"),
+						Type.Literal("add"),
+						Type.Literal("update"),
+						Type.Literal("clear"),
 					],
-					{ description: "For update: new status." },
+					{ description: "Operation to perform" },
 				),
-			),
-			text: Type.Optional(
-				Type.String({
-					description: "For update: replacement text (optional).",
-				}),
-			),
-		}),
-		renderResult(_result, _options, theme) {
-			return new Text(renderTodoLines(todos, theme as TodoTheme), 0, 0);
-		},
-
-		async execute(_id, params) {
-			// AgentToolResult now requires a `details` field. These todo results have
-			// no structured details, so emit `undefined` via small local helpers.
-			const ok = (text: string) => ({
-				content: [{ type: "text" as const, text }],
-				details: undefined,
-			});
-			const fail = (text: string) => ({
-				content: [{ type: "text" as const, text }],
-				details: undefined,
-				isError: true,
-			});
-			switch (params.action) {
-				case "list":
-					return ok(todoSummary());
-
-				case "set": {
-					const texts = parseItems(params.items ?? "");
-					if (!texts.length) return fail("set requires non-empty `items`.");
-					nextTodoId = 1;
-					todos = texts.map((text) => ({
-						id: nextTodoId++,
-						text,
-						status: "pending" as TodoStatus,
-					}));
-					persistTodos();
-					return ok(todoSummary());
-				}
-
-				case "add": {
-					const texts = parseItems(params.items ?? "");
-					if (!texts.length) return fail("add requires non-empty `items`.");
-					for (const text of texts)
-						todos.push({ id: nextTodoId++, text, status: "pending" });
-					persistTodos();
-					return ok(todoSummary());
-				}
-
-				case "update": {
-					const t = todos.find((x) => x.id === params.id);
-					if (!t) return fail(`No todo with id ${params.id}.`);
-					if (params.status) t.status = params.status;
-					if (params.text) t.text = params.text;
-					persistTodos();
-					return ok(todoSummary());
+				items: Type.Optional(
+					Type.String({
+						description:
+							"For set/add: newline-separated or numbered list of todo texts.",
+					}),
+				),
+				id: Type.Optional(
+					Type.Number({ description: "For update: target todo id." }),
+				),
+				status: Type.Optional(
+					Type.Union(
+						[
+							Type.Literal("pending"),
+							Type.Literal("in_progress"),
+							Type.Literal("done"),
+							Type.Literal("blocked"),
+						],
+						{ description: "For update: new status." },
+					),
+				),
+				text: Type.Optional(
+					Type.String({
+						description: "For update: replacement text (optional).",
+					}),
+				),
+			}),
+			renderResult(_result, _options, theme) {
+				return new Text(renderTodoLines(todos, theme as TodoTheme), 0, 0);
+			},
+
+			async execute(_id, params) {
+				// AgentToolResult now requires a `details` field. These todo results have
+				// no structured details, so emit `undefined` via small local helpers.
+				const ok = (text: string) => ({
+					content: [{ type: "text" as const, text }],
+					details: undefined,
+				});
+				const fail = (text: string) => ({
+					content: [{ type: "text" as const, text }],
+					details: undefined,
+					isError: true,
+				});
+				switch (params.action) {
+					case "list":
+						return ok(todoSummary());
+
+					case "set": {
+						const texts = parseItems(params.items ?? "");
+						if (!texts.length) return fail("set requires non-empty `items`.");
+						nextTodoId = 1;
+						todos = texts.map((text) => ({
+							id: nextTodoId++,
+							text,
+							status: "pending" as TodoStatus,
+						}));
+						persistTodos();
+						return ok(todoSummary());
+					}
+
+					case "add": {
+						const texts = parseItems(params.items ?? "");
+						if (!texts.length) return fail("add requires non-empty `items`.");
+						for (const text of texts)
+							todos.push({ id: nextTodoId++, text, status: "pending" });
+						persistTodos();
+						return ok(todoSummary());
+					}
+
+					case "update": {
+						const t = todos.find((x) => x.id === params.id);
+						if (!t) return fail(`No todo with id ${params.id}.`);
+						if (params.status) t.status = params.status;
+						if (params.text) t.text = params.text;
+						persistTodos();
+						return ok(todoSummary());
+					}
+
+					case "clear":
+						todos = [];
+						nextTodoId = 1;
+						persistTodos();
+						return ok("Todos cleared.");
+
+					default:
+						return fail(`Unknown action: ${String(params.action)}`);
 				}
-
-				case "clear":
-					todos = [];
-					nextTodoId = 1;
-					persistTodos();
-					return ok("Todos cleared.");
-
-				default:
-					return fail(`Unknown action: ${String(params.action)}`);
+			},
+		});
+
+		// Restore the checklist from session entries so it survives restart.
+		pi.on("session_start", async (_event, ctx) => {
+			const entries = ctx.sessionManager.getEntries() as Array<{
+				type: string;
+				customType?: string;
+				data?: { todos?: TodoItem[]; nextTodoId?: number };
+			}>;
+			const lastTodo = entries
+				.filter((e) => e.type === "custom" && e.customType === "todo-state")
+				.pop();
+			if (Array.isArray(lastTodo?.data?.todos)) {
+				todos = lastTodo.data.todos;
+				nextTodoId =
+					lastTodo.data.nextTodoId ??
+					todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
 			}
-		},
-	});
-
-	// Restore the checklist from session entries so it survives restart.
-	pi.on("session_start", async (_event, ctx) => {
-		const entries = ctx.sessionManager.getEntries() as Array<{
-			type: string;
-			customType?: string;
-			data?: { todos?: TodoItem[]; nextTodoId?: number };
-		}>;
-		const lastTodo = entries
-			.filter((e) => e.type === "custom" && e.customType === "todo-state")
-			.pop();
-		if (Array.isArray(lastTodo?.data?.todos)) {
-			todos = lastTodo.data.todos;
-			nextTodoId =
-				lastTodo.data.nextTodoId ??
-				todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
-		}
+		});
 	});
 }