@zhushanwen/pi-todo 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",
@@ -28,7 +28,7 @@
     "@xyz-agent/extension-protocol": "^0.2.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "@earendil-works/pi-ai": "*",
     "@sinclair/typebox": "*"

package/src/__tests__/todo.test.ts

@@ -1,4 +1,4 @@
-import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it } from "vitest";
 
 import {

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

@@ -0,0 +1,56 @@
+// Behavioral tests for todo dual-form traps (text/texts, id/ids).
+//
+// Complements the source-text prompt-quality locks in tool-prompt.test.ts: those
+// 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.
+//
+// handleAdd/handleDelete were exported specifically to enable these tests.
+
+import { describe, expect, it } from "vitest";
+
+import { createTodoSessionState } from "../state";
+import { handleAdd, handleDelete } from "../tool";
+
+describe("handleAdd — text/texts dual-form detection", () => {
+  it("triggers dual-form error when singular 'text' used instead of 'texts'", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", text: "write spec" })).toThrow(
+      /singular "text"|add needs texts/,
+    );
+  });
+
+  it("throws 'requires texts' when neither text nor texts given", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add" })).toThrow(/requires texts/);
+  });
+
+  it("throws 'requires texts' on empty array (missing, not dual-form)", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", texts: [] })).toThrow(/requires texts/);
+  });
+
+  it("does NOT throw when correct 'texts' array provided", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", texts: ["write spec"] })).not.toThrow();
+  });
+});
+
+describe("handleDelete — id/ids dual-form detection", () => {
+  it("triggers dual-form error when singular 'id' used instead of 'ids'", () => {
+    const state = createTodoSessionState();
+    expect(() => handleDelete(state, { action: "delete", id: 5 })).toThrow(
+      /singular "id"|delete needs ids/,
+    );
+  });
+
+  it("throws 'requires ids' when neither id nor ids given", () => {
+    const state = createTodoSessionState();
+    expect(() => handleDelete(state, { action: "delete" })).toThrow(/requires ids/);
+  });
+
+  it("does NOT throw when correct 'ids' array provided (after seeding a todo)", () => {
+    const state = createTodoSessionState();
+    handleAdd(state, { action: "add", texts: ["temp"] }); // seed todo #1
+    expect(() => handleDelete(state, { action: "delete", ids: [1] })).not.toThrow();
+  });
+});

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

