@oj-module/cli 0.2.6 → 0.2.14

package/src/preview-config.ts

@@ -0,0 +1,177 @@
+/**
+ * preview 派生 config（设计 §6 单服务化，2026-10-19）。
+ *
+ * 单服务 preview 由 oj 一个进程同时出 API 与静态（web 挂载 + spa: true），
+ * 而 spa 只能来自 config 文件（CLI --app-path 的 upsert 保留但不设置
+ * spa——实测 oj 0.1.80）。用户在模板里手改 config 不可取（web/dist 缺失时
+ * oj serve 整体拒启，会连带挂掉 ojm dev），故 preview 现场生成一份
+ * 派生 config：
+ *
+ *   - 与原 config 同目录（api/.ojm-preview.yaml，固定名）——config 内
+ *     相对路径（证书 / db / api 挂载目录）按 config 所在目录解析，派生后
+ *     与原件逐字一致，无需重写任何路径；
+ *   - 唯一改动：upsert {prefix: "/", web: <siteDir>, spa: true} 挂载 +
+ *     显式传 port 时覆盖 server.port；
+ *   - 临时产物：preview 进程退出即删（三路清理见 preview.ts），模板
+ *     .gitignore 已收录该文件名。
+ *
+ * 纯变换（derivePreviewConfigText）与落盘（writePreviewConfig）分离：
+ * 前者可单测到「除注入点外 doc 与原 parse 深相等」，后者只做 IO。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { resolveConfigPath } from "./layout";
+
+/** 派生 config 文件名（与原 config 同目录；固定名 = 崩溃自愈，不积累残留） */
+export const PREVIEW_CONFIG_NAME = ".ojm-preview.yaml";
+
+export interface DerivePreviewConfigOptions {
+	/** 全站产物目录（layout.distDir），写入 web 挂载的绝对路径 */
+	siteDir: string
+	/**
+	 * release 形态的后端模块根（api/dist）。给了且原 config 声明了 platform.modules 时，
+	 * 把 `platform.root` 一并改写到该目录——特权模块的受控根必须与 `--api-path` 同源，
+	 * 否则 release 下 reloadConfig 会按 dev 的 src 判定归属（装好的方案热更不生效）。
+	 */
+	apiRoot?: string
+	/** 显式端口时覆盖 server.port；缺省沿用原 config（oj 代码默认 9778） */
+	port?: number
+	/** 原 config 文本（测试注入）；缺省读 api/config.yaml */
+	configText?: string
+}
+
+export interface PreviewConfigFiles {
+	/** 派生 config 路径（startOj 的 configPath） */
+	configPath: string
+	/** 同步删除派生 config（幂等；文件已不存在不抛） */
+	cleanup: () => void
+}
+
+/** YAML 解析失败的人话报错（口径对齐 oj-config.ts 的 readServerBlock） */
+function parseConfigDoc(configText: string, configPath: string): Record<string, unknown> {
+	let doc: unknown;
+	try {
+		doc = parse(configText);
+	}
+	catch (error) {
+		throw new Error(
+			`[ojm] ${configPath} 解析失败（不是合法 YAML）：${(error as Error).message}\n`
+			+ "该文件由 ojm init 生成，改动后请用 YAML 语法检查确认缩进与引号。",
+		);
+	}
+	// 空 config（parse → null）合法：oj 用内置默认值；派生时从空对象建 mounts/server
+	if (doc === null || doc === undefined)
+		return {};
+	if (typeof doc !== "object" || Array.isArray(doc)) {
+		throw new TypeError(
+			`[ojm] ${configPath} 顶层不是映射（拿到 ${Array.isArray(doc) ? "序列" : typeof doc}）——`
+			+ "oj config 必须是键值结构，请检查文件内容。",
+		);
+	}
+	return doc as Record<string, unknown>;
+}
+
+/** 挂载条目 = 非空非数组的普通对象（mounts: 一行一条） */
+function isMountEntry(m: unknown): m is Record<string, unknown> {
+	return m !== null && typeof m === "object" && !Array.isArray(m);
+}
+
+/** 找 prefix === "/" 的 web 挂载条目下标；没有返回 -1 */
+function findRootWebMount(mounts: unknown[]): number {
+	return mounts.findIndex(m => isMountEntry(m) && m.prefix === "/" && "web" in m);
+}
+
+/**
+ * 是否存在 prefix === "/" 的 api 挂载（oj 语义：与 web 挂载配对时恒无 SPA
+ * 回落）。调用方（preview）必然注入 / web 挂载，故「有 / api 挂载」即「配对」。
+ */
+export function hasRootApiMount(mounts: unknown[]): boolean {
+	return mounts.some(m => isMountEntry(m) && m.prefix === "/" && "api" in m);
+}
+
+/** mounts 段校验：缺省视为无挂载；存在但非序列 → 人话报错（不静默置空掩盖手误） */
+function readMounts(doc: Record<string, unknown>, configPath: string): unknown[] {
+	if (doc.mounts === undefined || doc.mounts === null)
+		return [];
+	if (!Array.isArray(doc.mounts)) {
+		throw new TypeError(
+			`[ojm] ${configPath} 的 mounts 不是序列（拿到 ${typeof doc.mounts}）——`
+			+ "每个挂载占一行「- prefix: ...」列表，请对照 ojm init 生成的模板修正。",
+		);
+	}
+	return doc.mounts;
+}
+
+/**
+ * 原 config 文本 → 派生 config 文本。
+ *
+ * upsert 语义（DR-3）：已有 / web 条目 → 覆盖 web 指向、强制 spa: true，
+ * 保留该条目其余键（如 headers）；没有 → 追加新条目。其余挂载与原样
+ * 顶层段一律不动。
+ */
+export function derivePreviewConfigText(configText: string, opts: DerivePreviewConfigOptions & { configPath?: string }): string {
+	const configPath = opts.configPath ?? "api/config.yaml";
+	const doc = parseConfigDoc(configText, configPath);
+
+	const mounts = [...readMounts(doc, configPath)];
+	const idx = findRootWebMount(mounts);
+	if (idx >= 0) {
+		// 保留用户自定义键（headers 等），只接管指向与回落
+		mounts[idx] = { ...(mounts[idx] as Record<string, unknown>), web: opts.siteDir, spa: true };
+	}
+	else {
+		mounts.push({ prefix: "/", web: opts.siteDir, spa: true });
+	}
+	doc.mounts = mounts;
+
+	// platform.root 跟随 api 挂载根：dev = src，release（preview）= dist
+	const platform = doc.platform;
+	if (opts.apiRoot !== undefined && platform !== null && typeof platform === "object" && !Array.isArray(platform)) {
+		const mods = (platform as Record<string, unknown>).modules;
+		if (Array.isArray(mods) && mods.length > 0)
+			(platform as Record<string, unknown>).root = opts.apiRoot;
+	}
+
+	if (opts.port !== undefined) {
+		const server = doc.server !== null && typeof doc.server === "object" && !Array.isArray(doc.server)
+			? { ...(doc.server as Record<string, unknown>) }
+			: {};
+		server.port = opts.port;
+		doc.server = server;
+	}
+
+	return stringify(doc);
+}
+
+/** 读 config 文本的 mounts 序列（解析失败 / mounts 非序列即人话报错） */
+export function parseMounts(configText: string, configPath = "api/config.yaml"): unknown[] {
+	return readMounts(parseConfigDoc(configText, configPath), configPath);
+}
+
+/**
+ * 落盘派生 config 并返回清理器。config 文本读取失败（不存在/无权限）直接
+ * 抛——四查已保证 config 存在，这里只可能是 IO 异常。
+ */
+export function writePreviewConfig(projectRoot: string, opts: DerivePreviewConfigOptions): PreviewConfigFiles {
+	const configPath = resolveConfigPath(projectRoot);
+	const previewPath = path.join(path.dirname(configPath), PREVIEW_CONFIG_NAME);
+	const configText = opts.configText ?? fs.readFileSync(configPath, "utf-8");
+
+	fs.writeFileSync(previewPath, derivePreviewConfigText(configText, { ...opts, configPath }));
+
+	let cleaned = false;
+	const cleanup = () => {
+		if (cleaned)
+			return;
+		cleaned = true;
+		try {
+			fs.unlinkSync(previewPath);
+		}
+		catch {
+			// 已不存在（并发退出/手工删除）——幂等
+		}
+	};
+	return { configPath: previewPath, cleanup };
+}

