@oj-module/cli 0.2.57 → 0.2.63

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

@@ -103,6 +103,20 @@ export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: str
 	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）。
  *
@@ -111,12 +125,12 @@ export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: str
  * 整套同版本，路径算错会拿到半新半旧的组合。统一到这里。
  */
 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))
@@ -180,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

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.2.57",
-		"@oj-module/runtime/contract": "0.2.57",
-		"@oj-module/runtime/contract/errors": "0.2.57",
+		"@oj-module/runtime": "0.2.63",
+		"@oj-module/runtime/contract": "0.2.63",
+		"@oj-module/runtime/contract/errors": "0.2.63",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",