@oj-module/cli 0.2.5 → 0.2.8

package/src/dev.ts

@@ -183,11 +183,19 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 
 	// 终端 Ctrl+C / `kill`（SIGINT / SIGTERM）终止 dev 进程时，后端 oj 必须随之消亡：
 	// 起一个统一优雅停机，先停 oj 再退出；并打印后端终止信息。
+	// 终端 Ctrl-C 是进程组信号：外层 bin 转发一份 + 组送达一份，内层会收到
+	// 两个 SIGINT——once 首次触发即摘除，第二个走默认动作杀死本进程，
+	// shutdownDev 跑不完（与 preview 同根因，2026-10-19 冒烟实测）。on +
+	// 幂等守卫吞掉重复信号。
+	let shuttingDown = false;
 	const shutdown = () => {
+		if (shuttingDown)
+			return;
+		shuttingDown = true;
 		void shutdownDev(server, oj, hub);
 	};
-	process.once("SIGINT", shutdown);
-	process.once("SIGTERM", shutdown);
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
 
 	// 兜底：dev 进程以任何非优雅路径退出（未走 SIGINT/SIGTERM，如未捕获异常）时，
 	// 同步强杀 oj，确保它不孤儿化继续占端口（shutdownDev 已停则 kill 为 no-op）。

package/src/index.ts

@@ -7,7 +7,7 @@ import { buildBundle } from "./bundle";
 import { devServer } from "./dev";
 import { mergeManifests, printInfo } from "./info";
 import { initProject } from "./init";
-import { previewServer } from "./preview";
+import { runPreview } from "./preview";
 import { usageText } from "./usage";
 import { vendorCommand } from "./vendor";
 import { readCliVersion } from "./versions";
@@ -51,8 +51,8 @@ async function main() {
 		}
 		case "preview": {
 			const previewPortArg = Number(process.argv[3]);
-			const previewPort = Number.isFinite(previewPortArg) && previewPortArg > 0 ? previewPortArg : undefined;
-			await previewServer(projectRoot, { port: previewPort, ojStatic: process.argv.includes("--oj-static") });
+			const previewPort = Number.isInteger(previewPortArg) && previewPortArg > 0 ? previewPortArg : undefined;
+			await runPreview(projectRoot, { port: previewPort });
 			break;
 		}
 		case "dev": {

package/src/init.ts

@@ -146,6 +146,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	// 的「已存在即跳过」会把审批挡在门外（0.1.0 发布实测）——必须合并
 	ensureAllowBuilds(destDir, report);
 
+	// 5c) .gitignore：模板自带一份（模板兼作可运行 demo 用），但 npm/pnpm pack
+	//     会剥离 `.gitignore` 点文件（npm-packlist always-exclude，`files` 字段
+	//     绕不过），收录进 init.include.yaml 只会让安装包缺文件、readInitInclude
+	//     fail-fast 把整个 init 打挂（0.2.5 发布实测：目标目录只剩空壳）——
+	//     与 pnpm-workspace.yaml 同型，改由 init 现场生成
+	ensureGitignore(destDir, report);
+
 	console.log(`[ojm] init 完成：${destDir}`);
 	console.log(`[ojm]   新增 ${report.created.length} 项，跳过（已存在）${report.skipped.length} 项`);
 	for (const item of report.skipped)
@@ -360,6 +367,43 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	report.created.push(path.relative(process.cwd(), dest) || path.basename(dest));
 }
 
