@oj-module/cli 0.2.6 → 0.2.14

package/shell-dist/versions.json

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

package/src/__tests__/build-backend.test.ts

@@ -0,0 +1,64 @@
+// buildBackend spec：宿主 versions.json 双落点（方案安装的 C2-09 前置）。
+//
+// 安装器按 B-11 布局读 `<api>/dist/versions.json`（与 manifests.yaml 同层）做 peerRuntime
+// 强制比对；而站点壳的 versions.json 落在 web/dist。两者不同源时，新工程 `ojm build`
+// 完仍会在 preflight 被 C2-09 拒装——这条用例钉住「同源双写」，防止回归。
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { buildBackend } from "../build";
+
+/**
+ * 假 oj 二进制：只需成功退出——本 spec 验的是 buildBackend 在 oj build 之后的收尾动作
+ * （versions.json 同源落地），oj build 自身的产物由用例预先放好模拟。
+ */
+function fakeOj(projectRoot: string): void {
+	mkdirSync(join(projectRoot, "bin"), { recursive: true });
+	const bin = join(projectRoot, "bin", "oj");
+	writeFileSync(bin, "#!/bin/sh\nexit 0\n");
+	chmodSync(bin, 0o755);
+}
+
+function newProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-"));
+	mkdirSync(join(root, "api", "src", "demo"), { recursive: true });
+	writeFileSync(join(root, "api", "src", "demo", "manifest.yaml"), "name: demo\nversion: 0.1.0\n", "utf-8");
+	writeFileSync(join(root, "api", "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+	// 模拟 oj build 已产出的 manifests.yaml（验证收尾动作不破坏既有产物）
+	mkdirSync(join(root, "api", "dist"), { recursive: true });
+	writeFileSync(join(root, "api", "dist", "manifests.yaml"), "demo: 0.1.0\n", "utf-8");
+	fakeOj(root);
+	return root;
+}
+
+describe("given 宿主工程有 api/src When ojm build 后端", () => {
+	it("then api/dist/versions.json 与 shell-dist 同源落地（安装器 C2-09 前置）", async () => {
+		const root = newProject();
+
+		await buildBackend(root);
+
+		const hostVersions = join(root, "api", "dist", "versions.json");
+		expect(existsSync(hostVersions)).toBe(true);
+		const parsed = JSON.parse(readFileSync(hostVersions, "utf-8")) as Record<string, string>;
+		expect(typeof parsed["@oj-module/runtime"]).toBe("string");
+	});
+
+	it("then 既有 oj build 产物不被覆盖（manifests.yaml 原样保留）", async () => {
+		const root = newProject();
+
+		await buildBackend(root);
+
+		expect(readFileSync(join(root, "api", "dist", "manifests.yaml"), "utf-8")).toBe("demo: 0.1.0\n");
+	});
+});
+
+describe("given 纯前端工程（无 api/src）When ojm build 后端", () => {
+	it("then 跳过构建、不产出 api/dist", async () => {
+		const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-fe-"));
+
+		expect(await buildBackend(root)).toBe(false);
+		expect(existsSync(join(root, "api", "dist"))).toBe(false);
+	});
+});

package/src/__tests__/versions.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { hostArtifactFreshnessError } from "../versions";
+
+describe("hostArtifactFreshnessError（源码形态宿主产物过期守卫）", () => {
+	it("版本一致 → 通过", () => {
+		expect(hostArtifactFreshnessError("0.2.11", "0.2.11")).toBeUndefined();
+	});
+
+	it("任一侧缺失 → 跳过守卫", () => {
+		expect(hostArtifactFreshnessError(undefined, "0.2.11")).toBeUndefined();
+		expect(hostArtifactFreshnessError("0.2.11", undefined)).toBeUndefined();
+	});
+
+	it("宿主产物落后于 workspace runtime → 报真因并指向 build:shell", () => {
+		const err = hostArtifactFreshnessError("0.2.10", "0.2.11");
+		expect(err).toContain("shell-dist/versions.json）过期");
+		expect(err).toContain("0.2.10");
+		expect(err).toContain("0.2.11");
+		expect(err).toContain("build:shell");
+	});
+
+	it("宿主产物领先（跨仓消费旧版 runtime）→ 同样拦截", () => {
+		expect(hostArtifactFreshnessError("0.2.12", "0.2.11")).toContain("过期");
+	});
+});

package/src/build.ts

@@ -511,6 +511,15 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	//      SyntaxError: Invalid left-hand side in assignment（端点 500）。
 	// 0.1.32 / 0.1.50 均复现。产物体积换正确性，等上游修好再撤这个旗标。
 	execFileSync(oj, ["build", ...configArgs, "-d", apiSrc, "-o", apiDist, "--no-minify"], { stdio: "inherit" });
+	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 web/dist（mergeShellSite），
+	// 而方案安装器读的是 `<api>/dist/versions.json`（B-11：与 manifests.yaml 同层，用于
+	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
+	// preflight 直接 C2-09 fail-closed「无法读取宿主 runtime 版本」。
+	const versionsSrc = path.join(resolveShellDist(), "versions.json");
+	if (fs.existsSync(versionsSrc)) {
+		fs.mkdirSync(apiDist, { recursive: true });
+		fs.copyFileSync(versionsSrc, path.join(apiDist, "versions.json"));
+	}
 	return true;
 }
 

