@zhushanwen/pi-cw-tool 0.2.0

package/src/__tests__/detect-repo-workspace.test.ts

@@ -0,0 +1,183 @@
+/**
+ * detectRepoWorkspace 真实 git 测试 + executeCwAction 集成（真实 cwd）。
+ *
+ * 与 cw-tool.test.ts 分开：该文件 mock 了 node:child_process（spawnSync 被替换），
+ * 而本文件需要真实 git 探测，故不 mock，直接对临时 git repo 验证。
+ *
+ * 测试框架：vitest（从 vitest 导入 describe/it/expect/vi）。
+ */
+import { execSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+	buildCwArgs,
+	detectRepoWorkspace,
+	executeCwAction,
+} from "../cw-runner.ts";
+import { type CwSpawner } from "../cw-spawn.ts";
+import { DEV_ALLOWED } from "../index.ts";
+
+// ── 临时目录管理 ────────────────────────────────────────────────
+
+const tmpDirs: string[] = [];
+
+/** 建一个独立临时目录（afterEach 统一清理）。 */
+function makeTempDir(prefix: string): string {
+	const dir = mkdtempSync(path.join(tmpdir(), prefix));
+	tmpDirs.push(dir);
+	return dir;
+}
+
+/** 在 dir 下初始化一个含一次空 commit 的 git repo，返回 realpath 规范化后的 repo 根。 */
+function createGitRepo(parentDir: string, name: string): string {
+	const repo = path.join(parentDir, name);
+	mkdirSync(repo);
+	execSync("git init -q", { cwd: repo });
+	execSync("git -c user.name=test -c user.email=test@test.local commit -q --allow-empty -m init", {
+		cwd: repo,
+	});
+	// macOS 上 /tmp → /private/tmp：git rev-parse 输出 realpath，与 mkdtempSync 返回路径不一致，
+	// 统一以 realpath 为准（--workspace 最终传的也是 git 输出的规范化路径）。
+	return realpathSync(repo);
+}
+
+afterEach(() => {
+	for (const dir of tmpDirs.splice(0)) {
+		rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+// ── detectRepoWorkspace（真实 git）─────────────────────────────
+
+describe("detectRepoWorkspace（真实 git）", () => {
+	it("git repo 根目录 → 返回 repo 根（等于 --show-toplevel）", () => {
+		const base = makeTempDir("cw-detect-");
+		const repo = createGitRepo(base, "repo");
+		const toplevel = execSync("git rev-parse --show-toplevel", { cwd: repo })
+			.toString()
+			.trim();
+		expect(detectRepoWorkspace(repo)).toBe(toplevel);
+	});
+
+	it("repo 子目录（cwd 不在根）→ 仍返回 repo 根", () => {
+		const base = makeTempDir("cw-detect-");
+		const repo = createGitRepo(base, "repo");
+		const sub = path.join(repo, "src", "deep");
+		mkdirSync(sub, { recursive: true });
+		const toplevel = execSync("git rev-parse --show-toplevel", { cwd: sub })
+			.toString()
+			.trim();
+		expect(detectRepoWorkspace(sub)).toBe(toplevel);
+	});
+
+	it("同一 repo 的所有 worktree 返回相同值（repo 级统一，MF-1 核心证据）", () => {
+		const base = makeTempDir("cw-detect-");
+		const repo = createGitRepo(base, "repo");
+		const wtDir = path.join(base, "wt1");
+		execSync(`git worktree add -q ${wtDir}`, { cwd: repo });
+
+		const mainWs = detectRepoWorkspace(repo);
+		const wtWs = detectRepoWorkspace(wtDir);
+		expect(mainWs).toBe(repo);
+		expect(wtWs).toBe(repo);
+		expect(wtWs).toBe(mainWs);
+	});
+
+	it("非 git 目录 → undefined", () => {
+		const plain = makeTempDir("cw-detect-plain-");
+		expect(detectRepoWorkspace(plain)).toBeUndefined();
+	});
+
+	it("不存在的路径 → undefined（不抛）", () => {
+		const base = makeTempDir("cw-detect-");
+		expect(detectRepoWorkspace(path.join(base, "does-not-exist"))).toBeUndefined();
+	});
+});
+
+// ── executeCwAction 集成（真实 cwd，fake spawner 记录 args）─────
+
+describe("executeCwAction 集成（真实 git cwd）", () => {
+	/** 记录 args 的 fake spawner（不真调 cw）。 */
+	function recordingSpawner(): { spawner: CwSpawner; calls: Array<{ args: string[] }> } {
+		const calls: Array<{ args: string[] }> = [];
+		const spawner: CwSpawner = vi.fn(async (args: string[]) => {
+			calls.push({ args });
+			return { stdout: "{}", stderr: "", exitCode: 0 };
+		}) as unknown as CwSpawner;
+		return { spawner, calls };
+	}
+
+	it("cwd 在 git repo 内 → write action args 含 --workspace <repo 根>", async () => {
+		const base = makeTempDir("cw-int-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner, calls } = recordingSpawner();
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		expect(calls[0].args).toContain("--workspace");
+		expect(calls[0].args[calls[0].args.indexOf("--workspace") + 1]).toBe(repo);
+	});
+
+	it("cwd 在 linked worktree 内 → write action --workspace 指向 repo 主目录", async () => {
+		const base = makeTempDir("cw-int-");
+		const repo = createGitRepo(base, "repo");
+		const wtDir = path.join(base, "wt1");
+		execSync(`git worktree add -q ${wtDir}`, { cwd: repo });
+		const { spawner, calls } = recordingSpawner();
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, wtDir);
+		expect(calls[0].args).toContain("--workspace");
+		expect(calls[0].args[calls[0].args.indexOf("--workspace") + 1]).toBe(repo);
+	});
+
+	it("read-only action（status）即使在 git repo 内也不附加 --workspace（S-3）", async () => {
+		const base = makeTempDir("cw-int-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner, calls } = recordingSpawner();
+		await executeCwAction("status", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		expect(calls[0].args).not.toContain("--workspace");
+	});
+
+	it("cwd 为非 git 目录 → write action 不含 --workspace", async () => {
+		const plain = makeTempDir("cw-int-plain-");
+		const { spawner, calls } = recordingSpawner();
+		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, plain);
+		expect(calls[0].args).not.toContain("--workspace");
+	});
+
+	it("cwd 不存在 → write action 不含 --workspace（探测失败不抛）", async () => {
+		const base = makeTempDir("cw-int-");
+		const { spawner, calls } = recordingSpawner();
+		await executeCwAction(
+			"execute",
+			DEV_ALLOWED,
+			"cw_dev",
+			"u1",
+			{},
+			spawner,
+			path.join(base, "missing"),
+		);
+		expect(calls[0].args).not.toContain("--workspace");
+	});
+});
+
+// ── buildCwArgs 纯函数（workspace 参数）─────────────────────────
+
+describe("buildCwArgs（workspace 参数）", () => {
+	it("workspace + commitHash → --workspace 位于 --commitHash 之后", () => {
+		expect(buildCwArgs("execute", "u1", { commitHash: "abc" }, "/repo/root")).toEqual([
+			"execute",
+			"--unitId",
+			"u1",
+			"--commitHash",
+			"abc",
+			"--workspace",
+			"/repo/root",
+		]);
+	});
+
+	it("workspace 为空字符串 → 不追加", () => {
+		expect(buildCwArgs("status", "u1", {}, "")).toEqual(["status", "--unitId", "u1"]);
+	});
+});

package/src/cw-runner.ts

@@ -0,0 +1,275 @@
+/**
+ * cw action 执行核心：白名单校验 + 参数构造 + spawn + 输出解析。
+ *
+ * 与 Pi SDK 解耦（不 import pi 类型），纯逻辑 + 可注入 spawner，便于单测。
+ * 所有错误路径返回 `{ ok: false, error }`，不抛异常（由调用方映射为 tool 返回）。
+ */
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+
+import type { CwSpawner } from "./cw-spawn.ts";
+
+/** cw 全部 action 名（E1 后：clarify 已删、plan→design）。透传 cw，与 cw-cli ALL_ACTIONS 对齐。 */
+export const CW_ACTIONS = [
+	"create",
+	"design",
+	"design-review",
+	"execute",
+	"test",
+	"exec-review",
+	"retrospect",
+	"closeout",
+	"replan",
+	"abort",
+	"list",
+	"tree",
+	"status",
+	"handoff",
+	"frontier",
+] as const;
+export type CwAction = (typeof CW_ACTIONS)[number];
+
+/** 只读 action（不推进状态机，query only）。 */
+export const READONLY_ACTIONS = ["list", "tree", "status", "handoff", "frontier"] as const;
+
+/**
+ * 判断 action 是否为只读（属于 {@link READONLY_ACTIONS}）。
+ *
+ * 只读 action 的两个边界复用此判定（S-3/S-5）：
+ * - 不附加 `--workspace`（保守避免 cw 子命令拒收未知选项导致 readonly 查询失败，S-3）；
+ * - 不强制 unitId（list/tree/frontier 等全局查询不需要具体 unit，S-5）。
+ *
+ * 用 `.some(===)` 而非 `.includes()` 以保持 string 入参的类型安全（readonly tuple 的
+ * `.includes()` 要求字面量联合类型，传 string 会报错，无需 `as` 宽化）。
+ */
+export function isReadonlyAction(action: string): boolean {
+	return READONLY_ACTIONS.some((a) => a === action);
+}
+
+/** 透传给 cw 的可选参数（flags）。 */
+export interface CwToolOptions {
+	/** JSON 内容字符串，经 stdin 传给 cw（`cw --input -`）。与 inputFile 互斥。 */
+	input?: string;
+	/** input 文件路径，直接传 `--input <path>`。与 input 互斥。 */
+	inputFile?: string;
+	/** execute 关联的 commit（wave 层），传 `--commitHash`。 */
+	commitHash?: string;
+}
+
+/** 工具返回的 details 结构（结构化成功/失败，调用方按 `ok` 区分）。 */
+export type CwDetails =
+	| { ok: true; action: string; unitId: string | undefined; stdout: string; parsed: true; data: unknown }
+	| { ok: true; action: string; unitId: string | undefined; stdout: string; parsed: false }
+	| { ok: false; action: string; unitId: string | undefined; error: string };
+
+/**
+ * 白名单校验。返回错误消息（string）或 undefined（放行）。
+ *
+ * 设计为 string-based，独立于 schema 枚举——schema 是 LLM 输入的第一道约束，
+ * 此函数是 execute 内的防御性第二道（直接/程序化调用、宽松 provider 兜底），
+ * 同时是单测的核心契约（直接调 executeCwAction 传任意 action 验证拦截）。
+ */
+export function rejectDisallowedAction(
+	action: string,
+	allowed: readonly string[],
+	toolName: string,
+): string | undefined {
+	if (!allowed.includes(action)) {
+		return `action "${action}" 不在 ${toolName} 白名单。允许的 action: ${allowed.join(", ")}`;
+	}
+	return undefined;
+}
+
+/** git 探测超时（ms）：git 卡死时避免阻塞 agent turn。 */
+const GIT_PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * 探测 cwd 所属 repo 的主目录（repo 级 workspace）。
+ *
+ * 用 `git rev-parse --path-format=absolute --git-common-dir` 取 git common dir：
+ * 同一 repo 的所有 worktree 返回相同路径，dirname 即 repo 主目录。cw store 键控
+ * 从 per-cwd 升级为 repo 级（ADR-0045）后，spawn cw 时附带 --workspace 让 cw
+ * 在 repo 主目录解析/共享状态，避免同一 repo 的 worktree 间状态各自为政。
+ *
+ * 任何失败（非 git 目录、git 不在 PATH、路径不存在、超时）→ undefined（不抛）。
+ */
+export function detectRepoWorkspace(cwd: string): string | undefined {
+	try {
+		const result = spawnSync(
+			"git",
+			["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"],
+			{ encoding: "utf8", timeout: GIT_PROBE_TIMEOUT_MS },
+		);
+		if (result.status !== 0) return undefined;
+		const gitCommonDir = result.stdout.trim();
+		if (gitCommonDir.length === 0) return undefined;
+		return path.dirname(gitCommonDir);
+	} catch {
+		return undefined;
+	}
+}
+
+/** input / inputFile 互斥校验。 */
+export function rejectConflictingInput(opts: CwToolOptions): string | undefined {
+	if (opts.input !== undefined && opts.inputFile !== undefined) {
+		return "'input' 和 'inputFile' 互斥，只能传其中一个。";
+	}
+	return undefined;
+}
+
+/**
+ * unitId 缺失校验（S-5）。写 action 缺 unitId → 返回错误消息；只读 action 或已传 unitId → undefined（放行）。
+ *
+ * schema 已把 unitId 改为 Optional（只读 action 不需要），此函数是写 action 的运行时第二道约束
+ * （直接/程序化调用、宽松 provider 兜底），与 rejectDisallowedAction / rejectConflictingInput 同族。
+ */
+export function rejectMissingUnitId(action: string, unitId: string | undefined): string | undefined {
+	if (unitId === undefined && !isReadonlyAction(action)) {
+		return `action "${action}" 需要 unitId（只读 action ${READONLY_ACTIONS.join("/")} 可省略）`;
+	}
+	return undefined;
+}
+
+/**
+ * 构建 cw 命令行参数（action 后接 flags）。
+ *
+ * - unitId（若提供）→ `--unitId <id>`；undefined 则省略（只读 action 不需要，S-5）
+ * - input 内容 → `--input -`（经 stdin，见 executeCwAction）
+ * - inputFile 路径 → `--input <path>`
+ * - commitHash → `--commitHash <sha>`
+ * - workspace（repo 主目录，由调用方经 detectRepoWorkspace 探测）→ `--workspace <path>`，位于 --commitHash 之后
+ */
+export function buildCwArgs(
+	action: string,
+	unitId: string | undefined,
+	opts: CwToolOptions,
+	workspace?: string,
+): string[] {
+	const args: string[] = [action];
+	if (unitId !== undefined) {
+		args.push("--unitId", unitId);
+	}
+
+	if (opts.inputFile) {
+		args.push("--input", opts.inputFile);
+	} else if (opts.input !== undefined) {
+		args.push("--input", "-");
+	}
+
+	if (opts.commitHash) {
+		args.push("--commitHash", opts.commitHash);
+	}
+
+	if (workspace) {
+		args.push("--workspace", workspace);
+	}
+
+	return args;
+}
+
+/** 尝试把 stdout 解析为 JSON。成功返回解析值，失败返回 undefined。 */
+function tryParseJson(text: string): unknown | undefined {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) return undefined;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return undefined;
+	}
+}
+
+/** cw spawn 默认超时（5 分钟）。cw 卡死时避免永久挂起 agent turn。 */
+const DEFAULT_CW_TIMEOUT_MS = 300_000;
+
+/**
+ * 执行 cw action 的核心逻辑：白名单校验 → 参数冲突校验 → spawn → 解析。
+ *
+ * 失败判定：非零退出码（含被信号终止的 null）→ ok:false（stderr 折进错误消息；S-2 按 exitCode 判定）。
+ * 成功后 stdout 尝试 JSON.parse：成功 → parsed:true + data；失败 → parsed:false + 原样 stdout。
+ *
+ * @param action   调用方请求的 action（运行时再校验白名单）。
+ * @param allowed  该工具允许的 action 白名单。
+ * @param toolName 工具名（错误消息归属用）。
+ * @param unitId   cw unit id（写 action 必传；只读 action 可省略，见 rejectMissingUnitId）。
+ * @param opts     可选 flags。
+ * @param spawner   spawn 实现（默认走真实 cw，测试注入 fake）。
+ * @param cwd       子进程工作目录。
+ * @param signal    可选 SDK abort signal；与超时合并后透传给 spawner，abort 时 spawner kill 子进程。
+ * @param timeoutMs spawn 超时（ms），默认 5 分钟；0 表示不限时。超时返回 ok:false "cw 超时"。
+ */
+export async function executeCwAction(
+	action: string,
+	allowed: readonly string[],
+	toolName: string,
+	unitId: string | undefined,
+	opts: CwToolOptions,
+	spawner: CwSpawner,
+	cwd: string,
+	signal?: AbortSignal,
+	timeoutMs: number = DEFAULT_CW_TIMEOUT_MS,
+): Promise<CwDetails> {
+	const base = { action, unitId };
+
+	const actionErr = rejectDisallowedAction(action, allowed, toolName);
+	if (actionErr) return { ok: false, ...base, error: actionErr };
+
+	const inputErr = rejectConflictingInput(opts);
+	if (inputErr) return { ok: false, ...base, error: inputErr };
+
+	// unitId 运行时校验（S-5）：写 action 缺 unitId → 清晰错误（schema 已把 unitId 改 Optional）。
+	const unitIdErr = rejectMissingUnitId(action, unitId);
+	if (unitIdErr) return { ok: false, ...base, error: unitIdErr };
+
+	// repo 级 workspace（ADR-0045）：仅写 action 附加（S-3：只读 action 保守不加，避免 cw 子命令
+	// 拒收未知选项导致 readonly 查询失败）；cwd 在 git repo 内才探测，探测失败静默跳过。
+	const workspace = isReadonlyAction(action) ? undefined : detectRepoWorkspace(cwd);
+	const args = buildCwArgs(action, unitId, opts, workspace);
+	const stdinPayload = opts.input !== undefined ? opts.input : undefined;
+
+	// 合并 SDK abort signal 与超时为单个 signal 传给 spawner：spawner（默认实现）在 abort
+	// 时 kill 子进程，避免 abort/超时后僵尸 cw 继续推进状态机。
+	const combined = new AbortController();
+	let timedOut = false;
+	const onSdkAbort = (): void => combined.abort();
+	if (signal) {
+		if (signal.aborted) combined.abort();
+		else signal.addEventListener("abort", onSdkAbort, { once: true });
+	}
+	const timer =
+		timeoutMs > 0
+			? setTimeout(() => {
+					timedOut = true;
+					combined.abort();
+				}, timeoutMs)
+			: undefined;
+
+	let result;
+	try {
+		result = await spawner(args, stdinPayload, cwd, combined.signal);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { ok: false, ...base, error: `cw spawn 失败: ${msg}` };
+	} finally {
+		if (timer) clearTimeout(timer);
+		if (signal) signal.removeEventListener("abort", onSdkAbort);
+	}
+
+	// 超时优先于结果判定（spawner 被 kill 后 resolve，exitCode 通常为 null）。
+	if (timedOut) return { ok: false, ...base, error: "cw 超时" };
+
+	const { stdout, stderr, exitCode } = result;
+
+	// S-2：按 exitCode 判定失败（防御性，不依赖 cw 是否向 stderr 写非错误诊断信息）。
+	// 非零退出码（含 null=被信号终止）→ 失败；stderr 折进错误消息（成功时 stderr 不导致失败）。
+	if (exitCode !== 0) {
+		const parts: string[] = [`exit code ${exitCode ?? "null"}`];
+		if (stderr.trim()) parts.push(stderr.trim());
+		return { ok: false, ...base, error: parts.join(" | ") };
+	}
+
+	const data = tryParseJson(stdout);
+	if (data !== undefined) {
+		return { ok: true, ...base, stdout, parsed: true, data };
+	}
+	return { ok: true, ...base, stdout, parsed: false };
+}

package/src/cw-spawn.ts

@@ -0,0 +1,101 @@
+/**
+ * cw 子进程执行抽象。
+ *
+ * 设计为可注入（CwSpawner），使核心逻辑（cw-runner.ts）可在测试中用 fake
+ * spawner 替换，避免真调 cw。默认实现 {@link defaultCwSpawner} 走 child_process。
+ *
+ * cw 路径解析：spawn 裸命令名 `cw`，由 OS execvp 语义在 `process.env.PATH` 中
+ * 查找（架构约定 #16：禁止写死绝对路径）。env 继承自 process.env，确保 PATH 可用。
+ */
+import { spawn } from "node:child_process";
+
+/** cw 子进程执行结果。 */
+export interface CwSpawnResult {
+	/** stdout 内容（cw action 通常把结果 JSON 输出到 stdout）。 */
+	stdout: string;
+	/** stderr 内容（cw 的错误/诊断信息）。 */
+	stderr: string;
+	/** 进程退出码；null 表示被信号终止未产出退出码（视为异常）。 */
+	exitCode: number | null;
+}
+
+/**
+ * spawn cw 的可注入抽象。
+ *
+ * @param args   传给 cw 的参数（不含 `cw` 本身，由实现补上）。
+ * @param input  要写入子进程 stdin 的内容；undefined 表示不写（cw 不读 stdin）。
+ * @param cwd    子进程工作目录。
+ * @param signal 可选 abort signal；实现应在 abort 时 kill 子进程（见 defaultCwSpawner），
+ *               避免 abort 后僵尸 cw 子进程继续推进状态机（executeCwAction 把 SDK signal +
+ *               超时合并为此 signal 传入）。
+ */
+export type CwSpawner = (
+	args: string[],
+	input: string | undefined,
+	cwd: string,
+	signal?: AbortSignal,
+) => Promise<CwSpawnResult>;
+
+/**
+ * 默认 cw spawner：用 child_process.spawn 执行 PATH 中的 `cw`。
+ *
+ * - stdout/stderr 设 utf8 编码后全量捕获（data 回调收 string，无需 Buffer 处理）。
+ * - input（若提供）写入 stdin 后关闭；未提供则直接 end（cw 不阻塞等待 stdin）。
+ * - spawn 自身失败（如 cw 不在 PATH）走 'error' 事件，拼进 stderr、exitCode=-1 标记异常。
+ * - signal abort 时 kill 子进程（SIGTERM），避免 abort 后僵尸 cw 继续推进状态机；
+ *   signal 进入时已 aborted 则立即 kill。listener 在 settle 时移除防泄漏。
+ */
+export const defaultCwSpawner: CwSpawner = (args, input, cwd, signal) =>
+	new Promise<CwSpawnResult>((resolve) => {
+		const child = spawn("cw", args, {
+			cwd,
+			env: process.env,
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+
+		let stdout = "";
+		let stderr = "";
+
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+
+		// abort → kill 子进程，防止 cw 状态机被已 abort 的僵尸子进程推进。
+		const onAbort = (): void => {
+			child.kill("SIGTERM");
+		};
+		if (signal) {
+			if (signal.aborted) {
+				child.kill("SIGTERM");
+			} else {
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
+
+		if (input !== undefined) {
+			child.stdin.write(input, "utf8");
+		}
+		child.stdin.end();
+
+		// error 与 close 可能先后触发；用 settled 守卫保证只 resolve 一次并清理 listener。
+		let settled = false;
+		const finish = (result: CwSpawnResult): void => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+
+		child.on("error", (err: NodeJS.ErrnoException) => {
+			// spawn 失败（cw 不在 PATH / 无执行权限等）。exitCode=-1 区分于正常退出码。
+			finish({ stdout, stderr: `${stderr}\n[spawn error] ${err.message}`, exitCode: -1 });
+		});
+		child.on("close", (code: number | null) => {
+			finish({ stdout, stderr, exitCode: code });
+		});
+	});