@pi-archimedes/todo 2.0.1 → 2.2.0

package/README.md

@@ -2,7 +2,9 @@
 
 Todo list management with auto-clear and live subagent visibility for the [Pi coding agent](https://github.com/earendil-works/pi).
 
-## Features
+Track complex multi-step tasks structured in a todo list with automatic clearing on completion and live side-by-side visibility into subagent tasks. Having an active progress display keeps long tasks on track and gives both you and the model clear visibility into completed steps and next actions.
+
+## What you get
 
 - **`manage_todo_list` tool** — structured todo tracking with `read` and `write` operations
 - **Auto-clear** — when all todos are completed, the list clears itself after a brief 2-second delay
@@ -25,16 +27,16 @@ Main agent todos (left) alongside a subagent's todos (right), separated by a div
 
 ![todos and subagent](../../docs/images/todos-and-subagent.png)
 
-## Installation
+## Install
 
 ```bash
-pi install @pi-archimedes/todo
+pi install npm:@pi-archimedes/todo
 ```
 
-Or install the full [pi-archimedes](../..) meta package for the integrated experience:
+Or install full meta package:
 
 ```bash
-pi install pi-archimedes
+pi install npm:pi-archimedes
 ```
 
 ## Usage
@@ -79,8 +81,10 @@ The `manage_todo_list` tool accepts two operations:
 
 ## Auto-clear
 
-When all todos in the list are marked `completed`, the widget shows the all-done state for 2 seconds, then auto-clears. No need to manually run `/todos clear`.
+When all todos in the list are marked as `completed`, the widget shows the all-done state for 2 seconds, then auto-clears. No need to manually run `/todos clear`.
 
-## Subagent integration
+## Integration
 
 When installed via `pi-archimedes` (the meta package), subagent todo events flow through `@pi-archimedes/core/bus` and appear as separate columns in the widget. Each subagent gets its own column labeled with its agent name. The column auto-removes when the subagent finishes.
+
+← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/todo",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.0.1"
+    "@pi-archimedes/core": "2.2.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/state-manager.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fc from "fast-check";
+import { TodoStateManager } from "./state-manager.js";
+import type { TodoItem } from "./types.js";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeTodo(id: number, title: string, description: string, status: TodoItem["status"]): TodoItem {
+  return { id, title, description, status };
+}
+
+// ── TodoStateManager ────────────────────────────────────────────────────────
+
+describe("TodoStateManager", () => {
+  let manager: TodoStateManager;
+
+  beforeEach(() => {
+    manager = new TodoStateManager();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("read", () => {
+    it("returns empty array initially", () => {
+      expect(manager.read()).toEqual([]);
+    });
+
+    it("returns copy (mutations don't affect internal state)", () => {
+      manager.write([makeTodo(1, "Test", "desc", "not-started")]);
+      const copy = manager.read();
+      copy.push(makeTodo(2, "Injected", "desc", "not-started"));
+      expect(manager.read()).toHaveLength(1);
+    });
+  });
+
+  describe("write", () => {
+    it("stores todos correctly", () => {
+      manager.write([
+        makeTodo(1, "Task 1", "desc 1", "not-started"),
+        makeTodo(2, "Task 2", "desc 2", "in-progress"),
+      ]);
+      expect(manager.read()).toHaveLength(2);
+      expect(manager.read()[0]?.title).toBe("Task 1");
+      expect(manager.read()[1]?.status).toBe("in-progress");
+    });
+
+    it("with all completed schedules auto-clear", () => {
+      manager.write([makeTodo(1, "Done", "desc", "completed")]);
+      expect(manager.read()).toHaveLength(1);
+      vi.advanceTimersByTime(2000);
+      expect(manager.read()).toHaveLength(0);
+    });
+
+    it("does not schedule auto-clear when not all completed", () => {
+      manager.write([
+        makeTodo(1, "Done", "desc", "completed"),
+        makeTodo(2, "Pending", "desc", "not-started"),
+      ]);
+      vi.advanceTimersByTime(2000);
+      expect(manager.read()).toHaveLength(2);
+    });
+  });
+
+  describe("clear", () => {
+    it("empties todos", () => {
+      manager.write([makeTodo(1, "Task", "desc", "not-started")]);
+      manager.clear();
+      expect(manager.read()).toEqual([]);
+    });
+  });
+
+  describe("getStats", () => {
+    it("computes correct counts", () => {
+      manager.write([
+        makeTodo(1, "A", "desc", "not-started"),
+        makeTodo(2, "B", "desc", "in-progress"),
+        makeTodo(3, "C", "desc", "completed"),
+        makeTodo(4, "D", "desc", "completed"),
+      ]);
+      expect(manager.getStats()).toEqual({
+        total: 4,
+        completed: 2,
+        inProgress: 1,
+        notStarted: 1,
+      });
+    });
+
+    it("returns zero stats for empty list", () => {
+      expect(manager.getStats()).toEqual({
+        total: 0,
+        completed: 0,
+        inProgress: 0,
+        notStarted: 0,
+      });
+    });
+  });
+
+  describe("validate", () => {
+    it("catches missing fields", () => {
+      const result = manager.validate([{ id: 1, title: "", description: "", status: "" } as any]);
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+
+    it("catches invalid status values", () => {
+      const result = manager.validate([{ id: 1, title: "Test", description: "desc", status: "invalid" } as any]);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]).toContain("status");
+    });
+
+    it("catches non-array input", () => {
+      const result = manager.validate("not an array" as any);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]).toBe("todoList must be an array");
+    });
+
+    it("accepts valid input", () => {
+      const result = manager.validate([
+        makeTodo(1, "Task", "desc", "not-started"),
+        makeTodo(2, "Task 2", "desc", "in-progress"),
+        makeTodo(3, "Task 3", "desc", "completed"),
+      ]);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
+    it("property: validate(write(x)).valid === true after write (round-trip)", () => {
+      fc.assert(
+        fc.property(
+          fc.array(
+            fc.record({
+              id: fc.nat({ max: 1000 }),
+              title: fc.string({ minLength: 1, maxLength: 50 }),
+              description: fc.string({ minLength: 1, maxLength: 100 }),
+              status: fc.oneof(fc.constant("not-started"), fc.constant("in-progress"), fc.constant("completed")),
+            }),
+          ),
+          (todos) => {
+            const mgr = new TodoStateManager();
+            mgr.write(todos as TodoItem[]);
+            const readTodos = mgr.read();
+            const result = mgr.validate(readTodos);
+            if (!result.valid) {
+              throw new Error(`Round-trip validation failed: ${JSON.stringify(result.errors)}`);
+            }
+          },
+        ),
+        { verbose: false },
+      );
+    });
+  });
+});