@@ -0,0 +1,105 @@
+// 提示词质量回归：todo tool 的 description 与 runtime 纠错文案必须是
+// "弱模型友好"的——条件必填字段要给完整 JSON 正例，双形陷阱（text/texts、
+// id/ids）要给消歧反例，失败后 throw 要带 Correct 正例让模型自我纠正。
+//
+// 本测试用源码文本断言锁定这些约束，防止后续重构把正例/反例/纠错文案删掉或
+// 弱化。读源码而非 import，避免 mock 链（tool.ts 依赖 typebox/ExtensionAPI/
+// Theme 等值导入）。参考 subagent-workflow 的 prompt 回归范式。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOL_SRC = readFileSync(join(__dirname, "../tool.ts"), "utf-8");
+
+/**
+ * 提取 description 拼接区（从 `description:` 到下一个 `promptSnippet:`）。
+ * tool.ts 的 description 用字符串拼接（非模板字面量），故整段截取后做子串断言。
+ */
+function extractDescriptionRegion(src: string): string {
+	// 锚定到 registerTodoTool 内的 tool description，而非 schema 字段的 description:
+	// （Type.String({ description: "..." }) 等 schema 字段会先被 indexOf 命中，导致
+	// 捕获区域含 schema 描述 + tool 描述——虽当前子串唯一能过但 fragile to restructuring）。
+	const regIdx = src.indexOf("registerTodoTool");
+	if (regIdx === -1) throw new Error("registerTodoTool not found in tool.ts");
+	const start = src.indexOf("description:", regIdx);
+	if (start === -1) throw new Error("tool description: not found in registerTodoTool");
+	const end = src.indexOf("promptSnippet:", start);
+	if (end === -1) throw new Error("promptSnippet: not found in tool.ts");
+	return src.slice(start, end);
+}
+
+const DESCRIPTION_REGION = extractDescriptionRegion(TOOL_SRC);
+
+// ── description 必须给完整 JSON 正例 ─────────────────
+
+describe("todo description — 给完整 JSON 正例", () => {
+	it("add 正例：含 {\"action\":\"add\",\"texts\"", () => {
+		// 弱模型 add 时易误用单数 text；正例必须显式 texts 数组。
+		expect(DESCRIPTION_REGION).toContain('{"action":"add","texts"');
+	});
+
+	it("add+verification 正例：含 isVerification", () => {
+		expect(DESCRIPTION_REGION).toContain('"isVerification":true');
+	});
+
+	it("update single 正例：含 {\"action\":\"update\",\"id\"", () => {
+		expect(DESCRIPTION_REGION).toContain('{"action":"update","id"');
+	});
+
+	it("update batch 正例：含 {\"action\":\"update\",\"updates\"", () => {
+		// updates[] 批量路径是 [批量优先] 规范的核心，正例不可缺。
+		expect(DESCRIPTION_REGION).toContain('{"action":"update","updates"');
+	});
+
+	it("delete 正例：含 {\"action\":\"delete\",\"ids\"", () => {
+		// 弱模型 delete 时易误用单数 id；正例必须显式 ids 数组。
+		expect(DESCRIPTION_REGION).toContain('{"action":"delete","ids"');
+	});
+});
+
+// ── description 必须给双形陷阱反例（消歧） ──────────
+
+describe("todo description — 双形陷阱反例（消歧单复数）", () => {
+	it("Don't 段存在", () => {
+		expect(DESCRIPTION_REGION).toMatch(/Don't/);
+	});
+
+	it("反例标注：text 属于 update（add 用 texts）", () => {
+		// 反例必须含消歧词，告诉模型 text 属于 update 而非 add。
+		expect(DESCRIPTION_REGION).toContain("text is for update");
+		expect(DESCRIPTION_REGION).toContain("add uses texts");
+	});
+
+	it("反例标注：id 属于 update（delete 用 ids）", () => {
+		expect(DESCRIPTION_REGION).toContain("id is for update");
+		expect(DESCRIPTION_REGION).toContain("delete uses ids");
+	});
+
+	it("反例标注：update 缺 id", () => {
+		expect(DESCRIPTION_REGION).toContain("missing id");
+	});
+});
+
+// ── runtime throw 必须带 Correct 纠错正例 ───────────
+
+describe("todo runtime — throw 含 Correct 纠错正例", () => {
+	it("源码含 ≥4 处 Correct: 纠错文案（覆盖 add/delete/update 路径）", () => {
+		// 每个 required throw 必须追加完整 JSON 正例，弱模型失败后能自我纠正。
+		const matches = TOOL_SRC.match(/Correct:/g) || [];
+		expect(matches.length).toBeGreaterThanOrEqual(4);
+	});
+
+	it('add 双形检测：含 singular "text" 纠错文案', () => {
+		expect(TOOL_SRC).toContain('singular "text"');
+		expect(TOOL_SRC).toContain('"text" — that field is for update');
+	});
+
+	it('delete 双形检测：含 singular "id" 纠错文案', () => {
+		expect(TOOL_SRC).toContain('singular "id"');
+		expect(TOOL_SRC).toContain('"id" — that field is for update');
+	});
+});

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

@@ -6,8 +6,8 @@
  * 已注册 tool，再以不同 ctx.mode 调 execute。每个用例新建 state（隔离），
  * 无模块级状态需重置。
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it } from "vitest";
 
 import { createTodoSessionState, type TodoSessionState } from "../state";

package/src/commands.ts

@@ -6,7 +6,7 @@
  * 用户在 TUI 中不可见。
  */
 
-import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 
 import type { TodoSessionState } from "./state";
 import { TodoListComponent } from "./component";

package/src/component.ts

@@ -2,7 +2,7 @@
  * /todos 命令的 TUI 组件 — 独立可关闭的 todo 列表视图（双列布局）。
  */
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 
 import type { Todo } from "./model";

package/src/handlers.ts

@@ -3,7 +3,7 @@
  * before_agent_start / agent_end。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
 	migrateTodo,

package/src/index.ts

@@ -20,7 +20,7 @@
  * model 层纯函数返回 Result 对象（合法），dispatcher 拿到 error 时 throw。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { registerTodosCommand } from "./commands";
 import { registerTodoEventHandlers } from "./handlers";

package/src/render.ts

