@oj-module/cli 0.2.23 → 0.2.26

package/devkit/manual.md

@@ -1764,20 +1764,22 @@ module-root 下数据源是「扫描 + `web.config.ts` 登记」并集（未登
 ### 10.3 本地市场链路：`ojm market` 子命令
 
 `market` 是一组**本地模拟 CDN + 市场链路**工具，专供作者在本机验证「方案包能不能发、能不能装」，
-**不触碰真实生产 CDN**。所有产物落在工程根 `cdn/`（由 `config.yaml` 的 `/cdn` 挂载直出），
-首跑用 `market setup` 把系统设置 `framework.market_cdn_url` 指过去即可在本地市场页看到。
+**不触碰真实生产 CDN**。所有产物落在工程根 `cdn/`（由 `config.yaml` 的 `/cdn` 挂载直出）。
+**脚手架 seed 的 `framework.market_cdn_url` 缺省即相对路径 `/cdn`（本站点自供），起站即市场可用，
+无需 setup**；只有指向外部真 CDN 时才需要 `market setup` 改写设置。
 
-> 跑任何子命令前先 `ojm market setup` 一次（把模拟 CDN 地址写进站点配置）。
+> `market setup` 已非必需（见上）；它只剩「指向外部真 CDN」一个场景。
 > 想看「这个包到底能不能装」而不污染工程，用 `ojm market trial`（一次性隔离站点，跑完即毁）。
 > 每个子命令都能 `ojm market <sub> --help` 单独看帮助。
 
 | 子命令 | 一句话 |
 |---|---|
-| `ojm market setup [--url <站点>] [--user <u> --pass <p>] [--new-pass <p>]` | 把 `framework.market_cdn_url` 指向本地 `cdn/`；首跑若账号处于首次改密期会先自动改密再写入 |
+| `ojm market setup [--url <站点>] [--user <u> --pass <p>] [--new-pass <p>]` | **外部真 CDN 场景才需要**：把 `framework.market_cdn_url` 改写为绝对地址；账号须 **superadmin**（该设置安全组仅 superadmin 可写，admin 角色会被 403）；首跑若账号处于首次改密期会先自动改密再写入 |
 | `ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]` | 把方案包落进 `cdn/` 并做包级 detached 签名；**不碰索引**（索引由 `build-index` 重建，避免多人发布互相覆盖） |
 | `ojm market build-index [--id <key>] [--key <pem>] [--check]` | 扫描 `cdn/*.tgz`、提取包内 manifest，全量重建 `bundles.yaml` + `manifests.yaml` 并签名；结果只取决于目录内容，连续执行字节一致 |
 | `ojm market verify [--file <tgz>] [--rebuild-index]` | 离线验包（不起站点、不装、不要凭据）：sha256 完整性 / 包级 Ed25519 验签 / 索引验签 / manifest 结构分列输出；`--rebuild-index` 额外比对重建索引与盘上索引的漂移 |
 | `ojm market trial [--fixture <name>@<version>] [--keep]` | 在一次性隔离站点里跑完整安装，跑完即毁；`--keep` 保留现场供排查 |
+| `ojm market walkthrough [--fixture <name>@<version>] [--only <op>] [--keep] [--strict]` | 隔离站点上 14 项全套自检（主链 9：index/install/reinstall/enable/verify/history/upgrade/rollback/uninstall；负向 5：tamper/nosig/badindex/stranger/evil——预期失败口径，防线没拦住才算 FAIL）；AC 表 + 失败文案脱敏落盘 `logs/walkthrough-<ts>.md`；`--only` 单跑验原子性 |
 
 - `--fixture <name>@<version>`：用内置合成包（无需先 build）；`--real <方案工程>`：先 `ojm build --bundle` 再拿真实产物。
 - `--id <key>` / `--key <pem>`：包级签名身份（与 `ojm sign` 同体系，默认取 `~/.ojm/keys`）。
@@ -1936,7 +1938,7 @@ ojm keygen --id <publisher>.<key-name>
 ojm sign dist/<name>-<version>.tgz --id <publisher>.<key-name> --check
 
 # ③ 安装/分发：.sig 自动探测随包上传
