@xynogen/pix-todo 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,25 @@
+# pix-todo
+
+Pi tool — durable execution checklist (`todo`).
+
+## What it does
+
+Registers the `todo` tool, which gives the agent a persistent task checklist that survives context compaction and session restore. The checklist is seeded by the model via the `set` action and tracks items through four statuses: `pending` (○), `in_progress` (◐), `done` (●), and `blocked` (⊘). State is persisted via Pi's `appendEntry("todo-state")` so the agent can recover its position after long runs or compaction events. The agent calls `todo(action:"list")` to resume where it left off. Actions: `list`, `set`, `add`, `update`, `clear`.
+
+## Install
+
+```bash
+pi install npm:@xynogen/pix-todo
+```
+
+## Full distro
+
+To install the complete pix suite (all packages + Pi itself):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
+```
+
+## License
+
+MIT

package/package.json

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

package/src/once.ts

@@ -0,0 +1,16 @@
+/**
+ * Idempotency guard for extension activation.
+ *
+ * pix-core (the meta-package) invokes this package's factory in addition to a
+ * possible direct install. Pi's loader uses jiti with `moduleCache: false`, so
+ * each load pass re-evaluates modules — a plain module-level flag would not be
+ * shared. The dedupe key therefore lives on `globalThis`, which persists for
+ * the lifetime of the process across all load passes.
+ */
+export function once(key: string, fn: () => void): void {
+	const g = globalThis as { __pixLoaded?: Set<string> };
+	const loaded = (g.__pixLoaded ??= new Set<string>());
+	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("pix-todo") — a process-wide globalThis
+// guard that dedupes activation across pix-core + a standalone install. Tests
+// re-register a fresh host per case, so clear the registry first to let each
+// registerTodo run (mirrors pix-core/once.test.ts clearing __pixLoaded).
+beforeEach(() => {
+	delete (globalThis as { __pixLoaded?: Set<string> }).__pixLoaded;
+});
+
 // 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("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);
-		}
+		});
 	});
 }