@zhushanwen/pi-todo 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/gui.test.ts

@@ -3,18 +3,17 @@ import { describe, expect, it } from "vitest";
 import { buildGui, type Todo } from "../model";
 
 describe("buildGui", () => {
-	it("maps 4 statuses to list-tree with correct icons", () => {
+	it("maps 3 statuses to list-tree with correct icons", () => {
 		const todos: Todo[] = [
 			{ id: 1, text: "pending task", status: "pending" },
 			{ id: 2, text: "active task", status: "in_progress" },
 			{ id: 3, text: "done task", status: "completed" },
-			{ id: 4, text: "cancelled task", status: "cancelled" },
 		];
 		const gui = buildGui(todos);
 		expect(gui.v).toBe(1);
 		expect(gui.component.type).toBe("list-tree");
 		const items = gui.component.props.items;
-		expect(items).toHaveLength(4);
+		expect(items).toHaveLength(3);
 		// pending → dot, no status（guiResult 的 stripUndefined 删除 undefined 键）
 		expect(items[0]).toMatchObject({ icon: "dot", label: "#1: pending task", depth: 0 });
 		expect(items[0]).not.toHaveProperty("status");
@@ -22,8 +21,6 @@ describe("buildGui", () => {
 		expect(items[1]).toMatchObject({ icon: "circle", label: "#2: active task", status: "running", depth: 0 });
 		// completed → check, done
 		expect(items[2]).toMatchObject({ icon: "check", label: "#3: done task", status: "done", depth: 0 });
-		// cancelled → cross, failed
-		expect(items[3]).toMatchObject({ icon: "cross", label: "#4: cancelled task", status: "failed", depth: 0 });
 	});
 
 	it("empty todos → empty list-tree", () => {

package/src/__tests__/schema.test.ts

@@ -0,0 +1,76 @@
+// Schema 强约束回归（T4/TC3/TC4）：TodoParams 为 discriminated union（按 action），
+// 每个分支只声明自己的参数且 additionalProperties:false。用 typebox 的 Value.Check
+// 验证：缺失必填、多余字段、已删除的 action 都在 schema 层被拒绝，不依赖运行时 throw。
+//
+// 选 Value.Check 而非 ajv：typebox 自带 Value 校验器与其 schema 语义一致；
+// spike 确认 Value.Check 与 plain ajv 对本 schema 的拒绝结论一致（ajv 的
+// discriminator:true 选项会编译失败，故不依赖该选项）。
+
+import { describe, expect, it } from "vitest";
+
+import { Value } from "typebox/value";
+
+import { TodoParams } from "../tool";
+
+describe("TodoParams discriminated union schema", () => {
+	describe("合法 payload 通过", () => {
+		it("list（无参）", () => {
+			expect(Value.Check(TodoParams, { action: "list" })).toBe(true);
+		});
+		it("add + texts", () => {
+			expect(Value.Check(TodoParams, { action: "add", texts: ["write spec"] })).toBe(true);
+		});
+		it("update 单条 + id + status", () => {
+			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "in_progress" })).toBe(true);
+		});
+		it("update 批量 + updates", () => {
+			expect(Value.Check(TodoParams, { action: "update", updates: [{ id: 1, status: "completed" }] })).toBe(true);
+		});
+		it("delete + ids", () => {
+			expect(Value.Check(TodoParams, { action: "delete", ids: [1, 2] })).toBe(true);
+		});
+	});
+
+	describe("TC4: 缺失必填被 schema 拒绝", () => {
+		it("add 缺 texts", () => {
+			expect(Value.Check(TodoParams, { action: "add" })).toBe(false);
+		});
+		it("update 缺 id 且缺 updates", () => {
+			expect(Value.Check(TodoParams, { action: "update" })).toBe(false);
+		});
+		it("delete 缺 ids", () => {
+			expect(Value.Check(TodoParams, { action: "delete" })).toBe(false);
+		});
+	});
+
+	describe("TC3: 已删除的 clear action 被拒绝", () => {
+		it("clear 不在 action 枚举内", () => {
+			expect(Value.Check(TodoParams, { action: "clear" })).toBe(false);
+		});
+	});
+
+	describe("额外属性被拒绝（additionalProperties:false）", () => {
+		it("TC7: add 同时传 text+texts（text 是多余字段）→ 拒绝", () => {
+			// schema 层拒绝双形陷阱；handler 层另有 defense-in-depth throw（见 tool-detectors）
+			expect(Value.Check(TodoParams, { action: "add", texts: ["y"], text: "x" })).toBe(false);
+		});
+		it("list 携带多余 texts → 拒绝", () => {
+			expect(Value.Check(TodoParams, { action: "list", texts: ["x"] })).toBe(false);
+		});
+		it("update 单条携带多余 ids → 拒绝", () => {
+			expect(Value.Check(TodoParams, { action: "update", id: 1, ids: [1] })).toBe(false);
+		});
+	});
+
+	describe("status 枚举强约束", () => {
+		it("合法三态 status 通过", () => {
+			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "completed" })).toBe(true);
+		});
+		it("TC2: cancelled 不再合法", () => {
+			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "cancelled" })).toBe(false);
+		});
+		it("非法 status 被拒绝", () => {
+			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "banana" })).toBe(false);
+		});
+	});
+});

