@oj-module/cli 0.2.2 → 0.2.6

package/shell-dist/assets/runtime.js

@@ -201,7 +201,8 @@ function mapAuthPayload(data) {
 	};
 }
 function fetchLogin(data) {
-	return request.post("auth/login", { json: data }).json().then((env) => mapAuthPayload(env.data));
+	const path = data.method === "ldap" ? "auth/ldap-login" : "auth/login";
+	return request.post(path, { json: data }).json().then((env) => mapAuthPayload(env.data));
 }
 function fetchLogout(data) {
 	return request.post("auth/logout", { json: { refresh_token: data?.refreshToken ?? "" } }).json().then(() => {});
@@ -255,10 +256,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.2",
+			"version": "0.2.6",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-16 22:08:56"
+		"lastBuildTime": "2026-10-19 12:08:59"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -8321,6 +8322,39 @@ function generateMenuItemsFromRoutes(routeList, parentPath = "/") {
 }
 var init_generate_menu_items_from_routes = __esmMin((() => {}));
 //#endregion
+//#region src/router/utils/merge-solution-categories.ts
+/**
+* 方案路由归并（纯函数，R21）：按 path 把 sys_solution_route 行注记到已注册路由上。
+*
+* - 三值 category 原样落 handle.category（main=常规组、admin=管理组、hidden=不进菜单）；
+* - hidden 与 enabled=0（禁用）复用既有 hideInMenu 通路——只过滤菜单层，路由仍可达
+*   （禁用的路由摘除归装载层三处同写，D12）；
+* - order 覆写为声明序：框架项保留 100 间隔带、方案项从 200 起编，共用一条序轴；
+* - 未匹配路由（框架/后端）原样保留（同一对象引用），入参不突变；
+* - solRoutes 为空（端点失败/未登录降级空表）时原样返回——降级不阻断，路由照常。
+*
+* title 不在此覆写：entry.ts 是模块元数据唯一来源（module-loader 既有惯例），
+* title_key 随行下发仅供深检对比。
+*/
+function mergeSolutionCategories(routes, solRoutes) {
+	if (solRoutes.length === 0) return routes;
+	const byPath = new Map(solRoutes.map((r) => [r.path, r]));
+	return routes.map((route) => {
+		const row = route.path ? byPath.get(route.path) : void 0;
+		if (!row) return route;
+		return {
+			...route,
+			handle: {
+				...route.handle,
+				category: row.category,
+				order: row.order,
+				hideInMenu: row.category === "hidden" || !row.enabled || (route.handle.hideInMenu ?? false)
+			}
+		};
+	});
+}
+var init_merge_solution_categories = __esmMin((() => {}));
+//#endregion
 //#region src/router/utils/resolve-login-route.ts
 /**
 * 内外 login 路由去重（P3，login 模块化）：唯一合成入口（SRP/DRY），
@@ -8380,18 +8414,20 @@ var init_access = __esmMin((() => {
 	init_ascending();
 	init_flatten_routes();
 	init_generate_menu_items_from_routes();
+	init_merge_solution_categories();
 	init_resolve_login_route();
 	initialState$1 = {
 		wholeMenus: generateMenuItemsFromRoutes(baseRoutes),
 		routeList: baseRoutes,
 		flatRouteList: flattenRoutes(baseRoutes),
-		isAccessChecked: false
+		isAccessChecked: false,
+		solutionRoutes: []
 	};
 	lastRegisteredRoutes = [];
-	useAccessStore = create((set) => ({
+	useAccessStore = create((set, get) => ({
 		...initialState$1,
 		setAccessStore: (routes) => {
-			const newRoutes = ascending([...resolveLoginRoute(baseRoutes, routes, router, rootRoute), ...routes]);
+			const newRoutes = ascending([...resolveLoginRoute(baseRoutes, routes, router, rootRoute), ...mergeSolutionCategories(routes, get().solutionRoutes)]);
 			router.patchRoutes(ROOT_ROUTE_ID, routes);
 			const flatRouteList = flattenRoutes(newRoutes);
 			const newState = {
@@ -8404,6 +8440,10 @@ var init_access = __esmMin((() => {
 			set(() => newState);
 			return newState;
 		},
+		setSolutionRoutes: (rows) => {
+			set({ solutionRoutes: rows });
+			if (lastRegisteredRoutes.length > 0) get().setAccessStore(lastRegisteredRoutes);
+		},
 		reset: () => {
 			router._internalSetRoutes(rootRoute);
 			set(initialState$1);
@@ -8739,7 +8779,10 @@ var init_request = __esmMin((() => {
 							}
 						}
 						return refreshTokenAndRetry(request, options, refreshToken);
-					} else return handleErrorResponse(response);
+					} else {
+						if (options.silentError) return response;
+						return handleErrorResponse(response);
+					}
 				}
 				return response;
 			}]
@@ -8777,11 +8820,13 @@ function fetchRbacOplog(query) {
 	for (const [k, v] of Object.entries(query)) if (v != null && v !== "") sp.set(k, String(v));
 	return get(`system/oplog?${sp.toString()}`);
 }
+var fetchRbacOplogPost = (body) => post("system/oplog", body);
 var fetchRbacSettings = () => get("system/settings");
 var fetchRbacUpdateSetting = (key, value) => put("system/settings", {
 	key,
 	value
 });
+var fetchSolutionRoutes = () => get("_platform/solutions/routes");
 function fetchRbacContacts(keyword, limit) {
 	return get(`_platform/contacts?keyword=${encodeURIComponent(keyword)}${limit ? `&limit=${limit}` : ""}`);
 }
@@ -8827,6 +8872,46 @@ function groupByModule(items) {
 		items
 	}));
 }
+/**
+* 框架自有设置模块（seed.sql 现行集合；新增框架设置模块须同步）。
+* 方案设置经安装预检强制 `moduleOf(key)===name`（R24），落库 module 列即方案名——
+* 据此把 sys_setting 行二分为框架区（维持按 group 聚合的现状渲染）与方案区（按模块三层嵌套）。
+*/
+var FRAMEWORK_SETTING_MODULES = /* @__PURE__ */ new Set([
+	"framework",
+	"market",
+	"ldap",
+	"sso"
+]);
+/**
+* 设置行按模块三层嵌套分组（R20/R24，纯函数）：框架卡在前（按 group 列聚合、保持服务端
+* `order by group, key` 次序），方案卡在后（module 名升序、组内按 group 列聚合）。
+* 不按 key 首段切组——框架 seed 存在无点号键（ldap_base_dn），首段不是其模块名；
+* module 列是落库的所有权真源。空行降级返回空数组。
+*/
+function groupSettingsByModule(rows) {
+	const framework = /* @__PURE__ */ new Map();
+	const solutions = /* @__PURE__ */ new Map();
+	for (const item of rows) if (FRAMEWORK_SETTING_MODULES.has(item.module)) (framework.get(item.group) ?? framework.set(item.group, []).get(item.group)).push(item);
+	else {
+		const groups = solutions.get(item.module) ?? solutions.set(item.module, /* @__PURE__ */ new Map()).get(item.module);
+		(groups.get(item.group) ?? groups.set(item.group, []).get(item.group)).push(item);
+	}
+	const cards = [];
+	for (const [group, items] of framework) cards.push({
+		module: null,
+		group,
+		label_key: null,
+		items
+	});
+	for (const module of [...solutions.keys()].sort()) for (const [group, items] of solutions.get(module)) cards.push({
+		module,
+		group,
+		label_key: `${module}:settings.group.${group}`,
+		items
+	});
+	return cards;
+}
 //#endregion
 //#region src/api/system/menu/index.ts
 init_api_provider();
@@ -9545,6 +9630,55 @@ function defineModule(definition) {
 	return definition;
 }
 //#endregion
+//#region src/store/solution-routes.ts
+init_access();
+init_auth();
+var useSolutionRoutes = create((set) => ({
+	routes: [],
+	loaded: false,
+	refresh: async () => {
+		try {
+			const routes = await fetchSolutionRoutes();
+			set({
+				routes,
+				loaded: true
+			});
+			useAccessStore.getState().setSolutionRoutes(routes);
+		} catch {
+			set({
+				routes: [],
+				loaded: true
+			});
+			useAccessStore.getState().setSolutionRoutes([]);
+		}
+	},
+	reset: () => {
+		set({
+			routes: [],
+			loaded: false
+		});
+		useAccessStore.getState().setSolutionRoutes([]);
+	}
+}));
+/**
+* token 就绪监视（R21）：登录成功（token 翻转）强制重拉一次；登出清空行并解除归并。
+* 幂等（armed 防重），模块导入即武装——宿主链（shell 无 AuthGuard）同样生效。
+*/
+var armed = false;
+function watchTokenReady() {
+	if (armed) return;
+	armed = true;
+	let lastToken = useAuthStore.getState().token;
+	if (lastToken) useSolutionRoutes.getState().refresh();
+	useAuthStore.subscribe((state) => {
+		if (state.token === lastToken) return;
+		lastToken = state.token;
+		if (state.token) useSolutionRoutes.getState().refresh();
+		else useSolutionRoutes.getState().reset();
+	});
+}
+watchTokenReady();
+//#endregion
 //#region src/utils/get-all-expanded-keys/index.ts
 function getAllExpandedKeys(data, fieldName = "key") {
 	return data.flatMap((item) => [item[fieldName], ...item.children?.length ? getAllExpandedKeys(item.children, fieldName) : []]);
@@ -27594,10 +27728,11 @@ init_tabs();
 init_user();
 init_get_app_info();
 init_get_redirect_path();
+init_request();
 init_user$1();
 init_local_icons();
 init_ri();
 init_menu_icons();
 init_tree();
 //#endregion
-export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, bindingDiff, canAssignRole, canDeleteRole, canEditRoleBindings, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchChangePassword, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLdapLogin, fetchLogin, fetchLoginMethods, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRbacAdminResetPassword, fetchRbacContactDetail, fetchRbacContacts, fetchRbacCreateRole, fetchRbacCreateUser, fetchRbacDeleteRole, fetchRbacOplog, fetchRbacPermissionList, fetchRbacRoleList, fetchRbacSetForbidden, fetchRbacSettings, fetchRbacUpdateBindings, fetchRbacUpdateSetting, fetchRbacUpdateUserRoles, fetchRbacUserList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, groupByModule, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, roleLabel, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useTabKey, useTabsStore, useUserStore, external_exports as z };
+export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, bindingDiff, canAssignRole, canDeleteRole, canEditRoleBindings, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchChangePassword, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLdapLogin, fetchLogin, fetchLoginMethods, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRbacAdminResetPassword, fetchRbacContactDetail, fetchRbacContacts, fetchRbacCreateRole, fetchRbacCreateUser, fetchRbacDeleteRole, fetchRbacOplog, fetchRbacOplogPost, fetchRbacPermissionList, fetchRbacRoleList, fetchRbacSetForbidden, fetchRbacSettings, fetchRbacUpdateBindings, fetchRbacUpdateSetting, fetchRbacUpdateUserRoles, fetchRbacUserList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchSolutionRoutes, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, groupByModule, groupSettingsByModule, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, request, roleLabel, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useSolutionRoutes, useTabKey, useTabsStore, useUserStore, external_exports as z };

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-ELLiP0aL4p7v4pSj08o8IQ=='; 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-p4BgRegxexzGkBE95NQxKA=='; 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="ELLiP0aL4p7v4pSj08o8IQ==">{
+		<script type="importmap" nonce="p4BgRegxexzGkBE95NQxKA==">{
   "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.2",
-  "@oj-module/runtime/contract": "0.2.2",
-  "@oj-module/runtime/contract/errors": "0.2.2",
+  "@oj-module/runtime": "0.2.6",
+  "@oj-module/runtime/contract": "0.2.6",
+  "@oj-module/runtime/contract/errors": "0.2.6",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/args.ts

@@ -38,6 +38,29 @@ export function parseApiArgs(argv: string[]): { dir: string, check: boolean, doc
 	return { dir, check: flags.has("--check"), docs: flags.has("--docs"), exempt };
 }
 
+/**
+ * `ojm build [--bundle] [--out <dir>]`。
+ * `--bundle`：方案包构建（manifest.yaml 契约校验 → 确定性 tgz + sha256），
+ * 与站点级 `ojm build`（后端 oj build + 模块产物合并）互斥分工（devkit 手册「打包与分发」）。
+ * `--out` 的值不得以 `--` 开头（同 parseApiArgs 的消费式扫描，P6 同款坑）。
+ */
+export function parseBuildArgs(argv: string[]): { bundle: boolean, out?: string } {
+	const flags = new Set<string>();
+	let out: string | undefined;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--out") {
+			out = argv[i + 1];
+			i++; // 消费紧随的值，不被当 flag
+			continue;
+		}
+		if (a.startsWith("--")) {
+			flags.add(a);
+		}
+	}
+	return { bundle: flags.has("--bundle"), out };
+}
+
 /**
  * `ojm vendor [tag] [--force]`：下载/更新 oj vendor（npm 包 @oj-bin/oj）。
  * tag 缺省追 npm latest；形如 `v0.1.13` 或 `0.1.13`（自动补 v 前缀，装包时去掉）。
@@ -53,3 +76,47 @@ export function parseVendorArgs(argv: string[]): { force: boolean, tag?: string
 		tag: tag === undefined ? undefined : (tag.startsWith("v") ? tag : `v${tag}`),
 	};
 }
+
+export interface LifecycleArgs {
+	positionals: string[]
+	url?: string
+	user?: string
+	pass?: string
+	locale?: string
+	name?: string
+	version?: string
+	task?: string
+}
+
+/**
+ * `ojm install|enable|disable` 共用解析：位置参数（目标/方案名）+ 值式 flag。
+ * 站点寻址三件套 --url/--user/--pass（环境变量 OJM_URL/OJM_USER/OJM_PASS 兜底，见 src/site.ts）；
+ * install 专属 --name/--version（文件名身份覆盖）与 --locale（终态文案语言）；
+ * trust 专属 --task（TOFU 确认目标任务 id，P2-3）。
+ * 值式 flag 逐项消费紧随的值，不被当位置参数（P6 同款坑，parseApiArgs 同纪律）。
+ */
+export function parseLifecycleArgs(argv: string[]): LifecycleArgs {
+	const valueFlags = new Set(["--url", "--user", "--pass", "--locale", "--name", "--version", "--task"]);
+	const values: Record<string, string> = {};
+	const positionals: string[] = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]!;
+		if (valueFlags.has(a)) {
+			values[a] = argv[i + 1] ?? "";
+			i++; // 消费紧随的值
+			continue;
+		}
+		if (!a.startsWith("--"))
+			positionals.push(a);
+	}
+	return {
+		positionals,
+		url: values["--url"],
+		user: values["--user"],
+		pass: values["--pass"],
+		locale: values["--locale"],
+		name: values["--name"],
+		version: values["--version"],
+		task: values["--task"],
+	};
+}

