@oj-module/cli 0.2.56 → 0.2.62

package/src/lifecycle/__tests__/bundle-summary.test.ts

@@ -0,0 +1,106 @@
+// BDD：`ojm build` 末尾用户方案摘要（计划 docs/plans/20261103-0925-ojm-build-solution-summary.md）。
+// 摘要只报告不裁决：判定口径与 --bundle 打包对象同源（模块级契约 ∪ 根契约，减内置名单）；
+// log 注入断言，夹具只摆契约/名单/构建结果三样，不需要真实工程结构。
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { summarizeBuiltSolutions } from "../../bundle";
+
+let project: string;
+let lines: string[];
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-build-summary-"));
+	lines = [];
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+/** 模块级契约：src/<name>/solution.yaml（+ web/entry.ts 保持真实模块目录形态） */
+function moduleContract(name: string): void {
+	const dir = join(project, "src", name);
+	mkdirSync(join(dir, "web"), { recursive: true });
+	writeFileSync(join(dir, "web", "entry.ts"), "export default {};\n");
+	writeFileSync(join(dir, "solution.yaml"), `name: ${name}\nversion: 1.0.0\nsummary: ${name}\n`);
+}
+
+function builtinList(names: string[]): void {
+	mkdirSync(join(project, "src"), { recursive: true });
+	writeFileSync(join(project, "src", ".ojm-builtin.json"), JSON.stringify({ modules: names }));
+}
+
+function summaryOf(built: { name: string, version: string }[]): string[] {
+	summarizeBuiltSolutions(project, built, l => lines.push(l));
+	return lines;
+}
+
+describe("summarizeBuiltSolutions", () => {
+	it("场景：全部构建成功 → 一行列出可打包方案 + 一行列出内置模块", () => {
+		moduleContract("crm");
+		moduleContract("erp");
+		builtinList(["home", "login"]);
+		const out = summaryOf([
+			{ name: "crm", version: "1.0.0" },
+			{ name: "erp", version: "0.2.0" },
+			{ name: "home", version: "9.9.9" },
+			{ name: "login", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("用户方案 2 份已构建") && l.includes("crm@1.0.0") && l.includes("erp@0.2.0"))).toBe(true);
+		expect(out.some(l => l.includes("框架自带模块 2 份已构建"))).toBe(true);
+	});
+
+	it("场景：方案没进构建 → 点名未构建方案与排查方向", () => {
+		moduleContract("crm");
+		moduleContract("erp");
+		builtinList(["home"]);
+		const out = summaryOf([
+			{ name: "crm", version: "1.0.0" },
+			{ name: "home", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("crm@1.0.0"))).toBe(true);
+		expect(out.filter(l => l.includes("erp")).join("\n")).toContain("未构建");
+	});
+
+	it("场景：零用户方案 → 提示 ojm new", () => {
+		moduleContract("home");
+		builtinList(["home"]);
+		const out = summaryOf([{ name: "home", version: "9.9.9" }]);
+		expect(out.some(l => l.includes("用户方案 0 份") && l.includes("ojm new"))).toBe(true);
+	});
+
+	it("场景：非内置模块缺契约 → 警告不会被打包", () => {
+		builtinList(["home"]);
+		const out = summaryOf([
+			{ name: "foo", version: "0.1.0" },
+			{ name: "home", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("缺方案契约") && l.includes("foo@0.1.0"))).toBe(true);
+	});
+
+	it("场景：旧单方案工程（根契约、无 src/ 树）→ 列出根契约方案，不误报缺契约", () => {
+		writeFileSync(join(project, "manifest.yaml"), "name: demo-solution\nversion: 0.1.0\nsummary: 旧写法\n");
+		const out = summaryOf([{ name: "demo-solution", version: "0.1.0" }]);
+		expect(out.some(l => l.includes("用户方案 1 份已构建") && l.includes("demo-solution@0.1.0"))).toBe(true);
+		expect(out.every(l => !l.includes("缺方案契约"))).toBe(true);
+	});
+
+	it("场景：新脚手架形态（内置集中 src/app，无用户方案）→ 0 份提示，src/app 不被误判", () => {
+		// 脚手架 init 后：src/ 下只有 app（平台聚合树，无契约）与 oj-market，均在内置名单
+		mkdirSync(join(project, "src", "app", "web"), { recursive: true });
+		writeFileSync(join(project, "src", "app", "web", "entry.ts"), "export default {};\n");
+		mkdirSync(join(project, "src", "oj-market", "web"), { recursive: true });
+		writeFileSync(join(project, "src", "oj-market", "web", "entry.ts"), "export default {};\n");
+		builtinList(["app", "oj-market", "_platform", "auth", "notification", "personal-center", "system", "web"]);
+		const out = summaryOf([
+			{ name: "app", version: "0.2.56" },
+			{ name: "oj-market", version: "0.2.56" },
+		]);
+		expect(out.some(l => l.includes("用户方案 0 份") && l.includes("ojm new"))).toBe(true);
+		expect(out.some(l => l.includes("框架自带模块 2 份已构建"))).toBe(true);
+		expect(out.every(l => !l.includes("缺方案契约"))).toBe(true);
+	});
+});

package/src/lifecycle/__tests__/bundle.test.ts

@@ -15,6 +15,21 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { parse, stringify } from "yaml";
 import { buildBundle } from "../../bundle";
 
+// GNU tar 把 Windows 盘符绝对路径里的 `C:` 当「远程主机:路径」（Cannot connect to C: resolve failed），
+// 需 --force-local；但 Windows 自带 bsdtar 不支持该选项（报 Option --force-local is not supported），
+// 且 bsdtar 本就不做远程解析。按实际解析到的 tar 版本决定：仅 win32 + GNU tar 才加。POSIX 恒不加。
+const TAR_LOCAL: string[] = (() => {
+	if (process.platform !== "win32")
+		return [];
+	try {
+		const version = execFileSync("tar", ["--version"], { encoding: "utf-8", shell: true });
+		return /GNU tar/i.test(version) ? ["--force-local"] : [];
+	}
+	catch {
+		return [];
+	}
+})();
+
 const FIXTURE_VALID = join(dirname(fileURLToPath(import.meta.url)), "fixtures/fixture-valid");
 
 let project: string;
@@ -104,6 +119,12 @@ describe("buildBundle · 正路径", () => {
 		expect(tarList(r.tgz).some(n => n.endsWith("/modules.json"))).toBe(false);
 	});
 
+	it("r1 前提：模块源码 locales 双语随包（安装期角色 title 解析数据源，计划 20261103-0948）", async () => {
+		const names = tarList((await pack()).tgz);
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/locales/zh-CN.json");
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/locales/en-US.json");
+	});
+
 	it("solution.yaml 作为 bundle 契约（优先于 manifest.yaml，避开 oj 按 manifest.yaml 枚举 api 后端的冲突）", async () => {
 		// 根目录若用 manifest.yaml 当 bundle 契约，会被 oj 的 api 模块搜索枚举误判为 api 模块；
 		// 故解决方案改用 solution.yaml，bundle 工具优先认它（manifest.yaml 仅旧方案回退）。
@@ -320,8 +341,10 @@ function writeManifest(m: unknown): void {
 }
 
 function tarList(tgz: string): string[] {
-	return execFileSync("tar", ["-tvzf", tgz], { encoding: "utf8" })
+	return execFileSync("tar", [...TAR_LOCAL, "-tvzf", tgz], { encoding: "utf8", shell: true })
 		// 铁律②（P1-6）：tar 输出恒带尾随换行，trim 后再 split
+		// bsdtar on Windows emits CRLF; strip \r before splitting.
+		.replace(/\r/g, "")
 		.trim()
 		.split("\n")
 		.map(line => line.split(" ").pop()!);

package/src/lifecycle/__tests__/deterministic-tar.test.ts

@@ -10,6 +10,21 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { createDeterministicTgz } from "../../deterministic-tar";
 
+// GNU tar 把 Windows 盘符绝对路径里的 `C:` 当「远程主机:路径」（Cannot connect to C: resolve failed），
+// 需 --force-local；但 Windows 自带 bsdtar 不支持该选项（报 Option --force-local is not supported），
+// 且 bsdtar 本就不做远程解析。按实际解析到的 tar 版本决定：仅 win32 + GNU tar 才加。POSIX 恒不加。
+const TAR_LOCAL: string[] = (() => {
+	if (process.platform !== "win32")
+		return [];
+	try {
+		const version = execFileSync("tar", ["--version"], { encoding: "utf-8", shell: true });
+		return /GNU tar/i.test(version) ? ["--force-local"] : [];
+	}
+	catch {
+		return [];
+	}
+})();
+
 let dir: string;
 let outDir: string;
 
@@ -97,7 +112,7 @@ describe("createDeterministicTgz · 产物可被系统 tar 消费（extract 段
 		const { names } = await packAndList("a.tgz");
 		const extractDir = join(outDir, "unpacked");
 		mkdirSync(extractDir);
-		execFileSync("tar", ["-xzf", join(outDir, "a.tgz"), "-C", extractDir]);
+		execFileSync("tar", [...TAR_LOCAL, "-xzf", join(outDir, "a.tgz"), "-C", extractDir], { shell: true });
 		const root = join(extractDir, names[0]!.slice(0, -1));
 		expect(readFileSync(join(root, "b-dir/zh.txt"), "utf8")).toBe("中文内容\n");
 		expect(existsSync(join(root, "b-dir/empty-dir"))).toBe(true);
@@ -130,8 +145,10 @@ describe("createDeterministicTgz · 打包自检（C2-30 构建列）", () => {
 // ── 助手 ──
 
 function tarList(tgz: string): string[] {
-	return execFileSync("tar", ["-tvzf", tgz], { encoding: "utf8" })
+	return execFileSync("tar", [...TAR_LOCAL, "-tvzf", tgz], { encoding: "utf8", shell: true })
 		// 铁律②（P1-6）：tar 输出恒带尾随换行，trim 后再 split
+		// bsdtar on Windows emits CRLF; strip \r before splitting.
+		.replace(/\r/g, "")
 		.trim()
 		.split("\n");
 }

package/src/market/bootstrap.ts

@@ -118,9 +118,12 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	}
 	writeFileSync(configPath, readFileSync(path.join(templateDir, "config.yaml"), "utf-8"), "utf-8");
 
-	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj 解析；plugins 让 auth 插件可用）
+	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj[.exe] 解析；plugins 让 auth 插件可用）。
+	// 跨平台：ojBin 在 Windows 为 bin/oj.exe、Linux/macOS 为 bin/oj——拷贝目标文件名必须
+	// 与源一致（path.basename），否则 Windows 下落盘成无扩展名的 `oj`，后续 resolveOjBin
+	// 按 bin/oj.exe 解析会找不到、后端构建检查也报「缺少 bin/oj.exe」（trial/walkthrough 隔离站点挂死）。
 	mkdirSync(path.join(root, "bin"), { recursive: true });
-	cpSync(ojBin, path.join(root, "bin", "oj"), { recursive: true });
+	cpSync(ojBin, path.join(root, "bin", path.basename(ojBin)), { recursive: true });
 	const versionMarker = path.join(projectRoot, "bin", ".oj-version");
 	if (existsSync(versionMarker)) {
 		cpSync(versionMarker, path.join(root, "bin", ".oj-version"));

package/src/new.ts

@@ -26,6 +26,26 @@ import { readBuiltinModules } from "./builtin";
 import { tryResolveLayout } from "./layout";
 import { assertValidSolutionName, RESERVED_NAMES } from "./manifest-contract";
 
+/**
+ * 内建聚合模块 app 的 web 路由根（src/app/web 下各 routes.ts 的顶层 path）：
+ * 这些路径由框架内置页面独占。ojm new 生成的默认路由为 /name，
+ * 若 name 命中其中之一，会与内置页面撞 route id，导致运行时白屏。
+ * 这里在脚手架阶段即拒绝，避免生成即炸。
+ *
+ * 与 readBuiltinModules（内建模块名）互补：内建模块名只覆盖 home /
+ * personal-center / system，而 login / change-password / notification-center 是
+ * app 聚合内的路由根，并非独立内建模块名，故单列此表。
+ * app 路由根增删时此处须同步。
+ */
+const BUILTIN_ROUTE_ROOTS = new Set([
+	"home",
+	"login",
+	"change-password",
+	"notification-center",
+	"personal-center",
+	"system",
+]);
+
 export interface NewSolutionOptions {
 	/** 示例路由布局（默认 container；none = 无外壳裸页面） */
 	layout?: "container" | "none"
@@ -76,6 +96,13 @@ export function createSolution(projectRoot: string, name: string, opts: NewSolut
 			+ "想改造自带模块：`ojm new <新名>` 生成骨架后把代码复制过去（自带身份按目录名判定，复制即脱离）。",
 		);
 	}
+	if (BUILTIN_ROUTE_ROOTS.has(name)) {
+		throw new Error(
+			`[ojm] 「${name}」与框架内置页面路由根（${[...BUILTIN_ROUTE_ROOTS].join("/")}）撞车——`
+			+ `ojm new 生成的默认路由 /${name} 会与内置 ${name} 页面冲突（route id 碰撞白屏）。`
+			+ "请换一个不与内置页面撞名的方案名。",
+		);
+	}
 	const dir = path.join(projectRoot, "src", name);
 	if (fs.existsSync(dir))
 		throw new Error(`[ojm] src/${name}/ 已存在。换个名字，或删掉该目录后重试。`);

package/src/oj.ts

@@ -9,7 +9,10 @@
  * 由 `ojm vendor` 的最低版本门禁挡住（见 src/vendor.ts 的 MIN_OJ_VERSION）。
  *
  * 健康判据：GET {base}/health 状态码 <400（oj 内置匿名健康端点；2xx/3xx 均视为就绪）。
- * 秒退：ready 拒绝，错误信息带 stderr 尾部（证书缺失等常见错因可直接读出）。
+ * 秒退：ready 拒绝，错误信息优先带 stderr 尾部（证书缺失等常见错因可直接读出）；
+ * 若 oj 把 FATAL 落盘到 logs/ 而未进 stderr（手册说 `--console-log` 会镜像到终端，但
+ * 部分环境仍可能只落盘），再读 `<configDir>/logs/server-*.log` 最新文件兜底，绝不输出
+ * 无意义的 "(无输出)"（方案 A' 失败提示不吞，评审 E-1）。
  */
 
 import type { Buffer } from "node:buffer";
@@ -21,6 +24,43 @@ import process from "node:process";
 import { readOjPluginsDir, readOjPort } from "./oj-config";
 import { resolveOjBin } from "./vendor";
 
+/**
+ * logs/ 兜底（评审 E-1）：oj 启动期 FATAL 有时只落盘不进 stderr。
+ * 给定 oj 的日志目录（通常 `<configDir>/logs`），挑最新的 `server-*.log`，
+ * 抽出 ERROR/FATAL/panic 等关键行（没有则取末 30 行），供失败信息兜底展示。
+ * 找不到日志目录 / 文件即返回空串（调用方维持 "(无输出)"）。
+ */
+function readLatestLogError(logsDir: string): string {
+	if (!logsDir || !fs.existsSync(logsDir))
+		return "";
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(logsDir, { withFileTypes: true });
+	}
+	catch {
+		return "";
+	}
+	const logs = entries
+		.filter(e => e.isFile() && /^server-.*\.log$/.test(e.name))
+		.map((e) => {
+			try {
+				return { name: e.name, mtime: fs.statSync(path.join(logsDir, e.name)).mtimeMs };
+			}
+			catch {
+				return null;
+			}
+		})
+		.filter((x): x is { name: string, mtime: number } => x !== null)
+		.sort((a, b) => b.mtime - a.mtime);
+	if (logs.length === 0)
+		return "";
+	const text = fs.readFileSync(path.join(logsDir, logs[0].name), "utf-8");
+	const lines = text.split(/\r?\n/);
+	const keyLines = lines.filter(l => /error|fatal|panic|denied|invalid|unable|cannot|fail|exception|refused/i.test(l));
+	const picked = keyLines.length > 0 ? keyLines.slice(-30) : lines.slice(-30);
+	return picked.join("\n").trim();
+}
+
 export interface OjProcess {
 	port: number
 	/** 健康就绪（或失败拒绝：秒退带 stderr 尾部 / 超时） */
@@ -63,8 +103,12 @@ export function startOj(
 	apiSource: string | string[],
 	poll: StartOjPoll = {},
 	extraArgs: string[] = [],
+	logsDir?: string,
 ): OjProcess {
 	const port = readOjPort(configPath);
+	// logs/ 兜底目录（评审 E-1）：oj FATAL 有时只落盘不进 stderr。缺省按 config 同级
+	// 的 logs/（与 oj 默认 logs_dir 一致）；调用方可显式覆盖（preview 派生 config 等）。
+	const resolvedLogsDir = logsDir ?? path.join(path.dirname(configPath), "logs");
 	// 约定：vendor 二进制在 <project>/bin/oj。工程根不能按「config 往上两级」算：
 	// module-root 布局的 config 在仓库根（<project>/config.yaml），往上两级会越过工程，
 	// 落到父目录找 bin/oj。改为「向上找最近的含 bin/ 的目录」，两种布局都成立。
@@ -84,10 +128,27 @@ export function startOj(
 	// 注入条件：用户未在 toml 显式声明 plugins_dir（env 优先级更高，注入会覆盖），
 	// 且 bin/plugins 确实存在（缺失时保持 oj 原行为，不生次生错误）。
 	const pluginsDir = path.join(projectRoot, "bin", "plugins");
-	const env: NodeJS.ProcessEnv | undefined
-		= !readOjPluginsDir(configPath) && fs.existsSync(pluginsDir)
-			? { ...process.env, OJ_PLUGINS_DIR: pluginsDir }
-			: undefined;
+	// win32：oj 是原生 Windows 二进制，从 Git Bash / MSYS 终端启动时继承 MSYS 风格 PATH
+	// （如 `/c/WINDOWS/system32`），Windows CreateProcess 无法按该形式解析可执行文件 → 内部
+	// `tar` 等系统工具 "command not found in PATH"（市场安装解包即挂）。追加原生 Windows 系统
+	// 目录（tar.exe 所在）；cmd/PowerShell 用户 PATH 本就含这些，无副作用。
+	// win32: Git Bash/MSYS 把 PATH 写成 /usr/bin 这类 Unix 风格条目，oj 内部按 Windows 规则检索命令
+	// 时无法据此定位 tar.exe（系统 tar 在 C:\Windows\System32），市场安装解包会报 tar not found in PATH。
+	// 剔除无盘符的 Unix 风格条目、仅保留 Windows 绝对路径，并兜底补上系统目录与 Git bin。
+	// cmd/PowerShell 用户 PATH 本就全是 Windows 形态，过滤无副作用。
+	const env: NodeJS.ProcessEnv | undefined = (() => {
+		let base: NodeJS.ProcessEnv = process.env;
+		if (process.platform === "win32") {
+			const cur = process.env.PATH ?? process.env.Path ?? "";
+			const winEntries = cur.split(";").filter(e => /^[A-Z]:[\\/]/i.test(e.trim()));
+			const sysDirs = ["C:\\Windows\\System32", "C:\\Windows", "C:\\Program Files\\Git\\usr\\bin"];
+			const missing = sysDirs.filter(d => !winEntries.some(e => e.toLowerCase().startsWith(d.toLowerCase())));
+			base = { ...process.env, PATH: [...winEntries, ...missing].join(";") };
+		}
+		return !readOjPluginsDir(configPath) && fs.existsSync(pluginsDir)
+			? { ...base, OJ_PLUGINS_DIR: pluginsDir }
+			: base;
+	})();
 
 	let stderrTail = "";
 	// --console-log：oj 新版终端默认静默（console_log 缺省 false，只落 logs/），
@@ -109,6 +170,13 @@ export function startOj(
 
 	let settled = false;
 	let pollTimer: NodeJS.Timeout | undefined;
+	// oj 端口被占用时 stderr 通常会带这些签名（Rust 绑定失败 / 系统错误码）；命中即
+	// 补一条「先杀占用进程」的可操作提示，避免只甩晦涩的 oj 原生报错。
+	const portInUseHint = (text: string): string => {
+		if (/Address already in use|EADDRINUSE|os error 98|os error 10048|地址已被使用|端口已被占用/i.test(text))
+			return "\n可能原因：后端端口被占用（通常是上次 ojm dev 未正常退出留下的 oj 孤儿进程）。请先结束占用进程再重试。";
+		return "";
+	};
 	const ready = new Promise<void>((resolve, reject) => {
 		const intervalMs = poll.intervalMs ?? 500;
 		const timeoutMs = poll.timeoutMs ?? 10_000;
@@ -129,9 +197,12 @@ export function startOj(
 		}, intervalMs);
 		pollTimer.unref();
 		child.once("exit", (code) => {
+			const hint = portInUseHint(stderrTail);
+			// A' 失败提示不吞：stderr 空时读 logs/ 最新 server-*.log 兜底（评审 E-1）
+			const tail = stderrTail.trim() || readLatestLogError(resolvedLogsDir);
 			finish(new Error(
-				`[ojm] oj 进程异常退出（code ${code}）。\n`
-				+ `stderr 尾部：\n${stderrTail.trim() || "（无输出）"}`,
+				`[ojm] oj 进程异常退出（code ${code}）。${hint}\n`
+				+ `stderr 尾部：\n${tail || "（无输出）"}`,
 			));
 		});
 		// spawn 本身失败（如 ENOENT）只发 error 不发 exit，必须单独兜住
@@ -141,9 +212,11 @@ export function startOj(
 			finish(new Error(`[ojm] 无法启动 oj（${binPath}）：${err.message}${hint}`));
 		});
 		const timeout = setTimeout(() => {
+			const hint = portInUseHint(stderrTail);
+			const tail = stderrTail.trim() || readLatestLogError(resolvedLogsDir);
 			finish(new Error(
-				`[ojm] oj 健康检查超时（${Math.round(timeoutMs / 1000)}s）：${healthUrl} 一直不可达。\n`
-				+ `stderr 尾部：\n${stderrTail.trim() || "（无输出）"}`,
+				`[ojm] oj 健康检查超时（${Math.round(timeoutMs / 1000)}s）：${healthUrl} 一直不可达。${hint}\n`
+				+ `stderr 尾部：\n${tail || "（无输出）"}`,
 			));
 		}, timeoutMs);
 		timeout.unref();

package/src/port-check.ts

@@ -0,0 +1,38 @@
+import net from "node:net";
+
+/**
+ * 探测某端口是否已被占用（即有进程在监听）。
+ *
+ * 用于 `ojm dev` 启动前的后端端口预检：若 oj 的目标端口已被（通常是上次未正常
+ * 退出、遗留的）oj 孤儿进程占据，提前给出清晰提示并禁止启动，避免 oj 健康检查
+ * 超时后才以晦涩信息失败。
+ *
+ * 探测方式：本进程尝试在该端口上 `listen`——
+ *   - `EADDRINUSE` → 端口已被占用，返回 true；
+ *   - 绑定成功 → 端口空闲，立即释放并返回 false；
+ *   - 其它错误（如权限）→ 无法确认占用，保守返回 false（宁可放行，不让带病禁止）。
+ *
+ * 不用「TCP connect 探活」：某些环境下连向空闲端口的连接会被静默丢弃（既不 RST 也
+ * 不 SYN-ACK），导致探测挂起并以「保守判占用」告终，从而误杀每一次 ojm dev 启动。
+ * bind 探测同步返回，绝不挂起。
+ */
+export function isPortOccupied(port: number, host = "127.0.0.1"): Promise<boolean> {
+	return new Promise((resolve) => {
+		const probe = net.createServer();
+		let settled = false;
+		const done = (occupied: boolean) => {
+			if (settled)
+				return;
+			settled = true;
+			resolve(occupied);
+		};
+		probe.once("error", (err: NodeJS.ErrnoException) => {
+			// EADDRINUSE = 端口确被占用；其余（EACCES 等）无法确认，保守放行
+			done(err.code === "EADDRINUSE");
+		});
+		probe.listen(port, host, () => {
+			// 能绑定说明空闲：立即释放后返回 false
+			probe.close(() => done(false));
+		});
+	});
+}

package/src/rekey.ts

@@ -0,0 +1,51 @@
+import type { DevSecretsDeps } from "./dev-secrets";
+/**
+ * `ojm rekey` —— 重新生成开发态本机密钥并重封 dev jwt_secret（方案 A' 第 8 点）。
+ *
+ * 只动 gitignored 的 `config/secrets-*.pem` 与 `config.local.yaml` 里的 dev 覆盖，
+ * **绝不**触碰 tracked `config.yaml`（prod 路径零改动，A-3 不变量）。
+ *
+ * 典型场景：
+ *   - 本机 dev 密钥对被人误删/改坏，`ojm dev` 因 jws/ENC 解不开起不来 → `ojm rekey` 重生。
+ *   - 想让本机 jwt_secret 轮换（dev 可随意轮换，无外部密文依赖）。
+ * 之后 `ojm dev` 会用新密钥自动重合并重起；无需手改任何 tracked 文件。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { provisionDevSecrets, resolveLocalConfigPath } from "./dev-secrets";
+import { resolveCertDir, resolveConfigPath } from "./layout";
+
+export interface RekeyResult {
+	/** 重生后的 `config.local.yaml` 路径 */
+	localPath: string
+	/** 是否真正重新生成了密钥对（已存在且可用则 rekey 只重封 jwt，不重生成） */
+	regeneratedKey: boolean
+}
+
+export interface RekeyDeps extends DevSecretsDeps {}
+
+/**
+ * 重新供给开发态本机密钥：删除旧 `secrets-*.pem` → `provisionDevSecrets` 因缺失而重生成，
+ * 并跟着重封 jwt_secret 写入 `config.local.yaml`。返回落点信息。
+ */
+export function rekeyCommand(projectRoot: string, deps: RekeyDeps = {}): RekeyResult {
+	const configPath = resolveConfigPath(projectRoot);
+	if (!fs.existsSync(configPath))
+		throw new Error(`[ojm] 未找到 config.yaml（${configPath}），无法 rekey。请确认当前目录是 ojm 工程。`);
+
+	const keysDir = resolveCertDir(projectRoot);
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	const publicKey = path.join(keysDir, "secrets-public.pem");
+	const hadKey = fs.existsSync(privateKey) || fs.existsSync(publicKey);
+	// 强制重生：先删旧的，provisionDevSecrets 见缺失即 keygen（A' 自动 rekey 的同一入口）
+	for (const f of [privateKey, publicKey]) {
+		if (fs.existsSync(f))
+			fs.rmSync(f);
+	}
+
+	provisionDevSecrets(projectRoot, configPath, deps);
+	return {
+		localPath: resolveLocalConfigPath(configPath),
+		regeneratedKey: hadKey,
+	};
+}

package/src/static-handler.ts

@@ -15,7 +15,7 @@
 
 import type http from "node:http";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { extname, normalize, resolve } from "node:path";
+import { extname, normalize, resolve, sep } from "node:path";
 
 const MIME: Record<string, string> = {
 	".html": "text/html; charset=utf-8",
@@ -185,7 +185,12 @@ export function createStaticHandler(opts: StaticHandlerOptions): (req: http.Inco
 			res.end("400 Bad Request: malformed URL encoding");
 			return;
 		}
-		const rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, "");
+		// URL 路径是「类 Unix 斜杠语义」，不能用 path.normalize 的 OS 方言：
+		// 在 Windows 上 path.normalize("/assets/x.js") 会变成 "\\assets\\x.js"，
+		// 既让下方 /__ojm_reload.js 等精确匹配全部落空（404），又让 resolveFile
+		// 把前导反斜杠当成「盘符根」解析到 C:\\assets\\...（错位 404）。统一转回
+		// 正斜杠——POSIX 上 path.sep 即 "/" 此换行为 no-op，跨平台安全。
+		const rel = normalize(urlPath).split(sep).join("/").replace(/^(\.\.[/\\])+/, "");
 
 		if (opts.reload) {
 			if (rel === "/__ojm_reload") {

package/src/usage.ts

@@ -111,8 +111,18 @@ export const HELP_GROUPS: HelpGroup[] = [
 				zh: "启动开发服务器（/api 反代 oj + 模块重建 + SSE 刷新）",
 				en: "Start dev server (/api proxy to oj + module rebuild + SSE refresh)",
 				detail: {
-					zh: "ojm dev [port]\n  开发模式快捷键（仅 TTY 终端，类 Vite）：\n    r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开\n    q  退出（后端 oj 一并终止）\n  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）",
-					en: "ojm dev [port]\n  Dev-mode shortcuts (TTY only, Vite-like):\n    r  force rebuild + hot reload    h  show help    c  clear screen    o  open browser\n    q  quit (terminates the oj backend as well)\n  port defaults to 5174 (the oj backend port comes from config.yaml server.port)",
+					zh: "ojm dev [port]\n  开发模式快捷键（仅 TTY 终端，类 Vite）：\n    r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开\n    q  退出（后端 oj 一并终止）\n  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）\n  首次 clone 无本机密钥时自动供给 dev 密钥 + 随机 jwt_secret（方案 A'），并合并 config.local.yaml 后启动",
+					en: "ojm dev [port]\n  Dev-mode shortcuts (TTY only, Vite-like):\n    r  force rebuild + hot reload    h  show help    c  clear screen    o  open browser\n    q  quit (terminates the oj backend as well)\n  port defaults to 5174 (the oj backend port comes from config.yaml server.port)\n  On first clone without local keys, dev auto-provisions a dev keypair + random jwt_secret (plan A') and starts after merging config.local.yaml",
+				},
+			},
+			{
+				key: "rekey",
+				name: "rekey",
+				zh: "重生开发态本机密钥并重封 dev jwt_secret（不动 tracked config）",
+				en: "Regenerate the dev-local keypair and re-seal the dev jwt_secret (tracked config untouched)",
+				detail: {
+					zh: "ojm rekey\n  删除 config/secrets-*.pem → 重新 keygen → 重封 dev jwt_secret 写入 config.local.yaml\n  仅影响 gitignored 的本地文件，tracked config.yaml 零改动（方案 A' 第 8 点）\n  用于本机 dev 密钥对误删/损坏、或想轮换 dev jwt_secret；之后 ojm dev 自动用新密钥重合并重起",
+					en: "ojm rekey\n  Deletes config/secrets-*.pem → keygen again → re-seal the dev jwt_secret into config.local.yaml\n  Only affects gitignored local files; the tracked config.yaml is untouched (plan A' point 8)\n  Use when the local dev keypair was deleted/corrupted, or to rotate the dev jwt_secret; ojm dev then re-merges and restarts with the new key",
 				},
 			},
 			{

package/src/vendor.ts

@@ -79,6 +79,44 @@ export function ojBinName(platform: string = process.platform): string {
 	return platform === "win32" ? "oj.exe" : "oj";
 }
 
+/**
+ * oj devkit 文档同步（计划 docs/plans/20261103-1020-vendor-devkit-sync）：bin/devkit
+ * （@oj-bin/oj postinstall 落盘，与 bin/oj 同版本）→ 工程 `.claude/skills/oj-api-dev/`，
+ * 全部 `.md` **覆盖**拷入——skill 文档始终与已装 oj 版本一致（vendor/init 共用出口）。
+ * bin/devkit 缺失（旧版 oj/异常安装）→ ok:false，调用方记跳过、不失败。
+ * global.d.ts 不在此同步：工程根那份是模板自有变体、用户可编辑（init 首装 copyIfAbsent）。
+ */
+export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: string) => void = () => {}): { ok: boolean, files: string[] } {
+	const devkitDir = path.join(binDir, "devkit");
+	if (!fs.existsSync(path.join(devkitDir, "SKILL.md")))
+		return { ok: false, files: [] };
+	const skillDir = path.join(projectRoot, ".claude", "skills", "oj-api-dev");
+	fs.mkdirSync(skillDir, { recursive: true });
+	const files: string[] = [];
+	for (const name of fs.readdirSync(devkitDir)) {
+		if (!name.endsWith(".md"))
+			continue;
+		fs.copyFileSync(path.join(devkitDir, name), path.join(skillDir, name));
+		files.push(name);
+	}
+	log(`[ojm] oj devkit 文档已同步 → .claude/skills/oj-api-dev/（${files.length} 个文件，与已装 oj 同版本）`);
+	return { ok: true, files };
+}
+
+/**
+ * bin/ 下实际存在的 oj 文件名：Windows 原生二进制是 oj.exe，但也兼容无扩展名的
+ * `oj`（手动放置 / 脚本桩）。仅 win32 做回落，POSIX 恒为 `oj` 不受影响。
+ */
+function ojBinIn(binDir: string, platform: NodeJS.Platform = process.platform): string {
+	const primary = path.join(binDir, ojBinName(platform));
+	if (platform === "win32" && !fs.existsSync(primary)) {
+		const bare = path.join(binDir, "oj");
+		if (fs.existsSync(bare))
+			return bare;
+	}
+	return primary;
+}
+
 /**
  * 工程内 oj 二进制路径的**唯一口径**（<projectRoot>/bin/oj）。
  *
@@ -87,12 +125,12 @@ export function ojBinName(platform: string = process.platform): string {
  * 整套同版本，路径算错会拿到半新半旧的组合。统一到这里。
  */
 export function resolveOjBin(projectRoot: string): string {
-	return path.join(projectRoot, "bin", ojBinName());
+	return ojBinIn(path.join(projectRoot, "bin"));
 }
 
 /** 本地版本只认 .oj-version 标记；bin/oj 缺失或标记缺失都视为未安装（N6，格式 vX.Y.Z） */
 export function readLocalVersion(binDir: string, platform: NodeJS.Platform = process.platform): string | null {
-	if (!fs.existsSync(path.join(binDir, ojBinName(platform))))
+	if (!fs.existsSync(ojBinIn(binDir, platform)))
 		return null;
 	const marker = path.join(binDir, ".oj-version");
 	if (!fs.existsSync(marker))
@@ -156,10 +194,23 @@ function reportProbeFailure(log: (msg: string) => void, detail: string): void {
 /** npm 执行器（测试注入）；返回 stdout */
 export type NpmRun = (args: string[], cwd: string) => string;
 
-const NPM_CMD = process.platform === "win32" ? "npm.cmd" : "npm";
+/**
+ * npm 执行规格：按平台决定 execFileSync 的命令行。
+ *
+ * Windows 上 npm 实为 `npm.cmd` 批处理文件——`CreateProcess` 无法直接执行 `.cmd`
+ * （否则 `spawnSync npm.cmd EINVAL`，连 `npm view` 这步都过不去），必须由 `cmd.exe /c`
+ * 包裹运行。其余平台直接以 `npm` 执行即可。
+ */
+export function npmExecSpec(platform: string, args: string[]): { cmd: string, execArgs: string[] } {
+	if (platform === "win32")
+		return { cmd: "cmd.exe", execArgs: ["/c", "npm.cmd", ...args] };
+	return { cmd: "npm", execArgs: args };
+}
 
-const defaultRun: NpmRun = (args, cwd) =>
-	execFileSync(NPM_CMD, args, { cwd, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+export const defaultRun: NpmRun = (args, cwd) => {
+	const { cmd, execArgs } = npmExecSpec(process.platform, args);
+	return execFileSync(cmd, execArgs, { cwd, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+};
 
 export interface VendorDeps {
 	run?: NpmRun
@@ -222,6 +273,12 @@ function installFromNpm(version: string, binDir: string, run: NpmRun, log: (msg:
 	}
 }
 
+/** devkit 同步 + 缺失时的人话跳过行（vendorCommand 两个调用点共用） */
+function syncDevkitOrSkip(projectRoot: string, binDir: string, log: (msg: string) => void): void {
+	if (!syncOjDevkit(projectRoot, binDir, log).ok)
+		log("[ojm] bin/devkit 缺失，跳过 oj devkit 文档同步（旧版 oj 或异常安装；skill 文档不更新）");
+}
+
 /**
  * US-1..US-5 编排：解析目标版本（tag 缺省经 npm view 追 latest，显式 tag 去 v 前缀）
  * → 本地已是该版本则跳过（--force 除外）→ 临时目录安装 + 拷贝 → 报告版本 → 探针冒烟。
@@ -243,6 +300,9 @@ export async function vendorCommand(
 	const binDir = path.join(projectRoot, "bin");
 	const local = readLocalVersion(binDir);
 	if (!opts.force && local === `v${version}`) {
+		// 文档同步不随版本跳过：用户删过 skill 目录后重跑 vendor 即补齐（R4）。
+		// 先同步再打跳过行——「已是 vX」保持命令收尾行（既有门禁断言末行）。
+		syncDevkitOrSkip(projectRoot, binDir, log);
 		log(`[ojm] oj 已是 v${version}，跳过。`);
 		const result = probe(binDir);
 		if (!result.ok)
@@ -255,6 +315,7 @@ export async function vendorCommand(
 		log(`[ojm] 本地 ${local ?? "未安装"} → v${version}`);
 	installFromNpm(version, binDir, run, log);
 	log(`[ojm] oj ${local ? `${local} → ` : ""}v${version} 安装完成：${path.join(binDir, ojBinName(process.platform))}`);
+	syncDevkitOrSkip(projectRoot, binDir, log);
 	// 安装后冒烟：发布二进制可能因构建机路径被烤进而不可用（见 probeOjRuntime）
 	const result = probe(binDir);
 	if (!result.ok)