@oj-module/cli 0.2.26 → 0.2.27

package/README.md

@@ -23,81 +23,107 @@
 ## 命令
 
 ```bash
-ojm dev [port]   # 启动开发服务器（默认 5174）：宿主代理 + 本地模块重建
-ojm build        # 构建模块产物与 dist/modules.json
-ojm init [dir] [--yes]        # 脚手架：模板工程 + 证书签发 + 联网下载 oj 到 bin/
-ojm vendor [tag] [--force]    # 下载/重装 oj vendor（经 npm 包 @oj-bin/oj，tag 缺省取最新版本，形如 v0.1.13）
-ojm preview [port]   # 生产形态预览：oj migrate → oj serve 单服务（API + 静态 SPA 同进程）
-ojm info        # 输出报障所需的版本矩阵与后端观测
-ojm api [dir]   # 契约产物生成（client/openapi/mock stub）
-ojm merge <out> <in...>  # 合并多份 modules.json
+# 工程脚手架
+ojm init [dir] [--yes]                           # 前后端一体化脚手架（幂等补缺：重跑只补缺失，永不覆盖已有文件）
+ojm new <name> [--layout container|none] [--api] # 脚手架内生成用户方案骨架（src/<name>/ + solution.yaml）
+
+# 开发与构建
+ojm dev [port]                                   # 开发服务器：/api 反代 oj + 模块重建 + SSE 自动刷新（快捷键 r/h/c/o/q）
+ojm build [--bundle [name]] [--out <dir>]        # 构建后端（oj build）与模块产物；--bundle 打确定性方案包
+ojm preview [port]                               # 生产形态预览：migrate → oj serve 单服务（API + 静态 SPA 同进程）
+ojm api [dir] [--check] [--docs] [--exempt <p>]  # 契约代码生成（client/routes/openapi/stub）；--check 四重对账
+
+# 清单与诊断
+ojm info [--all]                                 # 版本矩阵与模块清单（报障用）
+ojm merge <out.json> <in1.json> [in2.json ...]   # 合并多团队清单（清单先后 = 接管优先级）
+ojm vendor [tag] [--force]                       # 下载/重装 oj vendor（经 npm 包 @oj-bin/oj，tag 形如 v0.1.13）
+
+# 方案市场（站点侧生命周期）
+ojm install <file.tgz | name[@version]>          # 安装方案包到目标站点（file 上传 / CDN 市场源）
+ojm enable|disable <name>                        # 启用/禁用已装方案（锁/sidecar/路由清单/模块清单四处同写）
+ojm uninstall <name>                             # 卸载已装方案（四处同删 + 权限级联清理）
+ojm trust ls|add|revoke|confirm                  # 发布方信任库管理（TOFU 确认）
+
+# 发布与签名（作者侧）
+ojm keygen --id <publisher.id>                   # 生成 Ed25519 签名密钥对（私钥缺省 ~/.ojm/keys/<id>/）
+ojm sign <file.tgz> --id <id> [--check]          # detached 侧车签名（产出 <tgz>.sig）
+ojm publish <dir> --id <id> [--check]            # 索引发布（重算 bundles/manifests + 侧车签名）
+
+# 本地市场模拟 CDN
+ojm market setup|publish|build-index|verify|trial|walkthrough
+
+# oj 子命令透传
+ojm test|exec|openapi|migrate|schema [args...]   # 透传给 oj 同名子命令（自动补 -c <project>/config.yaml）
 ```
 
-> `ojm init` / `ojm vendor` 需要访问 npm registry（经 `npm i @oj-bin/oj` 安装 oj 到 `bin/`，走 `.npmrc` 镜像配置）。已装版本记录在 `bin/.oj-version`，`ojm info` 可查。
+> 每个命令都有中英双语帮助：`ojm <cmd> --help` 看单命令详解，`ojm help` 看全量索引
+> （语言按 `OJM_LANG` / `LANG` 探测，缺省 zh-CN）。`ojm --version` 显示 cli 包版本。
+> 方案市场的完整链路（打包 → 签名 → 索引 → 安装 → 生命周期）见 devkit 手册 §10–§12。
 
 ### `ojm build`
 
