@zhushanwen/pi-base-tool-enhance 0.5.2 → 0.5.3

package/src/__tests__/kill-tree.test.ts

@@ -1,161 +0,0 @@
-// src/__tests__/kill-tree.test.ts —— 进程树 kill 真实进程验证（POSIX 进程组语义）
-// + pid 身份判据（getProcessStartTimeSec / pidStartMatchesRegistered——原 reaper.test.ts
-// 覆盖平移：收殓下沉 runtime 后 helper 移入本文件，kill 侧自防御仍消费）
-import { spawn, spawnSync } from "node:child_process";
-
-import { describe, expect, it, vi } from "vitest";
-
-vi.setConfig({ testTimeout: 20000 });
-
-import {
-	getProcessStartTimeSec,
-	isPidAlive,
-	killProcessTree,
-	pidStartMatchesRegistered,
-} from "../kill-tree.ts";
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * 轮询直到期望状态出现或超时：真实进程事件（退出 → libuv reap → pid 释放）在满载
- * 下延迟不可预估，固定 sleep 后单次断言是满载 flake 源——等状态而非猜时刻。
- */
-async function pollUntil(check: () => boolean, deadlineMs: number, what: string): Promise<void> {
-	const deadline = Date.now() + deadlineMs;
-	while (!check()) {
-		if (Date.now() > deadline) {
-			throw new Error(`timed out after ${deadlineMs}ms waiting for ${what}`);
-		}
-		await sleep(25);
-	}
-}
-
-/** pgrep -P 组内枚举：列组长直接子 pid（仅本进程组内，非全机扫描）。 */
-function listChildPids(pid: number): number[] {
-	const result = spawnSync("/usr/bin/pgrep", ["-P", String(pid)], { encoding: "utf8" });
-	// exit 1 = 无匹配（空表正常态）；解析失败按空表处理，由轮询重试兜住 spawn 竞态
-	return (result.stdout ?? "")
-		.split("\n")
-		.map((line) => Number.parseInt(line.trim(), 10))
-		.filter((n) => Number.isInteger(n) && n > 0);
-}
-
-/** 真实 detached spawn（与本包后台任务同款形态：自成进程组）。 */
-function spawnDetached(command: string) {
-	const child = spawn("/bin/sh", ["-c", command], {
-		detached: true,
-		stdio: "ignore",
-	});
-	child.on("error", () => {});
-	child.unref();
-	return child;
-}
-
-describe("isPidAlive", () => {
-	it("current process is alive", () => {
-		expect(isPidAlive(process.pid)).toBe(true);
-	});
-
-	it("exited process is dead (pid freed after reap)", async () => {
-		const child = spawnDetached("true");
-		const pid = child.pid;
-		if (pid === undefined) throw new Error("no pid");
-		// 轮询等退出 + libuv reap（SIGCHLD → waitpid 后 pid 释放）
-		await pollUntil(() => !isPidAlive(pid), 5000, "pid to be freed after reap");
-		expect(isPidAlive(pid)).toBe(false);
-	});
-
-	it("invalid pid (0/negative) is treated as dead", () => {
-		expect(isPidAlive(0)).toBe(false);
-		expect(isPidAlive(-1)).toBe(false);
-	});
-});
-
-describe("killProcessTree (process group semantics)", () => {
-	it("kills the whole detached process group including grandchildren", async () => {
-		// 组长 sh + 两个子 sleep：进程组 kill 必须全部覆盖
-		const child = spawnDetached("sleep 30 & sleep 30 & wait");
-		const pid = child.pid;
-		if (pid === undefined) throw new Error("no pid");
-		// 轮询等两个孙子 sleep 真正 fork 出来，并在 kill 之前用组内枚举（pgrep -P）
-		// 记录孙子 pid 快照——kill 后只对这些记录过的 pid 断言，禁止全机 pgrep -f
-		// 扫描（满载并行时其他包测试会真实 spawn 同名命令，跨包互踩）
-		let grandchildPids: number[] = [];
-		await pollUntil(
-			() => {
-				grandchildPids = listChildPids(pid);
-				return isPidAlive(pid) && grandchildPids.length >= 2;
-			},
-			5000,
-			"grandchildren to spawn inside the group",
-		);
-		expect(isPidAlive(pid)).toBe(true);
-
-		killProcessTree(pid);
-		// 轮询组长死（等 libuv reap，deadline 5s）
-		await pollUntil(() => !isPidAlive(pid), 5000, "group leader to die");
-
-		// 记录过的孙子 pid 也不得残留。覆盖面说明：killProcessTree 是进程组 kill
-		// （POSIX kill -- -<pgid>），孙子与组长同组、组长死后 reparent 不换组，
-		// 故「组 kill + 组内 pid 记录」已覆盖「reparent 后孙子也能被杀」的原始意图；
-		// pid 复用概率在 5s 轮询窗口内可忽略
-		await pollUntil(
-			() => grandchildPids.every((gpid) => !isPidAlive(gpid)),
-			5000,
-			"recorded grandchildren to die",
-		);
-	});
-
-	it("killing an already-dead pid is a silent no-op", async () => {
-		const child = spawnDetached("true");
-		const pid = child.pid;
-		if (pid === undefined) throw new Error("no pid");
-		// 轮询等死透再 kill：断言语义是「对已死 pid 发令为无害 no-op」
-		await pollUntil(() => !isPidAlive(pid), 5000, "pid to die");
-		expect(() => killProcessTree(pid)).not.toThrow();
-	});
-});
-
-describe("getProcessStartTimeSec (platform probe sanity)", () => {
-	it("returns a sane epoch-seconds value for a live process", () => {
-		const sec = getProcessStartTimeSec(process.pid);
-		expect(sec).toBeDefined();
-		const nowSec = Math.floor(Date.now() / 1000);
-		// 本进程必然启动于 [now - 10min, now + 5s]（时钟容差）
-		expect(sec!).toBeGreaterThan(nowSec - 600);
-		expect(sec!).toBeLessThan(nowSec + 5);
-	});
-
-	it("returns undefined for a dead pid", async () => {
-		const child = spawnDetached("sleep 0.1");
-		const pid = child.pid;
-		if (pid === undefined) throw new Error("no pid");
-		// 轮询等退出 + libuv reap（满载下延迟不可预估）
-		await pollUntil(() => getProcessStartTimeSec(pid) === undefined, 5000, "ps record to vanish");
-		expect(getProcessStartTimeSec(pid)).toBeUndefined();
-	});
-});
-
-describe("pidStartMatchesRegistered (pid identity predicate, §3.6)", () => {
-	it("exact match on registered pidStartTime authorizes (precise path)", () => {
-		expect(pidStartMatchesRegistered(1000, 1000, 1_700_000_000_000)).toBe(true);
-	});
-
-	it("registered mismatch (pid reuse suspicion) rejects", () => {
-		expect(pidStartMatchesRegistered(2000, 1000, 1_700_000_000_000)).toBe(false);
-	});
-
-	it("missing registration degrades to startedAt-seconds bound: original process authorizes", () => {
-		// 登记发生在 spawn 之后 → 原进程 start time 必然 ≤ floor(startedAt/1000)
-		const startedAtMs = 1_700_000_123_456; // floor = 1_700_000_123
-		expect(pidStartMatchesRegistered(1_700_000_123, undefined, startedAtMs)).toBe(true);
-		expect(pidStartMatchesRegistered(1_700_000_122, undefined, startedAtMs)).toBe(true);
-	});
-
-	it("missing registration degrades: newer-than-registration start time rejects (reuse)", () => {
-		const startedAtMs = 1_700_000_123_456;
-		expect(pidStartMatchesRegistered(1_700_000_124, undefined, startedAtMs)).toBe(false);
-	});
-});