@@ -2,7 +2,7 @@
  * Todo 渲染函数 — 状态栏、widget（双列）、tool result 渲染。
  */
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import {

package/src/tool.ts

@@ -4,7 +4,7 @@
 
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
-import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 
 import {
@@ -75,9 +75,18 @@ function handleList(state: TodoSessionState): string {
 }
 
 /** add action — 失败抛错 */
-function handleAdd(state: TodoSessionState, params: TodoActionParams): string {
+/** add action — 失败抛错。export 供 behavioral 测试（text/texts 双形陷阱检测）。 */
+export function handleAdd(state: TodoSessionState, params: TodoActionParams): string {
 	if (!params.texts || params.texts.length === 0) {
-		throw new Error("add requires texts parameter (non-empty array)");
+		// 双形陷阱：弱模型 add 时误用单数 text（那是 update 的字段）
+		if (params.text !== undefined) {
+			throw new Error(
+				'add needs texts (array). You passed singular "text" — that field is for update. Correct: {"action":"add","texts":["<your text>"]}',
+			);
+		}
+		throw new Error(
+			'add requires texts parameter (non-empty array). Correct: {"action":"add","texts":["..."]}',
+		);
 	}
 	const r = addTodos(state.todos, state.nextId, params.texts, params.isVerification);
 	if (r.error) throw new Error(r.resultText);
@@ -96,9 +105,14 @@ function handleBatchUpdate(state: TodoSessionState, params: TodoActionParams): s
 
 /** update action: single — 失败抛错 */
 export function handleSingleUpdate(state: TodoSessionState, params: TodoActionParams): string {
-	if (params.id === undefined) throw new Error("update requires id parameter");
+	if (params.id === undefined)
+		throw new Error(
+			'update requires id parameter. Correct: {"action":"update","id":<n>,"status":"in_progress"}',
+		);
 	if (params.status === undefined && params.text === undefined)
-		throw new Error("update requires at least status or text parameter");
+		throw new Error(
+			'update requires at least status or text parameter. Correct: {"action":"update","id":<n>,"status":"in_progress"}',
+		);
 	if (params.text !== undefined && params.text === "") throw new Error("text cannot be empty string");
 	if (
 		params.status !== undefined &&
@@ -140,9 +154,18 @@ function handleUpdate(state: TodoSessionState, params: TodoActionParams): string
 }
 
 /** delete action — 失败抛错；部分 id 缺失则整体拒绝（原子性） */
-function handleDelete(state: TodoSessionState, params: TodoActionParams): string {
+/** delete action — 失败抛错。export 供 behavioral 测试（id/ids 双形陷阱检测）。 */
+export function handleDelete(state: TodoSessionState, params: TodoActionParams): string {
 	if (!params.ids || params.ids.length === 0) {
-		throw new Error("delete requires ids parameter (non-empty array)");
+		// 双形陷阱：弱模型 delete 时误用单数 id（那是 update 的字段）
+		if (params.id !== undefined) {
+			throw new Error(
+				'delete needs ids (array). You passed singular "id" — that field is for update. Correct: {"action":"delete","ids":[<your id>]}',
+			);
+		}
+		throw new Error(
+			'delete requires ids parameter (non-empty array). Correct: {"action":"delete","ids":[<n>]}',
+		);
 	}
 	const uniqueIds = [...new Set(params.ids)];
 	const missing = uniqueIds.filter((id) => !state.todos.some((t) => t.id === id));
@@ -240,7 +263,17 @@ export function registerTodoTool(
 			"\n- add: Batch add todos (requires texts array; optional isVerification marks verification tasks)" +
 			"\n- update: Update todo(s) — single (id + optional status/text) or batch (updates[], takes priority)" +
 			"\n- delete: Batch delete todos (requires ids array)" +
-			"\n- clear: Clear all todos and reset IDs",
+			"\n- clear: Clear all todos and reset IDs" +
+			"\n\nExamples:" +
+			'\n{"action":"add","texts":["write spec","implement"]}' +
+			'\n{"action":"add","texts":["run tests"],"isVerification":true}' +
+			'\n{"action":"update","id":1,"status":"in_progress"}' +
+			'\n{"action":"update","updates":[{"id":1,"status":"completed"},{"id":2,"status":"in_progress"}]}' +
+			'\n{"action":"delete","ids":[3]}' +
+			"\n\nDon't:" +
+			'\n{"action":"add","text":"x"} ← text is for update; add uses texts:[...]' +
+			'\n{"action":"delete","id":3} ← id is for update; delete uses ids:[...]' +
+			'\n{"action":"update","status":"x"} ← missing id',
 		promptSnippet: "Use todo when breaking multi-step work into trackable items. Add verification todos (isVerification=true) for checks like running tests.",
 		promptGuidelines: [
 			"[Usage] 多步骤工作（3+步）时使用。AI 自发创建，无需用户触发",