-读取 `web.config.ts`，逐个模块构建（硬切换后只认 web/src + web/dist 布局）：
+构建后端与前端产物（module-root 布局为默认，模块由扫描 `src/*/web/entry.ts` 收录，
+`web.config.ts` 仅作可选覆盖；历史布局仍以 `web.config.ts` 的 `modules` 为真源）：
 
 ```
 web/dist/
-├── modules.json                              # 模块清单（供宿主 fetch）
+├── index.html                             # 全站合并后的宿主页（仅 build 做清场合并）
+├── modules.json                           # 模块清单（供宿主 fetch）
 └── modules/<name>/<version>/
-    ├── entry.js                              # 模块入口
-    ├── <chunk>.js                            # 保留 code splitting
+    ├── entry.js                           # 模块入口
+    ├── <chunk>.js                         # 保留 code splitting
     └── *.css
 ```
 
 - 只有共享表内的依赖被 external，其余依赖会被打进模块产物（不在表内时 CLI 会告警）；
 - 每个 chunk 计算 `sha384` 完整性摘要写入 `modules.json`，懒加载 chunk 标记 `lazy: true`；
 - 模块元信息（`name` / `version` / `peerRuntime`）通过 esbuild 打包后真实 `import()` entry 读取，而非正则解析——因此配置文件里可以写注释、用变量、做条件判断；
-- 读取元信息时 `@oj-module/runtime` 被替换为只读占位模块，避免在 Node 下加载含 Vite 专有 svg 导入的框架运行时。
+- 读取元信息时 `@oj-module/runtime` 被替换为只读占位模块，避免在 Node 下加载含 Vite 专有 svg 导入的框架运行时；
+- `--bundle [name]`：只组装不构建，先 `ojm build` 再打包——两段式契约校验（fail-fast）后产出确定性
+  `dist/<name>-<version>.tgz` + sha256（市场安装器的上游产物）；无参 = 全部用户方案。
 
 ### `ojm dev`
 
 1. 直接取本包内置的预构建宿主 `shell-dist`（随 cli 发布，**不再**查询 `node_modules/@oj-module/shell`，也无 monorepo 路径回退）；
 2. 先跑一次 `ojm build`；
-3. 起静态服务器：
+3. 起开发服务器：
 
    | 路由 | 来源 |
    |---|---|
+   | `/api/*` | 反代到 oj 后端（oj 端口以 `config.yaml` 的 `server.port` 为准，默认 9778） |
    | `/`、`/index.html` | `@oj-module/cli/shell-dist/index.html`（含 importmap） |
    | `/assets/*` | `@oj-module/cli/shell-dist/assets/*` |
    | `/modules.json` | 本地 `web/dist/modules.json` |
    | `/modules/*` | 本地 `web/dist/modules/*` |
 
-4. 监听 `web/src/` 变更并增量重建（防抖 300ms）。
-
-> 当前为「保存即重建 + 手动刷新」。完整 HMR（react-refresh preamble、dev-runtime 映射）在后续阶段接入。
+4. 监听 `web/src/`（module-root 为 `src/*/web/`）变更并增量重建（防抖 300ms），经 SSE 通道**自动刷新浏览器**；
+5. TTY 终端启用类 Vite 快捷键：`r` 强制重建热更新 · `h` 帮助 · `c` 清屏 · `o` 浏览器打开 · `q` 退出（后端 oj 一并终止，不留孤儿占端口）。
 
 ## 配置文件
 
-工程根目录的 `web.config.ts`：
+工程根目录的 `web.config.ts`（module-root 布局下可选，仅 `baseUrl` / `siteBase` /
+`htmlTransform` 等站点级配置才需要它；`modules` 登记只对历史布局必填）：
 
 ```ts
 export default {
   /** 产物 URL 前缀，留空表示同源相对路径；跨源时填 CDN 绝对地址 */
   baseUrl: "",
+  /** 站点部署子路径（如 "/oj"），留空 = 挂在域名根；与 baseUrl 正交可同用 */
+  siteBase: "",
+  /** 历史布局的模块登记；module-root 布局由扫描 src/*/web/entry.ts 得出 */
   modules: [
     { name: "demo", entry: "./web/src/demo/entry.ts", enabled: true },
   ],
+  /** 按路由改写 HTML 的模块（仅 ojm dev 生效，见下） */
+  htmlTransform: "./html-transform.ts",
 };
 ```
 
-`name` 必须与 `entry.ts` 中 `defineModule({ name })` 一致，不一致会直接构建失败。`enabled: false` 的模块会被跳过。
+`name` 必须与 `entry.ts` 中 `defineModule({ name})` 一致，不一致会直接构建失败。`enabled: false` 的模块会被跳过。
 
 ### 按路由改写 HTML（`htmlTransform`，可选）
 
