@oj-module/cli 0.2.20 → 0.2.25

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.20",
-  "@oj-module/runtime/contract": "0.2.20",
-  "@oj-module/runtime/contract/errors": "0.2.20",
+  "@oj-module/runtime": "0.2.25",
+  "@oj-module/runtime/contract": "0.2.25",
+  "@oj-module/runtime/contract/errors": "0.2.25",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

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

@@ -1,7 +1,7 @@
 // buildBackend spec：宿主 versions.json 双落点（方案安装的 C2-09 前置）。
 //
-// 安装器按 B-11 布局读 `<api>/dist/versions.json`（与 manifests.yaml 同层）做 peerRuntime
-// 强制比对；而站点壳的 versions.json 落在 web/dist。两者不同源时，新工程 `ojm build`
+// 安装器按 B-11 布局读 `dist/api/versions.json`（与 manifests.yaml 同层）做 peerRuntime
+// 强制比对；而站点壳的 versions.json 落在 dist/web。两者不同源时，新工程 `ojm build`
 // 完仍会在 preflight 被 C2-09 拒装——这条用例钉住「同源双写」，防止回归。
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -27,19 +27,19 @@ function newProject(): string {
 	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");
+	mkdirSync(join(root, "dist", "api"), { recursive: true });
+	writeFileSync(join(root, "dist", "api", "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 () => {
+	it("then dist/api/versions.json 与 shell-dist 同源落地（安装器 C2-09 前置）", async () => {
 		const root = newProject();
 
 		await buildBackend(root);
 
-		const hostVersions = join(root, "api", "dist", "versions.json");
+		const hostVersions = join(root, "dist", "api", "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");
@@ -50,16 +50,16 @@ describe("given 宿主工程有 api/src When ojm build 后端", () => {
 
 		await buildBackend(root);
 
-		expect(readFileSync(join(root, "api", "dist", "manifests.yaml"), "utf-8")).toBe("demo: 0.1.0\n");
+		expect(readFileSync(join(root, "dist", "api", "manifests.yaml"), "utf-8")).toBe("demo: 0.1.0\n");
 	});
 });
 
 describe("given 纯前端工程（无 api/src）When ojm build 后端", () => {
-	it("then 跳过构建、不产出 api/dist", async () => {
+	it("then 跳过构建、不产出 dist/api", async () => {
 		const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-fe-"));
 
 		expect(await buildBackend(root)).toBe(false);
-		expect(existsSync(join(root, "api", "dist"))).toBe(false);
+		expect(existsSync(join(root, "dist", "api"))).toBe(false);
 	});
 });
 
@@ -93,7 +93,7 @@ function newModuleRootProject(): string {
 }
 
 describe("given module-root 布局 When ojm build 后端", () => {
-	it("then 一次调用、单一输出根：--module-root src + -o api/dist（与 -d 互斥）", async () => {
+	it("then 一次调用、单一输出根：--module-root src + -o dist/api（与 -d 互斥）", async () => {
 		const root = newModuleRootProject();
 		fakeOjRecording(root, true);
 
@@ -102,9 +102,9 @@ describe("given module-root 布局 When ojm build 后端", () => {
 		// 逐模块 `-o <tmp>` 会让每个 tmp 各写一份 manifests.yaml，锁与兄弟目录关系全丢
 		const invoked = readFileSync(join(root, "bin", "invoked"), "utf-8").trim();
 		expect(invoked).toBe(
-			`build -c ${join(root, "config.yaml")} --module-root ${join(root, "src")} -o ${join(root, "api", "dist")} --no-minify`,
+			`build -c ${join(root, "config.yaml")} --module-root ${join(root, "src")} -o ${join(root, "dist", "api")} --no-minify`,
 		);
-		expect(existsSync(join(root, "api", "dist", "versions.json"))).toBe(true);
+		expect(existsSync(join(root, "dist", "api", "versions.json"))).toBe(true);
 	});
 
 	it("then oj 缺 --module-root 能力时 fail-fast，不落任何产物", async () => {
@@ -113,6 +113,6 @@ describe("given module-root 布局 When ojm build 后端", () => {
 
 		await expect(buildBackend(root)).rejects.toThrow(/不支持 --module-root/);
 		expect(existsSync(join(root, "bin", "invoked"))).toBe(false); // 没跑 oj build
-		expect(existsSync(join(root, "api", "dist"))).toBe(false);
+		expect(existsSync(join(root, "dist", "api"))).toBe(false);
 	});
 });

package/src/__tests__/cli.test.ts

@@ -0,0 +1,225 @@
+import type { Lang } from "../usage";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildCli, rewriteHelpArgv } from "../cli";
+
+/**
+ * dispatch 契约（cac 驱动后）：
+ *  - 帮助请求不执行 action（market setup --help 不建 CDN）
+ *  - 未知命令触发 command:*（index.ts 兜底打帮助 + exit 1）
+ *  - 校验从 parse*Args 搬入 action 后行为保持（new --layout / vendor tag）
+ *  - 位置参数与 variadic 映射（merge out in1 in2）
+ *  - --bundle 值映射到 buildBundle
+ *  - help 词形重写（ojm help <cmd> → <cmd> --help）
+ */
+
+const logs: string[] = [];
+let exitSpy: ReturnType<typeof vi.fn>;
+
+// 提升式 mock：vitest 测试体内注册的 vi.mock 拦不到 cli.ts 的 dynamic import，须 hoisted 顶层注册
+const buildBundleMock = vi.hoisted(() => vi.fn(async () => [{ file: "x.tgz" }]));
+vi.mock("../bundle", () => ({ buildBundle: buildBundleMock }));
+const vendorCommandMock = vi.hoisted(() => vi.fn(async () => {}));
+vi.mock("../vendor", () => ({ vendorCommand: vendorCommandMock }));
+
+beforeEach(() => {
+	logs.length = 0;
+	exitSpy = vi.fn();
+	vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => logs.push(args.join(" ")));
+	vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => logs.push(args.join(" ")));
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+	buildBundleMock.mockClear();
+	vendorCommandMock.mockClear();
+});
+
+interface RunResult { out: string, unknown: string[], exitCode: number | undefined }
+
+/** 跑一次 parse：捕获输出、command:* 与 exit；动作异步链经条件轮询拍平（vitest 下 dynamic import 解析需数百毫秒） */
+async function run(argv: string[], lang: Lang, cwd: string, until?: () => boolean): Promise<RunResult> {
+	const cli = buildCli(cwd, lang, { exit: exitSpy as unknown as (code: number) => never });
+	const unknown: string[] = [];
+	cli.on("command:*", () => unknown.push(String(cli.args[0])));
+	cli.parse(["node", "ojm", ...argv], { run: true });
+	try {
+		await vi.waitUntil(() => logs.length > 0 || exitSpy.mock.calls.length > 0 || unknown.length > 0 || !!until?.(), { timeout: 2500, interval: 10 });
+	}
+	catch {
+		// 无输出型动作（如帮助打屏后无日志）：兜底继续
+	}
+	await new Promise(r => setTimeout(r, 50));
+	return { out: logs.join("\n"), unknown, exitCode: exitSpy.mock.calls[0]?.[0] as number | undefined };
+}
+
+let tmp: string;
+beforeEach(() => {
+	tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ojm-cli-test-"));
+});
+
+describe("帮助不执行 action", () => {
+	it("子命令 --help 只出单命令帮助（不叠顶层分组帮助）", async () => {
+		// 回归：cac --help 后 unsetMatchedCommand 会让 args[0]=子命令，误叠顶层帮助（index.ts 已按 options.help 过滤）
+		const r = await run(["market", "verify", "--help"], "zh-CN", tmp);
+		expect(r.out).toContain("离线验包");
+		expect(r.out).not.toContain("oj 子命令透传");
+	});
+
+	it("market setup --help 打帮助、不触发 setup、不 exit", async () => {
+		const r = await run(["market", "setup", "--help"], "zh-CN", tmp);
+		expect(r.out).toContain("market");
+		expect(r.out).not.toContain("[ojm] 站点");
+		expect(r.exitCode).toBeUndefined();
+		expect(exitSpy).not.toHaveBeenCalled();
+	});
+});
+
+describe("单命令帮助（双语）", () => {
+	it("build --help 中文：语法 + 选项 + 详解", async () => {
+		const r = await run(["build", "--help"], "zh-CN", tmp);
+		expect(r.out).toContain("ojm build");
+		expect(r.out).toContain("--bundle");
+		expect(r.out).toContain("构建后端");
+	});
+
+	it("build --help 英文", async () => {
+		const r = await run(["build", "--help"], "en-US", tmp);
+		expect(r.out).toContain("Builds the backend");
+	});
+
+	it("market verify --help 按子命令注入详解（中/英）", async () => {
+		expect((await run(["market", "verify", "--help"], "zh-CN", tmp)).out).toContain("离线验包");
+		expect((await run(["market", "verify", "--help"], "en-US", tmp)).out).toMatch(/offline/i);
+	});
+
+	it("trust add --help 按子命令注入详解（中/英）", async () => {
+		expect((await run(["trust", "add", "--help"], "zh-CN", tmp)).out).toContain("新增信任");
+		expect((await run(["trust", "add", "--help"], "en-US", tmp)).out).toContain("64-hex public key");
+	});
+});
+
+describe("未知命令与兜底", () => {
+	it("未知命令触发 command:*", async () => {
+		const r = await run(["nope"], "zh-CN", tmp);
+		expect(r.unknown).toEqual(["nope"]);
+	});
+});
+
+describe("反常识行为修正（20261023-0937）", () => {
+	it("isKnownCommand：已知命令 true / 未知 false", async () => {
+		const { isKnownCommand } = await import("../usage");
+		expect(isKnownCommand("market")).toBe(true);
+		expect(isKnownCommand("trust")).toBe(true);
+		expect(isKnownCommand("nope")).toBe(false);
+	});
+
+	it("unknownCommandResult：help 形态报未知命令（双语），code 1", async () => {
+		const { unknownCommandResult } = await import("../cli");
+		const zh = unknownCommandResult("nope", "zh-CN", true);
+		expect(zh.text).toContain("[ojm] 未知命令：nope");
+		expect(zh.code).toBe(1);
+		const en = unknownCommandResult("nope", "en-US", true);
+		expect(en.text).toContain("[ojm] Unknown command: nope");
+		expect(en.code).toBe(1);
+	});
+
+	it("unknownCommandResult：非 help 形态给顶层帮助，code 1", async () => {
+		const { unknownCommandResult } = await import("../cli");
+		const { usageText } = await import("../usage");
+		const r = unknownCommandResult("nope", "zh-CN", false);
+		expect(r.text).toBe(usageText("zh-CN"));
+		expect(r.code).toBe(1);
+	});
+
+	it("localizeCacError：未知选项本地化（双语）+ 指引", async () => {
+		const { localizeCacError } = await import("../cli");
+		const zh = localizeCacError(new Error("Unknown option `--foo`"), "zh-CN");
+		expect(zh).toBeInstanceOf(Error);
+		expect((zh as Error).message).toContain("未知选项：--foo");
+		expect((zh as Error).message).toContain("--help");
+		const en = localizeCacError(new Error("Unknown option `--foo`"), "en-US");
+		expect((en as Error).message).toContain("Unknown option: --foo");
+	});
+
+	it("localizeCacError：非匹配错误原样返回（同一实例）", async () => {
+		const { localizeCacError } = await import("../cli");
+		const err = new Error("[ojm] 别的错误");
+		expect(localizeCacError(err, "zh-CN")).toBe(err);
+	});
+});
+
+describe("校验搬入 action 后行为保持", () => {
+	it("new 多余位置参数显式拒绝（F8）", async () => {
+		const r = await run(["new", "crm", "erp"], "zh-CN", tmp);
+		expect(r.out).toContain("只接受一个方案名");
+		expect(r.exitCode).toBe(1);
+	});
+
+	it("new --layout 非 container|none 报错", async () => {
+		const r = await run(["new", "demo", "--layout", "bogus"], "zh-CN", tmp);
+		expect(r.out).toContain("--layout 只接受 container | none");
+		expect(r.exitCode).toBe(1);
+	});
+
+	it("new 缺 name 打印用法并 exit 1", async () => {
+		const r = await run(["new"], "zh-CN", tmp);
+		expect(r.out).toContain("ojm new <name>");
+		expect(r.exitCode).toBe(1);
+	});
+
+	it("vendor 非法 tag 报错", async () => {
+		const r = await run(["vendor", "notatag"], "zh-CN", tmp);
+		expect(r.out).toContain("非法版本号");
+		expect(r.exitCode).toBe(1);
+	});
+
+	it("vendor 0.1.12 规范化补 v 前缀后传入 vendorCommand", async () => {
+		await run(["vendor", "0.1.12"], "zh-CN", tmp, () => vendorCommandMock.mock.calls.length > 0);
+		expect(vendorCommandMock).toHaveBeenCalledWith(tmp, { force: false, tag: "v0.1.12" });
+	});
+
+	it("vendor --force 透传 force", async () => {
+		await run(["vendor", "v0.1.12", "--force"], "zh-CN", tmp, () => vendorCommandMock.mock.calls.length > 0);
+		expect(vendorCommandMock).toHaveBeenCalledWith(tmp, { force: true, tag: "v0.1.12" });
+	});
+});
+
+describe("参数映射", () => {
+	it("merge <out> <inputs...> variadic 映射（缺文件报错提及输入名）", async () => {
+		const r = await run(["merge", "out.json", "in1.json", "in2.json"], "zh-CN", tmp);
+		expect(r.out).toContain("in1.json");
+		expect(r.exitCode).toBe(1);
+	});
+
+	it("build --bundle demo 映射 bundleName", async () => {
+		const r = await run(["build", "--bundle", "demo"], "zh-CN", tmp, () => buildBundleMock.mock.calls.length > 0);
+		expect(buildBundleMock).toHaveBeenCalledWith(tmp, { out: undefined, name: "demo" });
+		expect(r.exitCode).toBeUndefined();
+	});
+
+	it("build 裸 --bundle 无名称（全部用户方案）", async () => {
+		await run(["build", "--bundle"], "zh-CN", tmp, () => buildBundleMock.mock.calls.length > 0);
+		expect(buildBundleMock).toHaveBeenCalledWith(tmp, { out: undefined, name: undefined });
+	});
+});
+
+describe("help 词形", () => {
+	it("ojm help build → build --help", () => {
+		expect(rewriteHelpArgv(["help", "build"])).toEqual(["build", "--help"]);
+	});
+
+	it("ojm help trust add → trust add --help", () => {
+		expect(rewriteHelpArgv(["help", "trust", "add"])).toEqual(["trust", "add", "--help"]);
+	});
+
+	it("ojm help → 顶层 --help", () => {
+		expect(rewriteHelpArgv(["help"])).toEqual(["--help"]);
+	});
+
+	it("非 help 调用不改动", () => {
+		expect(rewriteHelpArgv(["build", "--bundle"])).toEqual(["build", "--bundle"]);
+	});
+});

package/src/__tests__/init-packagejson.test.ts

@@ -0,0 +1,29 @@
+// BDD：脚手架 package.json scripts 与模板的双写守卫（T3，发布工程师评审建议）。
+// 生成器（init.ts generatePackageJson）与模板（templates/package.json）各写一份 scripts，
+// 人肉同步必漂移（实证：typecheck:api 曾漏发生成器）——钉成测试：生成 scripts 的每个键
+// 都必须存在于模板 scripts（值一致），新增 script 先改模板再改生成器。
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { generatePackageJson } from "../init";
+
+const cliRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+describe("脚手架 package.json scripts 双写守卫（T3）", () => {
+	it("生成 scripts 的每个键都存在于模板且值一致", () => {
+		const template = JSON.parse(readFileSync(join(cliRoot, "templates/package.json"), "utf-8"));
+		const generated = generatePackageJson(cliRoot, "guard-check");
+		for (const [key, value] of Object.entries(generated.scripts)) {
+			expect(template.scripts[key], `生成器有而模板无的 script：${key}（先改 templates/package.json）`)
+				.toBe(value);
+		}
+	});
+
+	it("多方案 scripts 齐备：new / bundle / typecheck:api", () => {
+		const generated = generatePackageJson(cliRoot, "guard-check");
+		expect(generated.scripts.new).toBe("ojm new");
+		expect(generated.scripts.bundle).toBe("ojm build --bundle");
+		expect(generated.scripts["typecheck:api"]).toBe("tsc --noEmit -p src/tsconfig.json");
+	});
+});

package/src/__tests__/layout.test.ts

@@ -43,16 +43,16 @@ describe("resolveLayout / module-root", () => {
 
 		expect(layout.kind).toBe("module-root");
 		expect(layout.modulesSrc).toBe(join(root, "src"));
-		expect(layout.distDir).toBe(join(root, "web", "dist"));
-		expect(layout.apiDist).toBe(join(root, "api", "dist"));
+		expect(layout.distDir).toBe(join(root, "dist", "web"));
+		expect(layout.apiDist).toBe(join(root, "dist", "api"));
 		expect(layout.watchTarget).toBe(join(root, "src"));
 		// --module-root 取「源码树根目录」（oj 在其子树内递归找 manifest.yaml）
 		expect(layout.moduleRoot).toBe(join(root, "src"));
 	});
 
-	it("web/dist 存在不会被误判成 flat 布局", () => {
+	it("dist/web 存在不会被误判成 flat 布局（历史产物目录不算源码）", () => {
 		const root = newModuleRootProject();
-		mkdirSync(join(root, "web", "dist", "modules", "wiki", "0.1.0"), { recursive: true });
+		mkdirSync(join(root, "dist", "web", "modules", "wiki", "0.1.0"), { recursive: true });
 		expect(resolveLayout(root).kind).toBe("module-root");
 	});
 
@@ -102,11 +102,13 @@ describe("resolveLayout / 历史布局", () => {
 		expect(layout.kind).toBe("new");
 		expect(layout.modulesSrc).toBe(join(root, "web", "src"));
 		expect(layout.moduleRoot).toBeUndefined();
+		expect(layout.distDir).toBe(join(root, "dist", "web"));
+		expect(layout.apiDist).toBe(join(root, "dist", "api"));
 		expect(apiSrcOf(layout, "wiki")).toBe(join(root, "api", "src", "wiki"));
 		expect(webSrcOf(layout, "wiki")).toBe(join(root, "web", "src", "wiki"));
 	});
 
-	it("web/<name>/entry.ts 识别为 flat，产物落 build/", () => {
+	it("web/<name>/entry.ts 识别为 flat，web 产物落 build/（框架根仓约定不变），api 产物归 dist/api", () => {
 		const root = newRoot();
 		writeFile(root, "web/home/entry.ts", "export default {};\n");
 		writeFile(root, "web/home/__client/api.ts", "export {};\n");
@@ -115,6 +117,7 @@ describe("resolveLayout / 历史布局", () => {
 		expect(layout.kind).toBe("flat");
 		expect(layout.modulesSrc).toBe(join(root, "web"));
 		expect(layout.distDir).toBe(join(root, "build"));
+		expect(layout.apiDist).toBe(join(root, "dist", "api"));
 		expect(webSrcOf(layout, "home")).toBe(join(root, "web", "home"));
 	});
 

package/src/__tests__/new-scaffold.test.ts

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createSolution } from "../new";
+
+/**
+ * ojm new 骨架内容契约（20261023-1144 计划）。
+ * 背景：--api 骨架曾只产出裸命名导出 `export async function ping()`，
+ * oj 内省只读 default export 且链尾须为 HTTP 动词 → 打包后 routes.js 恒空、
+ * 装后探活 /api/<name>/ping 必然 404。骨架必须「生成即可路由」。
+ */
+
+const tmpRoots: string[] = [];
+
+function projectRoot(): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), "ojm-new-scaffold-"));
+	tmpRoots.push(root);
+	// createSolution 的 N0 工程判定：web.config.ts 与 src/ 至少一个
+	fs.mkdirSync(path.join(root, "src"), { recursive: true });
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tmpRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+});
+
+describe("ojm new --api 骨架可路由（BDD）", () => {
+	it("给定 createSolution(api: true)，生成的 api.ts 是 default-export 嵌套组形状", () => {
+		const root = projectRoot();
+		const result = createSolution(root, "crm", { api: true, layout: "none" });
+		const apiTs = fs.readFileSync(path.join(result.dir, "api", "api.ts"), "utf8");
+
+		// Then：default export 承载路由组（oj 内省只读 default export）
+		expect(apiTs).toContain("export default { ping }");
+		// Then：链尾是 HTTP 动词 get（METHODS 白名单），组名 ping → GET /api/crm/ping
+		expect(apiTs).toMatch(/const ping = \{[\s\S]*async get\(\)/);
+		// Then：落实注释承诺——出参挂平级 .response（pong: boolean）
+		expect(apiTs).toContain("ping.get.response");
+		expect(apiTs).toContain("pong");
+		// Then：不再有「裸命名导出而无 default export」的旧形状
+		expect(apiTs).not.toMatch(/^export async function ping/m);
+	});
+
+	it("给定 createSolution(api: true)，solution.yaml 过自家 market verify 五必填（20261023-1155）", async () => {
+		const root = projectRoot();
+		const result = createSolution(root, "crm", { api: true, layout: "none" });
+		const { parse: yamlParse } = await import("yaml");
+		const doc = yamlParse(fs.readFileSync(path.join(result.dir, "solution.yaml"), "utf8")) as Record<string, unknown>;
+
+		// Then：market/verify.ts structureCheck 五必填 name/version/summary/peerRuntime/archive 齐备
+		for (const key of ["name", "version", "summary", "peerRuntime", "archive"])
+			expect(doc[key], `solution.yaml 缺 ${key}（market verify 必填）`).toBeDefined();
+		expect((doc.archive as Record<string, unknown>).file).toBe("crm-0.1.0.tgz");
+	});
+});

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
  *