package/src/bundle.ts

@@ -116,8 +116,14 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 	}
 }
 
-/** C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version/desc 与 bundle 级逐一相等（oj 启动强校验同源） */
-function checkModuleManifest(built: string, name: string, version: string, summary: string): string[] {
+/**
+ * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
+ * （oj 启动强校验同源）。
+ *
+ * 变更（2026-10-21）：`desc === summary` 的等值要求已移除（与安装侧 extract.ts 同步）——
+ * 那是构建期映射的产物而不是安全边界，保留它会让 desc 与 summary 一字之差的包直接装不上。
+ */
+function checkModuleManifest(built: string, name: string, version: string, _summary: string): string[] {
 	const p = path.join(built, "manifest.yaml");
 	let doc: unknown;
 	try {
@@ -137,9 +143,6 @@ function checkModuleManifest(built: string, name: string, version: string, summa
 	if (mm.version !== version) {
 		out.push(`模块级 version「${String(mm.version)}」必须 === bundle version「${version}」`);
 	}
-	if (mm.desc !== summary) {
-		out.push(`模块级 desc「${String(mm.desc)}」必须 === bundle summary「${summary}」（安装器写 desc 即取 summary）`);
-	}
 	return out;
 }
 

package/src/contract/__tests__/handler-scan.test.ts

@@ -51,6 +51,35 @@ export default createMarketApi({} as Env);
 		]);
 	});
 
