pi-proactive 0.2.0-beta.4 → 0.2.0-beta.6

package/tools/verify-windows.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * pi-proactive **Windows 验收脚本**（W1..W6 逐项证据表）。
+ *
+ * 判据来源：`docs/project/windows-porting.md` §四（验收基准 W1..W6）。
+ * 纪律：
+ *   · **真机结论必须来自那台 Windows 机器** —— 非 Windows 上跑只做离线自检，
+ *     真机项一律标「**未验证**」（不得谎报通过）；
+ *   · 每项都给出**可核证据**（路径 / 字节数 / 命令输出 / 进程 pid），不是「应该能行」。
+ *
+ * 用法（Windows 真机）：
+ *   node pi-proactive/tools/verify-windows.mjs                 # 只验收（要求已安装 + 已常驻）
+ *   node pi-proactive/tools/verify-windows.mjs --install       # 先装再验收（一条命令）
+ *   node pi-proactive/tools/verify-windows.mjs --check-residue # 只查卸载残留
+ *   node pi-proactive/tools/verify-windows.mjs --selftest      # 非 Windows 上的离线自检
+ *
+ * 退出码：0=无失败项（可能仍有未验证项）；1=有失败项；2=用法错误。
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	MAX_SOCKET_PATH_BYTES,
+	defaultAgentDir,
+	defaultAgentId,
+	detectPlatform,
+	isAlive,
+	pkgRootFrom,
+	readJsonSafe,
+	resolveSocketPath,
+	run,
+} from "./daemon-common.mjs";
+
+const PKG_ROOT = pkgRootFrom(import.meta.url);
+
+const USAGE = `pi-proactive Windows 验收（${"W1..W6"}）
+
+  node pi-proactive/tools/verify-windows.mjs [选项]
+
+  --agent-dir <dir>    agent 根目录（默认 ~/.pi/agent）
+  --agent-id <id>      稳定身份（默认 employee#<主机名>#pi-proactive-daemon）
+  --task-name <n>      Windows 计划任务名（默认 PiProactiveDaemon）
+  --label <label>      launchd 单元标签（macOS/Linux 侧用）
+  --service-name <n>   systemd 单元名（Linux 侧用）
+  --install            先跑安装器再验收
+  --check-residue      只查卸载残留（任务/进程/目录/socket）
+  --selftest           离线自检（非 Windows 上也能跑；真机项标「未验证」）
+  -h, --help           本帮助
+`;
+
+function parseArgs(argv) {
+	const o = {
+		agentDir: defaultAgentDir(),
+		agentId: "",
+		taskName: process.env.PI_PROACTIVE_DAEMON_TASK || "PiProactiveDaemon",
+		label: process.env.PI_PROACTIVE_DAEMON_LABEL || "com.pi-proactive.daemon",
+		serviceName: process.env.PI_PROACTIVE_DAEMON_SERVICE || "pi-proactive-daemon.service",
+		install: false,
+		checkResidue: false,
+		selftest: false,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		const next = () => {
+			const v = argv[++i];
+			if (v === undefined) {
+				console.error(`参数 ${a} 缺值`);
+				process.exit(2);
+			}
+			return v;
+		};
+		if (a === "--agent-dir") o.agentDir = path.resolve(next());
+		else if (a === "--agent-id") o.agentId = next();
+		else if (a === "--task-name") o.taskName = next();
+		else if (a === "--label") o.label = next();
+		else if (a === "--service-name") o.serviceName = next();
+		else if (a === "--install") o.install = true;
+		else if (a === "--check-residue") o.checkResidue = true;
+		else if (a === "--selftest") o.selftest = true;
+		else if (a === "-h" || a === "--help") {
+			console.log(USAGE);
+			process.exit(0);
+		} else {
+			console.error(`未知参数：${a}`);
+			process.exit(2);
+		}
+	}
+	return o;
+}
+
+/**
+ * 一行验收结论。
+ * @typedef {{ id: string; name: string; verdict: "通过" | "失败" | "未验证"; evidence: string }} Row
+ */
+
+/** 找到「已安装的包根」（全局 npm root；找不到就退回本仓库包根）。 */
+function findInstalledPkg() {
+	const r = run("npm", ["root", "-g"], { timeout: 30_000 });
+	const globalRoot = (r.stdout ?? "").trim();
+	if (r.ok && globalRoot) {
+		const candidate = path.join(globalRoot, "pi-proactive");
+		if (fs.existsSync(candidate)) return { root: candidate, how: `npm root -g → ${candidate}` };
+	}
+	return { root: PKG_ROOT, how: "本仓库包根（未找到全局安装）" };
+}
+
+/** 扫描目录里的 .ts 文件（W6）。 */
+function findTypeScriptFiles(pkgRoot) {
+	const out = [];
+	const pkg = readJsonSafe(path.join(pkgRoot, "package.json"));
+	const entries = Array.isArray(pkg?.files) ? pkg.files : [];
+	const walk = (dir, depth) => {
+		if (depth > 8) return;
+		let names = [];
+		try {
+			names = fs.readdirSync(dir);
+		} catch {
+			return;
+		}
+		for (const n of names) {
+			const p = path.join(dir, n);
+			let st;
+			try {
+				st = fs.statSync(p);
+			} catch {
+				continue;
+			}
+			if (st.isDirectory()) walk(p, depth + 1);
+			else if (p.endsWith(".ts")) out.push(p);
+		}
+	};
+	for (const entry of entries) {
+		const abs = path.join(pkgRoot, entry);
+		let st;
+		try {
+			st = fs.statSync(abs);
+		} catch {
+			continue; // 白名单里的目录在开发态可能不存在（build/）
+		}
+		if (st.isDirectory()) walk(abs, 0);
+		else if (abs.endsWith(".ts")) out.push(abs);
+	}
+	return out;
+}
+
+/** W5：端点路径长度（< 100B 的硬约束）。 */
+function checkSocketPath(agentId, agentDir) {
+	const s = resolveSocketPath(PKG_ROOT, agentId, agentDir);
+	if (!s) {
+		return { id: "W5", name: "路径长度 < 100B", verdict: "失败", evidence: "算不出端点路径（socket 模块缺失）" };
+	}
+	return {
+		id: "W5",
+		name: "路径长度 < 100B",
+		verdict: s.bytes <= MAX_SOCKET_PATH_BYTES ? "通过" : "失败",
+		evidence: `${s.path} = ${s.bytes}B（上限 ${MAX_SOCKET_PATH_BYTES}B）`,
+	};
+}
+
+/** W6：包内零 .ts。 */
+function checkZeroTypeScript(installedRoot) {
+	const ts = findTypeScriptFiles(installedRoot);
+	return {
+		id: "W6",
+		name: "包内零 .ts",
+		verdict: ts.length === 0 ? "通过" : "失败",
+		evidence:
+			ts.length === 0
+				? `按 package.json 的 files 白名单扫描 ${installedRoot}：0 个 .ts`
+				: `发现 .ts：${ts.join(", ")}`,
+	};
+}
+
+/** W1：安装可见性。 */
+function checkInstallVisible(installedRoot, how) {
+	const pkgJson = path.join(installedRoot, "package.json");
+	const binEntry = readJsonSafe(pkgJson)?.bin?.["pi-proactive"];
+	const binPath = binEntry ? path.join(installedRoot, binEntry.replace(/^\.\//, "")) : "";
+	const binExists = binPath ? fs.existsSync(binPath) : false;
+	if (!binExists) {
+		return {
+			id: "W1",
+			name: "安装可见性",
+			verdict: "失败",
+			evidence: `找不到可执行入口：${binPath || "package.json 无 bin.pi-proactive"}（${how}）`,
+		};
+	}
+	const help = run(process.execPath, [binPath, "--help"], { timeout: 30_000 });
+	return {
+		id: "W1",
+		name: "安装可见性",
+		verdict: help.ok ? "通过" : "失败",
+		evidence: `${binPath} --help → exit ${help.code}${
+			help.ok ? `；输出首行：${(help.stdout ?? "").split("\n")[0] ?? ""}` : `；stderr：${(help.stderr ?? "").slice(0, 200)}`
+		}`,
+	};
+}
+
+/** W2：启动注入（扩展已注册）。 */
+function checkExtensionRegistered(installedRoot) {
+	const exts = readJsonSafe(path.join(installedRoot, "package.json"))?.pi?.extensions ?? [];
+	if (!Array.isArray(exts) || exts.length === 0) {
+		return { id: "W2", name: "启动注入（扩展注册）", verdict: "失败", evidence: "package.json 的 pi.extensions 为空" };
+	}
+	const missing = exts.filter((e) => !fs.existsSync(path.join(installedRoot, e.replace(/^\.\//, ""))));
+	return {
+		id: "W2",
+		name: "启动注入（扩展注册）",
+		verdict: missing.length === 0 ? "通过" : "失败",
+		evidence:
+			missing.length === 0
+				? `pi.extensions=${exts.join(", ")} 全部存在（${installedRoot}）`
+				: `缺少：${missing.join(", ")}`,
+	};
+}
+
+/** W3：常驻（进程在 + 心跳在更新 + 计划任务已建）。 */
+function checkResident(platform, agentDir, taskName, label, serviceName) {
+	const hbFile = path.join(agentDir, "proactive", "daemon", "heartbeat.json");
+	const hb = readJsonSafe(hbFile);
+	if (!hb || typeof hb.ts !== "number") {
+		return { id: "W3", name: "常驻（进程/心跳/任务）", verdict: "失败", evidence: `没有心跳文件：${hbFile}` };
+	}
+	const age = Date.now() - hb.ts;
+	const alive = isAlive(hb.pid);
+	let hostEvidence = "";
+	let hostOk = false;
+	if (platform === "win32") {
+		const r = run("schtasks", ["/Query", "/TN", taskName]);
+		hostOk = r.ok;
+		hostEvidence = `schtasks /Query /TN ${taskName} → exit ${r.code}`;
+	} else if (platform === "darwin") {
+		const r = run("launchctl", ["print", `gui/${process.getuid?.() ?? 0}/${label}`]);
+		hostOk = r.ok;
+		hostEvidence = `launchctl print → exit ${r.code}`;
+	} else {
+		const r = run("systemctl", ["--user", "is-active", serviceName]);
+		hostOk = r.ok;
+		hostEvidence = `systemctl --user is-active → exit ${r.code}`;
+	}
+	const fresh = age < 20_000;
+	const verdict = alive && fresh && hostOk ? "通过" : "失败";
+	return {
+		id: "W3",
+		name: "常驻（进程/心跳/任务）",
+		verdict,
+		evidence: `心跳 ${hbFile} ts 距今 ${Math.round(age / 1000)}s；pid=${hb.pid} ${alive ? "在跑" : "不在"}；${hostEvidence}`,
+	};
+}
+
+/** W4：卸载零残留（任务 / 进程 / 目录 / socket）。 */
+function checkResidue(platform, agentDir, taskName, label, serviceName) {
+	const daemonDir = path.join(agentDir, "proactive", "daemon");
+	const residue = [];
+	if (platform === "win32") {
+		if (run("schtasks", ["/Query", "/TN", taskName]).ok) residue.push(`计划任务仍在：${taskName}`);
+	} else if (platform === "darwin") {
+		if (run("launchctl", ["print", `gui/${process.getuid?.() ?? 0}/${label}`]).ok) residue.push(`服务仍加载：${label}`);
+	} else {
+		if (run("systemctl", ["--user", "is-enabled", serviceName]).ok) residue.push(`服务仍 enabled：${serviceName}`);
+	}
+	if (fs.existsSync(daemonDir)) residue.push(`状态/日志目录仍在：${daemonDir}`);
+	const socketPath = resolveSocketPath(PKG_ROOT, defaultAgentId(), agentDir)?.path;
+	if (socketPath && fs.existsSync(socketPath)) residue.push(`socket 端点仍在：${socketPath}`);
+	const hb = readJsonSafe(path.join(daemonDir, "heartbeat.json"));
+	if (hb && isAlive(hb.pid)) residue.push(`值班进程还在（pid=${hb.pid}）`);
+	return {
+		id: "W4",
+		name: "卸载零残留",
+		verdict: residue.length === 0 ? "通过" : "失败",
+		evidence: residue.length === 0 ? "任务/进程/目录/socket 四处均无残留" : residue.join("；"),
+	};
+}
+
+/** 打印证据表。 */
+function printTable(rows) {
+	const width = Math.max(...rows.map((r) => r.id.length), 3);
+	console.log("| 判据 | 项目 | 结论 | 证据 |");
+	console.log(`|------|------|------|------|`);
+	for (const r of rows) {
+		console.log(`| ${r.id.padEnd(width)} | ${r.name} | ${r.verdict} | ${r.evidence.replace(/\|/g, "/")} |`);
+	}
+	const failed = rows.filter((r) => r.verdict === "失败");
+	const unverified = rows.filter((r) => r.verdict === "未验证");
+	console.log("");
+	console.log(`结论：失败 ${failed.length} 项 / 未验证 ${unverified.length} 项 / 共 ${rows.length} 项`);
+	if (unverified.length > 0) {
+		console.log(`未验证项：${unverified.map((r) => r.id).join(", ")} —— 不得当作已通过`);
+	}
+	return failed.length > 0 ? 1 : 0;
+}
+
+// ------------------------------------------------------------------ 入口 ----
+
+const opts = parseArgs(process.argv.slice(2));
+const platform = detectPlatform("");
+const agentId = opts.agentId || defaultAgentId();
+const installed = findInstalledPkg();
+
+if (opts.install) {
+	const installer = path.join(PKG_ROOT, "tools", "daemon-install.mjs");
+	const r = run(process.execPath, [installer, "--agent-dir", opts.agentDir, "--agent-id", agentId], {
+		timeout: 180_000,
+	});
+	console.log(r.stdout);
+	if (!r.ok) {
+		console.error(r.stderr);
+		process.exit(1);
+	}
+}
+
+if (opts.checkResidue) {
+	const code = printTable([checkResidue(platform, opts.agentDir, opts.taskName, opts.label, opts.serviceName)]);
+	process.exit(code);
+}
+
+if (opts.selftest || platform !== "win32") {
+	// 离线自检：能离线判的判；**真机项一律「未验证」**（不得谎报通过）。
+	const rows = [
+		checkInstallVisible(installed.root, installed.how),
+		checkExtensionRegistered(installed.root),
+		{
+			id: "W3",
+			name: "常驻（进程/心跳/任务）",
+			verdict: "未验证",
+			evidence: `非 Windows 平台（${platform}）→ 常驻/计划任务的真机结论必须在 Windows 上取证`,
+		},
+		{
+			id: "W4",
+			name: "卸载零残留",
+			verdict: "未验证",
+			evidence: "非 Windows 平台 → 卸载残留的真机结论必须在 Windows 上取证",
+		},
+		checkSocketPath(agentId, opts.agentDir),
+		checkZeroTypeScript(installed.root),
+	];
+	if (platform !== "win32") {
+		rows[0] = {
+			...rows[0],
+			verdict: rows[0].verdict === "通过" ? "通过" : rows[0].verdict,
+			evidence: `${rows[0].evidence}（本地包结构；真机全局安装仍需在 Windows 上取证）`,
+		};
+	}
+	console.log(`平台：${platform}（真机验收必须在 Windows 上跑；当前是离线自检）`);
+	const code = printTable(rows);
+	process.exit(code);
+}
+
+const rows = [
+	checkInstallVisible(installed.root, installed.how),
+	checkExtensionRegistered(installed.root),
+	checkResident(platform, opts.agentDir, opts.taskName, opts.label, opts.serviceName),
+	checkResidue(platform, opts.agentDir, opts.taskName, opts.label, opts.serviceName),
+	checkSocketPath(agentId, opts.agentDir),
+	checkZeroTypeScript(installed.root),
+];
+process.exit(printTable(rows));