-模块联邦站点每条路由都出同一份 `index.html`，逐路由的 `<title>` / OpenGraph 无从表达——IM 链接预览与非 JS 爬虫只会看到默认 title。配 `htmlTransform` 指向一个模块（相对工程根的路径，或已安装的包名），`ojm dev` 与 `ojm preview` 会加载它，对 `/`、`/index.html` 与 SPA 回落的深链接统一生效：
-
-```ts
-// web.config.ts
-export default {
-  baseUrl: "",
-  modules: [/* … */],
-  htmlTransform: "./html-transform.ts",
-};
-```
+模块联邦站点每条路由都出同一份 `index.html`，逐路由的 `<title>` / OpenGraph 无从表达——IM 链接预览与非 JS 爬虫只会看到默认 title。配 `htmlTransform` 指向一个模块（相对工程根的路径，或已安装的包名），`ojm dev` 会加载它，对 `/`、`/index.html` 与 SPA 回落的深链接统一生效：
 
 ```ts
 // html-transform.ts —— default 导出即变换函数
@@ -109,10 +135,11 @@ export default async function (path: string, html: string) {
 ```
 
 - `path` 是解码后的请求路径（查询串已剥离），`html` 是宿主原文；
-- 先变换、后注入 dev 刷新脚本，故 `ojm dev` 的热刷新不受影响；
+- 先变换、后注入 dev 刷新脚本，故热刷新不受影响；
 - 变换抛错或返回非字符串 → 回退原文，站点不 500；
 - 模块缺失或 default 不是函数 → 启动即人话报错（fail-fast）；
-- 非 HTML 资产（`/assets/*`、`/modules/*`）不受影响。
+- 非 HTML 资产（`/assets/*`、`/modules/*`）不受影响；
+- **仅 `ojm dev` 生效**：单服务 `ojm preview` 由 oj 直出 HTML，钩子无从介入（启动 WARN 并指向 oj 的 `server.html_meta` / `server.html_meta_handler`）。
 
 ## 子出口
 
@@ -122,6 +149,15 @@ import { generateImportmap, generateShellEntries, isSharedDep, SHARED_DEPS } fro
 
 // 配置加载
 import { loadModulesConfig, resolveModuleEntry } from "@oj-module/cli/config";
