@oj-module/cli 0.2.57 → 0.2.63

package/src/build/backend.ts

@@ -5,6 +5,7 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { ALIAS_PATHS_FILE, syncAliasPaths } from "../alias-paths";
+import { mergeConfigForDev } from "../dev-secrets";
 import { resolveConfigPath, tryResolveLayout } from "../layout";
 import { requireModuleRootCapability } from "../oj-caps";
 import { resolveOjBin } from "../vendor";
@@ -50,7 +51,15 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	// <project>/config/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
 	// sql_guard 声明校验不生效（oj 只 warn 两行，极易被忽略）。
 	const configPath = resolveConfigPath(projectRoot);
-	const configArgs = fs.existsSync(configPath) ? ["-c", configPath] : [];
+	// 与 dev 同一条合并链路（方案 A'）：tracked + gitignored config.local.yaml 深合并 →
+	// .ojm-tmp-config.yaml，-c 指向合并产物。全新 clone 的机器只有本机 dev 密钥对，tracked
+	// 的 prod ENC（jwt_secret）按设计解不开——直接喂 tracked 会让密封值预检误杀（dev 能跑、
+	// build 必挂）。合并产物里 jwt 已被本机 dev 密文覆盖，而编译本身不需要密文明文，产物也不
+	// 嵌 config（部署侧自带）。产物与 config.yaml 同目录，secrets.private_key_path 等相对路径
+	// 解析不变；非 jwt 的 ENC 解不开仍由链路内红线抛错（防护不降级）。
+	let effectiveConfigPath: string | undefined;
+	if (fs.existsSync(configPath))
+		effectiveConfigPath = mergeConfigForDev(projectRoot, configPath);
 	// --no-minify：oj 的 swc minify 当前会把产物压坏，必须绕开。实测两种坏法：
 	//   1) `const rows = await db.query(...); rows[0]` → 压成 `await db.query(...)[0]`，
 	//      下标先于 await 求值，Promise 上取 [0] 得 undefined（登录恒 401）；
@@ -61,11 +70,11 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	// oj 在子树内递归找 manifest.yaml（命中 src/<name>/api/manifest.yaml 即停）。
 	const sourceArgs = layout?.moduleRoot ? ["--module-root", layout.moduleRoot] : ["-d", apiSrc];
 	// 出包前先自己确认 config 能读：读不动时 oj build 会静默关掉 sql_guard（见函数注释）
