@oj-module/cli 0.2.23 → 0.2.25

package/src/__tests__/usage.test.ts

@@ -1,69 +1,67 @@
 import { describe, expect, it } from "vitest";
-import { getCommandHelp, resolveHelpRequest } from "../usage";
+import { resolveLang, usageText } from "../usage";
 
-describe("getCommandHelp", () => {
-	it("返回命令级帮助（init）", () => {
-		const t = getCommandHelp("init");
-		expect(t).toBeDefined();
-		expect(t).toContain("ojm init");
+describe("resolveLang", () => {
+	it("显式 OJM_LANG 优先于系统 locale", () => {
+		expect(resolveLang({ OJM_LANG: "en-US", LANG: "zh_CN.UTF-8" } as NodeJS.ProcessEnv)).toBe("en-US");
+		expect(resolveLang({ OJM_LANG: "zh-CN", LANG: "en_US.UTF-8" } as NodeJS.ProcessEnv)).toBe("zh-CN");
 	});
 
-	it("子命令优先：market setup 命中专属条目", () => {
-		expect(getCommandHelp("market", "setup")).toContain("ojm market setup");
+	it("无显式设置时按 LANG/LC_ALL 前缀探测英文", () => {
+		expect(resolveLang({ LANG: "en_US.UTF-8" } as NodeJS.ProcessEnv)).toBe("en-US");
+		expect(resolveLang({ LC_ALL: "en_GB.UTF-8" } as NodeJS.ProcessEnv)).toBe("en-US");
+		expect(resolveLang({ LANG: "C" } as NodeJS.ProcessEnv)).toBe("zh-CN");
 	});
 
-	it("子命令无专属条目时回退到命令级（market 无 sub）", () => {
-		const t = getCommandHelp("market");
-		expect(t).toContain("ojm market");
+	it("非法值回退 zh-CN", () => {
+		expect(resolveLang({ OJM_LANG: "fr" } as NodeJS.ProcessEnv)).toBe("zh-CN");
 	});
 
-	it("trust 子命令（add/revoke/confirm/ls）各自有专属条目", () => {
-		for (const sub of ["ls", "add", "revoke", "confirm"]) {
-			const t = getCommandHelp("trust", sub);
-			expect(t, `trust ${sub}`).toBeDefined();
-			expect(t).toContain(`ojm trust ${sub}`);
-		}
-	});
-
-	it("未知命令返回 undefined", () => {
-		expect(getCommandHelp("nope")).toBeUndefined();
+	it("全缺省为 zh-CN", () => {
+		expect(resolveLang({} as NodeJS.ProcessEnv)).toBe("zh-CN");
 	});
 });
 
-describe("resolveHelpRequest", () => {
-	it("ojm --help → 顶层（无 cmd）", () => {
-		expect(resolveHelpRequest(["--help"])).toEqual({ cmd: undefined, sub: undefined });
-	});
+describe("usageText 分组（cac 渲染）", () => {
+	const ZH_TITLES = ["工程脚手架", "开发与构建", "清单与诊断", "方案市场（站点侧生命周期）", "发布与签名（作者侧）", "本地市场模拟 CDN", "oj 子命令透传"];
+	const EN_TITLES = ["Project scaffolding", "Development & build", "Manifest & diagnostics", "Marketplace (site-side lifecycle)", "Publishing & signing (author side)", "Local marketplace mock CDN", "oj subcommand passthrough"];
 
-	it("ojm -h → 顶层（无 cmd）", () => {
-		expect(resolveHelpRequest(["-h"])).toEqual({ cmd: undefined, sub: undefined });
-	});
-
-	it("ojm init --help → cmd=init", () => {
-		expect(resolveHelpRequest(["init", "--help"])).toEqual({ cmd: "init", sub: undefined });
-	});
-
-	it("ojm trust add --help → cmd=trust sub=add", () => {
-		expect(resolveHelpRequest(["trust", "add", "--help"])).toEqual({ cmd: "trust", sub: "add" });
-	});
-
-	it("ojm market setup --help → cmd=market sub=setup", () => {
-		expect(resolveHelpRequest(["market", "setup", "--help"])).toEqual({ cmd: "market", sub: "setup" });
+	it("中文分组头齐全且顺序固定", () => {
+		const text = usageText("zh-CN");
+		let last = -1;
+		for (const title of ZH_TITLES) {
+			const i = text.indexOf(`${title}:`);
+			expect(i, title).toBeGreaterThan(last);
+			last = i;
+		}
 	});
 
-	it("ojm help init → cmd=init", () => {
-		expect(resolveHelpRequest(["help", "init"])).toEqual({ cmd: "init", sub: undefined });
+	it("英文分组头齐全且顺序固定", () => {
+		const text = usageText("en-US");
+		let last = -1;
+		for (const title of EN_TITLES) {
+			const i = text.indexOf(`${title}:`);
+			expect(i, title).toBeGreaterThan(last);
+			last = i;
+		}
 	});
 
-	it("ojm help trust add → cmd=trust sub=add", () => {
-		expect(resolveHelpRequest(["help", "trust", "add"])).toEqual({ cmd: "trust", sub: "add" });
+	it("两种语言均含全部命令语法行", () => {
+		for (const lang of ["zh-CN", "en-US"] as const) {
+			const text = usageText(lang);
+			for (const cmd of ["ojm init [dir]", "ojm dev [port]", "ojm build", "ojm preview [port]", "ojm api [dir]", "ojm info", "ojm merge", "ojm vendor", "ojm install", "ojm trust", "ojm keygen", "ojm sign", "ojm publish", "ojm market verify", "ojm test", "ojm migrate"])
+				expect(text, `${lang} ${cmd}`).toContain(cmd);
+		}
 	});
 
-	it("ojm help → 顶层（无 cmd）", () => {
-		expect(resolveHelpRequest(["help"])).toEqual({ cmd: undefined, sub: undefined });
+	it("trust 子命令索引行是 short 一句话，不复读语法行（回归）", () => {
+		const zh = usageText("zh-CN");
+		expect(zh).toMatch(/ojm trust ls\s+列出已信任 key/);
+		expect(zh).not.toContain("ojm trust ls          ojm trust ls");
 	});
 
-	it("非帮助调用返回 null（ojm build）", () => {
-		expect(resolveHelpRequest(["build", "--bundle"])).toBeNull();
+	it("版本项保留（双语）", () => {
+		expect(usageText("zh-CN")).toContain("ojm --version | -V");
+		expect(usageText("en-US")).toContain("ojm --version | -V");
 	});
 });

package/src/build.ts

@@ -522,7 +522,7 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	if (syncedPaths === "created" || syncedPaths === "updated")
 		console.log(`[ojm] 已${syncedPaths === "created" ? "生成" : "更新"} ${ALIAS_PATHS_FILE}（\`#/<模块名>/…\` 的 TS paths 投影）`);
 
-	const apiDist = layout?.apiDist ?? path.join(projectRoot, "api", "dist");
+	const apiDist = layout?.apiDist ?? path.join(projectRoot, "dist", "api");
 	console.log("[ojm] oj build（后端）…");
 	// 必须显式给 -c：oj build 的 -c 缺省是 ./config.yaml（相对 CWD），而 config 在
 	// <project>/config/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
@@ -546,8 +546,8 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 		apiDist,
 		"--no-minify",
 	], { stdio: "inherit" });
-	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 web/dist（mergeShellSite），
-	// 而方案安装器读的是 `<api>/dist/versions.json`（B-11：与 manifests.yaml 同层，用于
+	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 dist/web（mergeShellSite），
+	// 而方案安装器读的是 `dist/api/versions.json`（B-11：与 manifests.yaml 同层，用于
 	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
 	// preflight 直接 C2-09 fail-closed「无法读取宿主 runtime 版本」。
 	const versionsSrc = path.join(resolveShellDist(), "versions.json");
@@ -585,7 +585,7 @@ function mergeShellSite(distDir: string, siteBase: string): void {
 /**
  * 构建模块工程。
  *
- * 产出（web 布局：web/dist）：
+ * 产出（layout.distDir：module-root / new → dist/web；flat → build）：
  *   <dist>/modules/<name>/<version>/{entry.js, chunk-*.js, *.css}
  *   <dist>/modules.json
  *

package/src/bundle.ts

@@ -23,8 +23,8 @@
 //   <project>/solution.yaml | manifest.yaml          → 工程根契约（旧单方案写法）
 //   <project>/src/<模块>/solution.yaml | manifest.yaml → 模块级契约（绝不进 <模块>/api/，§1.2 红线）
 //   任一处均 → <name>-<version>/manifest.yaml（Form A；tgz 内名固定为 manifest.yaml）
-//   <project>/api/dist/<name>-<version>/        → <name>-<version>/api/<name>-<version>/（oj build 产物原样，C2-31 分层核对）
-//   <project>/web/dist/modules/<name>/          → <name>-<version>/web/modules/<name>/（只入包方案自己的模块；
+//   <project>/dist/api/<name>-<version>/        → <name>-<version>/api/<name>-<version>/（oj build 产物原样，C2-31 分层核对）
+//   <project>/dist/web/modules/<name>/          → <name>-<version>/web/modules/<name>/（只入包方案自己的模块；
 //                                                 web.entry/css 存在性复核）
 // 红线：modules.json 禁入包（C2-31——该清单由安装器在目标站点 upsert，防覆盖宿主清单）；
 // 文件面契约（tables↔schema.yaml、locales 双语齐备）构建期 fail-fast（契约 §4.1 构建列）。
@@ -257,8 +257,8 @@ async function planBundle(projectRoot: string, layout: ProjectLayout, target: Bu
 
 /**
  * 组装段（写盘）：staging 单根 <name>-<version>/ → 红线自检 → 确定性 tgz + sha256。
- * 入包内容与 §11.1 一致：只组装本方案的模块产物（api/dist/<name>-<version>/ 与
- * web/dist/modules/<name>/），模板/宿主模块不随包。
+ * 入包内容与 §11.1 一致：只组装本方案的模块产物（layout.apiDist/<name>-<version>/ 与
+ * layout.distDir/modules/<name>/），模板/宿主模块不随包。
  */
 async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan: BundlePlan, outDir: string): Promise<BundleBuildResult> {
 	const m = plan.manifest;
@@ -274,7 +274,7 @@ async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan:
 
 		// api：oj build 产物原样入包（编译编排不在此重跑——作者先 oj build，本命令只校验与组装）
 		if (m.api !== undefined) {
-			const built = path.join(projectRoot, "api/dist", `${name}-${version}`);
+			const built = path.join(layout.apiDist, `${name}-${version}`);
 			if (!fs.existsSync(built)) {
 				throw new Error(`[ojm] 方案包构建失败：缺少 oj build 产物 ${path.relative(projectRoot, built)}（manifest 声明了 api 段；先对 api/ 运行 oj build，产物原样入包）`);
 			}
@@ -286,18 +286,18 @@ async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan:
 		}
 
 		// web：只入包方案自己的模块产物（web 段缺省 = 纯后端方案，整段跳过）。
-		// 为何不是整树：web/dist/modules 里除本方案模块外还有脚手架模板模块（home/login/
+		// 为何不是整树：dist/web/modules 里除本方案模块外还有脚手架模板模块（home/login/
 		// personal-center/notification/system/oj-market…），而安装器 deployWeb 会把包内
 		// web/modules 整树覆盖进目标站 <dist>/modules——整树入包等于用开发机上的模板产物
 		// 覆盖目标站同名前端。方案包只该带自己那一份，模板模块属宿主面，不由方案分发。
 		if (m.web !== undefined) {
-			const webModules = path.join(projectRoot, "web/dist/modules");
+			const webModules = path.join(layout.distDir, "modules");
 			if (!fs.existsSync(webModules)) {
-				throw new Error("[ojm] 方案包构建失败：缺少站点构建产物 web/dist/modules（manifest 声明了 web 段；先运行 ojm build 生成模块产物）");
+				throw new Error(`[ojm] 方案包构建失败：缺少站点构建产物 ${path.relative(projectRoot, webModules)}（manifest 声明了 web 段；先运行 ojm build 生成模块产物）`);
 			}
 			const ownWeb = path.join(webModules, name);
 			if (!fs.existsSync(ownWeb)) {
-				throw new Error(`[ojm] 方案包构建失败：缺少本方案的站点产物 web/dist/modules/${name}/（方案包只入包方案自己的模块；请确认 web.config.ts 已登记 ${name} 且本次 ojm build 已产出）`);
+				throw new Error(`[ojm] 方案包构建失败：缺少本方案的站点产物 ${path.relative(projectRoot, ownWeb)}/（方案包只入包方案自己的模块；请确认 web.config.ts 已登记 ${name} 且本次 ojm build 已产出）`);
 			}
 			fs.mkdirSync(path.join(root, "web", "modules"), { recursive: true });
 			fs.cpSync(ownWeb, path.join(root, "web", "modules", name), { recursive: true });

package/src/cli.ts

@@ -0,0 +1,265 @@
+import type { CAC } from "cac";
+import type { HelpEntry, Lang } from "./usage";
+/**
+ * `ojm` 的 cac 接线：命令注册 + action 薄分发（解析 → 既有 handler）。
+ * 帮助文本（双语注册表）在 usage.ts；handler 真逻辑在各业务模块，本模块不掺业务。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import cac from "cac";
+import { findCommand, groupHelpText, HELP_GROUPS, resolveLang, topHelpSections, usageText } from "./usage";
+
+export interface CliDeps { exit?: (code: number) => never }
+
+/** `ojm help [cmd [sub]]` → `<cmd> [sub] --help`：词形归一，交给 cac 的 help 机制。 */
+export function rewriteHelpArgv(argv: string[]): string[] {
+	if (argv[0] !== "help")
+		return argv;
+	if (argv.length === 1)
+		return ["--help"];
+	return [...argv.slice(1), "--help"];
+}
+
+/**
+ * 未知命令兜底结果（index.ts 打印 + 退出用）。
+ * help 形态（ojm nope --help / ojm help nope）：报「未知命令」exit 1——打帮助退 0 会掩盖拼写错误。
+ */
+export function unknownCommandResult(cmd: string, lang: Lang, helpRequested: boolean): { text: string, code: number } {
+	if (helpRequested) {
+		return {
+			text: lang === "zh-CN"
+				? `[ojm] 未知命令：${cmd}（ojm --help 查看全部命令）`
+				: `[ojm] Unknown command: ${cmd} (run ojm --help for the full command list)`,
+			code: 1,
+		};
+	}
+	return { text: usageText(lang), code: 1 };
+}
+
+/** cac 的内置报错是英文裸消息（Unknown option）——按语言重写成人话，带修复指引。 */
+export function localizeCacError(error: unknown, lang: Lang): unknown {
+	if (!(error instanceof Error))
+		return error;
+	const m = /^Unknown option `([^`]+)`/.exec(error.message);
+	if (!m)
+		return error;
+	return new Error(lang === "zh-CN"
+		? `[ojm] 未知选项：${m[1]}（ojm <cmd> --help 查看可用选项）`
+		: `[ojm] Unknown option: ${m[1]} (run ojm <cmd> --help for available options)`);
+}
+
+/** 与旧 index.ts 顶层 catch 同源：message 已是人话，堆栈仅 OJM_DEBUG=1（兼容旧名 RAM_DEBUG）。 */
+export function reportCliError(error: unknown, exit: (code: number) => never): void {
+	const isDebug = !!(process.env.OJM_DEBUG ?? process.env.RAM_DEBUG);
+	const body = error instanceof Error ? (isDebug ? error.stack ?? error.message : error.message) : String(error);
+	console.error(/^\[ojm/.test(body) ? body : `[ojm] ${body}`);
+	exit(1);
+}
+
+interface SiteOpts { url?: string, user?: string, pass?: string }
+
+function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code: number) => never): (...args: any[]) => Promise<void> {
+	switch (def.key) {
+		case "init":
+			return async (dir?: string, opts: { yes?: boolean } = {}) => {
+				const { initProject } = await import("./init");
+				await initProject(dir ? path.resolve(dir) : projectRoot, { yes: !!opts.yes });
+			};
+		case "dev":
+			return async (port?: string) => {
+				const { devServer } = await import("./dev");
+				const portArg = Number(port);
+				await devServer(projectRoot, { port: Number.isFinite(portArg) && portArg > 0 ? portArg : 5174 });
+			};
+		case "build":
+			return async (opts: { bundle?: unknown, out?: string } = {}) => {
+				// mri 可选值：裸 --bundle 得到 ""，--bundle name / --bundle=name 得到字符串
+				const bundle = opts.bundle !== undefined;
+				const bundleName = typeof opts.bundle === "string" && opts.bundle !== "" ? opts.bundle : undefined;
+				if (bundle) {
+					const { buildBundle } = await import("./bundle");
+					const results = await buildBundle(projectRoot, { out: opts.out, name: bundleName });
+					if (results.length > 1)
+						console.log(`[ojm] 共打包 ${results.length} 份方案包（逐包签名：ojm sign dist/<name>-<version>.tgz --id <publisher>.<key> --check）`);
+					return;
+				}
+				const { buildBackend, buildModules } = await import("./build");
+				await buildBackend(projectRoot);
+				await buildModules(projectRoot, { mergeSite: true });
+			};
+		case "new":
+			return async (name: string | undefined, extra: string[] = [], opts: { layout?: string, api?: boolean } = {}) => {
+				if (!name) {
+					console.error("[ojm] 用法：ojm new <name> [--layout container|none] [--api]（非交互环境必须显式给 name）");
+					exit(1);
+					return;
+				}
+				// 统一审查 F8：多余位置参数显式拒绝，不能静默丢弃（ojm new crm erp 只建 crm 是事故）
+				if (extra.length > 0)
+					throw new Error(`[ojm] ojm new 只接受一个方案名（多余参数：${extra.join(" ")}）`);
+				if (opts.layout !== undefined && opts.layout !== "container" && opts.layout !== "none")
+					throw new Error(`[ojm] --layout 只接受 container | none（实际：${opts.layout}）`);
+				const { createSolution } = await import("./new");
+				const created = createSolution(projectRoot, name, { layout: opts.layout as "container" | "none" | undefined, api: !!opts.api });
+				console.log(`[ojm] 已生成方案骨架：${path.relative(process.cwd(), created.dir)}`);
+				for (const f of created.files)
+					console.log(`[ojm]   + ${f}`);
+				console.log(`[ojm] 下一步：pnpm dev 看效果 → ojm build && ojm build --bundle ${name} 打包`);
+			};
+		case "preview":
+			return async (port?: string) => {
+				const { runPreview } = await import("./preview");
+				const portArg = Number(port);
+				await runPreview(projectRoot, { port: Number.isInteger(portArg) && portArg > 0 ? portArg : undefined });
+			};
+		case "api":
+			return async (dir?: string, opts: { check?: boolean, docs?: boolean, exempt?: string } = {}) => {
+				// S5：显式目录必须先存在——否则静默在错的目录下生成/对账
+				if (dir && !fs.existsSync(path.resolve(dir)))
+					throw new Error(`[ojm-api] 项目目录不存在：${dir}`);
+				const apiRoot = dir ? path.resolve(dir) : projectRoot;
+				if (opts.docs) {
+					const { runApiDocs } = await import("./contract/run");
+					const out = await runApiDocs(apiRoot);
+					console.log(`[ojm-api] 文档站已生成：${path.relative(projectRoot, out)}（浏览器直接打开即可）`);
+					return;
+				}
+				if (opts.check) {
+					const { checkApi } = await import("./contract/check");
+					// --exempt <path>：相对路径按项目根解析；缺省按布局找 .ojm-api-exempt.json（工程根 → api/）
+					const { violations, hints } = await checkApi({ cwd: apiRoot, exempt: opts.exempt ? path.resolve(projectRoot, opts.exempt) : undefined });
+					for (const v of violations)
+						console[v.level === "error" ? "error" : "warn"](`${v.level === "error" ? "✗" : "⚠"} ${v.message}`);
+					for (const h of hints)
+						console.log(h);
+					if (violations.length === 0)
+						console.log("[ojm-api] --check 通过：生成物同步、route 双向对账、routes.js 均无 drift。");
+					const errors = violations.filter(v => v.level === "error").length;
+					console.log(`[ojm-api] --check 结果：${errors} error / ${violations.length - errors} warn`);
+					if (errors > 0)
+						exit(1);
+					return;
+				}
+				const { runApi } = await import("./contract/run");
+				const result = await runApi({ cwd: apiRoot });
+				console.log(`[ojm-api] 契约 ${result.contracts} 份；写入 ${result.written.length} 个文件，跳过（未变）${result.skipped.length} 个；stub 新建 ${result.stubs.created} / 更新 ${result.stubs.updated} / 跳过 ${result.stubs.skipped}`);
+				for (const p of result.written)
+					console.log(`  + ${path.relative(apiRoot, p)}`);
+			};
+		case "info":
+			return async (opts: { all?: boolean } = {}) => {
+				const { printInfo } = await import("./info");
+				await printInfo(projectRoot, undefined, { all: !!opts.all });
+			};
+		case "vendor":
+			return async (tag?: string, opts: { force?: boolean } = {}) => {
+				if (tag !== undefined && !/^v?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(tag))
+					throw new Error(`[ojm] 非法版本号：${tag}（形如 v0.1.11 或 0.1.11）`);
+				const { vendorCommand } = await import("./vendor");
+				await vendorCommand(projectRoot, { force: !!opts.force, tag: tag === undefined ? undefined : (tag.startsWith("v") ? tag : `v${tag}`) });
+			};
+		case "merge":
+			return async (out?: string, inputs: string[] = []) => {
+				const { mergeManifests } = await import("./info");
+				await mergeManifests(out ?? "", inputs);
+			};
+		case "keygen":
+			return async (opts: { id?: string, out?: string, yes?: boolean } = {}) => {
+				const { keygenCommand } = await import("./keygen");
+				keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
+			};
+		case "sign":
+			return async (file: string | undefined, opts: { id?: string, key?: string, check?: boolean } = {}) => {
+				const { signCommand } = await import("./sign");
+				signCommand(file ?? "", { id: opts.id, key: opts.key, check: opts.check });
+			};
+		case "publish":
+			return async (dir: string | undefined, opts: { id?: string, key?: string, check?: boolean } = {}) => {
+				const { publishCommand } = await import("./publish");
+				publishCommand(dir ?? "", { id: opts.id, key: opts.key, check: opts.check });
+			};
+		case "install":
+			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string } = {}) => {
+				const { installCommand } = await import("./install");
+				await installCommand(target ?? "", { url: opts.url, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version });
+			};
+		case "enable":
+		case "disable":
+			return async (name: string | undefined, opts: SiteOpts = {}) => {
+				const { setEnabledCommand } = await import("./enable");
+				await setEnabledCommand(name ?? "", def.key === "enable", { url: opts.url, user: opts.user, pass: opts.pass });
+			};
+		case "uninstall":
+			return async (name: string | undefined, opts: SiteOpts = {}) => {
+				const { uninstallCommand } = await import("./uninstall");
+				await uninstallCommand(name ?? "", { url: opts.url, user: opts.user, pass: opts.pass });
+			};
+		case "trust":
+			return async (sub: string | undefined, keyId: string | undefined, pub: string | undefined, opts: SiteOpts & { task?: string } = {}) => {
+				const { trustCommand } = await import("./trust");
+				await trustCommand(sub ?? "", [keyId, pub].filter((v): v is string => v !== undefined), { url: opts.url, user: opts.user, pass: opts.pass, task: opts.task });
+			};
+		case "market":
+			return async (sub: string | undefined) => {
+				if (!sub) {
+					// bare `ojm market`：打印该组帮助（子命令索引），同旧 marketUsage 语义
+					console.log(groupHelpText("market-cdn", lang));
+					return;
+				}
+				// market 子命令自带解析器（trial/walkthrough 等 flag 各异）：raw 转发 process.argv
+				const { marketCommand } = await import("./market/command");
+				await marketCommand(sub, process.argv.slice(4));
+			};
+		case "oj":
+			return async () => {
+				// 透传：参数原样转发（process.argv 未被 help 词形改写污染——真实调用才走到这里）
+				const { runOjSubcommand } = await import("./oj-cmd");
+				runOjSubcommand(projectRoot, def.name, process.argv.slice(3));
+			};
+		default:
+			throw new Error(`[ojm] 未接线的命令键：${def.key}`);
+	}
+}
+
+export function buildCli(projectRoot: string, lang: Lang = resolveLang(), deps: CliDeps = {}): CAC {
+	const exit = deps.exit ?? ((code: number) => process.exit(code) as never);
+	const cli = cac("ojm");
+	for (const group of HELP_GROUPS) {
+		for (const def of group.commands) {
+			const cmd = cli.command(def.name, lang === "zh-CN" ? def.zh : def.en);
+			for (const o of def.options ?? [])
+				cmd.option(o.raw, lang === "zh-CN" ? o.zh : o.en);
+			if (def.allowUnknownOptions)
+				cmd.allowUnknownOptions();
+			const action = makeAction(def, projectRoot, lang, exit);
+			cmd.action((...args: unknown[]) => {
+				Promise.resolve(action(...args)).catch((error: unknown) => reportCliError(error, exit));
+			});
+		}
+	}
+
+	// help 回调：顶层 = 分组 sections；单命令 = 本地化小节标题 + 详解/子命令详解注入
+	const SECTION_TITLES: Record<string, { zh: string, en: string }> = {
+		Usage: { zh: "用法", en: "Usage" },
+		Options: { zh: "选项", en: "Options" },
+		Examples: { zh: "示例", en: "Examples" },
+	};
+	cli.help((sections) => {
+		const matched = cli.matchedCommand;
+		if (!matched)
+			return topHelpSections(lang);
+		const def = findCommand(matched.rawName);
+		const out = sections.map((s) => {
+			const t = s.title && SECTION_TITLES[s.title];
+			return t ? { ...s, title: lang === "zh-CN" ? t.zh : t.en } : s;
+		});
+		if (def?.detail)
+			out.push({ title: lang === "zh-CN" ? "详细说明" : "Details", body: lang === "zh-CN" ? def.detail.zh : def.detail.en });
+		const sub = cli.args[0];
+		if (def?.subs && sub && def.subs[sub])
+			out.push({ title: `${sub}:`, body: lang === "zh-CN" ? def.subs[sub].zh : def.subs[sub].en });
+		return out;
+	});
+	return cli;
+}

package/src/contract/check.ts

@@ -18,7 +18,7 @@ import { findOpenapiJson, groupIrByModule } from "./run";
  * ① 生成物同步：内存重生成 vs 磁盘逐字节 diff（含 stub 待更新）
  * ② route 双向对账：AST 扫 oj api.ts（default 导出方法名 + 语句起始 `.route = "..."` 赋值）
  *    vs 契约路由表：未实现 warn / 未登记 error / 参数段不一致 error
- * ③ routes.js diff：release 路由表（oj build 产物，api/dist 下各模块的 routes.js）vs openapi.json
+ * ③ routes.js diff：release 路由表（oj build 产物，dist/api 下各模块的 routes.js）vs openapi.json
  *   契约路由表；无 dist 给提示不判违规
  *
  * 原则：check 永不修文件——修复动作永远由人执行（重跑 ojm api / 补 handler / oj build）。
@@ -360,8 +360,8 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 	// ④ WS 路由鉴权对账（oj 0.1.30 起握手过鉴权守卫）
 	violations.push(...checkWsAnonymous(roots, resolveConfigPath(opts.cwd)));
 
-	// ③ routes.js diff
-	const distDir = join(opts.cwd, "api/dist");
+	// ③ routes.js diff（release 路由表读 layout.apiDist；无布局工程回退同一约定 dist/api）
+	const distDir = tryResolveLayout(opts.cwd)?.apiDist ?? join(opts.cwd, "dist", "api");
 	const distRows: { method: string, pattern: string }[] = [];
 	if (existsSync(distDir)) {
 		for (const entry of readdirSync(distDir, { withFileTypes: true })) {
@@ -373,7 +373,7 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 		}
 	}
 	if (distRows.length === 0) {
-		hints.push("[ojm-api] 未发现 api/dist/**/routes.js——release 路由表对账跳过；发布前请先 oj build 再跑 ojm api --check。");
+		hints.push(`[ojm-api] 未发现 ${relative(opts.cwd, distDir)}/**/routes.js——release 路由表对账跳过；发布前请先 oj build 再跑 ojm api --check。`);
 	}
 	else {
 		// 尾斜杠规范化：契约侧 fullPath 对「模块根路径」带尾斜杠（stripBase 的

package/src/dev.ts

@@ -35,6 +35,7 @@ import { loadProjectMocks, mockStatusCode } from "./dev-mock";
 import { createReloadHub, proxyApi, proxyWsUpgrade, sseScript } from "./dev-proxy";
 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";
@@ -123,6 +124,16 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 
 	const hub = createReloadHub();
 
+	// /cdn 反代（feature：market_cdn_url 可为相对路径 = 本站点自供）：config 有 /cdn 挂载
+	// 才反代到 oj；无挂载（旧模板/手改工程）或纯前端形态 → 回落静态，行为不变
+	let cdnPrefix: string | null = null;
+	try {
+		cdnPrefix = resolveCdnLayout(projectRoot).prefix;
+	}
+	catch {
+		cdnPrefix = null;
+	}
+
 	// 3) 静态半边（dev：模块产物优先，shell dist 兜底；no-store；注入刷新通道）
 	// hostRoots 钉死 shell dist：ojm build 的合并残留不得反向遮蔽宿主（F11）
 	// transform 来自 web.config.ts（可选）：按路由改写 title/OG，先于 reload 注入
@@ -175,6 +186,12 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 			return;
 		}
 
+		// 相对基址 CDN（/cdn）：站点自供挂载直发 oj（不剥前缀），否则静态层会回落成 index.html
+		if (cdnPrefix !== null && ojTarget !== undefined && (urlPath === cdnPrefix || urlPath.startsWith(`${cdnPrefix}/`))) {
+			void proxyApi(ojTarget)(req, res);
+			return;
+		}
+
 		serveStatic(req, res);
 	});