package/src/preview.ts

@@ -1,44 +1,58 @@
 /**
- * `ojm preview` —— 生产形态预览（设计 §6）。
+ * `ojm preview` —— 生产形态预览（设计 §6，2026-10-19 单服务化）。
  *
- * 职责：校验产物（fail-fast 四查）→ `oj migrate`（失败即退，不起 server）
- * → `oj serve`（release/js，仅 API）→ ojm 静态层兜底（SPA 回退，无 SSE
- * 注入、不设 no-store）。默认静态归 ojm（与 oj 手册 §13「SPA 回退经前置
- * 反代补」一致）；`--oj-static` 切换为 oj `--app-path` 直出（真 exercise
- * oj 静态层，history 深链接 404 是已知限制）。
+ * 职责：fail-fast 四查 → `oj migrate`（失败即退，不起 server）→ 派生
+ * preview config（注入 web 挂载 + spa: true）→ `oj serve`（release/js，
+ * **单进程同时出 API 与静态**）。ojm 不再自建 http server、不再反代——
+ * 前后端同端口同进程，与「oj serve + web 挂载」的生产公式逐字同形。
+ *
+ * 派生 config 为临时产物（api/.ojm-preview.yaml，与原件同目录保证相对
+ * 路径解析一致），三路清理：ready 拒绝路径 / SIGINT / process exit 兜底
+ * （语义与落盘见 preview-config.ts）。
+ *
+ * web.config.ts 的 htmlTransform 是 serve 期钩子，单服务下 oj 直出 HTML
+ * 无从介入——启动时检测到配置即 WARN 并指向 oj 的 html_meta /
+ * html_meta_handler（devkit 手册「静态站点与 per-route meta」）。
  *
  * 一律传绝对路径：oj 命令行相对 CWD、config 内相对 config 目录，混用即歧义。
  */
 
 import type { OjProcess } from "./oj";
