@oj-module/cli 0.2.20 → 0.2.23

package/src/index.ts

@@ -1,12 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { parseApiArgs, parseBuildArgs, parseInitArgs, parseLifecycleArgs, parseVendorArgs } from "./args";
+import { parseApiArgs, parseBuildArgs, parseInitArgs, parseLifecycleArgs, parseNewArgs, parseVendorArgs } from "./args";
 import { buildBackend, buildModules } from "./build";
 import { buildBundle } from "./bundle";
 import { devServer } from "./dev";
 import { mergeManifests, printInfo } from "./info";
 import { initProject } from "./init";
+import { createSolution } from "./new";
 import { runPreview } from "./preview";
 import { getCommandHelp, resolveHelpRequest, usageText } from "./usage";
 import { vendorCommand } from "./vendor";
@@ -50,10 +51,13 @@ async function main() {
 
 	switch (command) {
 		case "build": {
-			const { bundle, out } = parseBuildArgs(process.argv.slice(3));
+			const { bundle, bundleName, out } = parseBuildArgs(process.argv.slice(3));
 			if (bundle) {
 				// 方案包构建（P1-11）：契约校验 fail-fast → 确定性 tgz + sha256（消费方：市场安装器）
-				await buildBundle(projectRoot, { out });
+				// 多方案：无 bundleName 打全部用户方案（自带排除），有则只打 name 那一份
+				const results = await buildBundle(projectRoot, { out, name: bundleName });
+				if (results.length > 1)
+					console.log(`[ojm] 共打包 ${results.length} 份方案包（逐包签名：ojm sign dist/<name>-<version>.tgz --id <publisher>.<key> --check）`);
 				break;
 			}
 			// 设计 §5：后端 oj build（零 DB 副作用）→ 前端全站合并（仅 build 清场合并）
@@ -61,6 +65,19 @@ async function main() {
 			await buildModules(projectRoot, { mergeSite: true });
 			break;
 		}
+		case "new": {
+			const { name, layout, api } = parseNewArgs(process.argv.slice(3));
+			if (!name) {
+				console.error("[ojm] 用法：ojm new <name> [--layout container|none] [--api]（非交互环境必须显式给 name）");
+				process.exit(1);
+			}
+			const created = createSolution(projectRoot, name, { layout, api });
+			console.log(`[ojm] 已生成方案骨架：${path.relative(process.cwd(), created.dir)}`);
+			for (const f of created.files)
+				console.log(`[ojm]   + ${f}`);
+			console.log(`[ojm] 下一步：pnpm dev 看效果 → ojm build && ojm build --bundle ${name} 打包`);
+			break;
+		}
 		case "init": {
 			const { dest, yes } = parseInitArgs(process.argv.slice(3));
 			await initProject(dest ? path.resolve(dest) : projectRoot, { yes });
@@ -79,7 +96,7 @@ async function main() {
 			break;
 		}
 		case "info":
-			await printInfo(projectRoot);
+			await printInfo(projectRoot, undefined, { all: process.argv.slice(3).includes("--all") });
 			break;
 		case "vendor": {
 			const { force, tag } = parseVendorArgs(process.argv.slice(3));
@@ -197,7 +214,10 @@ async function main() {
 
 main().catch((error: unknown) => {
 	// Error 的 message 已是人话（含修复指引）；堆栈默认是噪音，OJM_DEBUG=1 才输出
-	// （旧名 RAM_DEBUG 一并读，兼容既有排障习惯）
-	console.error(`[ojm] ${error instanceof Error ? ((process.env.OJM_DEBUG ?? process.env.RAM_DEBUG) ? error.stack : error.message) : String(error)}`);
+	// （旧名 RAM_DEBUG 一并读，兼容既有排障习惯）。
+	// 文案常自带 [ojm] 前缀（bundle/publish/sign 等抛出的错误），顶层不再叠一个，否则变 [ojm] [ojm]。
+	const isDebug = !!(process.env.OJM_DEBUG ?? process.env.RAM_DEBUG);
+	const body = error instanceof Error ? (isDebug ? error.stack ?? error.message : error.message) : String(error);
+	console.error(/^\[ojm/.test(body) ? body : `[ojm] ${body}`);
 	process.exit(1);
 });

package/src/info.ts

@@ -12,8 +12,9 @@ import fs from "node:fs";
 
 import http from "node:http";
 import path from "node:path";
-import { loadModulesConfig } from "./config";
-import { resolveConfigPath } from "./layout";
+import { readBuiltinModules } from "./builtin";
+import { loadModulesConfig, loadSiteConfig, mergeModuleList } from "./config";
+import { resolveConfigPath, scanModules, tryResolveLayout } from "./layout";
 import { mergeModuleManifests } from "./manifest";
 import { probeOjCaps } from "./oj-caps";
 import { readOjApiPrefix, readOjServerField } from "./oj-config";
@@ -91,7 +92,50 @@ export function realOjObservability(projectRoot: string): OjObservability {
 	};
 }
 
-export async function printInfo(projectRoot: string, oj: OjObservability = realOjObservability(projectRoot)): Promise<void> {
+export interface PrintInfoOptions {
+	/** 展开框架自带模块（默认折叠为一行计数） */
+	all?: boolean
+}
+
+/**
+ * 模块清单条目解析：module-root 用「扫描 + 登记覆盖」并集（与 build 同源，
+ * 未登记的用户模块也可见——旧实现只读 web.config.ts 会漏掉它们）；历史布局
+ * 维持登记清单（loadModulesConfig）。
+ */
+async function resolveModuleEntries(projectRoot: string): Promise<{ name: string, entry: string, enabled: boolean }[]> {
+	const layout = tryResolveLayout(projectRoot);
+	if (layout?.kind === "module-root") {
+		const config = await loadSiteConfig(projectRoot);
+		return mergeModuleList(scanModules(layout), config.modules, projectRoot);
+	}
+	const config = await loadModulesConfig(projectRoot);
+	return config.modules.map(m => ({ name: m.name, entry: m.entry, enabled: m.enabled !== false }));
+}
+
+/** 清单渲染：自带模块默认折叠（--all 展开）；坏名单文件告警降级为平铺，info 不失败 */
+function renderModuleLines(entries: { name: string, entry: string, enabled: boolean }[], projectRoot: string, all: boolean): string {
+	let builtin = new Set<string>();
+	try {
+		builtin = readBuiltinModules(projectRoot);
+	}
+	catch (error) {
+		console.warn(`[ojm] ⚠️ ${error instanceof Error ? error.message : String(error)}——本次按无内置名单渲染。`);
+	}
+	const fmt = (m: { name: string, entry: string, enabled: boolean }) => `  · ${m.name}（${m.entry}）${m.enabled ? "" : " [disabled]"}`;
+	const own = entries.filter(m => builtin.has(m.name));
+	const user = entries.filter(m => !builtin.has(m.name));
+	const lines = user.map(fmt);
+	if (own.length > 0) {
+		if (all)
+			lines.push(...own.map(fmt));
+		else
+			lines.push(`  框架自带：${own.length} 个（ojm info --all 展开）`);
+	}
+	// 零模块时留占位行，避免清单段整段空白像渲染故障
+	return lines.length > 0 ? lines.join("\n") : "（无 web 模块）";
+}
+
+export async function printInfo(projectRoot: string, oj: OjObservability = realOjObservability(projectRoot), opts: PrintInfoOptions = {}): Promise<void> {
 	const cliVersion = readPkgVersion(path.join(projectRoot, "node_modules/@oj-module/cli/package.json"));
 	const runtimeVersion = readPkgVersion(path.join(projectRoot, "node_modules/@oj-module/runtime/package.json"));
 
@@ -107,10 +151,8 @@ export async function printInfo(projectRoot: string, oj: OjObservability = realO
 
 	let moduleLines = "（web.config.ts 加载失败或无模块）";
 	try {
-		const config = await loadModulesConfig(projectRoot);
-		moduleLines = config.modules
-			.map(m => `  · ${m.name}（${m.entry}）${m.enabled === false ? " [disabled]" : ""}`)
-			.join("\n");
+		const entries = await resolveModuleEntries(projectRoot);
+		moduleLines = renderModuleLines(entries, projectRoot, opts.all ?? false);
 	}
 	catch (error) {
 		moduleLines = `（加载失败：${(error as Error).message}）`;

package/src/init.ts

@@ -17,6 +17,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import yaml from "yaml";
 import { ALIAS_PATHS_FILE, syncAliasPaths } from "./alias-paths";
+import { BUILTIN_LIST_FILE, writeBuiltinList } from "./builtin";
 import { resolveCertDir, resolveConfigPath } from "./layout";
 import { probeOjCaps } from "./oj-caps";
 import { mintDevCert } from "./oj-cert";
@@ -125,6 +126,14 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	}, report, include, templatesDir);
 	pruneUnincludedApiPaths(destDir, include, report);
 
+	// 1a) src/.ojm-builtin.json：脚手架自带模块身份（名单派生自上面的白名单，单一真源）。
+	//     copyIfAbsent：旧工程重跑 init 时缺失才补写，已存在不覆盖用户手改。
+	const builtinStatus = writeBuiltinList(destDir, include);
+	if (builtinStatus === "created")
+		report.created.push(`src/${BUILTIN_LIST_FILE}`);
+	else if (builtinStatus === "skipped")
+		report.skipped.push(`${BUILTIN_LIST_FILE}（已存在，不覆盖用户手改）`);
+
 	// 1b) tsconfig.paths.json：把 oj 别名 `#/<模块名>/…` 投影成 TS 的 paths。
 	//     必须**现场生成**而不是随模板拷贝——模板兼作 demo 工程（多出 demo/home 两个
 	//     模块），而用户工程只有白名单里的那些；照拷会让 paths 指向不存在的目录。
@@ -233,7 +242,7 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		console.log(`[ojm]   · 跳过 ${item}`);
 	for (const item of report.warnings)
 		console.warn(`[ojm]   ! ${item}`);
-	console.log("[ojm] 下一步：pnpm install && pnpm dev（登录 admin / 123456）");
+	console.log("[ojm] 下一步：pnpm install && pnpm dev（登录 superadmin / 123456，角色账号见 devkit 手册 §1.1）");
 }
 
 /** 默认密封器：bin/oj secret keygen + seal（失败返回 null，不抛） */
@@ -576,7 +585,8 @@ function mergePackageJson(existing: Record<string, any>, generated: Record<strin
 	return merged;
 }
 
-function generatePackageJson(cliRoot: string, projectName: string) {
+/** 生成脚手架 package.json（导出供守卫测试：scripts ⊆ 模板 scripts，防双写漂移） */
+export function generatePackageJson(cliRoot: string, projectName: string) {
 	const { matrix: hostVersions } = resolveVersionMatrix(cliRoot);
 	const cliPkg = JSON.parse(fs.readFileSync(path.join(cliRoot, "package.json"), "utf-8"));
 
@@ -626,11 +636,17 @@ function generatePackageJson(cliRoot: string, projectName: string) {
 		type: "module",
 		private: true,
 		scripts: {
-			dev: "ojm dev",
-			build: "ojm build",
-			preview: "ojm preview",
-			info: "ojm info",
-			typecheck: "tsc --noEmit -p tsconfig.json",
+			"dev": "ojm dev",
+			"build": "ojm build",
+			"preview": "ojm preview",
+			"info": "ojm info",
+			"typecheck": "tsc --noEmit -p tsconfig.json",
+			// typecheck:api 指向 src/tsconfig.json（后端工程面，白名单收录）——
+			// 早期生成器漏发这条（与模板双写漂移），补上并钉守卫测试
+			"typecheck:api": "tsc --noEmit -p src/tsconfig.json",
+			// 多方案（phase 2/3）：打包全部用户方案（自带自动排除）/ 生成新方案骨架
+			"bundle": "ojm build --bundle",
+			"new": "ojm new",
 		},
 		devDependencies: devDeps,
 	};

package/src/lifecycle/__tests__/args.test.ts

@@ -0,0 +1,20 @@
+// BDD：ojm new 参数解析（统一审查 F8——多余位置参数须显式拒绝，不能静默丢弃）。
+// 静默丢弃的恶果：ojm new crm erp（手滑/粘贴）只建 crm，用户以为两份都建了。
+import { describe, expect, it } from "vitest";
+import { parseNewArgs } from "../../args";
+
+describe("parseNewArgs", () => {
+	it("name + 旗标组合", () => {
+		expect(parseNewArgs(["crm"])).toEqual({ name: "crm", layout: undefined, api: false });
+		expect(parseNewArgs(["crm", "--layout", "none", "--api"])).toEqual({ name: "crm", layout: "none", api: true });
+		expect(parseNewArgs([])).toEqual({ name: undefined, layout: undefined, api: false });
+	});
+
+	it("多余位置参数 → 报错而非静默丢弃", () => {
+		expect(() => parseNewArgs(["crm", "erp"])).toThrow(/只接受一个方案名/);
+	});
+
+	it("非法 --layout 值 → 报错", () => {
+		expect(() => parseNewArgs(["crm", "--layout", "sidebar"])).toThrow(/container \| none/);
+	});
+});

package/src/lifecycle/__tests__/builtin.test.ts

@@ -0,0 +1,97 @@
+// BDD：脚手架自带模块身份（`src/.ojm-builtin.json`）。
+// 消费契约：bundle 排除打包 / ojm info 折叠 / ojm new 拒名；文件缺失 → 空名单（旧工程兼容）。
+// 用例对应设计 docs/plans/2026-10-22-1640-multi-solution-bundle-design.md：
+//   B12（坏文件 fail-fast）/ T1（名单 == 白名单派生集）/ T2（copyIfAbsent，不覆盖用户手改）
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { BUILTIN_LIST_FILE, deriveBuiltinModules, readBuiltinModules, writeBuiltinList } from "../../builtin";
+
+let project: string;
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-builtin-"));
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+function writeList(content: string): void {
+	mkdirSync(join(project, "src"), { recursive: true });
+	writeFileSync(join(project, "src", BUILTIN_LIST_FILE), content);
+}
+
+describe("readBuiltinModules", () => {
+	it("文件缺失 → 空名单（旧工程/框架仓无内置概念，行为退化兼容）", () => {
+		expect(readBuiltinModules(project).size).toBe(0);
+	});
+
+	it("合法文件 → 返回 modules 集合", () => {
+		writeList(JSON.stringify({ modules: ["auth", "home"] }));
+		expect([...readBuiltinModules(project)].sort()).toEqual(["auth", "home"]);
+	});
+
+	it("b12 坏 JSON → fail-fast，报错含文件路径与错因（不静默降级）", () => {
+		writeList("{ not json");
+		expect(() => readBuiltinModules(project)).toThrow(new RegExp(`${BUILTIN_LIST_FILE.replace(".", "\\.")}`));
+	});
+
+	it("b12 modules 非数组 → fail-fast", () => {
+		writeList(JSON.stringify({ modules: "auth" }));
+		expect(() => readBuiltinModules(project)).toThrow(/modules/);
+	});
+
+	it("b12 modules 含非字符串项 → fail-fast", () => {
+		writeList(JSON.stringify({ modules: ["auth", 42] }));
+		expect(() => readBuiltinModules(project)).toThrow(/modules/);
+	});
+});
+
+describe("deriveBuiltinModules（名单派生自 init.include.yaml，单一真源）", () => {
+	it("t1 取 src/<name>/(api|web) 条目的模块名（含 web-only 模块），忽略无关路径", () => {
+		const include = new Set([
+			"src/auth/api",
+			"src/notification/api",
+			"src/login/web/entry.ts",
+			"src/oj-market/web/pages",
+			"src/styles.css",
+			"src/tsconfig.json",
+			"config.yaml",
+			"web.config.ts",
+		]);
+		expect([...deriveBuiltinModules(include)].sort())
+			.toEqual(["auth", "login", "notification", "oj-market"]);
+	});
+
+	it("白名单无模块条目 → 空集（不凭空造身份）", () => {
+		expect(deriveBuiltinModules(new Set(["config.yaml", "README.md"])).size).toBe(0);
+	});
+});
+
+describe("writeBuiltinList（init 接线：copyIfAbsent）", () => {
+	it("t1 写入派生名单（排序）+ 自注释头，返回 created", () => {
+		const include = new Set(["src/home/web/entry.ts", "src/auth/api", "src/login/web"]);
+		expect(writeBuiltinList(project, include)).toBe("created");
+		const p = join(project, "src", BUILTIN_LIST_FILE);
+		expect(existsSync(p)).toBe(true);
+		const doc = JSON.parse(readFileSync(p, "utf-8"));
+		expect(doc.modules).toEqual(["auth", "home", "login"]);
+		expect(typeof doc["//"]).toBe("string");
+	});
+
+	it("t2 已存在 → 返回 skipped 且内容原样不动（用户手改权）", () => {
+		const include = new Set(["src/auth/api"]);
+		expect(writeBuiltinList(project, include)).toBe("created");
+		const p = join(project, "src", BUILTIN_LIST_FILE);
+		writeFileSync(p, JSON.stringify({ modules: ["my-edit"] }));
+		expect(writeBuiltinList(project, include)).toBe("skipped");
+		expect(JSON.parse(readFileSync(p, "utf-8")).modules).toEqual(["my-edit"]);
+	});
+
+	it("派生集为空 → 不写文件，返回 none", () => {
+		expect(writeBuiltinList(project, new Set(["config.yaml"]))).toBe("none");
+		expect(existsSync(join(project, "src", BUILTIN_LIST_FILE))).toBe(false);
+	});
+});

package/src/lifecycle/__tests__/bundle.test.ts

@@ -1,6 +1,7 @@
 // BDD：`ojm build --bundle` 方案包组装（P1-11）。
 // 组装契约（对齐 tgz 内布局，契约 §2.9 + P1-9 staging copy 源定版）：
-//   <root>/manifest.yaml                          ← 必填，契约校验 fail-fast 先于打包
+//   <root>/solution.yaml | manifest.yaml           ← 必填（solution.yaml 优先，避开 oj 的 api 枚举冲突），契约校验 fail-fast 先于打包
+//   <root>/src/<模块>/solution.yaml | manifest.yaml ← 模块级方案：契约与所打包模块同位（同优先级回退）
 //   api/dist/<name>-<version>/                    ← oj build 产物原样 → tgz 内 api/<name>-<version>/（C2-31 分层核对）
 //   web/dist/modules/<name>/                      ← 站点构建模块产物 → tgz 内 web/modules/<name>/（只入包方案自己的模块）
 // 禁携 modules.json（C2-31 红线）；产物确定性（C2-32）由 deterministic-tar 承担，此处断言端到端复现。
@@ -48,7 +49,25 @@ function makePrebuiltArtifacts(): void {
 	writeFileSync(join(webDist, "demo-solution.css"), ".demo{}\n");
 }
 
-const pack = () => buildBundle(project, { out });
+const pack = () => buildBundle(project, { out }).then(r => r[0]!);
+
+/** 造一个 web-only 用户方案（模块级契约 + 站点产物，无 api 段校验面最小） */
+function addWebSolution(name: string, version = "0.1.0"): void {
+	const dir = join(project, "src", name);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "solution.yaml"), [
+		`name: ${name}`,
+		`version: ${version}`,
+		`summary: ${name} 用户方案`,
+		`changelog: ${name} 首个版本`,
+		"web:",
+		`  entry: modules/${name}/${version}/entry.js`,
+		"",
+	].join("\n"));
+	const webDist = join(project, "web/dist/modules", name, version);
+	mkdirSync(webDist, { recursive: true });
+	writeFileSync(join(webDist, "entry.js"), "export default {};\n");
+}
 
 describe("buildBundle · 正路径", () => {
 	it("产出 out/<name>-<version>.tgz + 64 位 sha256，布局单根三分（manifest/api/web）", async () => {
@@ -85,17 +104,161 @@ describe("buildBundle · 正路径", () => {
 		expect(tarList(r.tgz).some(n => n.endsWith("/modules.json"))).toBe(false);
 	});
 
+	it("solution.yaml 作为 bundle 契约（优先于 manifest.yaml，避开 oj 按 manifest.yaml 枚举 api 后端的冲突）", async () => {
+		// 根目录若用 manifest.yaml 当 bundle 契约，会被 oj 的 api 模块搜索枚举误判为 api 模块；
+		// 故解决方案改用 solution.yaml，bundle 工具优先认它（manifest.yaml 仅旧方案回退）。
+		const mf = join(project, "manifest.yaml");
+		const sf = join(project, "solution.yaml");
+		cpSync(mf, sf);
+		rmSync(mf);
+		const r = await pack();
+		expect(r.name).toBe("demo-solution");
+		expect(existsSync(r.tgz)).toBe(true);
+		// tgz 内固定为 manifest.yaml（安装侧只认这个名字），与源文件名无关
+		const names = tarList(r.tgz);
+		expect(names).toContain("demo-solution-0.1.0/manifest.yaml");
+		expect(names.some(n => n.endsWith("/solution.yaml"))).toBe(false);
+	});
+
+	it("src/<模块>/solution.yaml 作为 bundle 契约（模块级方案：契约与所打包模块同位）", async () => {
+		// 单模块方案：契约紧贴它打包的模块 src/<name>/，比工程根更直观；
+		// 仍不在 api/ 下、也不叫 manifest.yaml，等价避开 oj 按 manifest.yaml 枚举 api 后端的冲突。
+		const mf = join(project, "manifest.yaml");
+		const sf = join(project, "src/demo-solution/solution.yaml");
+		mkdirSync(dirname(sf), { recursive: true });
+		cpSync(mf, sf);
+		rmSync(mf);
+		const r = await pack();
+		expect(r.name).toBe("demo-solution");
+		expect(existsSync(r.tgz)).toBe(true);
+		// tgz 内固定为 manifest.yaml（安装侧只认这个名字），与源文件名/源位置无关
+		const names = tarList(r.tgz);
+		expect(names).toContain("demo-solution-0.1.0/manifest.yaml");
+		expect(names.some(n => n.endsWith("/solution.yaml"))).toBe(false);
+	});
+
+	it("src/ 下多份模块级契约 → 全部打包（多方案；B2）", async () => {
+		// 多方案正是本特性要支持的场景：每份契约独立校验、独立出包
+		rmSync(join(project, "manifest.yaml"));
+		addWebSolution("mod-a");
+		addWebSolution("mod-b");
+		const results = await buildBundle(project, { out });
+		expect(results.map(r => r.name).sort()).toEqual(["mod-a", "mod-b"]);
+		for (const r of results)
+			expect(existsSync(r.tgz)).toBe(true);
+	});
+
 	it("产物树混入 modules.json → 打包自检拒绝（C2-31 红线）", async () => {
 		writeFileSync(join(project, "web/dist/modules/demo-solution/0.1.0/modules.json"), "[]");
 		await expect(pack()).rejects.toThrow(/modules\.json/);
 	});
 
-	it("私钥/凭证混入包树 → 打包自检拒绝（P2-4 入包红线：*.pem/*.key/.env/id_ed25519/id_rsa）", async () => {
+	it("私钥/凭证混入包树 → 打包自检拒绝（P2-4 入包红线：*.pem/*.key/.env(.local…)/id_ed25519/id_rsa/*.p12/*.pfx）", async () => {
 		writeFileSync(join(project, "api/dist/demo-solution-0.1.0/signing.pem"), "-----BEGIN PRIVATE KEY-----\n");
 		await expect(pack()).rejects.toThrow(/私钥\/凭证/);
 		rmSync(join(project, "api/dist/demo-solution-0.1.0/signing.pem"));
 		writeFileSync(join(project, "web/dist/modules/demo-solution/0.1.0/.env"), "SECRET=1\n");
 		await expect(pack()).rejects.toThrow(/私钥\/凭证/);
+		rmSync(join(project, "web/dist/modules/demo-solution/0.1.0/.env"));
+		writeFileSync(join(project, "web/dist/modules/demo-solution/0.1.0/.env.production"), "SECRET=1\n");
+		await expect(pack()).rejects.toThrow(/私钥\/凭证/);
+	});
+});
+
+describe("buildBundle · 多方案与内置排除（B3/B7/B8/B9/B10/B12）", () => {
+	it("b3 内置方案跳过：名单内的模块契约不出包，用户契约照打", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		addWebSolution("crm");
+		addWebSolution("oj-market"); // 自带方案也带契约（第一方可分发形态）
+		mkdirSync(join(project, "src"), { recursive: true });
+		writeFileSync(join(project, "src/.ojm-builtin.json"), JSON.stringify({ modules: ["oj-market"] }));
+		const results = await buildBundle(project, { out });
+		expect(results.map(r => r.name)).toEqual(["crm"]);
+	});
+
+	it("b6/B3 无名单文件 → 无内置概念，多份契约全部打包", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		addWebSolution("crm");
+		addWebSolution("oj-market");
+		const results = await buildBundle(project, { out });
+		expect(results.map(r => r.name).sort()).toEqual(["crm", "oj-market"]);
+	});
+
+	it("b7+B8：目录不同契约 name 撞车 → 被 name===目录名 校验拦下（B8 使 B7 向量不可达，决策见计划文档）", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		addWebSolution("crm");
+		// 拷贝改目录忘改 name 的典型症状——B8 在收集期即拒，dist/ 不会出现同名产物
+		const dir = join(project, "src", "crm-copy");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "solution.yaml"), "name: crm\nversion: 0.1.0\nsummary: dup\nchangelog: x\nweb:\n  entry: modules/crm/0.1.0/entry.js\n");
+		await expect(buildBundle(project, { out })).rejects.toThrow(/与目录名「crm-copy」不一致/);
+	});
+
+	it("b8 模块级契约 name ≠ 目录名 → fail-fast", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		const dir = join(project, "src", "crm");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "solution.yaml"), "name: erp\nversion: 0.1.0\nsummary: x\n");
+		await expect(pack()).rejects.toThrow(/与目录名「crm」不一致/);
+	});
+
+	it("b9 两段式：多契约其一校验失败 → dist/ 零增量", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		addWebSolution("crm");
+		// erp 契约违规（name 大写触发契约校验）
+		const dir = join(project, "src", "erp");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "solution.yaml"), "name: erp\nversion: 0.1.0\nsummary: x\n");
+		await expect(buildBundle(project, { out })).rejects.toThrow(/C2-08/);
+		expect(existsSync(join(out, "crm-0.1.0.tgz"))).toBe(false);
+	});
+
+	it("b10 旧契约回退：src/<name>/manifest.yaml（非内置）参与收集", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		const dir = join(project, "src", "crm");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "manifest.yaml"), "name: crm\nversion: 0.1.0\nsummary: x\nchangelog: x\nweb:\n  entry: modules/crm/0.1.0/entry.js\n");
+		const webDist = join(project, "web/dist/modules/crm/0.1.0");
+		mkdirSync(webDist, { recursive: true });
+		writeFileSync(join(webDist, "entry.js"), "export default {};\n");
+		const results = await buildBundle(project, { out });
+		expect(results.map(r => r.name)).toEqual(["crm"]);
+	});
+
+	it("b12 坏 .ojm-builtin.json → fail-fast 报路径与错因", async () => {
+		mkdirSync(join(project, "src"), { recursive: true });
+		writeFileSync(join(project, "src/.ojm-builtin.json"), "{ not json");
+		await expect(pack()).rejects.toThrow(/\.ojm-builtin\.json/);
+	});
+
+	it("b4 --bundle <name>：按名打包；内置名拒绝；非法名拒绝", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		addWebSolution("crm");
+		addWebSolution("erp");
+		const one = await buildBundle(project, { out, name: "crm" });
+		expect(one.map(r => r.name)).toEqual(["crm"]);
+		await expect(buildBundle(project, { out, name: "erp2" })).rejects.toThrow(/未找到「erp2」/);
+		writeFileSync(join(project, "src/.ojm-builtin.json"), JSON.stringify({ modules: ["erp"] }));
+		await expect(buildBundle(project, { out, name: "erp" })).rejects.toThrow(/框架自带方案/);
+		await expect(buildBundle(project, { out, name: "../evil" })).rejects.toThrow(/非法/);
+		await expect(buildBundle(project, { out, name: "Bad Name" })).rejects.toThrow(/非法/);
+	});
+
+	it("b1 根契约优先于 src 契约（旧行为）+ B11 hint", async () => {
+		addWebSolution("crm"); // 根 manifest.yaml（demo-solution）仍在
+		const spy: string[] = [];
+		const orig = console.log;
+		console.log = (m?: unknown) => {
+			spy.push(String(m));
+		};
+		try {
+			const results = await buildBundle(project, { out });
+			expect(results.map(r => r.name)).toEqual(["demo-solution"]);
+		}
+		finally {
+			console.log = orig;
+		}
+		expect(spy.join("\n")).toMatch(/工程根契约优先/);
 	});
 });
 
@@ -106,9 +269,9 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 		expect(existsSync(join(out, "Demo-1.0.0+build.5.tgz"))).toBe(false);
 	});
 
-	it("manifest.yaml 缺失：可读报错指明期望路径", async () => {
+	it("manifest.yaml 缺失且无用户方案：可读报错指向 ojm new（B5）", async () => {
 		rmSync(join(project, "manifest.yaml"));
-		await expect(pack()).rejects.toThrow(/manifest\.yaml/);
+		await expect(pack()).rejects.toThrow(/没有可打包的用户方案/);
 	});
 
 	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 放行（等值要求已移除）", async () => {