@oj-module/cli 0.2.18 → 0.2.23

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

@@ -1,8 +1,9 @@
 // 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/                             ← 站点构建模块产物 → tgz 内 web/modules/（web.entry 存在性复核）
+//   web/dist/modules/<name>/                      ← 站点构建模块产物 → tgz 内 web/modules/<name>/（只入包方案自己的模块）
 // 禁携 modules.json（C2-31 红线）；产物确定性（C2-32）由 deterministic-tar 承担，此处断言端到端复现。
 import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -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 () => {
@@ -64,6 +83,16 @@ describe("buildBundle · 正路径", () => {
 			expect(names, `缺成员 ${member}`).toContain(`demo-solution-0.1.0/${member}`);
 	});
 
+	it("只入包方案自己的前端模块：模板模块（home/login…）不随包", async () => {
+		// 安装器 deployWeb 把包内 web/modules 整树覆盖进目标站，模板产物随包会覆盖宿主同名前端
+		const hostWeb = join(project, "web/dist/modules/home/0.1.0");
+		mkdirSync(hostWeb, { recursive: true });
+		writeFileSync(join(hostWeb, "entry.js"), "export default {};\n");
+		const names = tarList((await pack()).tgz);
+		expect(names.some(n => n.includes("/web/modules/home/"))).toBe(false);
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/0.1.0/entry.js");
+	});
+
 	it("端到端确定性：同一工程两次打包 sha256 相等（C2-32）", async () => {
 		const r1 = await pack();
 		const r2 = await pack();
@@ -75,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(/工程根契约优先/);
 	});
 });
 
@@ -96,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 () => {
@@ -116,6 +289,11 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 		await expect(pack()).rejects.toThrow(/web\/dist\/modules/);
 	});
 