+import type { PreviewConfigFiles } from "./preview-config";
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import http from "node:http";
-import path, { normalize } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
 import process from "node:process";
-import { proxyApi } from "./dev-proxy";
-import { loadHtmlTransform } from "./html-transform";
+import { loadModulesConfig } from "./config";
 import { resolveConfigPath, resolveLayout } from "./layout";
 import { startOj } from "./oj";
 import { readOjApiPrefix } from "./oj-config";
-import { createStaticHandler, decodeReqPath, listenOnFreePort } from "./static-handler";
+import { hasRootApiMount, parseMounts, writePreviewConfig } from "./preview-config";
 import { resolveOjBin } from "./vendor";
 
-const DEFAULT_PORT = 4173;
-
 export interface PreviewOptions {
+	/** 显式端口（覆盖派生 config 的 server.port）；缺省沿用 config（oj 代码默认 9778） */
 	port?: number
-	/** 静态改由 oj --app-path 直出（history 深链接 404，已知限制） */
-	ojStatic?: boolean
 	/** 注入桩站点目录（默认 layout.distDir） */
 	siteDir?: string
 	/** 注入桩 oj 命令执行（migrate）；默认 execFileSync(bin/oj, args, inherit) */
 	execOj?: (args: string[]) => void
 	/** 注入桩 oj 进程；默认 startOj */
 	ojStarter?: (configPath: string, base: string, apiPath: string, extraArgs: string[]) => OjProcess
+	/** 注入桩派生 config 落盘（测试）；默认 writePreviewConfig */
+	configWriter?: (projectRoot: string, opts: { siteDir: string, port?: number, apiRoot?: string }) => PreviewConfigFiles
 }
 