package/src/kill-tree.ts

@@ -1,151 +0,0 @@
-/**
- * 自实现进程树 kill 与 pid 判活/身份判据（设计文档 §3.5 bash_kill）。
- *
- * 为什么不用 pi 的 killProcessTree：它未从主入口导出（pi package.json exports 仅
- * `.`/`./rpc-entry`/`./client`，定义在 dist/utils/shell.d.ts 但子路径不暴露），不可
- * import。分支语义与 pi 实装对齐：Windows `taskkill /F /T`、POSIX 杀进程组
- * `kill -- -<pgid>`（本包后台任务 detached spawn 自成进程组，pgid = pid）；进程组
- * 杀不到时回退单 pid + `pgrep -P` 递归杀残留子进程。
- *
- * pid 身份判据（getProcessStartTimeSec / pidStartMatchesRegistered）：原定义于
- * reaper.ts，孤儿收殓下沉 runtime 后随 reaper.ts 删除平移至此（u-bte-remove）
- * ——消费方是 bash_kill 前校验与后台 timeout 到点校验（进程内自防御，与收殓无关）。
- */
-
-import { spawnSync, type SpawnSyncReturns } from "node:child_process";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("base-tool-enhance");
-
-/** ps 调用超时：卡死的 ps 不拖垮调用方（超时按取不到处理 → 保守跳过）。 */
-const PS_TIMEOUT_MS = 5000;
-/** 毫秒 → 秒（epoch 秒换算，spawn-background.ts 同名常量先例）。 */
-const MS_PER_SECOND = 1000;
-
-/**
- * pid 判活：kill(pid, 0) 不发信号只做权限校验。
- * ESRCH = 已死（含 libuv 自动 reap 后）；EPERM = 进程存在但属其他用户，仍视为活。
- */
-export function isPidAlive(pid: number): boolean {
-	if (!Number.isInteger(pid) || pid <= 0) return false;
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (err) {
-		return (err as NodeJS.ErrnoException).code === "EPERM";
-	}
-}
-
-/**
- * 杀整棵进程树（同步；收殓路径在 process.on("exit") 里跑，必须同步）。
- * 幂等：目标已死时静默成功。
- */
-export function killProcessTree(pid: number): void {
-	if (!Number.isInteger(pid) || pid <= 0) return;
-	if (process.platform === "win32") {
-		killProcessTreeWindows(pid);
-		return;
-	}
-	// POSIX：detached spawn 自成进程组（pgid = pid），杀进程组一次性覆盖全部子孙
-	try {
-		process.kill(-pid, "SIGKILL");
-		return;
-	} catch (err) {
-		logger.debug("process group kill missed, falling back to single pid + descendants", {
-			detail: { pid, err: err instanceof Error ? err.message : String(err) },
-		});
-	}
-	// 回退：组长已死（进程组不复存在）时单杀 pid + pgrep -P 递归清理残留子进程
-	try {
-		process.kill(pid, "SIGKILL");
-	} catch (err) {
-		// 目标已死：kill 幂等语义，仅留诊断
-		logger.debug("single pid kill missed (already dead?)", {
-			detail: { pid, err: err instanceof Error ? err.message : String(err) },
-		});
-	}
-	killDescendantsRecursive(pid);
-}
-
-function killProcessTreeWindows(pid: number): void {
-	try {
-		const result = spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
-			stdio: "ignore",
-			windowsHide: true,
-		});
-		if (result.error) throw result.error;
-	} catch (err) {
-		logger.debug("taskkill failed", {
-			detail: { pid, err: err instanceof Error ? err.message : String(err) },
-		});
-	}
-}
-
-/** pgrep -P 递归：先杀孙辈再杀子辈（防孙辈在父死后被 reparent 逃逸枚举）。 */
-function killDescendantsRecursive(pid: number): void {
-	let stdout: string;
-	try {
-		const result = spawnSync("pgrep", ["-P", String(pid)], { encoding: "utf8" });
-		if (result.error || result.status !== 0 || !result.stdout) return;
-		stdout = result.stdout;
-	} catch {
-		return;
-	}
-	for (const line of stdout.split("\n")) {
-		const childPid = Number.parseInt(line.trim(), 10);
-		if (Number.isInteger(childPid) && childPid > 0) {
-			killDescendantsRecursive(childPid);
-			try {
-				process.kill(childPid, "SIGKILL");
-			} catch (err) {
-				// 已死：kill 幂等语义，仅留诊断
-				logger.debug("descendant kill missed (already dead?)", {
-					detail: { pid: childPid, err: err instanceof Error ? err.message : String(err) },
-				});
-			}
-		}
-	}
-}
-
-/**
- * 取进程 start time（epoch 秒）。ps -o lstart= 跨 macOS/Linux（Linux /proc/
- * <pid>/stat 精度更高但 macOS 无 /proc，统一 ps 保跨平台一致）；= 号去表头。
- * 返回 undefined：进程不存在 / ps 不可用 / 输出不可解析——调用方一律按
- * 「无法校验 → 保守跳过」处理。
- */
-export function getProcessStartTimeSec(pid: number): number | undefined {
-	let result: SpawnSyncReturns<string>;
-	try {
-		result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
-			encoding: "utf8",
-			timeout: PS_TIMEOUT_MS,
-		});
-	} catch {
-		return undefined;
-	}
-	if (result.error || result.status !== 0 || !result.stdout) return undefined;
-	// lstart 形如 "Mon Aug 25 14:23:45 2026"（本地时区），Date.parse 按本地时区解释
-	const ms = Date.parse(result.stdout.trim());
-	return Number.isNaN(ms) ? undefined : Math.floor(ms / MS_PER_SECOND);
-}
-
-/**
- * pid 身份判据（§3.6「宁不杀勿误杀」的唯一定义点；原 reaper.ts 单点定义，收殓
- * 下沉后由进程内自防御消费——bash_kill kill 前校验与 background timeout 到点
- * kill 校验共用）。true = 当前占用该 pid 的进程 start time 与登记值匹配，可安全
- * kill。
- *  - 有登记 start time（spawn 时 ps 读取成功）→ 精确比较（同单位 epoch 秒）
- *  - 缺登记 start time（M3 前登记的存量条目 / ps 不可用平台）→ startedAtMs 秒级
- *    降级：登记发生在 spawn 之后（进程先启动、条目后登记），原进程 start time
- *    必然 ≤ floor(startedAtMs/1000)
- */
-export function pidStartMatchesRegistered(
-	actualStartSec: number,
-	registeredStartSec: number | undefined,
-	startedAtMs: number,
-): boolean {
-	return registeredStartSec !== undefined
-		? actualStartSec === registeredStartSec
-		: actualStartSec <= Math.floor(startedAtMs / MS_PER_SECOND);
-}