+
+// 构建 / 诊断 / 校验（Node 侧工具链复用）
+import { buildModules } from "@oj-module/cli/build";
+import { printInfo, mergeManifests } from "@oj-module/cli/info";
+import { collectExportGaps } from "@oj-module/cli/esm-exports";
+import { mergeModuleManifests } from "@oj-module/cli/manifest";
+
+// 预构建宿主资产（随包发布）
+import "@oj-module/cli/shell-dist/index.html";
 ```
 
 **硬共享**（`react` / `react-router` / `@tanstack/react-query` / `@oj-module/runtime` …）破坏即崩溃，必须由宿主提供，模块不得自带；**软共享**（`antd` / `dayjs` / `i18next` …）允许版本漂移。

package/devkit/manual.md

@@ -355,7 +355,7 @@ export default defineModule({
 | `order` | 菜单排序值（双段序轴）：`≥0` 主菜单区升序；`<0` 底部固定区（pin 在侧边栏底部，区内仍按 order 升序）；未声明按登记下标兜底；同 order 按根 path 字母序 |
 | `title` | 菜单标题，用 `"<模块名>:menu.<key>"` |
 | `icon` | `createElement(XxxOutlined)` |
-| `keepAlive` | 页面缓存（**必须挂在 `layout: "container"` 下才生效**） |
+| `keepAlive` | 页面缓存（多 tab 开启时有效；与 layout 解绑；相对/绝对声明均可，key 取路由绝对路径） |
 | `hideInMenu` | 不在菜单显示 |
 | `roles` / `permissions` | 路由级权限（页面级 / 按钮级） |
 | `iframeLink` | 内嵌 iframe 的外链地址 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.26",
+    "@oj-module/runtime": "0.2.27",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.26",
+			"version": "0.2.27",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-23 21:49:09"
+		"lastBuildTime": "2026-10-24 00:06:50"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -7272,24 +7272,6 @@ var init_scoped = __esmMin((() => {
 	init_request();
 }));
 //#endregion
-//#region src/router/utils/flatten-routes.ts
-/**
-* 将路由扁平化为一个对象，键为路由的 path，值为路由对象
-*/
-function flattenRoutes(routes) {
-	const result = {};
-	function traverse(items, parent) {
-		items.forEach((item) => {
-			if (item.index && parent?.path) result[`${parent.path}/`] = item;
-			if (item.path) result[item.path] = item;
-			if (item.children && item.children.length > 0) traverse(item.children, item);
-		});
-	}
-	traverse(routes);
-	return result;
-}
-var init_flatten_routes = __esmMin((() => {}));
-//#endregion
 //#region src/module-loader/keep-alive.ts
 /** 汇总一组模块定义里的全部路由（供扁平化与 exclude 计算） */
 function collectAllRoutes(definitions) {
@@ -7298,24 +7280,53 @@ function collectAllRoutes(definitions) {
 	return routes;
 }
 /**
+* 绝对路径求解：绝对 path 原样；相对 path 拼父层；index（无 path）即父层本身。
+* 规则同 addRouteIdByPath / generateMenuItemsFromRoutes / rewriteAdminPaths 的
+* resolveAbs——解决方案模块一律相对路径声明（安装时方可加 prefix 于顶层），
+* 运行时绝对路径由此规则涌现，exclude key 必须落进同一空间才能与
+* activeCacheKey（= pathname）匹配。
+*/
+function resolveAbsPath(path, parentAbs) {
+	if (!path) return parentAbs;
+	return path.startsWith("/") ? path : `${parentAbs.replace(/\/+$/, "")}/${path}`;
+}
+/**
 * 纯函数：从一组路由中收集 `handle.keepAlive === false` 的路由 key。
-* key 与 `flattenRoutes` 产出的键一致，从而能和 KeepAlive 的 `activeCacheKey`
-* （= pathname）精确匹配。
+* key = 路由绝对路径，与 activeCacheKey（= pathname）匹配。
 *
 * 这是 P2.1 把 exclude 计算从 access store 的 `flatRouteList` 反转到
 * module-loader 的核心：缓存是否排除只取决于「模块声明」，不再依赖某条路由
 * 是否套了 ContainerLayout（见设计文档 B13 / R9）。
 */
 function collectKeepAliveExcludes(routes) {
-	const flat = flattenRoutes(routes);
-	return Object.entries(flat).reduce((acc, [key, value]) => {
-		if (value.handle?.keepAlive === false) acc.push(key);
-		return acc;
-	}, []);
+	const out = [];
+	const walk = (items, parentAbs) => {
+		for (const item of items) {
+			const abs = resolveAbsPath(item.path, parentAbs);
+			const key = item.index ? parentAbs : abs;
+			if (item.handle?.keepAlive === false) out.push(key);
+			if (item.children?.length) walk(item.children, abs);
+		}
+	};
+	walk(routes, "");
+	return out;
 }
-/** 纯函数：收集所有路由 key（关闭多 tab 时用于整体排除，仅保留切换动画） */
+/**
+* 纯函数：收集所有路由 key（关闭多 tab 时用于整体排除，仅保留切换动画）。
+* 与 collectKeepAliveExcludes 同一套绝对 key 口径（tab 关闭分支的 exclude
+* 自此真正有意义），按出现序去重。
+*/
 function collectAllRoutePaths(routes) {
-	return Object.keys(flattenRoutes(routes));
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (items, parentAbs) => {
+		for (const item of items) {
+			const abs = resolveAbsPath(item.path, parentAbs);
+			seen.add(item.index ? parentAbs : abs);
+			if (item.children?.length) walk(item.children, abs);
+		}
+	};
+	walk(routes, "");
+	return [...seen];
 }
 /** 基于一组模块定义计算 exclude key（供单元测试） */
 function getKeepAliveExcludes(definitions) {
@@ -7325,9 +7336,7 @@ function getKeepAliveExcludes(definitions) {
 function getAllRoutePaths(definitions) {
 	return collectAllRoutePaths(collectAllRoutes(definitions));
 }
-var init_keep_alive = __esmMin((() => {
-	init_flatten_routes();
-}));
+var init_keep_alive = __esmMin((() => {}));
 //#endregion
 //#region src/module-loader/semver.ts
 function parse$2(version) {
@@ -8436,6 +8445,24 @@ var init_router = __esmMin((() => {
 	router = createRouter();
 }));
 //#endregion
+//#region src/router/utils/flatten-routes.ts
+/**
+* 将路由扁平化为一个对象，键为路由的 path，值为路由对象
+*/
+function flattenRoutes(routes) {
+	const result = {};
+	function traverse(items, parent) {
+		items.forEach((item) => {
+			if (item.index && parent?.path) result[`${parent.path}/`] = item;
+			if (item.path) result[item.path] = item;
+			if (item.children && item.children.length > 0) traverse(item.children, item);
+		});
+	}
+	traverse(routes);
+	return result;
+}
+var init_flatten_routes = __esmMin((() => {}));
+//#endregion
 //#region src/router/utils/generate-menu-items-from-routes.ts
 /**
 * 解析菜单 key 为绝对路径。

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-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" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-LoiG1HDggaNmP/FtNKL2EQ=='; 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="yoOEdSzDoQ4YJ5XCof4eFQ==">{
+		<script type="importmap" nonce="LoiG1HDggaNmP/FtNKL2EQ==">{
   "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.26",
-  "@oj-module/runtime/contract": "0.2.26",
-  "@oj-module/runtime/contract/errors": "0.2.26",
+  "@oj-module/runtime": "0.2.27",
+  "@oj-module/runtime/contract": "0.2.27",
+  "@oj-module/runtime/contract/errors": "0.2.27",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/vendor/host-versions.json

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