-export async function previewServer(projectRoot: string, opts: PreviewOptions = {}): Promise<http.Server> {
+export interface PreviewHandle {
+	/** 停 oj 子进程并清理派生 config（测试与编程式消费用） */
+	stop: () => Promise<void>
+}
+
+/**
+ * 单服务 preview。返回后进程保活依赖 oj 子进程 stdio 管道（ref 状态）
+ * 与已注册的信号 handler；Ctrl+C 走 SIGINT 善后。
+ */
+export async function runPreview(projectRoot: string, opts: PreviewOptions = {}): Promise<PreviewHandle> {
 	const layout = resolveLayout(projectRoot);
 	const siteDir = opts.siteDir ?? layout.distDir;
 	const ojBin = resolveOjBin(projectRoot);
@@ -55,8 +69,9 @@ export async function previewServer(projectRoot: string, opts: PreviewOptions =
 	if (!existsSync(path.join(apiDist, "manifests.yaml")))
 		throw new Error(`[ojm] ${apiDist} 缺少 manifests.yaml。\n请先 ojm build（后端 oj build 产物）。`);
 
-	// htmlTransform（web.config.ts，可选）先于起进程校验：配置坏了不该留下 oj 孤儿
-	const transform = await loadHtmlTransform(projectRoot);
+	// DR-5：htmlTransform 存在性检测（只读 web.config.ts 的字段，不 import 变换模块——
+	// 单服务下 oj 直出 HTML，钩子不生效；执行用户代码只会白付副作用）
+	await warnHtmlTransformUnsupported(projectRoot);
 
 	const execOj = opts.execOj ?? ((args: string[]) => execFileSync(ojBin, args, { stdio: "inherit" }));
 
@@ -64,57 +79,92 @@ export async function previewServer(projectRoot: string, opts: PreviewOptions =
 	console.log("[ojm] oj migrate（应用待执行迁移）…");
 	execOj(["migrate", "-c", configPath, "-d", apiDist]);
 
+	// 派生 config 在 migrate 成功后落盘：失败即退路径零残留
 	const base = readOjApiPrefix(configPath);
+	const writer = opts.configWriter ?? ((root: string, o: { siteDir: string, port?: number, apiRoot?: string }) => writePreviewConfig(root, o));
+	// apiRoot 交给派生器：release 下 platform.root 必须指向 api/dist（与 --api-path 同源）
+	const preview = writer(projectRoot, { siteDir, port: opts.port, apiRoot: apiDist });
+
+	// / api 挂载与注入的 / web 挂载配对时 oj 不开 SPA 回落（oj 语义，见 devkit 手册 §13）
+	if (hasRootApiMount(parseMounts(readFileSync(configPath, "utf-8"), configPath)))
+		console.warn("[ojm] config 的 api 挂载位于 /：与 web 挂载配对时 oj 不做 SPA 深链回落（已知限制），深链接刷新将 404。");
+
 	const starter = opts.ojStarter ?? ((cfg: string, b: string, apiPath: string, extraArgs: string[]) =>
 		startOj(cfg, b, apiPath, undefined, extraArgs));
-	const extraArgs = opts.ojStatic ? ["--app-path", siteDir] : [];
-	const oj = starter(configPath, base, apiDist, extraArgs);
+	// starter 可能同步抛错（startOj 首行 readOjPort 对缺/坏 server.port 即 throw，
+	// 先于返回 OjProcess）——此刻 exit 兜底尚未注册，必须就地清理派生 config
+	let oj: OjProcess;
+	try {
+		oj = starter(preview.configPath, base, apiDist, []);
+	}
+	catch (error) {
+		preview.cleanup();
+		throw error;
+	}
 	try {
 		await oj.ready;
 	}
 	catch (error) {
-		// F3：ready 拒绝必须先回收子进程，否则 oj 孤儿化继续占端口
+		// F3：ready 拒绝必须先回收子进程，否则 oj 孤儿化继续占端口；派生 config 一并清理
 		await oj.stop().catch(() => {});
+		preview.cleanup();
 		throw error;
 	}
-	console.log(`[ojm] oj 后端已就绪（release/js）：${base} → http://127.0.0.1:${oj.port}`);
+	console.log(`[ojm] oj 已就绪（release/js，单服务：${base} API + 静态 SPA 同进程）：http://127.0.0.1:${oj.port}`);
+	console.log(`\n[ojm] preview 已启动：http://localhost:${oj.port}`);
+	console.log(`[ojm] 静态由 oj web 挂载直出（spa 深链回落）；派生 config ${path.basename(preview.configPath)} 为本进程临时产物，退出自动清理`);
 
-	const ojTarget = `http://127.0.0.1:${oj.port}`;
-	// 生产形态下按路由改写 title/OG（transform 已在起进程前加载校验）
-	const serveStatic = createStaticHandler({ roots: [siteDir], reload: null, noStore: false, transform });
-
-	const server = http.createServer((req, res) => {
-		const urlPath = decodeReqPath(req.url ?? "/");
-		if (urlPath === null) {
-			res.writeHead(400, { "content-type": "text/plain" });
-			res.end("400 Bad Request: malformed URL encoding");
-			return;
-		}
-		const rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, "");
-		// 反代前缀跟随 config 的 mounts:（api 挂载 prefix；F2）
-		if (rel.startsWith(`${base}/`)) {
-			void proxyApi(ojTarget)(req, res);
+	// 退出回收：派生 config 必须随 oj 一起消亡（test/integration 断言其不存在）
+	// 终端 Ctrl-C 是进程组信号：外层 bin 转发一份 + 组送达一份，内层会收到
+	// 两个 SIGINT。用 on + 幂等守卫吞掉第二个——once 在首次触发后即摘除，
+	// 第二个 SIGINT 会走默认动作杀死本进程，清理全没跑（2026-10-19 冒烟实测）。
+	let stopping = false;
+	const onSigint = () => {
+		if (stopping)
 			return;
-		}
-		serveStatic(req, res);
-	});
-
-	server.on("close", () => {
-		void oj.stop();
-	});
-	process.once("SIGINT", () => {
+		stopping = true;
 		console.log("\n[ojm] 正在退出…");
-		void oj.stop();
-		server.close(() => process.exit(0));
+		// 同步先删派生 config：后续任何死亡路径（含信号）都零残留；oj 运行中
+		// 已读入 config，运行期删除文件无影响
+		preview.cleanup();
+		void oj.stop().finally(() => process.exit(0));
 		setTimeout(() => process.exit(0), 1500).unref();
-	});
+	};
+	process.on("SIGINT", onSigint);
+	// 兜底：非优雅路径退出（未捕获异常等）时同步清掉派生 config，防下次启动读到陈旧文件
+	const onExit = () => {
+		preview.cleanup();
+	};
+	process.once("exit", onExit);
+
+	// stop 摘除信号/退出 handler：编程式同进程多次调用不累积旧实例的闭包
+	// （CLI 单次调用行为不变）
+	const stop = async () => {
+		process.removeListener("SIGINT", onSigint);
+		process.removeListener("exit", onExit);
+		await oj.stop();
+		preview.cleanup();
+	};
 
-	const actualPort = await listenOnFreePort(server, opts.port ?? DEFAULT_PORT);
-	console.log(`\n[ojm] preview 已启动：http://localhost:${actualPort}`);
-	if (opts.ojStatic)
-		console.log(`[ojm] --oj-static：oj 已挂静态直出 http://127.0.0.1:${oj.port}（history 深链接 404 为已知限制；ojm 本口仍提供 SPA 兜底 + /api 反代）`);
-	else
-		console.log(`[ojm] 静态兜底：ojm（SPA 回退）+ ${base} 反代 oj`);
+	return { stop };
+}
 
-	return server;
+/**
+ * web.config.ts 配了 htmlTransform → WARN。加载失败（缺文件/坏配置）静默
+ * 跳过：能走到 preview 的工程必然过 ojm build，config 问题会在那里先炸。
+ */
+async function warnHtmlTransformUnsupported(projectRoot: string): Promise<void> {
+	try {
+		const config = await loadModulesConfig(projectRoot);
+		if (config.htmlTransform) {
+			console.warn(
+				"[ojm] web.config.ts 配置了 htmlTransform：单服务 preview 由 oj 直出 HTML，该钩子不生效。\n"
+				+ "逐路由 meta 请改用 oj 的 server.html_meta（构建期 JSON）或 server.html_meta_handler（运行期 handler），"
+				+ "见 bin/devkit/api-manual.md「静态站点与 per-route meta」。",
+			);
+		}
+	}
+	catch {
+		// config 加载失败：不阻塞 preview（build 已先行校验过）
+	}
 }

package/src/sign.ts

@@ -17,6 +17,12 @@ export interface SignOptions {
 	id?: string
 	/** 私钥 PEM 文件（缺省 ~/.ojm/keys/<id>/private.pem） */
 	key?: string
+	/**
+	 * 内存私钥 PEM（一次性/隔离场景专用，与 --key 二选一）。
+	 * 用途：`ojm market trial` 的一次性 keypair 不落盘，经此直接传进来；
+	 * 给了它就跳过文件存在性检查，也永远不读真 ~/.ojm/keys（计划 §3.3.1）。
+	 */
+	privateKeyPem?: string
 	/** 写完离线自检（verifyCanonical 复核） */
 	check?: boolean
 	/** 测试注入；缺省 process.cwd() */
@@ -46,10 +52,17 @@ export function signCommand(tgz: string, opts: SignOptions = {}): SignResult {
 	if (!fs.existsSync(tgz))
 		throw new Error(`[ojm] 方案包不存在：${tgz}`);
 	const cwd = opts.cwd ?? process.cwd();
-	// key 解析：--key 显式文件优先；否则 ~/.ojm/keys/<id>/private.pem（--id 必填）
-	let keyFile: string;
+	// key 解析：内存 PEM（不落盘）> --key 显式文件 > ~/.ojm/keys/<id>/private.pem（--id 必填）
+	let keyFile = "";
 	let keyId: string;
-	if (opts.key !== undefined) {
+	let memoryPem: string | undefined;
+	if (opts.privateKeyPem !== undefined && opts.privateKeyPem !== "") {
+		memoryPem = opts.privateKeyPem;
+		keyId = opts.id ?? "";
+		if (keyId === "")
+			throw new Error("[ojm] 使用内存私钥时须同时给 --id <publisher.id>（.sig 的发布方标识；C2-37 命名空间）");
+	}
+	else if (opts.key !== undefined) {
 		keyFile = path.resolve(cwd, opts.key);
 		keyId = opts.id ?? keyIdFromKeyPath(path.relative(os.homedir(), keyFile)) ?? "";
 		if (keyId === "")
@@ -63,13 +76,15 @@ export function signCommand(tgz: string, opts: SignOptions = {}): SignResult {
 	}
 	if (!isValidKeyId(keyId))
 		throw new Error(`[ojm] key_id 命名空间非法（C2-37）：「${keyId}」`);
-	if (!fs.existsSync(keyFile))
-		throw new Error(`[ojm] 私钥文件不存在：${keyFile}（用 ojm keygen --id ${keyId} 生成，或 --key 指定）`);
+	if (memoryPem === undefined) {
+		if (!fs.existsSync(keyFile!))
+			throw new Error(`[ojm] 私钥文件不存在：${keyFile}（用 ojm keygen --id ${keyId} 生成，或 --key 指定）`);
+	}
 
 	const bytes = new Uint8Array(fs.readFileSync(tgz));
 	const sha256 = createHash("sha256").update(bytes).digest("hex");
 	const canonical = canonicalString(deriveName(tgz), deriveVersion(tgz), sha256);
-	const privateKeyPem = readPrivateKeyPem(keyFile);
+	const privateKeyPem = memoryPem ?? readPrivateKeyPem(keyFile!);
 	const value = signCanonical(privateKeyPem, canonical);
 	const publicKeyHex = exportRawPublicKeyHex(privateKeyPem);
 	const sig = { alg: SIG_ALG, key_id: keyId, public_key: publicKeyHex, value, canon: CANON };

package/src/usage.ts

@@ -20,8 +20,9 @@ export function usageText(): string {
         --bundle   方案包构建：manifest.yaml 契约校验（C2，fail-fast）→ 确定性 tgz
                    → dist/<name>-<version>.tgz + sha256（市场安装器的上游产物）
         --out <dir>  --bundle 输出目录（缺省 dist/）
-  ojm preview [port] [--oj-static]
-        生产形态预览（migrate → oj serve + 静态兜底）
+  ojm preview [port]
+        生产形态预览（migrate → oj serve 单服务：API 与静态 SPA 同进程，深链回落）
+        静态由 oj web 挂载直出；ojm 不起第二个服务、不做反代
   ojm api [dir] [--check] [--docs] [--exempt <path>]
         契约代码生成（client / routes / openapi / stub）
         --check   四重对账（生成物同步 / route 双向 / routes.js / WS 路由鉴权）
@@ -64,6 +65,25 @@ export function usageText(): string {
         （与 archive .sig 同构，公钥取 ~/.ojm/keys/<id>/private.pem，缺省 --id 推导）→ 写回
         <dir>。CDN 侧 resolveCdn/index 拉取索引时校验签名（篡改/不符即拒，G4 fail-closed）。
         --check 离线自检两份索引签名
+  ojm market setup [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]
+        把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由
+        api/config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin
+        must_change=1），会自动改密换全权 token 后再写入。
+  ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]
+        把方案包落进 cdn/：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz
+        → 包级 detached 签名 <name>-<version>.tgz.sig。**不碰索引**（D-1：索引由
+        build-index 扫描重建，多人发布才不会互相覆盖）。
+  ojm market build-index [--id <key>] [--key <pem>] [--check]
+        扫描 cdn/*.tgz、提取包内 manifest，全量重建 bundles.yaml + manifests.yaml 并签名。
+        结果只取决于目录内容：连续执行字节一致。
+  ojm market verify [--file <tgz>] [--rebuild-index]
+        离线验包（不起站点、不装、不要凭据）：sha256 完整性 / 包级 Ed25519 验签 /
+        索引验签 / manifest 结构（含 C2-31 desc===summary、各版本 0001 迁移一致）分列输出。
+        --rebuild-index 额外比对「扫描重建的索引」与盘上索引，检出落了包却没重建的漂移。
+        注意：结论恒带边界声明——校验通过只说明来源与完整性，不构成内容安全性背书。
+  ojm market trial [--fixture <name>@<version>] [--keep]
+        在一次性隔离站点（随机端口 + 一次性 DB/密钥/凭据/信任库/CDN）里跑完整安装，
+        跑完即毁；--keep 保留现场供排查。用于确认「这个包到底能不能装」，不污染你的工程。
   ojm test|exec|openapi|migrate|schema [args...]
         透传给 oj 同名子命令（自动补 -c <project>/api/config.yaml；其余参数原样转发）
         例：ojm test --anonymous / ojm migrate --db report / ojm openapi --check

package/src/vendor.ts

@@ -32,9 +32,11 @@ export const NPM_PKG = "@oj-bin/oj";
  * docs/superpowers/specs/2026-10-14-ojm-0.1.18-design.md）；**0.1.20 抬到 0.1.73**：
  * 平级 `.response` 出参声明位自 oj v0.1.72 起、`oj openapi` 的 `del`→`delete`
  * 操作键归一自 v0.1.73 起，`ojm api` 的 openapi 流水线以这两者为前提
- * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。
+ * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。**0.2.13 抬到 0.1.81**：
+ * 模板侧 `solution-perms.ts` 权限级联清理用 `startswith` 操作键（v0.1.81 补齐，
+ * 构造器迁移收尾），oj < 0.1.81 时卸载方案报 `unknown variant startswith` fail-closed。
  */
-export const MIN_OJ_VERSION = "0.1.73";
+export const MIN_OJ_VERSION = "0.1.81";
 
 /** 按段数值比较（字符串比较会把 0.1.9 判成大于 0.1.69）；非数字段按 0 处理 */
 export function isSupportedOjVersion(version: string): boolean {

package/src/versions.ts

@@ -100,9 +100,37 @@ export function validateSharedVersions(
 	return errors;
 }
 
+/**
+ * 源码形态守卫（R5 prepack 断言的本地版）：cli 源码树内 shell-dist 与
+ * packages/runtime 同源于一次宿主构建，升 runtime 后忘跑 build:shell 会让
+ * versions.json 停在旧版本，门禁误报「请对齐版本后重新安装」。此处先对比
+ * 两者版本，过期直接报真因。发布形态（pack 后）无同级 runtime 目录，跳过。
+ */
+export function hostArtifactFreshnessError(
+	hostRuntime: string | undefined,
+	workspaceRuntime: string | undefined,
+): string | undefined {
+	if (!hostRuntime || !workspaceRuntime || hostRuntime === workspaceRuntime)
+		return undefined;
+	return `内置宿主产物（shell-dist/versions.json）过期：其中 runtime 版本（${hostRuntime}）≠ 本仓 packages/runtime 版本（${workspaceRuntime}）。
+这是升 runtime 后未重建宿主导致的漂移，请执行：pnpm --filter @oj-module/cli build:shell`;
+}
+
 /** 校验模块工程的共享依赖版本矩阵，违规直接抛错并打印期望值 */
 export function checkSharedVersions(projectRoot: string, shellDist: string): void {
 	const versions = readHostVersions(shellDist);
+
+	let workspaceRuntime: string | undefined;
+	try {
+		workspaceRuntime = JSON.parse(fs.readFileSync(path.join(CLI_ROOT, "..", "runtime", "package.json"), "utf-8")).version;
+	}
+	catch {
+		/* 发布形态：cli 包旁无 runtime 源码目录，跳过守卫 */
+	}
+	const stale = hostArtifactFreshnessError(versions["@oj-module/runtime"], workspaceRuntime);
+	if (stale)
+		throw new Error(stale);
+
 	const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf-8"));
 	const errors = validateSharedVersions(pkg, versions, spec => readInstalledVersion(projectRoot, spec));
 

package/templates/api/.ojm-api-exempt.json

@@ -1,5 +1,9 @@
 {
 	"_comment": "ojm api --check 豁免清单（D12/F19）：把契约与 oj 路由对账中「确认无害」的差异降级为 skip。modules=整模块跳过双向对账（值是 oj 后端模块名，即 api/src/<模块> 的目录名）；paths=按路径跳过，'/xxx/*' 为一层通配（只盖 /xxx/<单段>），其余为精确前缀匹配。仅降级 error→skip，绝不引入新错误；文件缺失或 JSON 损坏时静默按空豁免处理。注意：本文件是严格 JSON，写 // 注释会导致解析失败、豁免静默全失效——说明请写在本 _comment 字段。",
-	"modules": ["web", "notifications"],
-	"paths": ["/auth/*"]
+	"modules": [
+		"web"
+	],
+	"paths": [
+		"/auth/*"
+	]
 }

package/templates/api/config.yaml

@@ -24,11 +24,18 @@
 
 # 站点挂载（oj v0.1.58 起顶层扁平表：一行=一个 URL 前缀+一个目录，api/web 恰好其一）。
 # 被删除的 server.api_prefix / app_spa_fallback 已由 mounts 取代；
-# ojm dev/preview 的 SPA 深链回落由 ojm 自建静态层负责，无需 oj 的 spa。
+# ojm dev 的 SPA 深链回落由 ojm 自建静态层负责；ojm preview 为单服务形态，
+# 现场生成派生 config（api/.ojm-preview.yaml，注入下面的 web 挂载 + spa: true），无需手改。
 mounts:
   - prefix: /api # api 挂载：/api/<module>/...（目录相对 config 所在目录 → api/src）
     api: src
-  # 生产若由 oj 直出前端（不走 ojm 静态层），取消下一行注释并先 build 出 web/dist：
+  # 本地模拟 CDN：直出工程根 cdn/（内容见 cdn/README.md）。
+  # 红线：生产请删掉这一条挂载，并把 system 设置 framework.market_cdn_url 指向真 CDN。
+  # 不得给此挂载设 spa——缺文件必须返回 404，回落 index.html 会让市场解析崩。
+  - prefix: /cdn
+    web: ../cdn
+  # 生产若由 oj 直出前端（前后端同进程，即 ojm preview 的生产形态），
+  # 取消下一行注释并先 build 出 web/dist（preview 会自动注入等价挂载，无需手改）：
   # - prefix: "/"
   #   web: "../web/dist"   # 相对 api/config.yaml → 项目根/web/dist
   #   spa: true
@@ -74,6 +81,12 @@ vars:
 # ---- 平台 exec 白名单（ojm install 的解压/迁移两处消费；模板逐字对齐 lifecycle steps 命令构造，
 # 不得增删——多一个 token 都会 NotCapable）----
 platform:
+  # 平台特权模块名单：方案安装器的 reloading 段调 server.reloadConfig 触发热更。
+  # 缺这条 → 装在最后一步报 NotCapable: module '_platform' is not platform-privileged。
+  modules: [_platform]
+  # 受控挂载根 = api 挂载目录（dev 形态 src）。ojm preview 派生 config 时会改写为 dist，
+  # 保持与 `--api-path` 同源；手写部署请按实际模块根填写。
+  root: src
   # ---- U6 信任库加固（P3-1；P2-2 红线 spike 结论）----
   # 威胁：devkit 0.1.75 语义下 fs: 段对全部模块生效（jail = fs.root），且 trusted_paths 只增不减——
   # 信任库落在第三方方案模块可写的 fs.root 内即可被其伪造信任锚。加固须两端配合：
@@ -90,6 +103,15 @@ platform:
         - 'tar -xzf ${path:archive} -C ${path:dest}'
         - 'oj migrate --format json -d ${path:dir} ${raw:module}'
 
+# ---- 方案安装器的落盘面（fs.* 全局）----
+# 安装器要解包到 modules/.staging、写 dist/modules、备份 db.sqlite——全在 config 目录内。
+# 缺本段 = fs.* 抛 NotCapable，且失败发生在任务文件落盘之前：表现为「POST 安装返回 200、
+# 但 task 查询恒 404」，排查成本极高。生产收紧口径见上面 platform 段的 U6 说明
+# （fs.root 收窄到安装子树 + third-party 模块 jail 隔离属部署清单项）。
+fs:
+  root: .
+  readonly: false
+
 # ---- LDAP 连接段（D1/PRD §4.5 两段式之连接段；oj 插件严格解析本段，未知键启动 fail-fast——只写下列键）----
 # 取消注释并填值即接通目录服务；应用映射段在 DB/设置页（ldap.enabled、ldap_base_dn、
 # ldap_uid_attr、ldap_email_attr，group=ldap，即时生效）。本段改动属 restart_pending，需重启。

package/templates/api/src/_platform/README.md

@@ -0,0 +1,31 @@
+# `_platform` —— 平台内核层
+
+本目录是 oj 框架的**平台内核**，不是业务模块（manifest `name: _platform` 仅声明共有表，
+不拥有业务路由前缀）。它服务于 `api/src` 下所有第一方内置模块（`system`/`auth`/`home`/…）
+以及运行时经方案市场安装的方案包。
+
+## 三层职责
+
+1. **`_shared/service/`** —— 跨模块服务（被业务模块向上 import）。
+   - `infra/`：跨模块基础设施（与具体业务无关的通用能力）
+     - `guard.ts` 判权决策矩阵（AC1-1~6）
+     - `access.ts` 判权 IO 出口（`assertSuperAdmin` / `assertSystemAdmin` / `assertPermission`）
+     - `query.ts` 分页/模糊查询工具
+     - `rate.ts` 速率限制（登录失败/联系人查询）
+     - `audit.ts` 审计原语（`auditOp` / `auditDeny`）
+     - `oplog.ts` 操作日志查询（`searchOplog`）
+   - `domain/`：管理域共享服务（多模块共用的「系统管理」域逻辑，所有权归 `_platform` 的 `sys_*` 表）
+     - `users.ts` / `roles.ts` / `settings.ts` / `solution-perms.ts` / `contacts.ts`
+2. **`_lifecycle/`** —— 方案生命周期引擎（安装/卸载/注册/验签/信任的声明式状态机，
+   与编排端点 `market/api.ts` 职责分离，见 `market/api.ts` 顶部 ISP 注释）。
+3. **编排 API 面** —— 经 oj 扫描 `src/**/api.ts` 暴露，路径前缀即目录名：
+   - `contacts/api.ts` → `/api/_platform/contacts`
+   - `market/api.ts` → `/api/_platform/market`（方案市场，全 superadmin 门禁，R9）
+   - `solutions/api.ts` → `/api/_platform/solutions`（方案路由/验签数据源）
+
+## 边界约定
+
+- 平台内核**不写**业务功能；业务功能归属第一方模块（`/api/<模块>/*`）或运行时方案包。
+- `migrations/` / `schema.yaml` / `seed*.sql` 落地平台共有表（`users` + RBAC 六表 + 设置/日志/路由注册 + 信任库）。
+- `system` 模块管理这些 `sys_*` 表，但其领域服务在本目录 `domain/`（共享内核），
+  非 `system/` 内——避免跨模块 import 私有目录。

package/templates/api/src/_platform/_lifecycle/atomic.ts

@@ -9,7 +9,7 @@ export interface FsFace {
 	writeFile: (path: string, data: Uint8Array) => Promise<void>
 	readFile: (path: string) => Promise<Uint8Array>
 	mkdir: (path: string, opts?: { recursive?: boolean }) => Promise<void>
-	remove: (path: string, opts?: { recursive?: boolean }) => Promise<void>
+	remove: (path: string, opts?: { recursive?: boolean, force?: boolean }) => Promise<void>
 	rename: (oldPath: string, newPath: string) => Promise<void>
 	/** 复制文件（R14 迁移前置备份：sqlite 库 copy 为 <db>.bak-<ts>）；两路径须同文件系统无需递归 */
 	copyFile: (src: string, dest: string) => Promise<void>