+/**
+ * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
+ *
+ * 内容与 templates/.gitignore 对齐（模板兼作可运行 demo，ignore 的是同一套
+ * 现场产物）：dev 下载的 bin/oj、sqlite/日志/现场签发的私钥与证书、构建产物。
+ * 它不能随模板拷贝——npm/pnpm pack 剥离 `.gitignore`，详见 initProject 5c。
+ */
+const SCAFFOLD_GITIGNORE = `# 由 ojm init 生成。
+node_modules/
+bin/
+.ojm-tmp-*
+# ojm preview 的派生 config（临时产物，进程退出即删；见 preview-config.ts）
+api/.ojm-preview.yaml
+# 本地 sqlite 与运行日志
+api/db.sqlite
+api/db.sqlite-shm
+api/db.sqlite-wal
+api/logs/
+# 现场签发的开发证书与凭据私钥（ojm dev 缺证时自动签发，见 oj-cert.ts）；私钥绝不入仓
+api/config/*.pem
+api/config/cert.jws
+# 构建产物
+api/dist/
+web/dist/
+modules/dist/
+`;
+
+function ensureGitignore(destDir: string, report: InitReport): void {
+	const gitignorePath = path.join(destDir, ".gitignore");
+	if (fs.existsSync(gitignorePath)) {
+		report.skipped.push(".gitignore");
+		return;
+	}
+	fs.writeFileSync(gitignorePath, SCAFFOLD_GITIGNORE);
+	report.created.push(".gitignore");
+}
+
 /**
  * 确保工程根 pnpm-workspace.yaml 的 allowBuilds 含 `esbuild: true`。
  *  - 文件不存在（本函数即唯一来源，见下）→ 按 SCAFFOLD_WORKSPACE_YAML 生成

package/src/preview-config.ts

@@ -0,0 +1,163 @@
+/**
+ * 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
+	/** 显式端口时覆盖 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;
+
+	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 }) => 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,91 @@ 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 }) => writePreviewConfig(root, o));
+	const preview = writer(projectRoot, { siteDir, port: opts.port });
+
+	// / 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/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 路由鉴权）

package/templates/api/config.yaml

@@ -24,11 +24,13 @@
 
 # 站点挂载（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：
+  # 生产若由 oj 直出前端（前后端同进程，即 ojm preview 的生产形态），
+  # 取消下一行注释并先 build 出 web/dist（preview 会自动注入等价挂载，无需手改）：
   # - prefix: "/"
   #   web: "../web/dist"   # 相对 api/config.yaml → 项目根/web/dist
   #   spa: true

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>

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

@@ -5,7 +5,7 @@
 // 参数化 insert，与 audit.ts 同纪律（值不拼字符串）。
 
 // db 为 oj isolate 注入全局（同模板 service 层惯例，installer.ts 同款；测试由夹具装 globalThis.db）
-declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown> };
+declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown>, table: (name: string) => any };
 
 export interface HistoryRow {
 	solution: string
@@ -20,10 +20,15 @@ export interface HistoryRow {
 /** 守卫式 insert：表不存在/写失败一律静默（留痕失败不影响主流程） */
 export async function recordHistory(row: HistoryRow): Promise<void> {
 	try {
-		await db.exec(
-			"insert into market_history (solution, version, action, status, operator, message, created_at) values (?, ?, ?, ?, ?, ?, ?)",
-			[row.solution, row.version, row.action, row.status, row.operator, row.message, Math.floor(Date.now() / 1000)],
-		);
+		await db.table("market_history").insert({
+			solution: row.solution,
+			version: row.version,
+			action: row.action,
+			status: row.status,
+			operator: row.operator,
+			message: row.message,
+			created_at: Math.floor(Date.now() / 1000),
+		}).run();
 	}
 	catch {
 		// 表不存在（市场方案未装）或写失败：静默跳过，不阻断主流程

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

@@ -14,7 +14,7 @@
 // setEnabled 四处同写（D12/AC-P1-6）：锁摘除/恢复 + sidecar + sys_solution_route.enabled +
 // modules.json enabled；启用从 sidecar 摘除前记录恢复版本。db 为 isolate 全局（同模板 service 层）。
 
-import type { OpEntry } from "../_shared/service/audit";
+import type { OpEntry } from "../_shared/service/infra/audit";
 import type { TaskLock } from "./lock";
 import type { StateStore } from "./state";
 import type { FetchFace } from "./steps/download";
@@ -22,7 +22,7 @@ import type { ExecFace } from "./steps/extract";
 import type { SettingDecl, SolutionDecl, SolutionSnapshot } from "./steps/register";
 import type { ReloadFace } from "./steps/reload";
 import type { InstallContext, InstallStage, StageResult, TaskRecord, TaskStatus } from "./types";
-import { auditOp } from "../_shared/service/audit";
+import { auditOp } from "../_shared/service/infra/audit";
 import { atomicWriteText, fsFace, randomId } from "./atomic";
 import { recordHistory } from "./history";
 import { acquireTaskLock, commitLockEntry, readLock, writeLock } from "./lock";
@@ -40,7 +40,7 @@ import { appendAnonymousPaths, bumpInstallSeq } from "./text-edit";
 import { createTrustStore } from "./trust";
 
 // db/http 为 oj isolate 注入全局（同模板 service 层惯例，register.ts/audit.ts 同款；测试由夹具装 globalThis.db）
-declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown> };
+declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown>, table: (name: string) => any };
 
 export type { InstallContext, InstallStage, StageResult, TaskRecord, TaskStatus };
 
@@ -1039,7 +1039,7 @@ export async function setEnabled(input: SetEnabledInput): Promise<{ ok: boolean,
 	}
 	// ③ route 表 enabled（生命周期开关，非注册内容直写，D10 不适用）
 	try {
-		await db.exec("update sys_solution_route set enabled = ? where module = ?", [enabled ? 1 : 0, name]);
+		await db.table("sys_solution_route").update({ enabled: enabled ? 1 : 0 }).where({ field: "module", op: "eq", value: name }).run();
 	}
 	catch (e) {
 		audit(false, `route enabled 写失败：${String(e)}`);

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

@@ -101,7 +101,7 @@ export function sha384Bytes(data: Uint8Array): Uint8Array {
 	view.setUint32(padded - 4, bitLenLo);
 
 	const h: Array<[number, number]> = IV.map(x => [x[0], x[1]] as [number, number]);
-	const w = Array.from({ length: 80 });
+	const w = Array.from({ length: 80 }, () => [0, 0] as [number, number]);
 	for (let off = 0; off < padded; off += 128) {
 		for (let t = 0; t < 16; t++) {
 			w[t] = [view.getUint32(off + t * 8), view.getUint32(off + t * 8 + 4)];

package/templates/api/src/_platform/_lifecycle/steps/download.ts

@@ -39,7 +39,7 @@ export function archiveFileOf(manifest: unknown): { ok: true, file: string, arch
 	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
 		return { ok: false, message: "C2-29：manifest 不是键值对象，archive 身份不可得" };
 	}
-	const archive = (manifest as Record<string, unknown>).archive;
+	const archive = (manifest as Record<string, unknown>).archive as Record<string, unknown>;
 	if (typeof archive !== "object" || archive === null || Array.isArray(archive)) {
 		return { ok: false, message: "C2-29：archive 段缺失或不是键值对象（Form B 真源须含 file/sha256/size）" };
 	}