-ojm install dist/<name>-<version>.tgz --url <站点> --user admin --pass …
+ojm install dist/<name>-<version>.tgz --url <站点> --user superadmin --pass …
 ```
 
 宿主验签六码（失败文案双语，`--locale` 切换）：`sig_missing`（缺签）/ `sig_alg`（算法

package/devkit/module-dev-and-cdn-playground.md

@@ -68,15 +68,15 @@
 
 模板自带一个**本地模拟 CDN**（工程根 `cdn/` + 工程根 `config.yaml` 里的 `/cdn` 挂载），配上 `ojm market` 四条命令，就能在本地复刻「发包 → 上架 → 索引 → 安装」全链路。不需要外部服务。
 
-### 4.1 全流程（五步）
+### 4.1 全流程（五步，step 1 已省）
 
 ```bash
-# 0) 起站点（dev 或 serve 均可；市场地址必须指向 oj 子进程的端口，见 §5.1）
+# 0) 起站点（dev 或 serve 均可）
 ojm dev
 
-# 1) 打开市场地址：把 framework.market_cdn_url 指向 http://127.0.0.1:9778/cdn
-#    站点管理员首次登录处于改密悬挂期时会自动改密换全权 token
-ojm market setup --user admin --pass 123456 --new-pass <你的口令>
+# 1) 【免 setup】脚手架 seed 的 framework.market_cdn_url 缺省即 /cdn（本站点自供，
+#    dev 形态 ojm 已把 /cdn 反代给 oj 子进程）。只有指向外部真 CDN 时才需要：
+#    ojm market setup --user superadmin --pass 123456 --new-pass <你的口令>
 
 # 2) 发包：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz → 包级签名
 #    --rebuild-index 顺带重建索引
@@ -93,7 +93,7 @@ ojm market verify --rebuild-index
 
 | 命令 | 做什么 | **不**做什么 |
 |---|---|---|
-| `market setup` | 写系统设置 `framework.market_cdn_url` | 不改写工程根 `config.yaml`（`/cdn` 挂载由模板自带） |
+| `market setup` | 写系统设置 `framework.market_cdn_url`（**外部真 CDN 场景才需要**；脚手架缺省 /cdn 免 setup） | 不改写工程根 `config.yaml`（`/cdn` 挂载由模板自带） |
 | `market publish` | 落 `<name>-<version>.tgz` + 包级 `.tgz.sig` | **不碰索引**（索引是共享单文件，多人发布会互相覆盖） |
 | `market build-index` | 扫 `cdn/*.tgz` 提取包内 manifest，全量重建两份索引并签名 | 不落包 |
 | `market verify` | 完整性 / 包级签 / 索引签 / manifest 结构四类校验 + 漂移检出 | 不起站点、不装、不访问任何远端 |
@@ -111,9 +111,9 @@ ojm market verify --rebuild-index
 
 ## 5. 两个已经踩过的坑（别再踩）
 
-### 5.1 dev 形态下，`/cdn` 不在 dev server 上
+### 5.1 dev 形态下，`/cdn` 由 oj 子进程直出（ojm 已代为反代）
 
-`ojm dev` 的 Node 服务在 **5174**，只把 `/api` 反代给 oj 子进程；`/cdn` 是 **oj 的挂载**，只在 oj 子进程（`config.yaml` 的 `server.port`，默认 9778）上成立。所以市场地址**必须写绝对 URL** 且端口取自 config——写成相对 `/cdn` 的话，dev 下取到的是 index.html，报出来是难懂的 YAML 解析错，不是干净 404。`market setup` 已按 config 推导，别手改。
+`ojm dev` 的 Node 服务在 **5174**，把 `/api` 与 `/cdn`（config 有 `/cdn` 挂载时）一并反代给 oj 子进程；`/cdn` 是 **oj 的挂载**，直出工程根 `cdn/`。`framework.market_cdn_url` 写成相对路径 `/cdn`（seed 缺省值）时，服务端按**请求源**补全同源绝对 URL 再拉取——dev 下请求走 5174，反代链路内透传，拿到的是真索引。2026-10-23 之前 dev 只反代 `/api`，相对基址会拿到静态层回落的 index.html（难懂的 YAML 解析错）——该坑已由 dev 反代 + 消费侧 `withSiteOrigin` 补全闭环。历史上下文：`market setup` 写绝对地址（`http://<host>:<config server.port>/cdn`）依旧兼容可用。
 
 ### 5.2 CDN 里摆了 `.tgz.sig` 侧车，不等于能装
 
@@ -165,7 +165,7 @@ node "$CLI_PKG/bin/ojm.mjs" market verify --rebuild-index
 node "$CLI_PKG/bin/ojm.mjs" build                 # 生成 api/dist + web/dist（含 api/dist/versions.json）
 # config：platform.root 改成 api/dist（安装目标恒为 release 部署，root 必须与 --api-path 同源）
 (bin/oj serve -c config.yaml -b /api --api-path api/dist --console-log &)