+	it("标识符默认导出指回工厂调用：const x = createXxx(env); export default x（market/api.ts 真形态）", () => {
+		// 真实模板形态：工厂调用赋给 const，再 export default 该标识符。
+		// 此前 scanHandlerFile 只认「default 导出 = 调用表达式」，认不出
+		// 「default 导出 = 标识符 → 指向一次工厂调用」，导致 market 整族 route 漏登。
+		const rows = scan("api.ts", `
+import type { Env } from "./types";
+export function createMarketApi(env: Env) {
+	return {
+		"install": {
+			async post() { return {}; },
+		},
+		"verify": {
+			async post() { return {}; },
+			last: {
+				async get() { return {}; },
+			},
+		},
+	};
+}
+const marketApi = createMarketApi({} as Env);
+export default marketApi;
+`);
+		expect(rows.map(r => `${r.method} ${r.full}`).sort()).toEqual([
+			"GET _platform/market/verify/last",
+			"POST _platform/market/install",
+			"POST _platform/market/verify",
+		]);
+	});
+
 	it("无 return 对象 / 未知 callee / 点分 callee 不可解析 → 零行（不炸不猜）", () => {
 		expect(scan("a.ts", "export default createMissingApi({});")).toEqual([]);
 		expect(scan("b.ts", `

package/src/contract/__tests__/market-client.integration.test.ts

@@ -0,0 +1,170 @@
+// ScopedRequestLike 真源在 runtime contract（生成物 __client/api.ts 也从这里 import，
+// 自身不再 re-export——旧写法 type import 自 __client 会在再生后 TS2305）。
+import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
+
+// 集成回归：真实 httpMarketClient（统一后委托 ojm 生成 client）的委托行为。
+// 经 bindRequest 注入 mock request，验证每条 MarketClient 方法 → 正确 URL/body/query + 返回形状；
+// 并验证 index 的 503「未配置市场地址」→ [] 空态（PRD §5.3）。
+//
+// 不加载 @oj-module/runtime 重依赖（antd / pro-components 在 node 环境无法 import），仅桩 request、
+// 透传真实 zod（供生成 client 的 DEV 响应校验走真实路径）。ContractApiError 由轻量子路径提供。
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { bindRequest } from "../../../templates/web/src/_platform/__client/api";
+import { httpMarketClient } from "../../../templates/web/src/oj-market/api/defaultClient";
+
+// index() 直连 request（不走生成 client），故把桩 request 做成可变实现，测试内统一指向同一 mock。
+const { requestImpl } = vi.hoisted(() => ({
+	requestImpl: {
+		get: () => { throw new Error("placeholder"); },
+		post: () => { throw new Error("placeholder"); },
+		put: () => { throw new Error("placeholder"); },
+		delete: () => { throw new Error("placeholder"); },
+		patch: () => { throw new Error("placeholder"); },
+		head: () => { throw new Error("placeholder"); },
+	},
+}));
+
+vi.mock("@oj-module/runtime", async () => {
+	const { z } = await import("zod");
+	return {
+		z,
+		// defaultClient 顶层 bindRequest(request) 用到；测试内立即被 mock 覆盖，不会真发请求。
+		request: requestImpl,
+	};
+});
+
+interface Call {
+	method: string
+	url: string
+	opts?: { searchParams?: Record<string, string | number | boolean>, json?: unknown }
+}
+
+function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }) {
+	const calls: Call[] = [];
+	const make = (method: string) => (url: string, opts?: Call["opts"]) => {
+		calls.push({ method, url, opts });
+		const r = responder({ method, url, opts });
+		if (r.status && r.status >= 400) {
+			// ky 形态：HTTPError 携带 response.status（httpMarketClient.isUnconfigured 依赖它）
+			throw Object.assign(new Error(`HTTP ${r.status}`), { response: { status: r.status } });
+		}
+		return { json: () => Promise.resolve({ code: 0, data: r.data ?? null }) };
+	};
+	const req = {
+		get: make("get"),
+		post: make("post"),
+		put: make("put"),
+		delete: make("delete"),
+		patch: make("patch"),
+		head: make("head"),
+	} as unknown as ScopedRequestLike;
+	return { calls, req };
+}
+
+// 让 index() 直连的 request 与生成 client 的 bindRequest 指向同一 mock，行为一致。
+// 桥接：占位方法零参签名 ↔ ScopedRequestLike 真实签名，经 any 双向打通（测试桩，无运行时差异）。
+function useMock(m: ReturnType<typeof mockRequest>) {
+	bindRequest(m.req);
+	const req = m.req as unknown as Record<keyof typeof requestImpl, () => never>;
+	for (const k of Object.keys(requestImpl) as Array<keyof typeof requestImpl>)
+		requestImpl[k] = req[k];
+}
+
+describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
+	let mock: ReturnType<typeof mockRequest>;
+
+	beforeEach(() => {
+		mock = mockRequest(() => ({ data: {} }));
+		useMock(mock);
+	});
+
+	it("meta() → GET _platform/market/meta，返回 { apiVersion }", async () => {
+		mock = mockRequest(() => ({ data: { apiVersion: "1.2.3" } }));
+		useMock(mock);
+		const r = await httpMarketClient.meta();
+		expect(mock.calls).toEqual([{ method: "get", url: "_platform/market/meta", opts: undefined }]);
+		expect(r).toEqual({ apiVersion: "1.2.3" });
+	});
+
+	it("index() → GET _platform/market/index，返回 IndexRow[]", async () => {
+		const rows = [{ name: "a", latest: "1.0", installed: "1.0", enabled: true, upgradable: false }];
+		mock = mockRequest(() => ({ data: rows }));
+		useMock(mock);
+		const r = await httpMarketClient.index();
+		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/index" });
+		expect(r).toEqual(rows);
+	});
+
+	it("index() 遇 503（未配置市场地址）→ [] 空态，不抛（PRD §5.3）", async () => {
+		mock = mockRequest(c => (c.url === "_platform/market/index" ? { status: 503 } : { data: {} }));
+		useMock(mock);
+		const r = await httpMarketClient.index();
+		expect(r).toEqual([]);
+		// 503 是配置态而非故障：silentError 抑制全局 toast + retry:0 不重试（原
+		// market-client-unconfigured 用例的断言并入此处——工厂形态退役后唯一活口）
+		expect(mock.calls).toHaveLength(1);
+		expect(mock.calls[0].opts).toMatchObject({ silentError: true, retry: 0 });
+	});
+
+	it("install(input) → POST _platform/market/install，body 含 name/version/source", async () => {
+		mock = mockRequest(() => ({ data: { task_id: "t-1" } }));
+		useMock(mock);
+		const r = await httpMarketClient.install({ name: "alpha", version: "2.0", source: "file" });
+		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/install" });
+		expect(mock.calls[0].opts?.json).toEqual({ name: "alpha", version: "2.0", source: "file" });
+		expect(r).toEqual({ task_id: "t-1" });
+	});
+
+	it("install(input) 缺省 version/source → null / cdn 兜底", async () => {
+		mock = mockRequest(() => ({ data: { task_id: "t-2" } }));
+		useMock(mock);
+		await httpMarketClient.install({ name: "beta" });
+		expect(mock.calls[0].opts?.json).toEqual({ name: "beta", version: null, source: "cdn" });
+	});
+
+	it("task(id) → GET _platform/market/task? 带 id", async () => {
+		const rec = { id: "t-1", name: "a", version: "1.0", status: "done", stage: "done", progress: 100, message: "ok", stages: [], startedAt: 1 };
+		mock = mockRequest(() => ({ data: rec }));
+		useMock(mock);
+		const r = await httpMarketClient.task("t-1");
+		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/task" });
+		expect(mock.calls[0].opts?.searchParams).toEqual({ id: "t-1" });
+		expect(r).toEqual(rec);
+	});
+
+	it("enable(input) → POST _platform/market/enable，body {name,enabled}", async () => {
+		mock = mockRequest(() => ({ data: { ok: true, message: "done" } }));
+		useMock(mock);
+		const r = await httpMarketClient.enable({ name: "a", enabled: false });
+		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/enable" });
+		expect(mock.calls[0].opts?.json).toEqual({ name: "a", enabled: false });
+		expect(r).toEqual({ ok: true, message: "done" });
+	});
+
+	it("history() → GET _platform/market/history，返回 MarketHistory[]", async () => {
+		const hist = [{ id: 1, solution: "a", version: "1.0", action: "install", status: "ok", operator: null, message: null, created_at: 1 }];
+		mock = mockRequest(() => ({ data: hist }));
+		useMock(mock);
+		const r = await httpMarketClient.history();
+		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/history" });
+		expect(r).toEqual(hist);
+	});
+
+	it("uninstallImpact(name) → GET _platform/market/uninstall-impact? 带 name", async () => {
+		mock = mockRequest(() => ({ data: { name: "a", affectedRoles: 2, affectedUsers: 5 } }));
+		useMock(mock);
+		const r = await httpMarketClient.uninstallImpact("a");
+		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/uninstall-impact" });
+		expect(mock.calls[0].opts?.searchParams).toEqual({ name: "a" });
+		expect(r).toEqual({ name: "a", affectedRoles: 2, affectedUsers: 5 });
+	});
+
+	it("uninstall(name) → POST _platform/market/uninstall，body {name}", async () => {
+		mock = mockRequest(() => ({ data: { ok: true, message: "removed" } }));
+		useMock(mock);
+		const r = await httpMarketClient.uninstall("a");
+		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/uninstall" });
+		expect(mock.calls[0].opts?.json).toEqual({ name: "a" });
+		expect(r).toEqual({ ok: true, message: "removed" });
+	});
+});

package/src/contract/handler-scan.ts

@@ -94,6 +94,20 @@ function collectObjectDecls(sf: ts.SourceFile): Map<string, ts.ObjectLiteralExpr
 	return decls;
 }
 
+/** 顶层 `const x = createXxx(env)` 调用声明表：工厂形态经标识符引用（`export default x`）时的解析依据 */
+function collectCallDecls(sf: ts.SourceFile): Map<string, ts.CallExpression> {
+	const decls = new Map<string, ts.CallExpression>();
+	for (const stmt of sf.statements) {
+		if (!ts.isVariableStatement(stmt))
+			continue;
+		for (const decl of stmt.declarationList.declarations) {
+			if (ts.isIdentifier(decl.name) && decl.initializer && ts.isCallExpression(decl.initializer))
+				decls.set(decl.name.text, decl.initializer);
+		}
+	}
+	return decls;
+}
+
 /** verb 键 → 实现函数名（供 `.route` 语句按函数名查找；内联写法回落键名） */
 function implNameOf(prop: ts.ObjectLiteralElementLike): string | undefined {
 	if (ts.isShorthandPropertyAssignment(prop))
@@ -141,9 +155,16 @@ function defaultExportObject(sf: ts.SourceFile, decls: Map<string, ts.ObjectLite
  * 是调用表达式，此前扫描器不认，route-unregistered 守卫对 market/solutions 全族失效）：
  * 解析同文件同名函数声明体内 return 的对象字面量（运行时 oj 内省执行工厂拿到该对象，静态
  * 扫描镜像此语义）。支持多个 return；对象内标识符引用仍解析文件级顶层 const。
+ * 补全（P2-14 形态遗漏）：`export default createXxxApi(marketEnv())` 中 `call.expression`
+ * 是**带实参的调用表达式**，函数名落在 `call.expression.expression`（createXxxApi）；
+ * 旧逻辑直接 dottedNameOf(call.expression) 对 CallExpression 返回 undefined → 扫成 0 路由，
+ * 致使 ojm api --check 把 market 全族端点判为「未实现 / stub 缺失」。此处穿透一层取被调函数名。
  */
 function factoryReturnObjects(sf: ts.SourceFile, call: ts.CallExpression): ts.ObjectLiteralExpression[] {
-	const callee = dottedNameOf(call.expression);
+	// `export default createXxxApi(marketEnv())`：`call.expression` 为带实参的调用表达式，
+	// 函数名在其 `.expression`；`export default obj.createXxxApi(marketEnv())` 同样穿透。
+	const target = ts.isCallExpression(call.expression) ? call.expression.expression : call.expression;
+	const callee = dottedNameOf(target);
 	if (callee === undefined)
 		return [];
 	for (const stmt of sf.statements) {
@@ -189,6 +210,7 @@ export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow
 	const sf = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
 	const routes = collectRouteDecls(sf);
 	const decls = collectObjectDecls(sf);
+	const callDecls = collectCallDecls(sf);
 	const relDir = relative(apiSrcDir, dirname(filePath)).split(sep).join("/");
 	const rows: HandlerRow[] = [];
 	const seen = new Set<ts.Node>();
@@ -251,10 +273,19 @@ export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow
 		walk(root, "", filePrefix, 1);
 	}
 	else {
-		// P2-14：工厂形态（CallExpression）——组前缀从目录镜像起算（同内联字面量形态）
+		// 工厂形态（P2-14 + 补全）：export default 后接
+		//  - CallExpression 直调：createXxx(env) / createXxx(marketEnv())
+		//  - Identifier 引用：const api = createXxx(env); export default api
+		// 组前缀从目录镜像起算（同内联字面量形态）。
 		for (const stmt of sf.statements) {
-			if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isCallExpression(stmt.expression)) {
-				for (const obj of factoryReturnObjects(sf, stmt.expression))
+			if (!ts.isExportAssignment(stmt) || stmt.isExportEquals)
+				continue;
+			const expr = stmt.expression;
+			const callExpr = ts.isCallExpression(expr)
+				? expr
+				: (ts.isIdentifier(expr) ? callDecls.get(expr.text) : undefined);
+			if (callExpr) {
+				for (const obj of factoryReturnObjects(sf, callExpr))
 					walk(obj, "", "", 1);
 			}
 		}

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": {
@@ -161,6 +161,12 @@ async function main() {
 			publishCommand(positionals[0] ?? "", { id, key, check });
 			break;
 		}
+		case "market": {
+			// 本地模拟 CDN 与市场链路（setup / publish / build-index）
+			const { runMarket } = await import("./market/command");
+			await runMarket(process.argv.slice(3));
+			break;
+		}
 		default: {
 			if (command && OJ_PASSTHROUGH.has(command)) {
 				const { runOjSubcommand } = await import("./oj-cmd");

package/src/init.ts

@@ -98,6 +98,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		fs.mkdirSync(skillDir, { recursive: true });
 		for (const name of ["SKILL.md", "api-manual.md"])
 			copyIfAbsent(path.join(devkit, name), path.join(skillDir, name), report);
+		// v0.1.82 起 devkit 新增两份专题指南（api-manual/SKILL 均引用它们）：
+		// SQL 构造器能力矩阵/方言差异、oj test L1 测试指南。它们是**增量文档**、
+		// 不影响 ojm 运行，故「有则拷、无则记跳过」——bin/devkit 来自用户本地
+		// oj 版本（MIN_OJ_VERSION 只钉到 0.1.73），旧版 devkit 没有这两个文件，
+		// 为两份文档把整个 init 打挂不值当（用户升 oj 后重跑 init 即补上）。
+		for (const name of ["sql-builder-guide.md", "oj-test-guide.md"])
+			copyIfPresent(path.join(devkit, name), path.join(skillDir, name), report);
 		copyIfAbsent(path.join(devkit, "global.d.ts"), path.join(destDir, "global.d.ts"), report);
 	}
 	else {
@@ -367,6 +374,21 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	report.created.push(path.relative(process.cwd(), dest) || path.basename(dest));
 }
 
+/**
+ * 同 copyIfAbsent，但**源缺失**时记一条跳过而非抛错。
+ *
+ * 用于从 bin/devkit 拷第三方版本化内容（两份专题指南）：devkit 随用户本地 oj
+ * 版本而变，旧版没有新文件属正常版本 skew，不是安装包损坏——缺了只少份文档，
+ * 不该让 init 失败。源在而目标已存在仍走 copyIfAbsent 的幂等跳过。
+ */
+function copyIfPresent(src: string, dest: string, report: InitReport): void {
+	if (!fs.existsSync(src)) {
+		report.skipped.push(`${path.basename(src)}（bin/devkit 无此文件，跳过）`);
+		return;
+	}
+	copyIfAbsent(src, dest, report);
+}
+
 /**
  * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
  *
@@ -378,6 +400,8 @@ 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

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

@@ -33,7 +33,7 @@ afterEach(() => {
 
 /** 预置「已构建」产物：oj build（api/dist/<name>-<version>/）与站点构建（web/dist/modules/） */
 function makePrebuiltArtifacts(): void {
-	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version/desc 与 bundle 级逐一相等，C2-31）
+	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version 与 bundle 级逐一相等，C2-31）
 	const apiDist = join(project, "api/dist/demo-solution-0.1.0");
 	mkdirSync(join(apiDist, "ping"), { recursive: true });
 	mkdirSync(join(apiDist, "migrations"), { recursive: true });
@@ -101,9 +101,9 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 		await expect(pack()).rejects.toThrow(/manifest\.yaml/);
 	});
 
-	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 拒绝", async () => {
+	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 放行（等值要求已移除）", async () => {
 		writeFileSync(join(project, "api/dist/demo-solution-0.1.0/manifest.yaml"), "name: demo-solution\ndesc: 不一致描述\nversion: 0.1.0\n");
-		await expect(pack()).rejects.toThrow(/C2-31/);
+		await expect(pack()).resolves.toMatchObject({ name: "demo-solution" });
 	});
 
 	it("c2-31 分层核对：api/dist 缺 <name>-<version>/ → 可读报错指明期望产物路径", async () => {