package/src/__tests__/steer.test.ts

@@ -2,11 +2,8 @@ import { describe, expect, it } from "vitest";
 
 import {
 	buildBeforeAgentStartMessage,
-	buildMinimalReminder,
 	handleAutoClear,
 	handleCompletionSteer,
-	handleReminder,
-	handleStallDetection,
 	reconstructState,
 } from "../handlers";
 import type { Todo } from "../model";
@@ -101,95 +98,7 @@ describe("handleAutoClear", () => {
 	});
 });
 
-// ── stall detection ─────────────────────────────────
-
-describe("handleStallDetection", () => {
-	it("fires once when idle exceeds STALL_THRESHOLD (5)", () => {
-		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
-			userMessageCount: 10, lastTodoCallCount: 5,
-		});
-		expect(handleStallDetection(s)).toBe(true);
-		expect(s.stallNotified).toBe(true);
-		expect(s.pendingSteerMessage).toContain("#1");
-	});
-
-	it("does not fire twice (single-shot lock)", () => {
-		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
-			userMessageCount: 10, lastTodoCallCount: 5, stallNotified: true,
-		});
-		expect(handleStallDetection(s)).toBe(false);
-		expect(s.pendingSteerMessage).toBeNull();
-	});
-
-	it("does not fire below threshold", () => {
-		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
-			userMessageCount: 8, lastTodoCallCount: 5,
-		});
-		expect(handleStallDetection(s)).toBe(false);
-	});
-});
-
-// ── reminder ────────────────────────────────────────
-
-describe("handleReminder", () => {
-	it("fires when idle exceeds REMINDER_INTERVAL (2)", () => {
-		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
-			userMessageCount: 5, lastTodoCallCount: 3,
-		});
-		expect(handleReminder(s)).toBe(true);
-		expect(s.pendingSteerMessage).toContain("#1");
-	});
-
-	it("does not fire within interval", () => {
-		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
-			userMessageCount: 4, lastTodoCallCount: 3,
-		});
-		expect(handleReminder(s)).toBe(false);
-	});
-});
-
-// ── reminder / context builders ─────────────────────
-
-	describe("buildMinimalReminder", () => {
-	it("mentions the next pending task with action directive", () => {
-		const s = makeState([
-			{ id: 1, text: "done", status: "completed" },
-			{ id: 2, text: "next", status: "pending" },
-		]);
-		const out = buildMinimalReminder(s);
-		expect(out).toContain("#2 next");
-		expect(out).toContain("必须处理");
-		expect(out).toContain("todo update");
-	});
-
-	it("includes in_progress todos as pending", () => {
-		const s = makeState([
-			{ id: 1, text: "working", status: "in_progress" },
-			{ id: 2, text: "next", status: "pending" },
-		]);
-		expect(buildMinimalReminder(s)).toContain("#1 working");
-	});
-
-	it("excludes cancelled todos from reminder", () => {
-		const s = makeState([
-			{ id: 1, text: "cancelled task", status: "cancelled" },
-			{ id: 2, text: "active", status: "in_progress" },
-		]);
-		const out = buildMinimalReminder(s);
-		expect(out).toContain("#2 active");
-		expect(out).not.toContain("#1");
-	});
-
-	it("returns empty string when only cancelled remain", () => {
-		expect(
-			buildMinimalReminder(makeState([{ id: 1, text: "x", status: "cancelled" }])),
-		).toBe("");
-	});
-
-	it("returns empty string when no pending", () => {
-		expect(buildMinimalReminder(makeState([{ id: 1, text: "done", status: "completed" }]))).toBe("");
-	});
-});
+// ── before_agent_start context injection ────────────
 
 describe("buildBeforeAgentStartMessage", () => {
 	it("injects hidden context for pending tasks only", () => {
@@ -213,21 +122,12 @@ describe("buildBeforeAgentStartMessage", () => {
 		expect(m!.message.content).toContain("搁置不等于完成");
 	});
 
-	it("excludes cancelled todos from context injection", () => {
+	it("includes in_progress todos as pending", () => {
 		const s = makeState([
-			{ id: 1, text: "cancelled", status: "cancelled" },
-			{ id: 2, text: "active", status: "pending" },
+			{ id: 1, text: "working", status: "in_progress" },
+			{ id: 2, text: "next", status: "pending" },
 		]);
-		const m = buildBeforeAgentStartMessage(s);
-		expect(m).toBeDefined();
-		expect(m!.message.content).toContain("#2: active");
-		expect(m!.message.content).not.toContain("#1");
-	});
-
-	it("returns undefined when only cancelled remain", () => {
-		expect(
-			buildBeforeAgentStartMessage(makeState([{ id: 1, text: "x", status: "cancelled" }])),
-		).toBeUndefined();
+		expect(buildBeforeAgentStartMessage(s)!.message.content).toContain("#1: working");
 	});
 
 	it("returns undefined when list empty", () => {
@@ -260,7 +160,7 @@ describe("reconstructState", () => {
 		expect(s.nextId).toBe(2);
 	});
 
-	it("uses the last todo entry and GCs older ones (splice from tail)", () => {
+	it("uses the last todo entry (不再 splice GC 旧条目)", () => {
 		const entries = [
 			todoEntry([{ id: 1, text: "old", status: "pending" }], 2),
 			todoEntry([{ id: 5, text: "new", status: "completed" }], 6),
@@ -269,7 +169,19 @@ describe("reconstructState", () => {
 		reconstructState(s, makeCtx(entries));
 		expect(s.todos[0].id).toBe(5);
 		expect(s.nextId).toBe(6);
-		expect(entries).toHaveLength(1);
+	});
+
+	it("TC10: 不修改传入的 entries（纯读，不再 splice）", () => {
+		const entries = [
+			todoEntry([{ id: 1, text: "old", status: "pending" }], 2),
+			todoEntry([{ id: 5, text: "new", status: "completed" }], 6),
+		];
+		const ctx = makeCtx(entries);
+		const seen = ctx.sessionManager.getEntries();
+		const lenBefore = seen.length;
+		const s = createTodoSessionState();
+		reconstructState(s, ctx);
+		expect(seen).toHaveLength(lenBefore); // reconstructState 未 splice 任何条目
 	});
 
 	it("migrates legacy status on replay", () => {
@@ -280,6 +192,14 @@ describe("reconstructState", () => {
 		expect(s.todos[0].status).toBe("pending");
 	});
 
+	it("migrates legacy cancelled → completed on replay (TC1)", () => {
+		const legacy = [{ id: 1, text: "a", status: "cancelled" }] as unknown as Todo[];
+		const entries = [todoEntry(legacy, 2)];
+		const s = createTodoSessionState();
+		reconstructState(s, makeCtx(entries));
+		expect(s.todos[0].status).toBe("completed");
+	});
+
 	it("skips dirty (null/primitive) elements without throwing", () => {
 		const entries = [
 			todoEntry([null, { id: 1, text: "ok", status: "pending" }] as unknown as Todo[], 3),

package/src/__tests__/todo.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from "vitest";
 import {
 	addTodos,
 	formatTodoLine,
+	formatTodoList,
 	migrateTodo,
 	type Todo,
 	updateTodos,
@@ -25,8 +26,8 @@ describe("Todo data model", () => {
 		expect(migrated.id).toBe(1);
 	});
 
-	it("should include exactly four valid statuses", () => {
-		expect(VALID_STATUSES).toEqual(["pending", "in_progress", "completed", "cancelled"]);
+	it("VALID_STATUSES 仅三态（pending/in_progress/completed）", () => {
+		expect(VALID_STATUSES).toEqual(["pending", "in_progress", "completed"]);
 	});
 
 	it("should migrate verifying → in_progress", () => {
@@ -53,10 +54,12 @@ describe("Todo data model", () => {
 		expect(migrated.status).toBe("pending");
 	});
 
-	it("should preserve cancelled status (FR-1 four-state)", () => {
+	it("TC1: 历史 cancelled → completed（三态化降级，不丢数据）", () => {
 		const todo = { id: 1, text: "dropped", status: "cancelled" } as unknown as Todo;
 		const migrated = migrateTodo(todo);
-		expect(migrated.status).toBe("cancelled");
+		expect(migrated.status).toBe("completed");
+		expect(migrated.text).toBe("dropped");
+		expect(migrated.id).toBe(1);
 	});
 
 	it("should throw on null/primitive input (dirty data guard)", () => {
@@ -71,7 +74,6 @@ describe("Todo data model", () => {
 describe("todo add", () => {
 	it("should add todos with sequential IDs", () => {
 		const result = addTodos([], 1, ["A", "B"]);
-		expect(result.error).toBeUndefined();
 		expect(result.newTodos).toHaveLength(2);
 		expect(result.newTodos[0].id).toBe(1);
 		expect(result.newTodos[1].id).toBe(2);
@@ -81,26 +83,24 @@ describe("todo add", () => {
 	it("should append to existing todos", () => {
 		const existing: Todo[] = [{ id: 1, text: "existing", status: "pending" }];
 		const result = addTodos(existing, 2, ["new task"]);
-		expect(result.error).toBeUndefined();
 		expect(result.newTodos).toHaveLength(2);
 		expect(result.newTodos[1].id).toBe(2);
 		expect(result.newTodos[1].text).toBe("new task");
 		expect(result.newNextId).toBe(3);
 	});
 
-	it("should return error when texts is empty", () => {
-		const result = addTodos([], 1, []);
-		expect(result.error).toBe("texts required");
+	it("TC6: should throw when texts is empty array", () => {
+		expect(() => addTodos([], 1, [])).toThrow(/requires texts/);
 	});
 
-	it("should return error when all texts are empty after trim", () => {
-		const result = addTodos([], 1, ["  ", " "]);
-		expect(result.error).toBe("all texts empty");
+	it("TC6: should throw when any text is empty after trim (不再静默 filter)", () => {
+		// C1 决策：任一项 trim 后空串 → throw，不再 filter 静默丢弃
+		expect(() => addTodos([], 1, ["  ", "valid"])).toThrow(/empty or whitespace-only/);
+		expect(() => addTodos([], 1, ["  ", " "])).toThrow(/empty or whitespace-only/);
 	});
 
 	it("should trim texts", () => {
 		const result = addTodos([], 1, ["  new task  "]);
-		expect(result.error).toBeUndefined();
 		expect(result.newTodos[0].text).toBe("new task");
 	});
 });
@@ -130,6 +130,18 @@ describe("todo update batch", () => {
 		expect(result.updatedTodos[2].text).toBe("C done");
 	});
 
+	it("TC6: trims text on apply（批量路径）", () => {
+		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
+		const result = updateTodos(todos, [{ id: 1, text: "  B updated  " }]);
+		expect(result.error).toBeUndefined();
+		expect(result.updatedTodos[0].text).toBe("B updated");
+	});
+
+	it("TC6: should throw when any batch text is empty after trim (不再静默跳过)", () => {
+		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
+		expect(() => updateTodos(todos, [{ id: 1, text: "   " }])).toThrow(/empty or whitespace-only/);
+	});
+
 	it("should reject duplicate ids in updates[]", () => {
 		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
 		const result = updateTodos(todos, [
@@ -157,24 +169,31 @@ describe("todo update batch", () => {
 		const result = updateTodos(todos, [{ id: 1, status: "banana" }]);
 		expect(result.error).toContain("invalid status");
 	});
-
-	it("cancelled todo 不可恢复（status 更新拒绝）", () => {
-		const todos: Todo[] = [{ id: 1, text: "dropped", status: "cancelled" }];
-		const result = updateTodos(todos, [{ id: 1, status: "pending" }]);
-		expect(result.error).toBe("id 1 is cancelled");
-		expect(result.resultText).toContain("cannot be restored");
-		expect(result.updatedTodos).toEqual(todos);
-	});
 });
 
 // ── handleSingleUpdate 守卫（tool 单条路径）────
 
 describe("handleSingleUpdate guards (tool single path)", () => {
-	it("cancelled todo + status → cannot restore", () => {
+	it("TC6: text='  ' (纯空格) → throw (trim 后空串拒绝，不只判 ===)", () => {
 		const state = createTodoSessionState();
-		state.todos = [{ id: 1, text: "dropped", status: "cancelled" }];
-		expect(() => handleSingleUpdate(state, { action: "update", id: 1, status: "pending" }))
-			.toThrow("#1 is cancelled (cannot restore)");
+		state.todos = [{ id: 1, text: "x", status: "pending" }];
+		expect(() => handleSingleUpdate(state, { action: "update", id: 1, text: "   " }))
+			.toThrow(/empty or whitespace-only/);
+	});
+
+	it("trims text on apply", () => {
+		const state = createTodoSessionState();
+		state.todos = [{ id: 1, text: "x", status: "pending" }];
+		handleSingleUpdate(state, { action: "update", id: 1, text: "  hello  " });
+		expect(state.todos[0].text).toBe("hello");
+	});
+
+	it("TC11: 最后一个 completed 时无 'All todos completed' 收尾文案", () => {
+		const state = createTodoSessionState();
+		state.todos = [{ id: 1, text: "only", status: "in_progress" }];
+		const out = handleSingleUpdate(state, { action: "update", id: 1, status: "completed" });
+		expect(out).not.toContain("All todos completed");
+		expect(out).toContain("Updated todo #1");
 	});
 });
 
@@ -210,7 +229,7 @@ describe("completed without interception", () => {
 	});
 });
 
-// ── formatTodoLine ──────────────────────────────────
+// ── formatTodoLine / formatTodoList ──────────────────
 
 describe("formatTodoLine", () => {
 	it("should format pending todo", () => {
@@ -227,10 +246,20 @@ describe("formatTodoLine", () => {
 		const todo: Todo = { id: 3, text: "task C", status: "completed" };
 		expect(formatTodoLine(todo)).toBe("[x] #3: task C");
 	});
+});
+
+describe("formatTodoList (TC3/TC5)", () => {
+	it("TC5: formats the full list by reusing formatTodoLine, joined by newline", () => {
+		const todos: Todo[] = [
+			{ id: 1, text: "A", status: "pending" },
+			{ id: 2, text: "B", status: "in_progress" },
+			{ id: 3, text: "C", status: "completed" },
+		];
+		expect(formatTodoList(todos)).toBe("[ ] #1: A\n[~] #2: B\n[x] #3: C");
+	});
 
-	it("should format cancelled todo", () => {
-		const todo: Todo = { id: 4, text: "task D", status: "cancelled" };
-		expect(formatTodoLine(todo)).toBe("[-] #4: task D");
+	it("empty list → empty string", () => {
+		expect(formatTodoList([])).toBe("");
 	});
 });
 
@@ -314,68 +343,3 @@ describe("widget rendering", () => {
 		expect(lines.length).toBe(11); // 1 header + ceil(19/2)=10 rows; Pi truncates at 10
 	});
 });
-
-// ── agent_end logic (pure data) ─────────────────────
-
-describe("agent_end logic", () => {
-	it("should detect stall when no todo activity for threshold rounds", () => {
-		const STALL_THRESHOLD = 5;
-		const userMessageCount = 10;
-		const lastTodoCallCount = 3;
-		const todos: Todo[] = [{ id: 1, text: "pending task", status: "pending" }];
-
-		const isStalled =
-			todos.length > 0 &&
-			userMessageCount - lastTodoCallCount >= STALL_THRESHOLD;
-
-		expect(isStalled).toBe(true);
-	});
-
-	it("should detect reminder when interval elapsed", () => {
-		const REMINDER_INTERVAL = 2;
-		const userMessageCount = 5;
-		const lastTodoCallCount = 3;
-		const todos: Todo[] = [{ id: 1, text: "task", status: "pending" }];
-
-		const needsReminder =
-			todos.length > 0 &&
-			userMessageCount - lastTodoCallCount >= REMINDER_INTERVAL;
-
-		expect(needsReminder).toBe(true);
-	});
-
-	it("should auto-clear when all completed and delay rounds elapsed", () => {
-		const AUTO_CLEAR_DELAY_ROUNDS = 2;
-		const userMessageCount = 7;
-		const allCompletedAtCount = 4;
-
-		const shouldClear =
-			allCompletedAtCount !== null &&
-			userMessageCount - allCompletedAtCount >= AUTO_CLEAR_DELAY_ROUNDS;
-
-		expect(shouldClear).toBe(true);
-	});
-
-	it("should not auto-clear when delay rounds not yet elapsed", () => {
-		const AUTO_CLEAR_DELAY_ROUNDS = 2;
-		const userMessageCount = 5;
-		const allCompletedAtCount = 4;
-
-		const shouldClear =
-			allCompletedAtCount !== null &&
-			userMessageCount - allCompletedAtCount >= AUTO_CLEAR_DELAY_ROUNDS;
-
-		expect(shouldClear).toBe(false);
-	});
-
-	it("should pick first pending todo as next recommended", () => {
-		const todos: Todo[] = [
-			{ id: 1, text: "A", status: "completed" },
-			{ id: 2, text: "B", status: "pending" },
-			{ id: 3, text: "C", status: "pending" },
-		];
-		const next = todos.find((t) => t.status !== "completed");
-		expect(next!.id).toBe(2);
-		expect(next!.text).toBe("B");
-	});
-});

package/src/__tests__/tool-detectors.test.ts

@@ -4,6 +4,11 @@
 // verify the Correct/error STRINGS exist; these exercise the actual throw logic of
 // handleAdd/handleDelete, so a refactor cannot silently drop the dual-form detection.
 //
+// Note: the schema layer (TodoParams, additionalProperties:false) already rejects
+// dual-form payloads before they reach the handler in production. These handler-level
+// tests are defense-in-depth — they ensure the handler ALSO throws clearly if called
+// directly (e.g. by another extension bypassing schema validation).
+//
 // handleAdd/handleDelete were exported specifically to enable these tests.
 
 import { describe, expect, it } from "vitest";
@@ -29,6 +34,13 @@ describe("handleAdd — text/texts dual-form detection", () => {
     expect(() => handleAdd(state, { action: "add", texts: [] })).toThrow(/requires texts/);
   });
 
+  it("TC7: 同时传 text 和 texts → throw（明确提示 add 只接受 texts）", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", text: "x", texts: ["y"] })).toThrow(
+      /only accepts texts array/,
+    );
+  });
+
   it("does NOT throw when correct 'texts' array provided", () => {
     const state = createTodoSessionState();
     expect(() => handleAdd(state, { action: "add", texts: ["write spec"] })).not.toThrow();