package/src/build.ts

@@ -10,7 +10,7 @@ import tailwindcss from "@tailwindcss/vite";
 import { build as esbuild } from "esbuild";
 import { build } from "vite";
 import { loadModulesConfig, resolveModuleEntry } from "./config";
-import { resolveLayout } from "./layout";
+import { resolveConfigPath, resolveLayout } from "./layout";
 import { isSharedDep, SHARED_DEPS } from "./shared-deps";
 import { resolveOjBin } from "./vendor";
 import { checkSharedVersions, resolveShellDist } from "./versions";
@@ -72,6 +72,7 @@ export const fetchRbacUpdateUserRoles = _fn;
 export const fetchRbacAdminResetPassword = _fn;
 export const fetchRbacSetForbidden = _fn;
 export const fetchRbacOplog = _fn;
+export const fetchRbacOplogPost = _fn;
 export const fetchRbacSettings = _fn;
 export const fetchRbacUpdateSetting = _fn;
 export const fetchRbacContacts = _fn;
@@ -79,12 +80,15 @@ export const fetchRbacContactDetail = _fn;
 export const fetchLoginMethods = _fn;
 export const fetchChangePassword = _fn;
 export const fetchLdapLogin = _fn;
+// 方案路由归并（P1-14/R21 读端点 + 分组纯函数）
+export const fetchSolutionRoutes = _fn;
 export const roleLabel = _fn;
 export const canEditRoleBindings = _fn;
 export const canDeleteRole = _fn;
 export const canAssignRole = _fn;
 export const bindingDiff = _fn;
 export const groupByModule = _fn;
