@oj-module/cli 0.2.56 → 0.2.57

package/src/build.ts

@@ -1,885 +1,16 @@
-import type { Plugin as EsbuildPlugin } from "esbuild";
-import type { Plugin } from "vite";
-import type { ProjectLayout } from "./layout";
-import type { RouteDefinitionLike } from "./manifest-routes-derive";
-import { execFileSync } from "node:child_process";
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import process from "node:process";
-import { pathToFileURL } from "node:url";
-import tailwindcss from "@tailwindcss/vite";
-import { build as esbuild } from "esbuild";
-import { build } from "vite";
-import { parse as parseYaml } from "yaml";
-import { ALIAS_PATHS_FILE, syncAliasPaths } from "./alias-paths";
-import { assertModuleList, loadSiteConfig, mergeModuleList, resolveModuleEntry } from "./config";
-import { moduleDir, resolveConfigPath, resolveLayout, scanModules, tryResolveLayout } from "./layout";
-import { requireModuleRootCapability } from "./oj-caps";
-import { isPrebuiltDep, isSharedDep, SHARED_DEPS } from "./shared-deps";
-import { normalizeSiteBase, rewriteIndexHtml } from "./site-base";
-import { resolveOjBin } from "./vendor";
-import { checkSharedVersions, resolveShellDist } from "./versions";
-
-/**
- * `@oj-module/runtime` 的只读占位源码（设计文档 B10 / §4.3）。
- *
- * 读取模块定义时只需要 entry 顶层调用 `defineModule({ name, version, ... })` 的
- * 结果，而绝不需要真正加载框架运行时（其产物含 Vite 专有的 `?react`/`?url` svg
- * 导入，Node 下无法加载）。通过 esbuild 虚拟模块插件内联进 bundle，从源头避开 svg
- * 问题；其余共享依赖保持 external，由 tsx/Node 在 import() 时按真实包加载。
- *
- * 这里列出运行时的「值导出」，使 esbuild 不会报 missing export（类型导出无需提供）。
- * `defineModule` 仅把入参原样回传，CLI 即可读取 name/version 等元数据。
- */
-const RUNTIME_STUB_SOURCE = `
-const _fn = (...a) => a[a.length - 1];
-const _obj = () => ({});
-// 组件
-export const BasicContent = _fn;
-export const BasicButton = _fn;
-export const BasicTable = _fn;
-export const Iframe = _fn;
-export const AccessControl = _fn;
-export const FormAvatarItem = _fn;
-export const FormTreeItem = _fn;
-export const AntdApp = _fn;
-// 页面级错误边界（增量⑥）：宿主壳与模块自绘子树包裹用
-export const ErrorBoundary = _fn;
-export const PageError = _fn;
-// api
-export const notify = _obj;
-export const fetchPie = _fn;
-export const fetchLine = _fn;
-export const fetchLogin = _fn;
-export const fetchLogout = _fn;
-export const fetchAsyncRoutes = _fn;
-export const fetchUserInfo = _fn;
-export const fetchRefreshToken = _fn;
-export const fetchRoleList = _fn;
-export const fetchAddRoleItem = _fn;
-export const fetchUpdateRoleItem = _fn;
-export const fetchDeleteRoleItem = _fn;
-export const fetchRoleMenu = _fn;
-export const fetchMenuByRoleId = _fn;
-export const fetchMenuList = _fn;
-export const fetchAddMenuItem = _fn;
-export const fetchUpdateMenuItem = _fn;
-export const fetchDeleteMenuItem = _fn;
-// RBAC（阶段 C 增补，与 runtime api/rbac 对齐）
-export const fetchRbacRoleList = _fn;
-export const fetchRbacPermissionList = _fn;
-export const fetchRbacCreateRole = _fn;
-export const fetchRbacUpdateBindings = _fn;
-export const fetchRbacDeleteRole = _fn;
-export const fetchRbacUserList = _fn;
-export const fetchRbacCreateUser = _fn;
-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;
-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;
-// i18n 初始化（宿主链路消费）
-export const setupI18n = _fn;
-// 全局副作用（宿主链路消费）
-export const LayoutEffects = _fn;
-export const accessControlCodes = _obj;
-export const AccessControlRoles = _obj;
-export const permissionPrefix = "permission:button";
-// store
-export const useAccessStore = _fn;
-export const useAuthStore = _fn;
-// 方案路由归并 store（token 就绪自动重拉，R21）
-export const useSolutionRoutes = _fn;
-export const useUserStore = _fn;
-export const useTabsStore = _fn;
-// 租户上下文（L2）：请求头由运行时注入，模块只在登出清理 / URL 带 tenant 参数时读写
-export const useTenantStore = _fn;
-export const currentTenant = () => "default";
-export const bootstrapTenant = () => "default";
-export const DEFAULT_TENANT = "default";
-export const TENANT_HEADER = "X-TENANT-ID";
-export const TENANT_QUERY_PARAM = "tenant";
-// 页签 key 唯一正确取口（keepAlive 下 useLocation 是激活页位置，0.1.21）
-export const useTabKey = _fn;
-// 图标
-export const menuIcons = _obj;
-export const EmbeddedIcon = _fn;
-export const ExternalIcon = _fn;
-export const LayoutCenterIcon = _fn;
-export const LayoutLeftIcon = _fn;
-export const LayoutRightIcon = _fn;
-export const MixedNavigationIcon = _fn;
-export const OutsidePageIcon = _fn;
-export const ProfileCardIcon = _fn;
-export const ServerErrorIcon = _fn;
-export const SideNavigationIcon = _fn;
-export const TopNavigationIcon = _fn;
-export const TwoColumnNavigationIcon = _fn;
-export const RiAccountCircleLine = _fn;
-export const RiContrastFill = _fn;
-export const RiFullscreenExitLine = _fn;
-export const RiFullscreenLine = _fn;
-export const RiMailCheckLine = _fn;
-export const RiMoonIcon = _fn;
-export const RiReactjsLine = _fn;
-export const RiSunIcon = _fn;
-export const RiUserSettingsLine = _fn;
-// 工具与常量
-export const handleTree = _fn;
-export const traverseTreeValues = _fn;
-export const filterTree = _fn;
-export const mapTree = _fn;
-export const getAllExpandedKeys = _fn;
-export const getAppInfo = _fn;
-export const getRedirectPath = _fn;
-// 站点部署 base（子路径部署）：stub 只需占位，元数据读取期不拼 URL
-export const resolveSiteBase = _fn;
-export const withSiteBase = _fn;
-// API 端点 base（整页跳转的后端端点、上传 action 用它拼 URL，与站点 base 正交）
-export const resolveApiBase = _fn;
-export const getYesNoOptions = _fn;
-export const getBooleanOptions = _fn;
-// 模块契约
-export const defineModule = (d) => d;
-export const defineRoutes = (...a) => a[a.length - 1];
-export const defineGuard = (...a) => a[a.length - 1];
-export const getModules = () => [];
-export const getModule = () => undefined;
-export const getRoutes = () => [];
-export const getHostRoutes = () => [];
-// 模块生效 web 路由前缀段取值口（R1.3：写进 modules.json 的 routePrefix，未声明回落 name）
-export const getModuleRoutePrefix = _fn;
-export const getRegisteredStore = () => undefined;
-export const getRegisteredApiPrefix = () => undefined;
-export const loadAll = async () => [];
-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 });
-`;
-
-/**
- * esbuild 插件：把 `@oj-module/runtime` 解析到一个内联的只读占位虚拟模块，
- * 避免真正加载框架运行时（含 svg）。用虚拟模块而非 alias 指向实体文件，是因为
- * 实体路径依赖 import.meta.url，在 vitest 等变换环境下拿不到合法的 file URL。
- */
-const runtimeStubPlugin: EsbuildPlugin = {
-	name: "ojm-runtime-stub",
-	setup(b) {
-		b.onResolve({ filter: /^@oj-module\/runtime$/ }, () => ({
-			path: "@oj-module/runtime",
-			namespace: "ojm-runtime-stub",
-		}));
-		b.onLoad({ filter: /.*/, namespace: "ojm-runtime-stub" }, () => ({
-			contents: RUNTIME_STUB_SOURCE,
-			loader: "js",
-			resolveDir: process.cwd(),
-		}));
-	},
-};
-
-/**
- * 把 entry 内所有动态 import 的目标（lazy 页面、i18n JSON）替换为虚拟空模块：
- * 元数据读取只需要 defineModule 的入参对象，动态模块永远不该执行。
- * 若放任这些模块进 bundle，esbuild 输出 ESM 时会把页面模块的裸导入 hoist 到
- * bundle 顶层（如 pro-components），Node import() 时即被求值并可能加载失败；
- * 若标为 external，vitest 等变换环境又会在 transform 阶段强行解析相对说明符。
- * 空模块两条路都堵死（P3.4）。
- */
-const dynamicImportStubPlugin: EsbuildPlugin = {
-	name: "ojm-dynamic-import-stub",
-	setup(b) {
-		// esbuild 的 onResolve 不支持按 kind 过滤，在回调里判断后放行其余 resolver
-		b.onResolve({ filter: /^\./ }, (args) => {
-			if (args.kind === "dynamic-import") {
-				return { path: args.path, namespace: "ojm-dynamic-stub" };
-			}
-			return null;
-		});
-		b.onLoad({ filter: /.*/, namespace: "ojm-dynamic-stub" }, () => ({
-			contents: "export default {};",
-			loader: "js",
-		}));
-	},
-};
-
-/**
- * 元数据读取封闭性（P3 验收发现）：裸导入全部桩化，`ojm init` 产出的外部工程
- * 尚未安装依赖（@oj-module/* 未发布），真实 import() 会
- * ERR_MODULE_NOT_FOUND；读元数据只需要 defineModule 入参，共享依赖执行与否无关。
- *
- * - 值统一为「自引用可调用代理」：任意属性链访问/调用都安全（JSX 元素在
- *   模块顶层求值等形态）。
- * - 从 modulesSrc 源码扫出的具名导入经 ownKeys/getOwnPropertyDescriptor 陷阱
- *   静态暴露——esbuild 对 CJS 桩做 __toESM 属性拷贝（走这两把陷阱），仅 get
- *   陷阱拷不出名字，顶层 `React.createElement` 会直接崩（验收实测）。
- * - `#` 开头的工程子路径导入不桩化，走默认解析。
- */
-/**
- * 扫描 modulesSrc 下全部源码，收集「裸说明符 → 具名导入列表」。
- * 只为给桩模块提供可静态暴露的名字（供 esbuild __toESM 拷贝），不求精确：
- * 解析不到的形状（多行、注释包裹等）只会让该名字未被种子，运行时落到 get
- * 陷阱兜底；扫到未使用的名字也无害。
- */
-function collectBareImportedNames(...roots: string[]): Map<string, string[]> {
-	const found = new Map<string, Set<string>>();
-	const record = (spec: string, clause: string) => {
-		if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("#"))
-			return;
-		const set = found.get(spec) ?? new Set<string>();
-		for (const raw of clause.split(",")) {
-			const name = raw.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim();
-			if (name && /^[\w$]+$/.test(name))
-				set.add(name);
-		}
-		set.add("default");
-		found.set(spec, set);
-	};
-	const walk = (dir: string) => {
-		let entries: fs.Dirent[];
-		try {
-			entries = fs.readdirSync(dir, { withFileTypes: true });
-		}
-		catch {
-			return;
-		}
-		for (const entry of entries) {
-			const filePath = path.join(dir, entry.name);
-			if (entry.isDirectory()) {
-				walk(filePath);
-				continue;
-			}
-			if (!/\.(?:ts|tsx|js|jsx|mjs)$/.test(entry.name))
-				continue;
-			const source = fs.readFileSync(filePath, "utf-8");
-			for (const m of source.matchAll(/(?:import|export)\s+(?:type\s+)?\{([^}]*)\}\s*(?:from\s*)?["']([^"']+)["']/g))
-				record(m[2], m[1]);
-			for (const m of source.matchAll(/import\s+(\w+)\s*(?:,\s*\{([^}]*)\}\s*)?from\s*["']([^"']+)["']/g)) {
-				if (m[1] && m[3])
-					record(m[3], m[1]);
-				if (m[2] && m[3])
-					record(m[3], m[2]);
-			}
-			// namespace / default 导入的属性访问（`React.lazy` / `ns.foo()`）：
-			// 名字从成员访问推断，否则 __toESM 拷贝后这些名字不存在（playground 实测）
-			const bindings = new Map<string, string>();
-			for (const m of source.matchAll(/import\s+(?:\*\s+as\s+)?(\w+)\s+from\s*["']([^"']+)["']/g)) {
-				if (m[1] && m[2] && !m[2].startsWith(".") && !m[2].startsWith("#"))
-					bindings.set(m[1], m[2]);
-			}
-			for (const [binding, spec] of bindings) {
-				for (const m of source.matchAll(new RegExp(`\\b${binding}\\.(\\w+)`, "g"))) {
-					const set = found.get(spec) ?? new Set<string>();
-					set.add(m[1]);
-					found.set(spec, set);
-				}
-			}
-		}
-	};
-	for (const root of roots)
-		walk(root);
-	return new Map([...found].map(([spec, set]) => [spec, [...set]]));
-}
-
-/** 每次元数据读取一个实例：modulesSrc 扫描出的「裸说明符 → 具名导入列表」 */
-function makeBareImportStubPlugin(namesBySpec: Map<string, string[]>): EsbuildPlugin {
-	return {
-		name: "ojm-bare-import-stub",
-		setup(b) {
-			b.onResolve({ filter: /^[^./#]/ }, args => ({ path: args.path, namespace: "ojm-bare-stub" }));
-			b.onLoad({ filter: /.*/, namespace: "ojm-bare-stub" }, (args) => {
-				const names = namesBySpec.get(args.path) ?? [];
-				return {
-					contents: [
-						// `apply` 返回 value（自身）而非 undefined：桩必须**可无限链式调用**。
-						// 反例（真踩过）：zustand v5 是柯里化 API——`create()(initializer)`
-						// 先调一次取工厂、再调一次取 store，且**都在模块顶层求值**。
-						// 若 apply 返回 undefined，元数据读取即抛
-						// `(0, import_zustand.create)(...) is not a function`，
-						// 整个 `ojm dev/build` 起不来（模块代码本身完全合法）。
-						// 同类形态：`axios.create(...)`、`i18next.createInstance(...)`、
-						// `createTheme(...)` 等顶层库工厂。桩只在元数据读取期跑，放宽只会
-						// 把「崩溃」变成「无害空转」。
-						"const value = new Proxy(function () {}, { get: () => value, apply: () => value });",
-						`const names = ${JSON.stringify(names)};`,
-						"module.exports = new Proxy({}, {",
-						"\tget: () => value,",
-						"\tgetOwnPropertyDescriptor: (_t, p) => names.includes(p) ? { enumerable: true, configurable: true, get: () => value } : undefined,",
-						"\townKeys: () => names,",
-						"});",
-					].join("\n"),
-					loader: "js",
-				};
-			});
-		},
-	};
-}
-
-/** modules.json 中的 chunk 条目 */
-export interface ChunkEntry {
-	url: string
-	integrity: string
-	/** 懒加载 chunk：L2 完整性档位下不受保护（设计文档 §4.7） */
-	lazy: boolean
-}
-
-/** modules.json 中的模块条目 */
-export interface BuiltModule {
-	name: string
-	version: string
-	enabled: boolean
-	dependencies: string[]
-	peerRuntime?: string
-	entry: string
-	integrity: string
-	css: string[]
-	chunks: ChunkEntry[]
-	/**
-	 * 生效的 web 路由前缀段（契约 C2-14：`web.route_prefix` 缺省 `/<name>`）。
-	 * 运行期据其改写模块路由根（单根约定下仅根段），缺省 = name 保证零漂移。
-	 */
-	routePrefix: string
-}
-
-/**
- * 解析模块生效的 web 路由前缀段（R1.1）。
- * module-root：读 `src/<name>/solution.yaml` 的 `web.route_prefix`（契约 C2-14，缺省 `/<name>`）；
- * 未配置/非法/非 module-root → 缺省 `name`，与现有路由根（顶层段即 name）逐字节一致。
- */
-function resolveRoutePrefix(layout: ProjectLayout, name: string): string {
-	if (layout.kind !== "module-root")
-		return name;
-	const solPath = path.join(moduleDir(layout, name), "solution.yaml");
-	if (!fs.existsSync(solPath))
-		return name;
-	try {
-		const doc = parseYaml(fs.readFileSync(solPath, "utf-8")) as Record<string, unknown>;
-		const web = doc.web;
-		if (web && typeof web === "object" && !Array.isArray(web)) {
-			const rp = (web as Record<string, unknown>).route_prefix;
-			if (typeof rp === "string" && /^\/[a-z][a-z0-9-]{0,63}$/.test(rp))
-				return rp.slice(1);
-		}
-	}
-	catch {
-		// YAML 解析失败 → 缺省，不阻断构建（契约校验会在别处暴露）
-	}
-	return name;
-}
-
-const ALGORITHM = "sha384";
-
-function sha384(file: string): string {
-	const digest = crypto.createHash(ALGORITHM).update(fs.readFileSync(file)).digest("base64");
-	return `${ALGORITHM}-${digest}`;
-}
-
-/**
- * 用 esbuild 把 entry 打包成单文件（含 runtime 占位 stub 与动态 import 空 stub），
- * 写出到工程内临时目录后以普通 `import()` 加载，从而读取模块定义
- * （name/version/peerRuntime/config）而无需真正加载整个框架运行时
- * （其源码含 Vite 专有的 `?react`/`?url` svg 导入），替代脆弱的正则（B10）。
- *
- * P3.4 起同时供主仓库 `scripts/build-modules.ts` 复用（经 exports `./build`）。
- */
-export async function readModuleDefinition(entryFile: string, projectRoot: string) {
-	// 必须落在工程目录内（而非 os.tmpdir），否则 bundle 外部化的共享依赖
-	// （react / antd …）在 import() 时无法从 /tmp 解析到 node_modules。
-	const outDir = fs.mkdtempSync(path.join(projectRoot, ".ojm-tmp-"));
-	try {
-		// entry 可能登记在 modulesSrc 之外（playground 登记仓库级模块），
-		// entry 所在目录同样入扫，保证其相对导入图的具名导入都被种子
-		const bareNames = collectBareImportedNames(resolveLayout(projectRoot).modulesSrc, path.dirname(entryFile));
-		await esbuild({
-			entryPoints: [entryFile],
-			// 固定输出名 entry.js：esbuild 默认取 entry 文件 basename，
-			// 会让非 entry.ts 文件名（如测试夹具）的产物对不上后续 import 路径
-			entryNames: "entry",
-			bundle: true,
-			format: "esm",
-			platform: "node",
-			packages: "external",
-			plugins: [runtimeStubPlugin, dynamicImportStubPlugin, makeBareImportStubPlugin(bareNames)],
-			outdir: outDir,
-			jsx: "automatic",
-			// 元数据读取不需要 css：empty 装载器把 `import "./styles.css"` 抹成空模块，
-			// 避免裸导入桩拦截 css 内部的 `@import "tailwindcss"`（js 桩无法注入 css）
-			loader: { ".ts": "ts", ".tsx": "tsx", ".json": "json", ".css": "empty" },
-			logLevel: "silent",
-		});
-		const bundled = path.join(outDir, "entry.js");
-		const mod = await import(pathToFileURL(bundled).href);
-		const definition = mod.default;
-		if (!definition?.name || !definition?.version) {
-			throw new Error(`${entryFile} 的 default 导出缺少 name 或 version`);
-		}
-		return definition as {
-			name: string
-			version: string
-			peerRuntime?: string
-			config?: { dependencies?: string[] }
-			// R5：entry.ts 声明的路由树（含 handle.category/order/title），
-			// buildBundle 据此派生 manifest.routes（单一真源，避免手工双写漂移）
-			routes?: RouteDefinitionLike[]
-		};
-	}
-	finally {
-		fs.rmSync(outDir, { recursive: true, force: true });
-	}
-}
-
-function warnUnsharedDeps(projectRoot: string) {
-	const pkgPath = path.join(projectRoot, "package.json");
-	if (!fs.existsSync(pkgPath))
-		return;
-
-	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-	const deps = Object.keys(pkg.dependencies ?? {});
-	const unshared = deps.filter(dep => !isSharedDep(dep) && !dep.startsWith("@oj-module/"));
-
-	if (unshared.length) {
-		console.warn(
-			`[ojm] ⚠️ 以下运行时依赖不在共享表内，会被打进模块产物：${unshared.join(", ")}\n`
-			+ "     若它应与宿主共用，请加入 SHARED_DEPS 并在宿主 importmap 中映射（设计文档 C8）",
-		);
-	}
-}
-
-/** 提取产物文件中的全部裸说明符（排除相对/绝对/# 路径） */
-function collectBareSpecifiers(file: string): string[] {
-	const source = fs.readFileSync(file, "utf-8");
-	const found = new Set<string>();
-	const patterns = [
-		/(?:import|export)\s[^'";]*?from\s*["']([^"']+)["']/g, // import/export ... from "x"
-		/import\s*["']([^"']+)["']/g, // 副作用导入 import "x"
-		/import\(\s*["']([^"']+)["']\s*\)/g, // 动态 import("x")
-	];
-	for (const pattern of patterns) {
-		for (const match of source.matchAll(pattern)) {
-			const spec = match[1]!;
-			if (!spec.startsWith(".") && !spec.startsWith("/") && !spec.startsWith("#"))
-				found.add(spec);
-		}
-	}
-	return [...found];
-}
-
-/**
- * P7.9 / B11 + C8：构建期扫描模块产物的裸说明符。
- * - 深路径命中共享表前缀但非精确 importmap 键（如 dayjs/plugin/utc）：
- *   构建期直接报错——importmap 无前缀通配，浏览器必抛
- *   "Failed to resolve module specifier"，不能拖到运行期（§4.7 错误契约）。
- * - 表外说明符：C8 构建期告警（按真实 import 分析，不依赖 package.json 字段）。
- */
-function assertResolvableSpecifiers(
-	moduleName: string,
-	moduleOutDir: string,
-	emitted: Map<string, { type: string, fileName: string }>,
-): void {
-	const exactKeys = new Set(SHARED_DEPS.map(dep => dep.specifier));
-	const deepPathErrors: string[] = [];
-	const unsharedWarnings = new Set<string>();
-
-	for (const info of emitted.values()) {
-		if (info.type !== "chunk")
-			continue;
-		for (const spec of collectBareSpecifiers(path.join(moduleOutDir, info.fileName))) {
-			if (exactKeys.has(spec))
-				continue;
-			if (isSharedDep(spec)) {
-				deepPathErrors.push(`  · ${info.fileName} → "${spec}"`);
-			}
-			else {
-				unsharedWarnings.add(spec);
-			}
-		}
-	}
-
-	if (deepPathErrors.length > 0) {
-		throw new Error(
-			`[ojm] 模块 "${moduleName}" 的产物含 importmap 无法解析的深路径说明符：\n`
-			+ `${deepPathErrors.join("\n")}\n`
-			+ "共享表只提供精确键（importmap 无前缀通配）。修复建议：改从包根导入"
-			+ "（如 dayjs 插件改在宿主侧注册），或联系框架方在 SHARED_DEPS 增补该深路径条目。",
-		);
-	}
-
-	if (unsharedWarnings.size > 0) {
-		console.warn(
-			`[ojm] ⚠️ 模块 "${moduleName}" import 了共享表外的三方库：${[...unsharedWarnings].join(", ")}\n`
-			+ "     它们会被打进模块产物。若应与宿主共用，请加入 SHARED_DEPS（设计文档 C8）",
-		);
-	}
-}
-
-/**
- * 构建后端（api/src 存在时编排 `bin/oj build`，D8）。
- *
- * 绝不在此处跑 migrate：oj build 本身零磁盘副作用，`ojm build` 保持零 DB
- * 副作用（CI/无 DB 环境可跑）；迁移由 preview 在起服务前应用（设计 §6）。
- * 无后端源码返回 false（纯前端工程跳过）。
- */
-export async function buildBackend(projectRoot: string): Promise<boolean> {
-	// 没有模块源码的工程（如 market 的隔离站点根）直接跳过——不能因为探测不到布局就抛
-	const layout = tryResolveLayout(projectRoot);
-	const moduleRoot = layout?.kind === "module-root";
-	const apiSrc = moduleRoot
-		? layout.modulesSrc
-		: path.join(projectRoot, "api/src");
-	if (!fs.existsSync(apiSrc))
-		return false;
-
-	const oj = resolveOjBin(projectRoot);
-	if (!fs.existsSync(oj)) {
-		throw new Error(
-			`[ojm] 找到 ${path.relative(projectRoot, apiSrc) || "."} 但缺少 ${oj}。\n`
-			+ "请重跑 ojm init 幂等补缺（不会覆盖 config 与用户代码）。",
-		);
-	}
-	// 能力闸门先于任何写入：失败时磁盘上不留半成品
-	if (moduleRoot)
-		requireModuleRootCapability(projectRoot);
-
-	// 别名投影：模块增删后要让 TS 的 paths 跟上（否则 `#/<模块名>/…` 在编辑器/typecheck
-	// 里解析不到，退化成 any）。内容未变不写盘。
-	const syncedPaths = syncAliasPaths(projectRoot);
-	if (syncedPaths === "created" || syncedPaths === "updated")
-		console.log(`[ojm] 已${syncedPaths === "created" ? "生成" : "更新"} ${ALIAS_PATHS_FILE}（\`#/<模块名>/…\` 的 TS paths 投影）`);
-
-	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"、
-	// sql_guard 声明校验不生效（oj 只 warn 两行，极易被忽略）。
-	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]`，
-	//      下标先于 await 求值，Promise 上取 [0] 得 undefined（登录恒 401）；
-	//   2) `if (cond) x = y` → 压成 `cond && x = y`，赋值作 && 右项缺括号 →
-	//      SyntaxError: Invalid left-hand side in assignment（端点 500）。
-	// 0.1.32 / 0.1.50 均复现。产物体积换正确性，等上游修好再撤这个旗标。
-	// v0.1.85：`--module-root <dir>` 与 `-d` 互斥（都是「源码树根」）。新布局给 src，
-	// oj 在子树内递归找 manifest.yaml（命中 src/<name>/api/manifest.yaml 即停）。
-	const sourceArgs = layout?.moduleRoot ? ["--module-root", layout.moduleRoot] : ["-d", apiSrc];
-	// 出包前先自己确认 config 能读：读不动时 oj build 会静默关掉 sql_guard（见函数注释）
-	if (configArgs.length)
-		assertSealedValuesOpenable(oj, configPath);
-	execFileSync(oj, [
-		"build",
-		...configArgs,
-		...sourceArgs,
-		"-o",
-		apiDist,
-		"--no-minify",
-	], { stdio: "inherit" });
-	// 宿主 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");
-	if (fs.existsSync(versionsSrc)) {
-		fs.mkdirSync(apiDist, { recursive: true });
-		fs.copyFileSync(versionsSrc, path.join(apiDist, "versions.json"));
-	}
-	return true;
-}
-
-/**
- * config 里的密封值（`oj secret seal` 产物）在 build 前试解一把——fail-closed。
- *
- * **为什么不能只信 oj 的 warn**：实测（oj 0.1.115）config 读不动时 `oj build` **退出码仍是 0**，
- * 只往 stderr 甩两行「读配置失败 → 镜像目录回落默认 tasks / 本次 build 按 sql_guard=off 处理」，
- * 然后照常出包。那两行夹在模块清单里极易被忽略，而关掉的 `sql_guard` 正是 tenant 声明校验
- * （跨模块 SQL 的唯一守卫）——包看起来完好，检查其实没跑。
- *
- * 探法就是 oj 自己的排障命令 `oj secret open`：它和 `oj serve` / `oj build` 用同一套密钥解析
- * （`OJ_SECRET_KEY` → `OJ_SECRET_KEY_FILE` → config 的 `secrets.private_key_path`），
- * 解不开就非零退出。明文只可能出现在它的 stdout，这里直接丢弃，不落终端也不落日志。
- */
-function assertSealedValuesOpenable(oj: string, configPath: string): void {
-	// 注释行不算：config 里留着注释掉的旧密文很常见，naive 匹配会让 build 因为一行 `#` 而失败
-	const live = fs.readFileSync(configPath, "utf-8")
-		.split("\n")
-		.filter(line => !line.trimStart().startsWith("#"))
-		.join("\n");
-	const sealed = [...new Set(live.match(/ENC\[[^\]\n]+\]/g) ?? [])];
-	for (const value of sealed) {
-		try {
-			execFileSync(oj, ["secret", "open", "-c", configPath, value], { stdio: ["ignore", "ignore", "pipe"] });
-		}
-		catch (e) {
-			const stderr = String((e as { stderr?: unknown }).stderr ?? "").trim();
-			const detail = stderr || (e as Error).message;
-			throw new Error(
-				`[ojm] config 里的密封值解不开，已停在出包前：${configPath}\n`
-				+ `      oj 说：${detail}\n`
-				+ "\n"
-				+ "不能放行：oj build 遇到读不动的 config 不会失败（退出码 0），只 warn 两行就继续——\n"
-				+ "tasks 镜像目录回落默认值，sql_guard（tenant 声明校验）直接关掉。那种包看着正常，\n"
-				+ "跨模块 SQL 的守卫却没跑过。\n"
-				+ "\n"
-				+ "两类原因，都修得了：\n"
-				+ "  1) 本机加载的私钥与密封时用的公钥不是一对——最常见是换机器/换部署目录时只带了\n"
-				+ "     config.yaml，没带 config/secrets-private.pem；\n"
-				+ "  2) 密文被改过——手工编辑、复制被截断、编辑器把长行折了。\n"
-				+ "\n"
-				+ "单独验一条：oj secret open -c <config> '<那个 ENC[...] 值>'（成功=这条没问题，失败=就是它）\n"
-				+ "修法：把配对私钥带到本机（OJ_SECRET_KEY / OJ_SECRET_KEY_FILE / config 的 secrets.private_key_path\n"
-				+ "      三选一）；密钥确实换了，就在本机重新 oj secret seal 覆写该值（明文走 stdin，别上命令行）。",
-			);
-		}
-	}
-}
-
-/**
- * 全站合并（仅 `ojm build` 调用，设计 §5）：清场后拷 shell dist 全量，
- * 再由模块构建写入 modules.json 与 modules/。清场防旧哈希资产无限累积
- * （shell 每次重构建生成新哈希文件名）；devServer 热重建路径不合并——
- * dev 的 / 与 /assets/* 直接服务 shell dist，合并产物无人消费。
- *
- * siteBase 非空时（站点挂载在 `/oj` 这类子路径）改写 index.html 的站内绝对
- * URL；apiBase 非空时注入 `window.__OJ_API_BASE__`（API 挂载前缀部署期可配，
- * 见 site-base.ts）。两者都为空则产物与既有行为逐字节一致。
- */
-function mergeShellSite(distDir: string, siteBase: string, apiBase: string): void {
-	const shellDist = resolveShellDist();
-	fs.rmSync(distDir, { recursive: true, force: true });
-	fs.mkdirSync(path.dirname(distDir), { recursive: true });
-	fs.cpSync(shellDist, distDir, { recursive: true });
-
-	const indexPath = path.join(distDir, "index.html");
-	if (normalizeSiteBase(siteBase) !== "/" || apiBase.trim()) {
-		fs.writeFileSync(indexPath, rewriteIndexHtml(fs.readFileSync(indexPath, "utf-8"), siteBase, apiBase));
-		if (normalizeSiteBase(siteBase) !== "/")
-			console.log(`[ojm] 站点 index.html 已按 siteBase=${normalizeSiteBase(siteBase)} 重写（子路径部署）`);
-		if (apiBase.trim())
-			console.log(`[ojm] API 前缀已注入 index.html：${apiBase.trim().replace(/\/+$/, "")}（apiBase）`);
-	}
-	console.log(`[ojm] 已合并宿主站点 → ${distDir}`);
-}
-
-/**
- * 构建模块工程。
- *
- * 产出（layout.distDir：module-root / new → dist/web；flat → build）：
- *   <dist>/modules/<name>/<version>/{entry.js, chunk-*.js, *.css}
- *   <dist>/modules.json
- *
- * opts.mergeSite 仅 `ojm build` 传 true：清场 + 拷 shell dist 全量；
- * devServer 热重建默认 false，只写模块产物。
- */
-export async function buildModules(
-	projectRoot: string,
-	opts: { mergeSite?: boolean } = {},
-): Promise<BuiltModule[]> {
-	const layout = resolveLayout(projectRoot);
-	const config = await loadSiteConfig(projectRoot);
-	// module-root：模块清单由 src/*/web/entry.ts 扫描得出（web.config.ts 仅可选覆盖）；
-	// 历史布局：仍以 web.config.ts 的 modules 为唯一真源。
-	const modules = layout.kind === "module-root"
-		? mergeModuleList(scanModules(layout), config.modules, projectRoot)
-		: assertModuleList(projectRoot, config.modules);
-	const outDir = layout.distDir;
-	const baseUrl = config.baseUrl ?? "";
-
-	if (opts.mergeSite)
-		mergeShellSite(outDir, config.siteBase ?? "", config.apiBase ?? "");
-
-	// P4.5 / C4 / D12：构建前先过版本矩阵门禁，版本漂移直接拒绝
-	checkSharedVersions(projectRoot, resolveShellDist());
-
-	warnUnsharedDeps(projectRoot);
-
-	const built: BuiltModule[] = [];
-
-	for (const item of modules) {
-		if (item.enabled === false) {
-			console.log(`[ojm] 跳过已禁用模块 ${item.name}`);
-			continue;
-		}
-
-		const entryFile = resolveModuleEntry(projectRoot, item.entry);
-		const definition = await readModuleDefinition(entryFile, projectRoot);
-
-		if (definition.name !== item.name) {
-			throw new Error(
-				`模块名不一致：${layout.kind === "module-root" ? `src/${item.name}` : "web.config.ts"} 中为 "${item.name}"，entry.ts 中为 "${definition.name}"`,
-			);
-		}
-
-		const moduleOutDir = path.join(outDir, "modules", definition.name, definition.version);
-		const emitted = new Map<string, { fileName: string, type: "chunk" | "asset", isEntry: boolean, isDynamicEntry: boolean }>();
-
-		const collectChunks: Plugin = {
-			name: "ojm:collect-chunks",
-			writeBundle(_options, bundle) {
-				for (const [fileName, output] of Object.entries(bundle)) {
-					emitted.set(fileName, {
-						fileName,
-						type: output.type,
-						isEntry: output.type === "chunk" && output.isEntry,
-						isDynamicEntry: output.type === "chunk" && output.isDynamicEntry,
-					});
-				}
-			},
-		};
-
-		console.log(`[ojm] 构建 ${definition.name}@${definition.version} ...`);
-
-		await build({
-			root: projectRoot,
-			logLevel: "warn",
-			// §4.1-④：tailwind 模块管线——模块内 import 的 css 经 @tailwindcss/vite
-			// 编译，产物由宿主 <link> 注入（R16）；模块无 css 入口时插件不产生任何产物
-			plugins: [collectChunks, tailwindcss()],
-			// Spike A 坑 2：lib 模式不替换 process.env.NODE_ENV，
-			// 浏览器顶层求值会抛 process is not defined（风险 R15）
-			define: { "process.env.NODE_ENV": JSON.stringify("production") },
-			build: {
-				outDir: moduleOutDir,
-				emptyOutDir: true,
-				sourcemap: false,
-				/**
-				 * 模块产物压缩（2026-09-17 由 `false` 改为 `true`）。
-				 *
-				 * 本行原为 `false` **且无注释**（同文件其余设置都带 rationale）—— 经查出自
-				 * 2026-08-31 的调试提交 `1bf3200`，疑似调试期临时值遗留。实测代价极大：
-				 * 仅这一项就让 planning 的 gzip 从 186,730 → **75,872（−59.4%）**、
-				 * workitems 88,351 → **40,113（−54.6%）**（同一份产物只做压缩，未改任何配置）。
-				 * 背景：曾评估「把重复的生成 client 提成共享资产来省体积」，实测 gzip 净变化
-				 * 仅 −364 B（生成 client 压缩率 6.8%，且重复内容已被同一 bundle 内的 gzip
-				 * 滑窗吃掉）⇒ **真正的杠杆是压缩，不是去重**（见 oj-module 台账 T54）。
-				 *
-				 * ⚠️ **本项只作用于「模块产物」**，与宿主共享资产无关：`shell-dist/assets/*.js`
-				 * 由 `shell/scripts/build.mts` 自己的 esbuild 构建，且 `esm-exports.ts` 的
-				 * 导出面解析**依赖资产顶格输出**（其文件头写明「`minify: false` 下顶层语句
-				 * 一律顶格输出」）⇒ **不要**顺手把共享资产也压了，那会让导入完整性门禁失效。
-				 *
-				 * 代价（已知并接受）：生产产物栈不可读（`sourcemap: false` 保持不变 —— 开
-				 * sourcemap 会额外部署 .map 文件，属另一个决策）。
-				 */
-				minify: true,
-				lib: {
-					entry: entryFile,
-					formats: ["es"],
-					fileName: () => "entry.js",
-				},
-				rolldownOptions: {
-					// 只把共享依赖留给宿主 importmap；
-					// 相对路径 / 绝对路径是模块自身代码，需要打包
-					external: (id: string) => !id.startsWith(".") && !path.isAbsolute(id) && isPrebuiltDep(id),
-					output: {
-						// P7.x / e2e：模块产物内联动态 import（lazy 页面、i18n 等），
-						// 输出为**单文件**。原因：
-						// 1. 拆出的 chunk 只能靠 import.meta.url 在「真实 HTTP 服务」下解析，
-						//    任何非 HTTP 加载上下文（e2e harness、离线/原生壳、L2 完整性之外的
-					//    加载路径）都会 ECONNREFUSED / 404，导致页面空白；
-					// 2. 拆出的 lazy chunk 不受 L2 完整性保护（构建期已告警），是模块化
-					//    方案的真实完整性缺陷；单文件后整包受 modulepreload+integrity 覆盖；
-					// 3. 单文件模块是微前端模块的通用形态，宿主按真实 URL 一次性加载即可，
-					//    无孤儿 chunk 依赖。
-						codeSplitting: false as any,
-					},
-				},
-			},
-		});
-
-		// 运行期 require 门禁：CJS 依赖 require 了 external 共享包时，rolldown 只留一个浏览器
-		// 不可用的 require 桩（"Calling `require` for ..."），表现为模块加载即抛错、页面空白。
-		// 这类依赖必须移出 bundle 走宿主 importmap（shell 侧有 CJS→ESM 垫片）。
-		const builtEntry = path.join(moduleOutDir, "entry.js");
-		if (fs.existsSync(builtEntry)) {
-			const code = fs.readFileSync(builtEntry, "utf-8");
-			if (code.includes("doesn't expose the `require` function")) {
-				const specs = [...new Set([...code.matchAll(/ne\("([^"]+)"\)/g)].map(m => m[1]))];
-				throw new Error(
-					`[ojm] ${definition.name}@${definition.version} 产物含运行期 require(${specs.join(", ") || "?"})`
-					+ "——浏览器没有 require，模块加载即抛错。"
-					+ "根因：该 CJS 依赖被标为 bundle（自带副本），但它 require 的共享包被 external 了。"
-					+ "修复：把它从 SHARED_DEPS 的 bundle 列表移回共享资产，或改用该依赖的 ESM 入口。",
-				);
-			}
-		}
-
-		const prefix = `${baseUrl}/modules/${definition.name}/${definition.version}/`;
-		const chunks: ChunkEntry[] = [];
-		const css: string[] = [];
-
-		for (const info of emitted.values()) {
-			if (info.type === "asset") {
-				if (info.fileName.endsWith(".css"))
-					css.push(`${prefix}${info.fileName}`);
-				continue;
-			}
-
-			// P7.3：entry 也进 chunks（lazy:false）——宿主 L2 完整性按 chunks[]
-			// 注入 modulepreload+integrity，此前 entry 被 isEntry 跳过导致
-			// 顶层 integrity 成为死字段（评审 S3：入口恰好不受保护）
-			chunks.push({
-				url: `${prefix}${info.fileName}`,
-				integrity: sha384(path.join(moduleOutDir, info.fileName)),
-				lazy: info.isEntry ? false : info.isDynamicEntry,
-			});
-		}
-
-		// §4.6：lazy chunk 不受 L2 完整性保护，构建期必须显式提示
-		const lazyChunks = chunks.filter(c => c.lazy);
-		if (lazyChunks.length > 0) {
-			console.warn(
-				`[ojm] 模块 "${definition.name}" 含 ${lazyChunks.length} 个 lazy chunk，`
-				+ "它们在 L2 完整性档位下不受保护（§4.7 D7）：\n"
-				+ `${lazyChunks.map(c => `  · ${c.url}`).join("\n")}\n`
-				+ "若这些 chunk 也要求完整性，请升级到 L3（Service Worker）或使用逃生通道（§4.7）。",
-			);
-		}
-
-		// P7.9 / B11：扫描产物中的裸说明符，构建期拦截 importmap 无法解析的
-		// 深路径（如 dayjs/plugin/utc——isSharedDep 前缀命中但 importmap 只有
-		// 精确键，浏览器必抛 Failed to resolve module specifier）；
-		// 顺带以真实 import 分析落地 C8 表外依赖告警（不再只扫 package.json 字段）
-		assertResolvableSpecifiers(definition.name, moduleOutDir, emitted);
-
-		built.push({
-			name: definition.name,
-			version: definition.version,
-			enabled: true,
-			dependencies: definition.config?.dependencies ?? [],
-			peerRuntime: definition.peerRuntime,
-			entry: `${prefix}entry.js`,
-			integrity: sha384(path.join(moduleOutDir, "entry.js")),
-			css,
-			chunks,
-			routePrefix: resolveRoutePrefix(layout, definition.name),
-		});
-	}
-
-	const manifestPath = path.join(outDir, "modules.json");
-	fs.mkdirSync(outDir, { recursive: true });
-	fs.writeFileSync(manifestPath, `${JSON.stringify(built, null, 2)}\n`);
-	console.log(`[ojm] 清单已生成 → ${manifestPath}`);
-
-	return built;
-}
+// 构建编排 facade（2026-11-03 SOLID 拆分，行为零变化，计划 docs/plans/20261103-0930-build-t-solid-refactor）。
+//
+// 原单文件 885 行按职责（SRP）拆为 src/build/ 下四个模块，本文件只保留兼容出口——
+// 既有调用方（dev.ts / cli.ts / bundle.ts / market/bootstrap.ts / build-backend.test.ts，
+// 及经 package exports `./build` 复用的主仓 scripts/build-modules.ts）零改动：
+//
+//   module-def.ts    模块元数据读取（esbuild stub 机房 + readModuleDefinition）
+//   backend.ts       后端编排（oj build + 别名投影 + 密封值试解 + versions.json 双落点）
+//   site-merge.ts    宿主站点合并（shell-dist 全量 + index.html 改写）
+//   module-build.ts  前端模块构建（vite/rolldown + 产物完整性 + modules.json）
+//
+// 依赖方向无环：module-build → module-def / site-merge；其余互不依赖。
+export { buildBackend } from "./build/backend";
+export type { BuiltModule, ChunkEntry } from "./build/module-build";
+export { buildModules } from "./build/module-build";
+export { readModuleDefinition } from "./build/module-def";