-	if (configArgs.length)
-		assertSealedValuesOpenable(oj, configPath);
+	if (effectiveConfigPath)
+		assertSealedValuesOpenable(oj, effectiveConfigPath);
 	execFileSync(oj, [
 		"build",
-		...configArgs,
+		...(effectiveConfigPath ? ["-c", effectiveConfigPath] : []),
 		...sourceArgs,
 		"-o",
 		apiDist,
@@ -91,6 +100,10 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
  * 然后照常出包。那两行夹在模块清单里极易被忽略，而关掉的 `sql_guard` 正是 tenant 声明校验
  * （跨模块 SQL 的唯一守卫）——包看起来完好，检查其实没跑。
  *
+ * 对象是**合并产物**（`mergeConfigForDev` 出的 .ojm-tmp-config.yaml）：tracked 的 prod jwt
+ * ENC 在合并时已被本机 dev 密文覆盖，能走到这里的密文本机都该解得开——解不开只可能是本机
+ * dev jwt 坏了或 local 覆盖里带了别的密文，属兜底双保险（第一道闸是链路内红线）。
+ *
  * 探法就是 oj 自己的排障命令 `oj secret open`：它和 `oj serve` / `oj build` 用同一套密钥解析
  * （`OJ_SECRET_KEY` → `OJ_SECRET_KEY_FILE` → config 的 `secrets.private_key_path`），
  * 解不开就非零退出。明文只可能出现在它的 stdout，这里直接丢弃，不落终端也不落日志。
@@ -122,6 +135,9 @@ function assertSealedValuesOpenable(oj: string, configPath: string): void {
 				+ "     config.yaml，没带 config/secrets-private.pem；\n"
 				+ "  2) 密文被改过——手工编辑、复制被截断、编辑器把长行折了。\n"
 				+ "\n"
+				+ "dev 机提示：jwt_secret 由 config.local.yaml 供给（本机密钥可轮换）；若解不开的就是它，\n"
+				+ "      删掉 config.local.yaml 里的 auth.jwt_secret 行，重跑一次 ojm dev 会重新密封。\n"
+				+ "\n"
 				+ "单独验一条：oj secret open -c <config> '<那个 ENC[...] 值>'（成功=这条没问题，失败=就是它）\n"
 				+ "修法：把配对私钥带到本机（OJ_SECRET_KEY / OJ_SECRET_KEY_FILE / config 的 secrets.private_key_path\n"
 				+ "      三选一）；密钥确实换了，就在本机重新 oj secret seal 覆写该值（明文走 stdin，别上命令行）。",

package/src/build/module-def.ts

@@ -297,7 +297,20 @@ function makeBareImportStubPlugin(namesBySpec: Map<string, string[]>): EsbuildPl
 	return {
 		name: "ojm-bare-import-stub",
 		setup(b) {
-			b.onResolve({ filter: /^[^./#]/ }, args => ({ path: args.path, namespace: "ojm-bare-stub" }));
+			b.onResolve({ filter: /^[^./#]/ }, (args) => {
+				// 排除入口自身与绝对路径：entryPoints 在 Windows 上以盘符绝对路径（d:/...）
+				// 传入，会命中上面的裸说明符过滤被桩化成「可 thenable 的代理」——
+				// 整个入口模块变成 new Proxy(function(){},{get:()=>value,apply:()=>value})，
+				// mod.default 因而是一个 thenable，async readModuleDefinition 执行 return
+				// 时被当 thenable 接管、其 .then 永远不回调 resolve → Promise 永 pending →
+				// 事件循环排空 → Node 以退出码 0 静默退出（pnpm dev 起不来）。
+				// macOS/Linux 绝对路径以 / 开头已被过滤排除，故这是 Windows-only bug。
+				if (args.kind === "entry-point")
+					return null;
+				if (/^[a-z]:/i.test(args.path))
+					return null;
+				return { path: args.path, namespace: "ojm-bare-stub" };
+			});
 			b.onLoad({ filter: /.*/, namespace: "ojm-bare-stub" }, (args) => {
 				const names = namesBySpec.get(args.path) ?? [];
 				return {
@@ -348,6 +361,10 @@ export async function readModuleDefinition(entryFile: string, projectRoot: strin
 			// 会让非 entry.ts 文件名（如测试夹具）的产物对不上后续 import 路径
 			entryNames: "entry",
 			bundle: true,
+			// ESM 输出 + import() 加载：入口经下方 onResolve 修正后不会被裸导入桩误伤为
+			// thenable 代理，Windows/macOS 行为一致（此前 Windows 卡死的根因是入口被桩化成
+			// 代理导致 async return 被 thenable 接管而永不 settle）。元数据读取只需取
+			// `.default`，无需 CJS 语义。
 			format: "esm",
 			platform: "node",
 			packages: "external",
@@ -360,6 +377,8 @@ export async function readModuleDefinition(entryFile: string, projectRoot: strin
 			logLevel: "silent",
 		});
 		const bundled = path.join(outDir, "entry.js");
+		// 加载桩化产物（ESM）：入口不会被裸导入桩误伤为 thenable 代理（见 onResolve 修正），
+		// 故 mod.default 是真实定义，import() 正常 settle。
 		const mod = await import(pathToFileURL(bundled).href);
 		const definition = mod.default;
 		if (!definition?.name || !definition?.version) {

package/src/cli.ts

@@ -121,6 +121,13 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				const portArg = Number(port);
 				await devServer(projectRoot, { port: Number.isFinite(portArg) && portArg > 0 ? portArg : 5174 });
 			};
+		case "rekey":
+			return async () => {
+				const { rekeyCommand } = await import("./rekey");
+				const result = rekeyCommand(projectRoot);
+				console.log(`[ojm] 已重新生成开发态本机密钥与 dev jwt_secret：${path.relative(projectRoot, result.localPath) || result.localPath}`);
+				console.log("[ojm] 仅影响 gitignored 的 config.local.yaml 与 config/secrets-*.pem；tracked config.yaml 未改动。下次 ojm dev 会用新密钥自动重合并重起。");
+			};
 		case "build":
 			return async (opts: { bundle?: unknown, out?: string } = {}) => {
 				// mri 可选值：裸 --bundle 得到 ""，--bundle name / --bundle=name 得到字符串

package/src/contract/emit-stub.ts

@@ -2,7 +2,7 @@ import type { OjSchemaDiag } from "./emit-oj-schema";
 import type { IrEndpoint } from "./ir";
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, posix, sep } from "node:path";
 import { emitOjSchemaLine } from "./emit-oj-schema";
 import { splitRoute, wirePrefixOf } from "./ir";
 import { jsonSchemaToSample } from "./json-schema-sample";
@@ -147,8 +147,12 @@ export async function planStubWrites(ir: IrEndpoint[], opts: PlanStubOptions): P
 
 	const writes: StubWrite[] = [];
 	for (const [, { module, dir, endpoints }] of [...groups.entries()].sort()) {
-		const apiRoot = opts.apiRootOf ? opts.apiRootOf(module) : join(opts.apiSrcDir, module);
-		const filePath = join(apiRoot, dir, "api.ts");
+		// filePath 统一 POSIX 分隔符：契约/manifest/指纹键都按 `/` 比对，Windows 上
+		// path.join 会产出 `\`，导致落盘路径失配（stub 找不到、快照漂移）。
+		// fs 侧 Windows 同样接受 `/`，无需回转分隔符。
+		const apiRootRaw = opts.apiRootOf ? opts.apiRootOf(module) : posix.join(opts.apiSrcDir, module);
+		const apiRoot = apiRootRaw.split(sep).join("/");
+		const filePath = posix.join(apiRoot, dir, "api.ts");
 		// 模板天然 lint-clean（F6）→ 直接哈希发射内容；注入缝仅供测试/特殊工程对齐
 		const body = await fix(emitStubBody(endpoints, opts.diag), filePath);
 		const fingerprint = `// ojm-api:stub ${endpoints.map(e => e.name).sort().join(",")} sha256:${hashContent(body)}\n`;

package/src/dev-secrets.ts

@@ -0,0 +1,315 @@
+/**
+ * 开发态本地密钥/凭据自动供给（方案 A'，计划 docs/plans/20261103-1700）。
+ *
+ * 问题：tracked `config.yaml` 是共享模板，但其引用的机器本地密钥
+ * （`config/secrets-*.pem` 密封对 + 全部 `ENC[...]` 解密链）不随 git 分发——多名开发者
+ * clone 后解不开 → `oj serve` 起不来，且失败信息被吞。
+ *
+ * 设计（经架构师 + 工程师评审修正）：
+ *   - dev 密钥与 tracked prod ENC **解耦**：tracked 里的 `ENC[...]` 仅作 prod 资产，dev 完全忽略。
+ *   - 本机密钥 + dev `jwt_secret` 只活在 gitignored 的 `config.local.yaml`，由本模块自动供给。
+ *   - `mergeConfigForDev` 把 tracked + local 深合并成 `.ojm-tmp-config.yaml`（gitignored，与
+ *     config.yaml 同目录）交给 `oj serve -c`，**绝不写回 tracked**。
+ *   - **非 jwt 的 `ENC[...]` 红线**：若 tracked 出现其他解不开的 `ENC[...]`（如 `wecom_enc_key`，
+ *     落库加密键），触发清晰报错要求提供真实私钥，**不**自动用 dev 随机密钥重封（防破坏已加密数据）。
+ *   - 模板 drift：合并产物每次 `ojm dev` 现合现用，tracked 非密改动自动生效；本机密钥持久于
+ *     `config.local.yaml` 重合并时始终套用，模板怎么改都不丢。
+ */
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { parse, stringify } from "yaml";
+import { resolveCertDir } from "./layout";
+import { resolveOjBin } from "./vendor";
+
+/** `config.local.yaml` 落点（与 config.yaml 同目录，gitignored、可手编辑） */
+export function resolveLocalConfigPath(configPath: string): string {
+	return path.join(path.dirname(configPath), "config.local.yaml");
+}
+
+/** 合并产物落点（与 config.yaml 同目录，`.ojm-tmp-*` 已被模板 .gitignore 忽略） */
+export function resolveMergedConfigPath(configPath: string): string {
+	return path.join(path.dirname(configPath), ".ojm-tmp-config.yaml");
+}
+
+/**
+ * 写回护栏（A-4）：合并产物绝不允许写回 tracked config、且必须位于 gitignore 内。
+ * 否则哪天密钥被误写回跟踪文件就泄密了。
+ */
+export function assertOutputNotTracked(trackedConfigPath: string, mergedConfigPath: string): void {
+	if (path.resolve(mergedConfigPath) === path.resolve(trackedConfigPath)) {
+		throw new Error(
+			`[ojm] 内部错误：合并产物路径与 tracked config 相同（${mergedConfigPath}），拒绝写回以免覆盖共享配置。`,
+		);
+	}
+	// `.ojm-tmp-` 前缀已被模板 .gitignore 覆盖（无斜杠 → 任意层级匹配），双重保险
+	if (!path.basename(mergedConfigPath).startsWith(".ojm-tmp-")) {
+		throw new Error(
+			`[ojm] 内部错误：合并产物 ${mergedConfigPath} 未被 .gitignore 的 .ojm-tmp-* 覆盖，拒绝写入以免密钥泄漏。`,
+		);
+	}
+}
+
+/** 用本机私钥试解 `ENC[...]`；能解开返回 true（即使不使用明文也只在内存里） */
+function canOpenWith(enc: string, keyPath: string, projectRoot: string): boolean {
+	const ojBin = resolveOjBin(projectRoot);
+	if (!fs.existsSync(ojBin) || !fs.existsSync(keyPath))
+		return false;
+	try {
+		execFileSync(ojBin, ["secret", "open", "-k", keyPath, enc], { stdio: "pipe" });
+		return true;
+	}
+	catch {
+		return false;
+	}
+}
+
+/**
+ * 本机密钥对是否可用：公私钥文件都在，且 seal→open 往返自洽（公钥能封、私钥能解）。
+ * 用于自愈（E-3 + A' 自动 rekey）：若上次的密钥文件残缺/被改坏（如半截 pem），
+ * 直接删了重 keygen，而不是拿着坏文件去 seal 失败。返回 false 时调用方应删除后重生成。
+ */
+function keyPairUsable(keysDir: string, projectRoot: string): boolean {
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	const publicKey = path.join(keysDir, "secrets-public.pem");
+	const ojBin = resolveOjBin(projectRoot);
+	if (!fs.existsSync(ojBin) || !fs.existsSync(privateKey) || !fs.existsSync(publicKey))
+		return false;
+	try {
+		const probe = execFileSync(ojBin, ["secret", "seal", "-k", publicKey], {
+			input: "__ojm_probe__",
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (!probe.startsWith("ENC["))
+			return false;
+		execFileSync(ojBin, ["secret", "open", "-k", privateKey, probe], { stdio: "pipe" });
+		return true;
+	}
+	catch {
+		return false;
+	}
+}
+
+/** 递归扫出配置树里所有 `ENC[...]` 字符串值，返回其 JSON pointer 路径集合 */
+function findEncValues(node: unknown, pointer = "", out: Map<string, string> = new Map()): Map<string, string> {
+	if (typeof node === "string") {
+		if (/^ENC\[/.test(node))
+			out.set(pointer, node);
+	}
+	else if (Array.isArray(node)) {
+		node.forEach((item, i) => findEncValues(item, `${pointer}/${i}`, out));
+	}
+	else if (node && typeof node === "object") {
+		for (const [k, v] of Object.entries(node))
+			findEncValues(v, pointer ? `${pointer}/${k}` : `/${k}`, out);
+	}
+	return out;
+}
+
+export interface DevSecretsDeps {
+	/** 注入 oj 二进制路径（测试） */
+	ojBin?: string
+	/** 注入随机 jwt_secret 生成器（测试可固定） */
+	randomHex?: (bytes: number) => string
+	/** 注入日志（测试） */
+	log?: (msg: string) => void
+}
+
+/**
+ * 供给本机开发密钥与 dev `jwt_secret`（A-1）：
+ *   - `config/secrets-{private,public}.pem` 缺失 → `oj secret keygen`（幂等：存在即跳过）。
+ *   - `config.local.yaml` 的 `auth.jwt_secret` 缺失/解不开 → 生成随机 32 字节 hex →
+ *     `oj secret seal` 成 `ENC[...]`，连同 `secrets:` 段写入 `config.local.yaml`。
+ * 不写 tracked config。返回最终 local config 对象。
+ */
+export function provisionDevSecrets(
+	projectRoot: string,
+	configPath: string,
+	deps: DevSecretsDeps = {},
+): Record<string, unknown> {
+	const log = deps.log ?? ((msg: string) => console.log(msg));
+	const ojBin = deps.ojBin ?? resolveOjBin(projectRoot);
+	const randomHex = deps.randomHex ?? ((bytes: number) => crypto.randomBytes(bytes).toString("hex"));
+	const keysDir = resolveCertDir(projectRoot);
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	const publicKey = path.join(keysDir, "secrets-public.pem");
+
+	// 1) 密封密钥对（幂等：存在且可用即跳过，避免每次 dev 重启换新密钥致已签发会话失效，E-3）。
+	//    若文件存在但残缺/被改坏（seal→open 往返不过）→ 视为不可用，删了重 keygen（A' 自动 rekey）。
+	let provisionedKey = false;
+	const keyUsable = fs.existsSync(privateKey) && fs.existsSync(publicKey) && keyPairUsable(keysDir, projectRoot);
+	if (!keyUsable) {
+		if (!fs.existsSync(ojBin))
+			throw new Error(`[ojm] 未找到 oj 二进制（${ojBin}），无法生成开发密钥。请先运行 ojm vendor。`);
+		for (const f of [privateKey, publicKey]) {
+			if (fs.existsSync(f))
+				fs.rmSync(f);
+		}
+		fs.mkdirSync(keysDir, { recursive: true });
+		execFileSync(ojBin, ["secret", "keygen", "--out-dir", keysDir], { stdio: "pipe" });
+		provisionedKey = true;
+	}
+
+	// 2) 读/建 config.local.yaml
+	const localPath = resolveLocalConfigPath(configPath);
+	let local: Record<string, unknown> = {};
+	if (fs.existsSync(localPath)) {
+		try {
+			local = (parse(fs.readFileSync(localPath, "utf-8")) as Record<string, unknown>) ?? {};
+		}
+		catch {
+			local = {};
+		}
+	}
+	const auth = (local.auth as Record<string, unknown> | undefined) ?? {};
+	const existingJwt = typeof auth.jwt_secret === "string" ? auth.jwt_secret : "";
+
+	// 3) dev jwt_secret：缺失或本机密钥解不开 → 重新生成并 seal（仅 jwt，可随意轮换）
+	const jwtOk = existingJwt.startsWith("ENC[") && canOpenWith(existingJwt, privateKey, projectRoot);
+	let jwtSecretEnc = existingJwt;
+	if (!jwtOk) {
+		if (!fs.existsSync(ojBin))
+			throw new Error(`[ojm] 未找到 oj 二进制（${ojBin}），无法密封 jwt_secret。请先运行 ojm vendor。`);
+		const plain = randomHex(32);
+		const sealed = execFileSync(ojBin, ["secret", "seal", "-k", publicKey], {
+			input: plain,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (!sealed.startsWith("ENC["))
+			throw new Error("[ojm] oj secret seal 未返回 ENC[...]，开发密钥供给失败。");
+		jwtSecretEnc = sealed;
+	}
+
+	// 4) 写回 config.local.yaml（仅 dev 覆盖 + dev 密钥；不碰 tracked）
+	const nextLocal: Record<string, unknown> = { ...local };
+	nextLocal.auth = { ...auth, jwt_secret: jwtSecretEnc };
+	nextLocal.secrets = {
+		private_key_path: "./config/secrets-private.pem",
+		public_key_path: "./config/secrets-public.pem",
+	};
+	fs.writeFileSync(localPath, stringify(nextLocal));
+
+	if (provisionedKey)
+		log("[ojm] 已生成本机开发密钥：config/secrets-{private,public}.pem");
+	if (!jwtOk)
+		log("[ojm] 已生成本机开发 jwt_secret（密封于 config.local.yaml，git 不跟踪）。");
+
+	return nextLocal;
+}
+
+/**
+ * 红线（A-2）：tracked 里出现**非 jwt** 的 `ENC[...]` 且本机密钥解不开 → 清晰报错，
+ * 要求提供真实私钥；绝不自动用 dev 随机密钥重封（会破坏已加密落库数据）。
+ */
+export function checkNoUnopenableSharedEnc(
+	projectRoot: string,
+	configPath: string,
+	_deps: DevSecretsDeps = {},
+): void {
+	const keysDir = resolveCertDir(projectRoot);
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	if (!fs.existsSync(configPath) || !fs.existsSync(privateKey))
+		return; // 无 tracked 或无本机密钥时不查（密钥缺失由 provision/red-line 别处兜底）
+	let doc: unknown;
+	try {
+		doc = parse(fs.readFileSync(configPath, "utf-8"));
+	}
+	catch {
+		return;
+	}
+	const encValues = findEncValues(doc);
+	for (const [pointer, enc] of encValues) {
+		if (pointer === "/auth/jwt_secret")
+			continue; // jwt 由 dev 自行供给，忽略 tracked 的 prod ENC
+		if (!canOpenWith(enc, privateKey, projectRoot)) {
+			throw new Error(
+				`[ojm] 配置中 ${pointer} 是 ENC[...] 密文，但本机没有能解开的私钥（config/secrets-private.pem）。\n`
+				+ "        该密文通常由团队用真实密钥密封（如落库加密键 wecom_enc_key），dev 不会用随机密钥重封——否则会破坏已加密数据。\n"
+				+ "        请向团队获取对应私钥放到 config/secrets-private.pem，或在 config.local.yaml 里覆盖该字段为可解密的明文/ENC 后重试。",
+			);
+		}
+	}
+}
+
+/** 纯函数深合并（local 覆盖 tracked；数组整体替换，不 concat） */
+export function deepMerge(tracked: Record<string, unknown>, local: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = Array.isArray(tracked) ? [...(tracked as unknown[])] as unknown as Record<string, unknown> : { ...tracked };
+	for (const [k, v] of Object.entries(local)) {
+		const base = (out as Record<string, unknown>)[k];
+		if (
+			v && typeof v === "object" && !Array.isArray(v)
+			&& base && typeof base === "object" && !Array.isArray(base)
+		) {
+			(out as Record<string, unknown>)[k] = deepMerge(base as Record<string, unknown>, v as Record<string, unknown>);
+		}
+		else {
+			(out as Record<string, unknown>)[k] = v;
+		}
+	}
+	return out;
+}
+
+export interface MergeDeps extends DevSecretsDeps {
+	/** 注入供给逻辑（测试可替换为无 oj 的桩） */
+	provision?: (projectRoot: string, configPath: string, d: DevSecretsDeps) => Record<string, unknown>
+	/** 注入红线检查（测试可替换为 no-op） */
+	redLine?: (projectRoot: string, configPath: string, d: DevSecretsDeps) => void
+	/** 注入合并落点（测试可改） */
+	mergedPath?: (configPath: string) => string
+}
+
+/**
+ * dev 配置就绪 + 合并：供给本机密钥、红线校验、深合并 tracked + local → `.ojm-tmp-config.yaml`。
+ * 返回合并产物路径，供 `oj serve -c` 使用。幂等（密钥/secret 存在即跳过）。
+ */
+export function mergeConfigForDev(
+	projectRoot: string,
+	configPath: string,
+	deps: MergeDeps = {},
+): string {
+	const provision = deps.provision ?? provisionDevSecrets;
+	const redLine = deps.redLine ?? checkNoUnopenableSharedEnc;
+	const mergedPath = deps.mergedPath ?? ((cp: string) => resolveMergedConfigPath(cp));
+
+	// 必须先 provision 再 red-line：首次 clone 本机密钥尚不存在，provision 会先生成
+	// 本地密钥对；之后 red-line 才能拿本机私钥去校验 tracked 里的非 jwt ENC[...]，
+	// 否则红线会在「无密钥可校验」时直接 early-return，把打不开的共享密文漏过去
+	// （正是方案 A' 要解决的「启动失败被吞」根因之一）。
+	provision(projectRoot, configPath, deps);
+	redLine(projectRoot, configPath, deps);
+
+	let trackedDoc: Record<string, unknown> = {};
+	if (fs.existsSync(configPath)) {
+		try {
+			trackedDoc = (parse(fs.readFileSync(configPath, "utf-8")) as Record<string, unknown>) ?? {};
+		}
+		catch (error) {
+			throw new Error(`[ojm] ${configPath} 解析失败（不是合法 YAML）：${(error as Error).message}`);
+		}
+	}
+	// provision 已把本机密钥/jwt 写入 config.local.yaml；此处读回参与合并
+	const localDoc = readLocal(projectRoot, configPath);
+	const merged = deepMerge(trackedDoc, localDoc);
+
+	const outPath = mergedPath(configPath);
+	assertOutputNotTracked(configPath, outPath);
+	fs.writeFileSync(outPath, stringify(merged));
+	return outPath;
+}
+
+/** 读 config.local.yaml（不存在/解析失败 → 空对象） */
+function readLocal(projectRoot: string, configPath: string): Record<string, unknown> {
+	const localPath = resolveLocalConfigPath(configPath);
+	if (!fs.existsSync(localPath))
+		return {};
+	try {
+		return (parse(fs.readFileSync(localPath, "utf-8")) as Record<string, unknown>) ?? {};
+	}
+	catch {
+		return {};
+	}
+}

package/src/dev.ts

@@ -33,13 +33,15 @@ import { buildModules } from "./build";
 import { loadContractMocks, resolveMock } from "./contract/mock";
 import { loadProjectMocks, mockStatusCode } from "./dev-mock";
 import { createReloadHub, proxyApi, proxyWsUpgrade, sseScript } from "./dev-proxy";
+import { mergeConfigForDev } from "./dev-secrets";
 import { loadHtmlTransform } from "./html-transform";
 import { resolveConfigPath, resolveLayout } from "./layout";
 import { resolveCdnLayout } from "./market/cdn-layout";
 import { startOj } from "./oj";
 import { requireModuleRootCapability } from "./oj-caps";
 import { ensureDevCert } from "./oj-cert";
-import { readOjApiPrefix } from "./oj-config";
+import { readOjApiPrefix, readOjPort, readOjServerField } from "./oj-config";
+import { isPortOccupied } from "./port-check";
 import { createStaticHandler, decodeReqPath, listenOnFreePort } from "./static-handler";
 import { resolveShellDist } from "./versions";
 
@@ -107,10 +109,31 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 			? ["--module-root", layout.moduleRoot]
 			: resolve(projectRoot, "api/src");
 		apiBase = readOjApiPrefix(configPath);
-		await ensureDevCert(configPath);
+		// 后端端口预检：被占用（通常上次 ojm dev 未正常退出、遗留 oj 孤儿进程仍在跑）
+		// 直接禁止启动并给清晰指引，避免 oj 健康检查超时后才以晦涩信息失败。
+		const backendPort = readOjPort(configPath);
+		const backendHost = readOjServerField(configPath, "host") || "127.0.0.1";
+		if (await isPortOccupied(backendPort, backendHost)) {
+			throw new Error(
+				`[ojm] 后端 API 端口 ${backendPort} 已被占用，已禁止启动 ojm dev。\n`
+				+ "        原因通常是：上一次 ojm dev 未正常退出，遗留的 oj 进程仍在占用该端口。\n"
+				+ "        （oj 后端默认端口 9778；若 config.yaml 的 server.port 改过则为对应值。）\n\n"
+				+ "        请先结束占用该端口的进程，再重新运行 ojm dev：\n"
+				+ `          macOS / Linux： lsof -ti tcp:${backendPort} | xargs kill -9\n`
+				+ `          Windows：        netstat -ano | findstr :${backendPort}  找到 PID 后  taskkill /PID <PID> /F\n\n`
+				+ "        已停止启动，未留下新的 oj 孤儿进程。",
+			);
+		}
+		// 开发态本地密钥/凭据自动供给（方案 A'）：供给本机 secrets 密钥 + dev jwt_secret，
+		// 深合并 tracked config.yaml 与 gitignored config.local.yaml → .ojm-tmp-config.yaml。
+		// tracked 里的 ENC[...] 仅作 prod 资产，dev 完全忽略；非 jwt 的 ENC 解不开则清晰报错
+		// （红线，防用 dev 随机密钥重封破坏已加密数据）。合并产物与 config.yaml 同目录，oj
+		// 相对路径解析不变。
+		const effectiveConfigPath = mergeConfigForDev(projectRoot, configPath);
+		await ensureDevCert(effectiveConfigPath);
 		const fallbackStarter = (cfg: string, b: string, apiSrc: string | string[]) => startOj(cfg, b, apiSrc);
 		const starter: NonNullable<DevOptions["ojStarter"]> = opts.ojStarter ?? fallbackStarter;
-		oj = starter(configPath, apiBase, apiSource);
+		oj = starter(effectiveConfigPath, apiBase, apiSource);
 		try {
 			await oj.ready; // 失败人话报错（stderr 尾部），fail-fast
 		}

package/src/init.ts

@@ -154,8 +154,10 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	// 3) oj 二进制：从最新 release 联网下载（sha256 校验 → tar 解包 → chmod），
 	//    无内置兜底；bin/oj 已在则幂等跳过，缺 .oj-version 标记视为未装
 	const binDir = path.join(destDir, "bin");
-	if (fs.existsSync(path.join(binDir, "oj"))) {
-		report.skipped.push("bin/oj");
+	// Windows 上二进制名是 oj.exe，不能硬编码 `oj`（预置 bin/oj.exe 会被误判为未装而触发联网下载）。
+	const ojBin = resolveOjBin(destDir);
+	if (fs.existsSync(ojBin)) {
+		report.skipped.push(`bin/${path.basename(ojBin)}`);
 	}
 	else {
 		const installer = opts.ojInstaller ?? ((dir: string) => vendorCommand(path.dirname(dir), { force: false }));
@@ -328,7 +330,10 @@ function copyTemplates(
 	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
 		const src = path.join(srcDir, entry.name);
 		const dest = path.join(destDir, entry.name);
-		const srcRel = path.relative(rootDir, src);
+		// 跨平台：path.relative 在 Windows 返回反斜杠，而 include 集合与
+		// hasIncludedDescendant 的前缀对比都用正斜杠，必须归一后再比，
+		// 否则嵌套目录（src/app/api/<mod> 等）被误判为「未收录」整棵 skip。
+		const srcRel = path.relative(rootDir, src).split(path.sep).join("/");
 		const listed = include.has(srcRel);
 		if (!underIncluded && !listed && !hasIncludedDescendant(include, srcRel))
 			continue;
@@ -390,7 +395,11 @@ function readInitInclude(templatesDir: string): Set<string> {
 	const doc = yaml.parse(fs.readFileSync(yamlPath, "utf-8")) as { include?: string[] } | null;
 	const out = new Set<string>();
 	for (const raw of doc?.include ?? []) {
-		const p = path.normalize(raw).replace(/^(\.\/)+/, "");
+		// 跨平台：include 清单用正斜杠书写，但 path.normalize 在 Windows 会把
+		// 正斜杠折成反斜杠，导致与 srcRel（path.relative 在 Windows 同样出反斜杠）
+		// 的对比永远落空、整棵 src 子树被 skip。这里只把反斜杠归正、剥 ./ 前缀，
+		// 不引入平台分隔符（修复：Windows 下 init 不拷贝 src 树）。
+		const p = raw.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
 		out.add(p);
 		if (!fs.existsSync(path.join(templatesDir, p)))
 			throw new Error(`init.include.yaml 收录了不存在的路径：${p}（拼写错误或模板缺文件？）`);
@@ -496,6 +505,8 @@ logs/
 # 现场签发的开发证书与凭据私钥（ojm dev 缺证时自动签发，见 oj-cert.ts）；私钥绝不入仓
 config/*.pem
 config/cert.jws
+# 开发态本地覆盖层（方案 A'）：dev 自动供给的本机密钥 + dev jwt_secret；git 不跟踪
+config.local.yaml
 # 构建产物（ojm build：站点 dist/web + 后端 release dist/api）
 dist/
 `;

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;
@@ -326,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"));