+export const groupSettingsByModule = _fn;
 // hooks 与权限常量
 export const useAccess = _fn;
 export const usePreferences = _fn;
@@ -97,6 +101,8 @@ export const AccessControlRoles = _obj;
 export const permissionPrefix = "permission:button";
 // store
 export const useAuthStore = _fn;
+// 方案路由归并 store（token 就绪自动重拉，R21）
+export const useSolutionRoutes = _fn;
 export const useUserStore = _fn;
 export const useTabsStore = _fn;
 // 页签 key 唯一正确取口（keepAlive 下 useLocation 是激活页位置，0.1.21）
@@ -148,6 +154,8 @@ export const unloadModule = async () => {};
 export const useSlotNodes = () => [];
 // AC-D15：zod re-export——stub 用可调用代理（契约 schema 不在元数据读取期求值，仅占位防 missing export）
 export const z = new Proxy({}, { get: () => _fn });
+// R29：ky 实例 re-export（第一方市场编排面）——同 z，元数据读取期仅需可调用占位
+export const request = new Proxy({}, { get: () => _fn });
 `;
 
 /**
@@ -492,9 +500,9 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	const apiDist = path.join(projectRoot, "api/dist");
 	console.log("[ojm] oj build（后端）…");
 	// 必须显式给 -c：oj build 的 -c 缺省是 ./config.yaml（相对 CWD），而 config 在
-	// api/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
+	// <project>/config/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
 	// sql_guard 声明校验不生效（oj 只 warn 两行，极易被忽略）。
-	const configPath = path.join(projectRoot, "api/config.yaml");
+	const configPath = resolveConfigPath(projectRoot);
 	const configArgs = fs.existsSync(configPath) ? ["-c", configPath] : [];
 	// --no-minify：oj 的 swc minify 当前会把产物压坏，必须绕开。实测两种坏法：
 	//   1) `const rows = await db.query(...); rows[0]` → 压成 `await db.query(...)[0]`，

package/src/bundle.ts

@@ -0,0 +1,197 @@
+// 方案包构建（P1-11，`ojm build --bundle`）：manifest.yaml 契约校验（fail-fast 先于打包）
+// → 组装 tgz 内布局（契约 §2.9）→ 确定性打包（C2-32）+ sha256。
+// 组装映射（对齐 P1-9 staging copy 源一层定版，unpack 布局即安装器 extract 段消费面）：
+//   <project>/manifest.yaml                     → <name>-<version>/manifest.yaml（Form A）
+//   <project>/api/dist/<name>-<version>/        → <name>-<version>/api/<name>-<version>/（oj build 产物原样，C2-31 分层核对）
+//   <project>/web/dist/modules/                 → <name>-<version>/web/modules/（web.entry/css 存在性复核）
+// 红线：modules.json 禁入包（C2-31——该清单由安装器在目标站点 upsert，防覆盖宿主清单）；
+// 文件面契约（tables↔schema.yaml、locales 双语齐备）构建期 fail-fast（契约 §4.1 构建列）。
+import fs from "node:fs";
+import path from "node:path";
+
+import { parse } from "yaml";
+import { createDeterministicTgz } from "./deterministic-tar";
+import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
+
+export interface BundleBuildResult {
+	tgz: string
+	sha256: string
+	name: string
+	version: string
+}
+
+/**
+ * 从方案工程产出可安装 tgz + sha256。
+ * @param projectRoot 方案工程根（manifest.yaml 所在目录）
+ * @param opts 输出与选项
+ * @param opts.out 输出目录，缺省 `dist/`；产物 `<name>-<version>.tgz`
+ */
+export async function buildBundle(projectRoot: string, opts: { out?: string } = {}): Promise<BundleBuildResult> {
+	// 1) 读入并校验契约（构建即校验，坏清单出不了包）
+	const manifestPath = path.join(projectRoot, "manifest.yaml");
+	if (!fs.existsSync(manifestPath)) {
+		throw new Error(`[ojm] 方案包构建失败：${projectRoot} 下缺少 manifest.yaml（bundle 级契约是打包入口，写法见 devkit 手册「打包与分发」）`);
+	}
+	const parsed = parseManifest(fs.readFileSync(manifestPath, "utf8"));
+	if (!parsed.ok) {
+		throw new Error(`[ojm] 方案包构建失败：${parsed.error}`);
+	}
+	const m = parsed.manifest;
+	const violations = validateContract(m);
+	if (violations.length > 0) {
+		throw new Error(`[ojm] 方案包构建失败：manifest.yaml 契约校验未通过（${violations.length} 项违规，全量列出）：\n${violations.map(x => `- ${x}`).join("\n")}`);
+	}
+	const name = m.name as string;
+	const version = m.version as string;
+
+	// 2) 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）
+	const fileViolations = [
+		...checkTables(m, projectRoot, name),
+		...checkLocales(m, projectRoot, name),
+	];
+	if (fileViolations.length > 0) {
+		throw new Error(`[ojm] 方案包构建失败：文件面契约未通过（${fileViolations.length} 项，全量列出）：\n${fileViolations.map(x => `- ${x}`).join("\n")}`);
+	}
+
+	// order <200 仅构建期 lint 警告不阻断（C2-17：框架项保留 <200 间隔带）
+	const routes = Array.isArray(m.routes) ? m.routes as Record<string, unknown>[] : [];
+	for (const r of routes) {
+		const order = r.order;
+		if (typeof order === "number" && order < 200) {
+			console.warn(`[ojm] ⚠️ route「${String(r.path)}」order=${order} <200（框架项保留间隔带，建议 ≥200；仅警告不阻断）`);
+		}
+	}
+
+	// 3) 组装 staging：<name>-<version>/ 单根
+	const staging = fs.mkdtempSync(path.join(projectRoot, ".ojm-bundle-"));
+	try {
+		const root = path.join(staging, `${name}-${version}`);
+		fs.mkdirSync(root);
+		fs.copyFileSync(manifestPath, path.join(root, "manifest.yaml"));
+
+		// api：oj build 产物原样入包（编译编排不在此重跑——作者先 oj build，本命令只校验与组装；
+		// 编排接线随 P1-15 方案脚手架定形）
+		if (m.api !== undefined) {
+			const built = path.join(projectRoot, "api/dist", `${name}-${version}`);
+			if (!fs.existsSync(built)) {
+				throw new Error(`[ojm] 方案包构建失败：缺少 oj build 产物 ${path.relative(projectRoot, built)}（manifest 声明了 api 段；先对 api/ 运行 oj build，产物原样入包）`);
+			}
+			const layoutViolations = checkModuleManifest(built, name, version, m.summary as string);
+			if (layoutViolations.length > 0) {
+				throw new Error(`[ojm] 方案包构建失败：分层核对未通过（C2-31）：\n${layoutViolations.map(x => `- ${x}`).join("\n")}`);
+			}
+			fs.cpSync(built, path.join(root, "api", `${name}-${version}`), { recursive: true });
+		}
+
+		// web：站点构建模块产物入包（web 段缺省 = 纯后端方案，整段跳过）
+		if (m.web !== undefined) {
+			const webModules = path.join(projectRoot, "web/dist/modules");
+			if (!fs.existsSync(webModules)) {
+				throw new Error("[ojm] 方案包构建失败：缺少站点构建产物 web/dist/modules（manifest 声明了 web 段；先运行 ojm build 生成模块产物）");
+			}
+			fs.cpSync(webModules, path.join(root, "web", "modules"), { recursive: true });
+			const web = m.web as Record<string, unknown>;
+			for (const rel of [web.entry, ...(Array.isArray(web.css) ? web.css : [])]) {
+				if (typeof rel === "string" && !fs.existsSync(path.join(root, "web", rel))) {
+					throw new Error(`[ojm] 方案包构建失败：web 声明的产物不存在：${rel}（C2-27 成品存在性复核；请核对该文件是否已在本次构建产出）`);
+				}
+			}
+		}
+
+		// 红线自检：modules.json 禁入包任何位置（C2-31）+ 私钥/凭证禁入（P2-4 入包红线；
+		// 完整性自查发生在确定性打包前的 staging 上）
+		assertNoForbiddenMembers(root);
+
+		// 4) 确定性打包（C2-32；symlink 等成员守卫在打包原语内，C2-30）
+		const outDir = path.resolve(projectRoot, opts.out ?? "dist");
+		const tgzPath = path.join(outDir, `${name}-${version}.tgz`);
+		const sha256 = await createDeterministicTgz(staging, tgzPath);
+		const size = fs.statSync(tgzPath).size;
+		console.log(`[ojm] 方案包已生成 → ${tgzPath}`);
+		console.log(`[ojm] sha256：${sha256}（${size} 字节；确定性打包：同输入两次打包哈希一致，C2-32）`);
+		return { tgz: tgzPath, sha256, name, version };
+	}
+	finally {
+		fs.rmSync(staging, { recursive: true, force: true });
+	}
+}
+
+/** C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version/desc 与 bundle 级逐一相等（oj 启动强校验同源） */
+function checkModuleManifest(built: string, name: string, version: string, summary: string): string[] {
+	const p = path.join(built, "manifest.yaml");
+	let doc: unknown;
+	try {
+		doc = parse(fs.readFileSync(p, "utf8"));
+	}
+	catch (e) {
+		return [`api/<name>-<version>/manifest.yaml 读取失败（${e instanceof Error ? e.message : String(e)}）——oj 安装后要真实解析此文件`];
+	}
+	if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+		return ["api/<name>-<version>/manifest.yaml 必须是键值映射（oj 模块级，仅 oj 原生七键）"];
+	}
+	const mm = doc as Record<string, unknown>;
+	const out: string[] = [];
+	if (mm.name !== name) {
+		out.push(`模块级 name「${String(mm.name)}」必须 === bundle name「${name}」（oj 启动强校验 name == 目录名）`);
+	}
+	if (mm.version !== version) {
+		out.push(`模块级 version「${String(mm.version)}」必须 === bundle version「${version}」`);
+	}
+	if (mm.desc !== summary) {
+		out.push(`模块级 desc「${String(mm.desc)}」必须 === bundle summary「${summary}」（安装器写 desc 即取 summary）`);
+	}
+	return out;
+}
+
+/** api.tables ↔ schema.yaml 表集对照（C2-12a 构建列；schema 缺失/声明不一致均 fail-fast） */
+function checkTables(m: Record<string, unknown>, projectRoot: string, name: string): string[] {
+	const api = m.api as Record<string, unknown> | undefined;
+	if (api === undefined || api.tables === undefined)
+		return [];
+	const schemaPath = path.join(projectRoot, "api/src", name, "schema.yaml");
+	if (!fs.existsSync(schemaPath)) {
+		return [`【C2-12a】api.tables 已声明但缺少 ${path.relative(projectRoot, schemaPath)}，无法对照表集（oj 冗余校验同源）`];
+	}
+	return checkTablesAgainstSchema(m, fs.readFileSync(schemaPath, "utf8"));
+}
+
+/** locales 双语齐备（C2-25 构建列缺 key fail-fast；安装期信任构建产物不重复校验） */
+function checkLocales(m: Record<string, unknown>, projectRoot: string, name: string): string[] {
+	if (referencedI18nKeys(m).length === 0)
+		return [];
+	const dir = path.join(projectRoot, "web/src", name, "locales");
+	const texts: Partial<Record<"zh-CN" | "en-US", string>> = {};
+	const out: string[] = [];
+	for (const lang of ["zh-CN", "en-US"] as const) {
+		const p = path.join(dir, `${lang}.json`);
+		if (!fs.existsSync(p)) {
+			out.push(`【C2-25】manifest 引用了 i18n key 但缺少 ${path.relative(projectRoot, p)}（双语齐备，D4）`);
+			continue;
+		}
+		texts[lang] = fs.readFileSync(p, "utf8");
+	}
+	return [...out, ...checkLocalesComplete(m, texts["zh-CN"] ?? "", texts["en-US"] ?? "")];
+}
+
+/** 私钥/凭证文件名红线（P2-4 入包自检）：*.pem / *.key / .env / id_ed25519|id_rsa */
+const FORBIDDEN_MEMBER = /\.(?:pem|key)$|^\.env$|^id_(?:ed25519|rsa)$/;
+
+/** staging 全树扫描：modules.json 禁入（C2-31 红线）+ 私钥/凭证禁入（P2-4 红线） */
+function assertNoForbiddenMembers(root: string): void {
+	const visit = (dir: string) => {
+		for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+			const p = path.join(dir, e.name);
+			if (e.isDirectory()) {
+				visit(p);
+				continue;
+			}
+			if (e.isFile() && e.name === "modules.json") {
+				throw new Error(`[ojm] 打包自检失败（C2-31）：modules.json 禁入方案包（该清单由安装器在目标站点 upsert，防覆盖宿主清单）——位置：${p}`);
+			}
+			if (e.isFile() && FORBIDDEN_MEMBER.test(e.name)) {
+				throw new Error(`[ojm] 打包自检失败（P2-4 入包红线）：私钥/凭证文件「${e.name}」禁入方案包（*.pem / *.key / .env / id_ed25519 / id_rsa）——签名私钥永不入包，签名经 detached .sig 侧车随包分发（包内只含产物与公钥）。位置：${p}`);
+			}
+		}
+	};
+	visit(root);
+}