@zhushanwen/pi-goal 0.3.0 → 0.4.1

package/src/__tests__/goal-control-adapter.test.ts

@@ -0,0 +1,303 @@
+/**
+ * goal_control adapter 测试 — handler 用 fake ports
+ *
+ * 覆盖 #3 验收：
+ * - complete: active 守卫 + evidence 必填 + finalizeAndPersist（status→complete + history）
+ * - report_blocked: active 守卫 + reason 必填 + tickState + transitionStatus(active→blocked) + persistState
+ *
+ * 全解耦后不再测 todo 前置检查（checkCompletePrerequisites / buildProgressInput / findIncompleteTodos 已删）。
+ * complete 不做 todo 完成硬检查——AI 自行判断（prompt 软建议）。
+ *
+ * 不 import Pi SDK（handler 接收 ServicePorts，纯逻辑）。
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	handleComplete,
+	handleCreate,
+	handleReportBlocked,
+} from "../adapters/goal-control-adapter";
+import { createGoalState, transitionStatus } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import type { UiPort } from "../ports";
+import type { ServicePorts } from "../service";
+import { createGoalSession } from "../session";
+
+// ── Fake Ports ───────────────────────────────────────
+
+function makeFakePorts(): ServicePorts & {
+	states: GoalRuntimeState[];
+	history: unknown[];
+	notifications: Array<{ text: string; level: string }>;
+} {
+	const states: GoalRuntimeState[] = [];
+	const history: unknown[] = [];
+	const notifications: Array<{ text: string; level: string }> = [];
+	return {
+		states,
+		history,
+		notifications,
+		persistence: {
+			appendState: (s) => {
+				states.push(s);
+			},
+			appendHistory: (e) => {
+				history.push(e);
+			},
+		},
+		ui: {
+			setWidget: () => {},
+			setStatus: () => {},
+			notify: (text, level) => {
+				notifications.push({ text, level });
+			},
+			hasUI: true,
+			// widget.asTheme 期望 fg/bold（ports.ts 的 uiPort 同样携带）
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		} as UiPort,
+		messaging: {
+			sendContextMessage: () => {},
+			sendUserMessage: () => {},
+		},
+		session: {
+			getEntries: () => [],
+			getContextUsage: () => null,
+			signal: undefined,
+		},
+	};
+}
+
+const activeState = (overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeState => ({
+	...createGoalState("test"),
+	...overrides,
+});
+
+// ── handleComplete ───────────────────────────────────
+
+describe("handleComplete — active 守卫 + evidence + finalizeAndPersist", () => {
+	it("active + evidence → status complete + 写 history", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		const ports = makeFakePorts();
+
+		const details = handleComplete({ action: "complete", evidence: "tests pass" }, session, ports);
+
+		expect(details.action).toBe("complete");
+		expect(details.status).toBe("complete");
+		expect(session.state!.status).toBe("complete");
+		// finalizeAndPersist 写 history（FR-8.7）
+		expect(ports.history).toHaveLength(1);
+		expect(ports.notifications[0]?.level).toBe("info");
+	});
+
+	it("非 active（blocked）→ throw", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "blocked" });
+		expect(() => handleComplete({ action: "complete", evidence: "x" }, session, makeFakePorts())).toThrow(
+			/not active/,
+		);
+	});
+
+	it("evidence 空 → throw", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() =>
+			handleComplete({ action: "complete", evidence: "   " }, session, makeFakePorts()),
+		).toThrow(/evidence/);
+	});
+
+	it("completedTasks 写入 history", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		const ports = makeFakePorts();
+		handleComplete({ action: "complete", evidence: "done", completedTasks: 5 }, session, ports);
+		expect((ports.history[0] as { completedTasks?: number }).completedTasks).toBe(5);
+	});
+});
+
+// ── handleCreate ─────────────────────────────────────
+
+describe("handleCreate — slug+objective 必填 + 非终态守卫 + createGoal", () => {
+	it("无旧 goal + slug + objective → status active + slug 写入 + 持久化 + notify", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		const details = handleCreate(
+			{ action: "create", slug: "ship-feature-x", objective: "ship feature X" },
+			session,
+			ports,
+		);
+
+		expect(details.action).toBe("create");
+		expect(details.status).toBe("active");
+		expect(details.slug).toBe("ship-feature-x");
+		expect(session.state).not.toBeNull();
+		expect(session.state!.objective).toBe("ship feature X");
+		expect(session.state!.slug).toBe("ship-feature-x");
+		expect(session.state!.status).toBe("active");
+		// createGoal 内部 persistState 写一条 state
+		expect(ports.states).toHaveLength(1);
+		expect(ports.notifications[0]?.level).toBe("info");
+		expect(ports.notifications[0]?.text).toContain("ship feature X");
+	});
+
+	it("objective 空 → throw（即使有 slug）", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate({ action: "create", slug: "x", objective: "   " }, session, makeFakePorts()),
+		).toThrow(/objective/);
+	});
+
+	it("slug 空 → throw（即使有 objective）", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate({ action: "create", slug: "   ", objective: "do thing" }, session, makeFakePorts()),
+		).toThrow(/slug/);
+	});
+
+	it("slug 缺省 → throw", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate({ action: "create", objective: "do thing" }, session, makeFakePorts()),
+		).toThrow(/slug/);
+	});
+
+	it("已有 active goal → throw（D25 非终态守卫）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "active" });
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "new", objective: "new obj" },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/already active/i);
+	});
+
+	it("已有 paused goal → throw（paused 也是非终态）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "paused" });
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "new", objective: "new obj" },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/already active/i);
+	});
+
+	it("已有 blocked goal → throw（blocked 也是非终态）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "blocked" });
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "new", objective: "new obj" },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/already active/i);
+	});
+
+	it("已有终态 goal → 覆盖创建（快速路径，goalId 变新，slug 写入）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "complete" });
+		const oldId = session.state!.goalId;
+		const ports = makeFakePorts();
+
+		const details = handleCreate(
+			{ action: "create", slug: "next-obj", objective: "next obj" },
+			session,
+			ports,
+		);
+
+		expect(details.status).toBe("active");
+		expect(session.state!.objective).toBe("next obj");
+		expect(session.state!.slug).toBe("next-obj");
+		expect(session.state!.goalId).not.toBe(oldId);
+	});
+
+	it("tokenBudget <= 0 → throw", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "x", objective: "x", tokenBudget: 0 },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/tokenBudget/);
+	});
+
+	it("timeBudgetMinutes <= 0 → throw", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "x", objective: "x", timeBudgetMinutes: -5 },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/timeBudgetMinutes/);
+	});
+
+	it("合法 budget → 合并进新 state", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		handleCreate(
+			{ action: "create", slug: "x", objective: "x", tokenBudget: 8000, timeBudgetMinutes: 30 },
+			session,
+			ports,
+		);
+
+		expect(session.state!.budget.tokenBudget).toBe(8000);
+		expect(session.state!.budget.timeBudgetMinutes).toBe(30);
+	});
+});
+
+// ── handleReportBlocked ──────────────────────────────
+
+describe("handleReportBlocked — active 守卫 + tick + transition + persist", () => {
+	it("active + reason → status blocked + reason 记录 + tick 累加", () => {
+		const session = createGoalSession();
+		const past = Date.now() - 4000;
+		session.state = activeState({ timeStartedAt: past, timeUsedSeconds: 6 });
+		const ports = makeFakePorts();
+
+		const details = handleReportBlocked(
+			{ action: "report_blocked", reason: "stuck on X" },
+			session,
+			ports,
+		);
+
+		expect(details.action).toBe("report_blocked");
+		expect(details.status).toBe("blocked");
+		expect(session.state!.status).toBe("blocked");
+		expect(session.state!.lastBlockerReason).toBe("stuck on X");
+		// MF-3 tick：转 blocked 前累加当前运行段（6 + ~4s）
+		expect(session.state!.timeUsedSeconds).toBeGreaterThanOrEqual(9);
+		// persistState 持久化
+		expect(ports.states).toHaveLength(1);
+		expect(ports.notifications[0]?.level).toBe("warning");
+	});
+
+	it("非 active（complete）→ throw", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "complete" });
+		expect(() =>
+			handleReportBlocked({ action: "report_blocked", reason: "x" }, session, makeFakePorts()),
+		).toThrow(/not active/);
+	});
+
+	it("reason 空 → throw", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() =>
+			handleReportBlocked({ action: "report_blocked", reason: "" }, session, makeFakePorts()),
+		).toThrow(/reason/);
+	});
+
+	it("active→blocked 是合法转换", () => {
+		// transitionStatus 自身已由 engine 测试覆盖，此处验证集成不破坏
+		expect(transitionStatus("active", "blocked")).toBe("blocked");
+	});
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,119 @@
+/**
+ * index.ts 测试 — 工厂入口 + 跨扩展 API（pi.__goalInit）
+ *
+ * 覆盖 T1.8 (NFR-AC-8)：__goalInit 忽略 tasks 参数（tasks 废弃，D-16/FR-4 双轨消除）。
+ * 设计保证：__goalInit 签名仅 (objective, budget, ctx)，结构上无法接收 tasks。
+ *
+ * 用最小 fake pi + fake ctx 实例化 goalExtension 工厂，再调 pi.__goalInit。
+ */
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import goalExtension from "../index";
+
+// ── Minimal fake pi / ctx ─────────────────────────────
+
+interface FactoryFixture {
+	pi: ExtensionAPI & { __goalInit?: (...args: never[]) => unknown };
+	ctx: ExtensionContext;
+	states: unknown[];
+	history: unknown[];
+	sendUser: unknown[];
+}
+
+/** 工厂所需的最小 pi：registerCommand/registerTool/on/registerMessageRenderer + appendEntry/sendMessage/sendUserMessage */
+function makeFactoryFixture(): FactoryFixture {
+	const states: unknown[] = [];
+	const history: unknown[] = [];
+	const sendUser: unknown[] = [];
+	const pi = {
+		registerCommand: () => {},
+		registerTool: () => {},
+		on: () => {},
+		registerMessageRenderer: () => {},
+		appendEntry(customType: string, data?: unknown): void {
+			if (customType === "goal-history") history.push(data);
+			else states.push(data);
+		},
+		sendMessage: () => {},
+		sendUserMessage(content: unknown): void {
+			sendUser.push(content);
+		},
+	} as unknown as ExtensionAPI & { __goalInit?: (...args: never[]) => unknown };
+
+	const ctx = {
+		hasUI: true,
+		signal: { aborted: false } as AbortSignal,
+		getContextUsage: () => null,
+		ui: {
+			notify: () => {},
+			setStatus: () => {},
+			setWidget: () => {},
+			theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
+		},
+		sessionManager: { getEntries: () => [], getBranch: () => undefined },
+	} as unknown as ExtensionContext;
+
+	return { pi, ctx, states, history, sendUser };
+}
+
+// ── pi.__goalInit（NFR-AC-8 / T1.8）──────────────────
+
+describe("pi.__goalInit — tasks 参数废弃（NFR-AC-8 / T1.8）", () => {
+	it("工厂实例化后 __goalInit 存在且为函数", () => {
+		const { pi } = makeFactoryFixture();
+		goalExtension(pi);
+		expect(typeof pi.__goalInit).toBe("function");
+	});
+
+	it("正常调用 → 创建 goal（返回 true + 持久化 state）", () => {
+		const { pi, ctx, states } = makeFactoryFixture();
+		goalExtension(pi);
+		const ok = (pi.__goalInit as (o: string, b: unknown, c: ExtensionContext) => boolean)(
+			"build feature X",
+			undefined,
+			ctx,
+		);
+		expect(ok).toBe(true);
+		expect(states.length).toBeGreaterThanOrEqual(1); // appendState 调用
+		const persisted = states[0] as { objective?: string };
+		expect(persisted.objective).toBe("build feature X");
+	});
+
+	it("ctx 缺失 → 返回 false（创建失败，不 throw）", () => {
+		// FR-4.2/D-16: ctx 必填
+		const { pi } = makeFactoryFixture();
+		goalExtension(pi);
+		const init = pi.__goalInit as (o: string, b: unknown, c: unknown) => boolean;
+		expect(() => init("obj", undefined, undefined)).not.toThrow();
+		expect(init("obj", undefined, undefined)).toBe(false);
+	});
+
+	it("已有 active goal → 返回 false（拒绝重复创建）", () => {
+		const { pi, ctx } = makeFactoryFixture();
+		goalExtension(pi);
+		const init = pi.__goalInit as (o: string, b: unknown, c: ExtensionContext) => boolean;
+		expect(init("first goal", undefined, ctx)).toBe(true);
+		// 再创建 → 已有 active，拒绝
+		expect(init("second goal", undefined, ctx)).toBe(false);
+	});
+
+	it("传入 tasks（第 4 参数）→ 不 throw、不接收（结构保证：签名只取前 3 参）", () => {
+		// NFR-AC-8 核心断言：tasks 废弃后，即便调用方误传 tasks 也不影响创建。
+		// __goalInit 签名 (objective, budget, ctx) 不含 tasks 参数位，
+		// JS 多余实参被静默忽略，TS 层签名也不暴露 tasks。
+		const { pi, ctx, states } = makeFactoryFixture();
+		goalExtension(pi);
+		const init = pi.__goalInit as (...args: unknown[]) => boolean;
+		// 误传第 4 参 tasks（模拟旧调用方残留）→ 不 throw + 创建成功 + tasks 被忽略
+		const strayTasks = [{ id: 1, text: "legacy task" }];
+		let ok = false;
+		expect(() => {
+			ok = init("obj with stray tasks", undefined, ctx, strayTasks);
+		}).not.toThrow();
+		expect(ok).toBe(true);
+		// 创建的 state 不含 tasks 字段（tasks 被忽略）
+		const persisted = states[states.length - 1] as { tasks?: unknown };
+		expect(persisted.tasks).toBeUndefined();
+	});
+});