-node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user admin --pass 123456 --new-pass <新口令>
+node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user superadmin --pass 123456 --new-pass <新口令>
 # 市场页点安装 → 首次停在「待信任」→ 核对指纹 → ojm trust confirm --task <id> → 重试 → done
 ```
 
@@ -174,7 +174,7 @@ node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user admi
 | # | 现象 | 根因 / 正确做法 |
 |---|---|---|
 | ① | `oj build` 报 `tables 声明 "x" 不在 schema.yaml` | oj 用 `schema.yaml` 做表结构真源，`manifest.tables` 只是引用面；补 `schema.yaml`（`tables: {<t>: {pk, columns}}`），与迁移语句对齐 |
-| ② | `oj build` 成功但 `routes.js` 是空表、dist 里没有 handler | **只编译 `.ts` handler**；写成 `ping/api.js` 会被静默丢弃 → 改 `api.ts` |
+| ② | `oj build` 成功但 `routes.js` 是空表、dist 里没有 handler | **只编译 `.ts` handler**；写成 `ping/api.js` 会被静默丢弃 → 改 `api.ts`。另一同形坑（构建也零报错）：`api.ts` 写成裸具名导出（`export async function ping`）——oj 内省只读 **default export** 且链尾动词须在 METHODS 白名单（get/post/put/del/patch/head/options），裸导出的函数根本不在表里 → 改成 `const ping = { async get() {...} }; export default { ping }`（`ojm new --api` 骨架即此形状） |
 | ③ | `build --bundle` 报 `缺少 src/<name>/web/locales/…`（历史布局是 `web/src/<name>/locales/…`） | manifest 一旦引用 `title_key`/`label_key` 就必须双语 locale（后端方案也要）；且 key 必须**嵌套** `{"menu":{"main":"…"}}`，平铺 `"menu.main"` 查不到 |
 | ④ | 安装 POST 返回 200，但 `market/task` 恒 404 | 宿主 config 缺 `fs:` 段 → 安装器落盘被 jail 拒、失败发生在任务文件写入前；0.2.13 起模板自带，旧工程手补 |
 | ⑤ | 安装卡 `preflight`：`无法读取宿主 runtime 版本` | 安装器读 `api/dist/versions.json`；0.2.13 起 `ojm build` 双落点（旧版手抄 `web/dist/versions.json`） |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.23",
-  "description": "React Antd Admin 模块工程命令行工具（含预构建宿主 shell-dist）",
+  "version": "0.2.26",
+  "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
     ".": {
@@ -49,9 +49,10 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.23",
+    "@oj-module/runtime": "0.2.26",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
+    "cac": "^6.7.14",
     "esbuild": "^0.28.2",
     "tailwindcss": "^4.3.0",
     "tsx": "^4.23.12",
@@ -97,7 +98,6 @@
     "zustand": "^5.0.13"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "scripts": {

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.23",
+			"version": "0.2.26",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-22 18:50:31"
+		"lastBuildTime": "2026-10-23 21:49:09"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -6961,8 +6961,7 @@ function LayoutTabbar() {
 		location,
 		currentRoute,
 		setActiveKey,
-		addTab,
-		activeKey
+		addTab
 	]);
 	return /* @__PURE__ */ jsx("div", {
 		className: classes.tabsContainer,
@@ -8874,9 +8873,10 @@ async function handleErrorResponse(response) {
 			openMustChangeModal();
 			return response;
 		}
+		if (response.status === 403) return response;
 		const json = data;
 		message$1.error(json.msg || response.statusText);
-	} else message$1.error(response.statusText);
+	} else if (response.status !== 403) message$1.error(response.statusText);
 	return response;
 }
 var init_error_response = __esmMin((() => {

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-KUwgkL5p/qZWtW8VUNiLzg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-yoOEdSzDoQ4YJ5XCof4eFQ=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="KUwgkL5p/qZWtW8VUNiLzg==">{
+		<script type="importmap" nonce="yoOEdSzDoQ4YJ5XCof4eFQ==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

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.23",
-  "@oj-module/runtime/contract": "0.2.23",
-  "@oj-module/runtime/contract/errors": "0.2.23",
+  "@oj-module/runtime": "0.2.26",
+  "@oj-module/runtime/contract": "0.2.26",
+  "@oj-module/runtime/contract/errors": "0.2.26",
   "@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__/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");
+	});
+});