+	it("web/dist/modules 在但缺本方案目录 → 可读报错（不整树入包）", async () => {
+		rmSync(join(project, "web/dist/modules/demo-solution"), { recursive: true, force: true });
+		await expect(pack()).rejects.toThrow(/web\/dist\/modules\/demo-solution\//);
+	});
+
 	it("c2-12a：api.tables 与 schema.yaml 表集不一致 → 构建期拒绝", async () => {
 		const m = readManifest();
 		m.api.tables = ["note", "ghost"];

package/src/lifecycle/__tests__/manifest-contract.test.ts

@@ -1,4 +1,4 @@
-import type { InstallContext } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+import type { InstallContext } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
 
 // BDD：bundle 级 manifest.yaml 契约校验（P1-11，C2 规则构建列）。
 // 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md（C2-01~33 构建列，§4.1 矩阵）；
@@ -13,7 +13,7 @@ import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
-import { preflight } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+import { preflight } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
 import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");

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

@@ -0,0 +1,129 @@
+// BDD：`ojm new <name>` 方案骨架生成（docs/plans/2026-10-22-1640-multi-solution-bundle-design.md §C）。
+// N0 非工程拒绝 / N1 骨架 round-trip（生成→补产物→buildBundle 直接过）/ N2 --api
+// N3 非法·保留·内置·重名拒绝 / N5 空名拒绝 / N6 历史布局拒绝 / N7 失败清理
+import fs, { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, writeFileSync as writeFileSyncOrig } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildBundle } from "../../bundle";
+import { createSolution } from "../../new";
+
+let project: string;
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-new-"));
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+/** 最小 module-root 工程面：web.config.ts + src/（含一个自带模块 home 与内置名单） */
+function makeModuleRootProject(builtin = true): void {
+	mkdirSync(join(project, "src", "home", "web"), { recursive: true });
+	writeFileSync(join(project, "src", "home", "web", "entry.ts"), "export default { name: \"home\" };\n");
+	writeFileSync(join(project, "web.config.ts"), "export default { baseUrl: \"\", modules: [] };\n");
+	if (builtin)
+		writeFileSync(join(project, "src", ".ojm-builtin.json"), JSON.stringify({ modules: ["home"] }));
+}
+
+/** 给已生成的方案补站点产物，模拟「ojm build 之后」的打包前置 */
+function addWebArtifacts(name: string, version = "0.1.0"): void {
+	const webDist = join(project, "web/dist/modules", name, version);
+	mkdirSync(webDist, { recursive: true });
+	writeFileSync(join(webDist, "entry.js"), "export default {};\n");
+}
+
+describe("createSolution · 守卫", () => {
+	it("n0 非 ojm 工程（无 web.config.ts / src/）→ 拒绝且零写入", () => {
+		expect(() => createSolution(project, "crm")).toThrow(/不是 ojm 工程/);
+		expect(existsSync(join(project, "src"))).toBe(false);
+	});
+
+	it("n6 历史布局工程（web/src 树）→ 拒绝 + 迁移指引", () => {
+		mkdirSync(join(project, "web", "src", "old"), { recursive: true });
+		writeFileSync(join(project, "web.config.ts"), "export default { modules: [] };\n");
+		expect(() => createSolution(project, "crm")).toThrow(/module-root/);
+		expect(existsSync(join(project, "src", "crm"))).toBe(false);
+	});
+
+	it("n3 非法名（大写/数字开头/路径穿越）→ 拒绝", () => {
+		makeModuleRootProject();
+		for (const bad of ["Crm", "9crm", "../crm", "bad name"])
+			expect(() => createSolution(project, bad)).toThrow(/非法/);
+	});
+
+	it("n3 保留名（system）与内置名（home）→ 拒绝 + 指引", () => {
+		makeModuleRootProject();
+		expect(() => createSolution(project, "system")).toThrow(/保留名/);
+		expect(() => createSolution(project, "home")).toThrow(/框架自带/);
+	});
+
+	it("n3 目录已存在（非内置共享目录撞名）→ 拒绝", () => {
+		makeModuleRootProject();
+		mkdirSync(join(project, "src", "crm"), { recursive: true });
+		expect(() => createSolution(project, "crm")).toThrow(/已存在/);
+	});
+
+	it("n5 空名 → 拒绝", () => {
+		makeModuleRootProject();
+		expect(() => createSolution(project, "")).toThrow(/非法/);
+	});
+});
+
+describe("createSolution · 生成", () => {
+	it("n1 生成 web 骨架：solution.yaml/entry.ts/页面/双语 locales 齐备，layout 写进 handle", () => {
+		makeModuleRootProject();
+		const r = createSolution(project, "crm", { layout: "container" });
+		expect(r.files).toHaveLength(5);
+		const entry = readFileSync(join(project, "src/crm/web/entry.ts"), "utf-8");
+		expect(entry).toContain("layout: \"container\"");
+		expect(entry).toContain("crm:menu.main");
+		expect(readFileSync(join(project, "src/crm/solution.yaml"), "utf-8")).toContain("name: crm");
+		expect(JSON.parse(readFileSync(join(project, "src/crm/web/locales/zh-CN.json"), "utf-8")).menu.main).toBeTruthy();
+		expect(JSON.parse(readFileSync(join(project, "src/crm/web/locales/en-US.json"), "utf-8")).menu.main).toBeTruthy();
+		// --layout none
+		createSolution(project, "erp", { layout: "none" });
+		expect(readFileSync(join(project, "src/erp/web/entry.ts"), "utf-8")).toContain("layout: \"none\"");
+	});
+
+	it("n1 round-trip：生成的骨架补产物后 buildBundle({ name }) 直接过", async () => {
+		makeModuleRootProject();
+		createSolution(project, "crm");
+		addWebArtifacts("crm");
+		const results = await buildBundle(project, { out: join(project, "dist"), name: "crm" });
+		expect(results.map(r => r.name)).toEqual(["crm"]);
+		expect(existsSync(results[0]!.tgz)).toBe(true);
+	});
+
+	it("n2 --api：额外生成 api 骨架且 solution.yaml 含 api 段", () => {
+		makeModuleRootProject();
+		createSolution(project, "crm", { api: true });
+		expect(existsSync(join(project, "src/crm/api/manifest.yaml"))).toBe(true);
+		expect(readFileSync(join(project, "src/crm/api/manifest.yaml"), "utf-8")).toContain("name: crm");
+		expect(readFileSync(join(project, "src/crm/api/api.ts"), "utf-8")).toContain("/api/crm/ping");
+		const sol = readFileSync(join(project, "src/crm/solution.yaml"), "utf-8");
+		expect(sol).toContain("api:");
+		expect(sol).toContain("prefix: /api/crm");
+	});
+
+	it("n7 生成中途失败 → 不残留半截 src/<name>/", () => {
+		makeModuleRootProject();
+		// 让第二次写盘（entry.ts）必失败：首写（solution.yaml）成功后触发清理路径——
+		// 预置冲突文件会先在「目录已存在」守卫被拒，测不到 rmSync 回滚（审查发现 n7 旧用例假绿）
+		let calls = 0;
+		const spy = vi.spyOn(fs, "writeFileSync").mockImplementation(((...args: unknown[]) => {
+			calls++;
+			if (calls === 2)
+				throw new Error("ENOSPC: disk full");
+			return (writeFileSyncOrig as (...a: unknown[]) => unknown)(...args);
+		}) as typeof fs.writeFileSync);
+		try {
+			expect(() => createSolution(project, "crm")).toThrow(/disk full/);
+		}
+		finally {
+			spy.mockRestore();
+		}
+		expect(existsSync(join(project, "src", "crm"))).toBe(false);
+	});
+});

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

@@ -49,7 +49,8 @@ describe.skipIf(!smokeReady)("真机冒烟（需 OJM_SMOKE_URL/OJM_SMOKE_USER/OJ
 		mkdirSync(webDist, { recursive: true });
 		writeFileSync(join(webDist, "entry.js"), "export default {};\n");
 		writeFileSync(join(webDist, "demo-solution.css"), ".demo{}\n");
-		const { tgz } = await buildBundle(project, { out: join(project, "dist") });
+		const [built] = await buildBundle(project, { out: join(project, "dist") });
+		const { tgz } = built!;
 
 		const record = await installCommand(tgz, { url: SMOKE_URL ?? DEFAULT_SITE_URL, user: SMOKE_USER, pass: SMOKE_PASS });
 		expect(record.status).toBe("done");

package/src/manifest-contract.ts

@@ -16,11 +16,24 @@ export type ParseResult = { ok: true, manifest: BundleManifest } | { ok: false,
 
 // ── 契约 §2/§4 正则与清单（与 preflight.ts 逐字对应；改动须先改契约再同步双端与夹具）──
 
-/** C2-01：name 白名单 */
-const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+/** C2-01：name 白名单（导出供 ojm new/--bundle <name> 入口校验共用，DRY） */
+export const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+/**
+ * 方案名入口校验（`--bundle <name>` / `ojm new <name>` 共用，先校验再拼路径）：
+ * 与契约 C2-01 同一条正则；入口先给可读错误，契约校验再做正式判罚。
+ * 放在这里而非 bundle.ts——new 入口不应拖入打包模块图（esbuild/deterministic-tar 等）。
+ */
+export function assertValidSolutionName(name: string, where: string): void {
+	if (!NAME_RE.test(name)) {
+		throw new Error(
+			`[ojm] ${where}：「${name}」非法——须为 kebab-case（小写字母/数字/连字符，首字符为小写字母）。`,
+		);
+	}
+}
 
 /** §4.2 保留名清单（C2-01/13/14 共用；market 经 R9 恢复保留） */
-const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market", "framework", "health", "plugins", "_system"]);
+export const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market", "framework", "health", "plugins", "_system"]);
 
 /** C2-02 字符集：[0-9A-Za-z.-]（禁 +——oj validate_version 拒装，附录 B-1；禁 _——契约收紧） */
 const VERSION_CHARS_RE = /^[0-9A-Z.-]+$/i;

package/src/market/__tests__/bootstrap.test.ts

@@ -28,8 +28,16 @@ function fakeStarter() {
 function newSourceProject(): string {
 	const root = mkdtempSync(join(tmpdir(), "ojm-bootstrap-src-"));
 	mkdirSync(join(root, "bin", "plugins"), { recursive: true });
-	writeFileSync(join(root, "bin", "oj"), "#!/bin/sh\necho fake-oj\n", { mode: 0o755 });
-	writeFileSync(join(root, "bin", ".oj-version"), "v0.1.84\n");
+	// 假 oj 必须过 §7 双探：`-V` 报版本、`build --help` 含 --module-root，否则 buildBackend 在闸门处 fail-fast
+	writeFileSync(
+		join(root, "bin", "oj"),
+		"#!/bin/sh\n"
+		+ "if [ \"$1\" = \"-V\" ]; then echo oj 0.1.85; exit 0; fi\n"
+		+ "if [ \"$1\" = \"build\" ]; then echo \"      --module-root <MODULE_ROOT>  源码树根\"; exit 0; fi\n"
+		+ "echo fake-oj\n",
+		{ mode: 0o755 },
+	);
+	writeFileSync(join(root, "bin", ".oj-version"), "v0.1.85\n");
 	writeFileSync(join(root, "bin", "plugins", "auth.wasm"), "plugin", "utf-8");
 	mkdirSync(join(root, "api", "src", "_platform"), { recursive: true });
 	writeFileSync(join(root, "api", "src", "_platform", "seed.sql"), "-- seed\n", "utf-8");
@@ -60,7 +68,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
 
-		expect(existsSync(join(site.root, "api", "src", "_platform", "seed.sql"))).toBe(true);
+		expect(existsSync(join(site.root, "src", "_platform", "api", "seed.sql"))).toBe(true);
 		expect(existsSync(join(site.root, "bin", "oj"))).toBe(true);
 		expect(existsSync(join(site.root, "bin", "plugins", "auth.wasm"))).toBe(true);
 		expect(site.root).not.toBe(src);
@@ -75,8 +83,8 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		expect(site.port).toBeGreaterThan(1024);
 		expect(site.port).not.toBe(9778);
-		expect(started[0]?.configPath).toBe(join(site.root, "api", "config.yaml"));
-		const cfg = readFileSync(join(site.root, "api", "config.yaml"), "utf-8");
+		expect(started[0]?.configPath).toBe(join(site.root, "config.yaml"));
+		const cfg = readFileSync(join(site.root, "config.yaml"), "utf-8");
 		expect(cfg).toContain(`port: ${site.port}`);
 		await site.cleanup();
 	});
@@ -87,7 +95,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
 
-		const cfg = readFileSync(join(site.root, "api", "config.yaml"), "utf-8");
+		const cfg = readFileSync(join(site.root, "config.yaml"), "utf-8");
 		expect(cfg).not.toContain("__JWT_SECRET__");
 		await site.cleanup();
 	});
@@ -113,7 +121,8 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		expect(site.publisher.privateKeyPem).toContain("PRIVATE KEY");
 		const pemFiles = listFiles(site.root).filter(f => f.endsWith(".pem"));
-		const outside = pemFiles.filter(f => !f.includes("api/config"));
+		// listFiles 返回相对隔离根的路径；站点自身证书三件套在 config/ 下，其余任何 PEM 都是泄漏
+		const outside = pemFiles.filter(f => !f.startsWith("config/"));
 		expect(outside).toEqual([]);
 		await site.cleanup();
 	});
@@ -144,8 +153,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 describe("given 源工程没装 oj 二进制 When 自举", () => {
 	it("then 人话报错指向 ojm vendor，且不留半成品临时根", async () => {
 		const root = mkdtempSync(join(tmpdir(), "ojm-bootstrap-nooj-"));
-		mkdirSync(join(root, "api"), { recursive: true });
-		writeFileSync(join(root, "api", "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+		writeFileSync(join(root, "config.yaml"), "server:\n  port: 9778\n", "utf-8");
 		const { starter } = fakeStarter();
 
 		await expect(bootstrapIsolatedSite({ projectRoot: root, starter }))

package/src/market/bootstrap.ts

@@ -18,7 +18,7 @@
 import type { OjProcess } from "../oj";
 import { Buffer } from "node:buffer";
 import { createHash, createPrivateKey, randomBytes } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import net from "node:net";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -26,6 +26,7 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { buildBackend } from "../build";
+import { resolveLayout } from "../layout";
 import { exportRawPublicKeyHex, fingerprintOfPublicKey } from "../lifecycle/sign";
 import { startOj } from "../oj";
 import { mintDevCert } from "../oj-cert";
@@ -49,7 +50,7 @@ export interface IsolatedPublisher {
 }
 
 export interface IsolatedSite {
-	/** 临时根（含 api/ bin/ cdn/） */
+	/** 临时根（含 config.yaml / src/ / api/dist/ / bin/ / cdn/） */
 	root: string
 	port: number
 	baseUrl: string
@@ -94,19 +95,26 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	}
 
 	const root = mkdtempSync(path.join(tmpdir(), "ojm-trial-"));
-	const apiDir = path.join(root, "api");
-	const configPath = path.join(apiDir, "config.yaml");
+	// 新布局（`src/<name>/{api,web}`）：config.yaml 在隔离根，源码树根为 <root>/src，
+	// 构建产物仍是扁平根 <root>/api/dist（与真实工程同形）。
+	const srcDir = path.join(root, "src");
+	const configPath = path.join(root, "config.yaml");
 	const cdnDir = path.join(root, "cdn");
-	const dbPath = path.join(apiDir, "db.sqlite");
+	const dbPath = path.join(root, "db.sqlite");
 
-	// 1) api 树 + config（模板由 cli 包内置，init 同源；与 cli→templates 依赖红线不冲突——那是运行期文件而非 import）
+	// 1) 后端源码树 + config（模板由 cli 包内置，init 同源；与 cli→templates 依赖红线不冲突——那是运行期文件而非 import）
 	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-	const templateApi = path.join(cliRoot, "templates", "api");
-	if (!existsSync(path.join(templateApi, "config.yaml"))) {
-		throw new Error(`[ojm] cli 内置模板缺失：${templateApi}（@oj-module/cli 安装不完整？）`);
+	const templateDir = path.join(cliRoot, "templates");
+	if (!existsSync(path.join(templateDir, "config.yaml"))) {
+		throw new Error(`[ojm] cli 内置模板缺失：${templateDir}（@oj-module/cli 安装不完整？）`);
 	}
-	cpSync(path.join(templateApi, "src"), path.join(apiDir, "src"), { recursive: true });
-	writeFileSync(configPath, readFileSync(path.join(templateApi, "config.yaml"), "utf-8"), "utf-8");
+	// 只拷后端侧（`src/<name>/api`）：隔离站点不构建前端，web 源码拷过去只是噪音
+	for (const entry of readdirSync(path.join(templateDir, "src"), { withFileTypes: true })) {
+		const apiSide = path.join(templateDir, "src", entry.name, "api");
+		if (entry.isDirectory() && existsSync(apiSide))
+			cpSync(apiSide, path.join(srcDir, entry.name, "api"), { recursive: true });
+	}
+	writeFileSync(configPath, readFileSync(path.join(templateDir, "config.yaml"), "utf-8"), "utf-8");
 
 	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj 解析；plugins 让 auth 插件可用）
 	mkdirSync(path.join(root, "bin"), { recursive: true });
@@ -134,10 +142,13 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	const siteDir = path.join(root, "site");
 	mkdirSync(siteDir, { recursive: true });
 	writeFileSync(path.join(siteDir, "index.html"), "<!doctype html><html><body>ojm trial site</body></html>\n", "utf-8");
-	cfg = cfg.replace("web: ../cdn", `web: ${cdnDir}\n  - prefix: /\n    web: ${siteDir}\n    spa: true`);
+	cfg = cfg.replace("web: ./cdn", `web: ${cdnDir}\n  - prefix: /\n    web: ${siteDir}\n    spa: true`);
 	// 安装目标恒为 release 部署：装好的模块落在 api/dist，dev 形态（--api-path src）发现不了。
 	// 故隔离站点以 dist 起站，platform.root 同步改写（oj 校验 root 必须是生效的 api 挂载目录）。
-	cfg = cfg.replace("  root: src", "  root: dist");
+	// root 相对 **config 所在目录** 解析——config 在隔离根，产物在 <root>/api/dist，故不能写死
+	// `dist`（那是 config 还在 api/ 时的旧口径），按布局取值。
+	const apiDistRel = path.relative(root, resolveLayout(root).apiDist).split(path.sep).join("/");
+	cfg = cfg.replace("  root: src", `  root: ${apiDistRel}`);
 	// auth 守卫在装配期读 anonymous_paths，安装器注册的新匿名端点要重启才生效（首次安装 smoke 会 401）。
 	// 隔离站点直接预置被测方案的探活路径——与 scripts/verify-solution-smoke/bootstrap-host.mjs 同手法，
 	// 让 trial 验的是安装机制本身，而不是重启时序。
@@ -149,8 +160,8 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 		cfg = `${cfg.trimEnd()}\nfs:\n  root: .\n  readonly: false\n`;
 	writeFileSync(configPath, cfg, "utf-8");
 
-	// 4) 站点开发证书（oj serve 无绕过开关；mintDevCert 落 api/config 三件套）
-	await mintDevCert(path.join(apiDir, "config"));
+	// 4) 站点开发证书（oj serve 无绕过开关；mintDevCert 落 config.yaml 同级的 config/ 三件套）
+	await mintDevCert(path.join(root, "config"));
 
 	// 5) 一次性发布方身份：seed 派生，私钥只在内存
 	const keyId = "trial.publisher";
@@ -168,7 +179,7 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	const starter = opts.starter ?? ((cfgPath: string, base: string, apiSrc: string) => startOj(cfgPath, base, apiSrc));
 	let oj: OjProcess;
 	try {
-		oj = starter(configPath, "/api", path.join(apiDir, "dist"));
+		oj = starter(configPath, "/api", path.join(root, "api", "dist"));
 		await oj.ready;
 	}
 	catch (error) {
@@ -245,7 +256,9 @@ function freePort(): Promise<number> {
 function teardownReport(root: string, port: number): string[] {
 	const lines = [
 		`隔离根：${root}`,
-		"  api/    站点树（src + config.yaml + config/ 证书 + db.sqlite）",
+		"  config.yaml + config/ 证书 + db.sqlite   站点配置面",
+		"  src/    后端模块源码树（src/<name>/api，拷自 cli 内置模板）",
+		"  api/dist/  构建产物（安装目标）",
 		"  bin/    oj 二进制与插件（拷贝自源工程）",
 		"  cdn/    隔离 CDN（fixture 包 + 两份索引 + 签名）",
 		`监听端口：127.0.0.1:${port}（进程已停）`,

package/src/market/publish.ts

@@ -118,9 +118,17 @@ async function buildFixture(args: { fixture?: string, staging: string, cdnDir: s
 	return { name: spec.name, version: spec.version, tgzPath, sha256, preExisted: before.exists };
 }
 
-/** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录 */
+/** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录（一次只发一份：多方案工程请显式指定） */
 async function buildRealPackage(solutionRoot: string, staging: string, cdnDir: string): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
-	const built = await buildBundle(solutionRoot, { out: staging });
+	const builtList = await buildBundle(solutionRoot, { out: staging });
+	if (builtList.length !== 1) {
+		throw new Error(
+			`[ojm] market publish --real 一次只发布一份方案，但该工程打出了 ${builtList.length} 份用户方案。`
+			+ "请改用显式链路：在方案工程里 `ojm build --bundle <name>`，再 `ojm sign dist/<name>-<version>.tgz --id <publisher>.<key>`，"
+			+ "把 tgz + .sig 放进 cdn/ 后 `ojm market build-index`。",
+		);
+	}
+	const built = builtList[0]!;
 	const tgzPath = path.join(cdnDir, `${built.name}-${built.version}.tgz`);
 	const before = captureExisting(tgzPath);