@oj-module/cli 0.2.18 → 0.2.23

package/src/__tests__/init-packagejson.test.ts

@@ -0,0 +1,29 @@
+// BDD：脚手架 package.json scripts 与模板的双写守卫（T3，发布工程师评审建议）。
+// 生成器（init.ts generatePackageJson）与模板（templates/package.json）各写一份 scripts，
+// 人肉同步必漂移（实证：typecheck:api 曾漏发生成器）——钉成测试：生成 scripts 的每个键
+// 都必须存在于模板 scripts（值一致），新增 script 先改模板再改生成器。
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { generatePackageJson } from "../init";
+
+const cliRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+describe("脚手架 package.json scripts 双写守卫（T3）", () => {
+	it("生成 scripts 的每个键都存在于模板且值一致", () => {
+		const template = JSON.parse(readFileSync(join(cliRoot, "templates/package.json"), "utf-8"));
+		const generated = generatePackageJson(cliRoot, "guard-check");
+		for (const [key, value] of Object.entries(generated.scripts)) {
+			expect(template.scripts[key], `生成器有而模板无的 script：${key}（先改 templates/package.json）`)
+				.toBe(value);
+		}
+	});
+
+	it("多方案 scripts 齐备：new / bundle / typecheck:api", () => {
+		const generated = generatePackageJson(cliRoot, "guard-check");
+		expect(generated.scripts.new).toBe("ojm new");
+		expect(generated.scripts.bundle).toBe("ojm build --bundle");
+		expect(generated.scripts["typecheck:api"]).toBe("tsc --noEmit -p src/tsconfig.json");
+	});
+});

package/src/__tests__/layout.test.ts

@@ -0,0 +1,176 @@
+// layout spec：三种布局的探测、互斥、模块枚举与 config 落点。
+//
+// 这些取值是 dev/build/preview/bundle 的共同底座：探测错一次，`ojm build` 会构建 A
+// 而 `ojm dev` 预览 B，或产物写进空目录后表现为「health 200、模块 0 个」的假绿。
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import {
+	apiSrcOf,
+	moduleDir,
+	resolveCertDir,
+	resolveConfigPath,
+	resolveLayout,
+	scanModules,
+	webSrcOf,
+} from "../layout";
+
+function newRoot(): string {
+	return mkdtempSync(join(tmpdir(), "ojm-layout-"));
+}
+
+function writeFile(root: string, rel: string, content = ""): void {
+	const abs = join(root, rel);
+	mkdirSync(join(abs, ".."), { recursive: true });
+	writeFileSync(abs, content, "utf-8");
+}
+
+/** 新布局的最小工程：src/wiki/{api/manifest.yaml, web/entry.ts} + 根 config.yaml */
+function newModuleRootProject(): string {
+	const root = newRoot();
+	writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+	writeFile(root, "src/wiki/web/entry.ts", "export default {};\n");
+	writeFile(root, "config.yaml", "server:\n  port: 9778\n");
+	return root;
+}
+
+describe("resolveLayout / module-root", () => {
+	it("src/<name>/{api,web} 命中 module-root，产物根语义不变", () => {
+		const root = newModuleRootProject();
+		const layout = resolveLayout(root);
+
+		expect(layout.kind).toBe("module-root");
+		expect(layout.modulesSrc).toBe(join(root, "src"));
+		expect(layout.distDir).toBe(join(root, "web", "dist"));
+		expect(layout.apiDist).toBe(join(root, "api", "dist"));
+		expect(layout.watchTarget).toBe(join(root, "src"));
+		// --module-root 取「源码树根目录」（oj 在其子树内递归找 manifest.yaml）
+		expect(layout.moduleRoot).toBe(join(root, "src"));
+	});
+
+	it("web/dist 存在不会被误判成 flat 布局", () => {
+		const root = newModuleRootProject();
+		mkdirSync(join(root, "web", "dist", "modules", "wiki", "0.1.0"), { recursive: true });
+		expect(resolveLayout(root).kind).toBe("module-root");
+	});
+
+	it("枚举真源是标记文件：一侧可缺省，纯后端 / 纯前端各算一个模块", () => {
+		const root = newRoot();
+		writeFile(root, "src/_platform/api/manifest.yaml", "name: _platform\nversion: 0.1.0\n");
+		writeFile(root, "src/auth/api/manifest.yaml", "name: auth\nversion: 0.1.0\n");
+		writeFile(root, "src/about/web/entry.ts", "export default {};\n");
+
+		// 按名字排序（不依赖 readdir 顺序，产物才可复现）
+		const modules = scanModules(resolveLayout(root));
+		expect(modules.map(m => m.name)).toEqual(["_platform", "about", "auth"]);
+		expect(modules.map(m => !!m.apiSrc)).toEqual([true, false, true]);
+		expect(modules.map(m => !!m.webSrc)).toEqual([false, true, false]);
+		expect(modules[0].apiSrc).toBe(join(root, "src", "_platform", "api"));
+		expect(modules[1].webSrc).toBe(join(root, "src", "about", "web"));
+	});
+
+	it("非模块目录（既无 api/ 也无 web/，如共享库）静默跳过", () => {
+		const root = newRoot();
+		writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+		writeFile(root, "src/shared/util.ts", "export const x = 1;\n");
+		expect(scanModules(resolveLayout(root)).map(m => m.name)).toEqual(["wiki"]);
+	});
+
+	it("有 api/ 却缺 manifest.yaml：报错并指名目录（不静默当成非模块）", () => {
+		const root = newRoot();
+		writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+		writeFile(root, "src/broken/api/index.js", "export {};\n");
+		expect(() => resolveLayout(root)).toThrow(/src\/broken\//);
+	});
+
+	it("src/ 下没有任何模块标记时不算 module-root（避免把脚本 src/ 当模块树）", () => {
+		const root = newRoot();
+		mkdirSync(join(root, "src", "scripts"), { recursive: true });
+		expect(() => resolveLayout(root)).toThrow(/未发现模块源码/);
+	});
+});
+
+describe("resolveLayout / 历史布局", () => {
+	it("web/src 仍识别为 new，模块根不在 src/ 之下", () => {
+		const root = newRoot();
+		writeFile(root, "web/src/wiki/entry.ts", "export default {};\n");
+		writeFile(root, "api/src/wiki/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+
+		const layout = resolveLayout(root);
+		expect(layout.kind).toBe("new");
+		expect(layout.modulesSrc).toBe(join(root, "web", "src"));
+		expect(layout.moduleRoot).toBeUndefined();
+		expect(apiSrcOf(layout, "wiki")).toBe(join(root, "api", "src", "wiki"));
+		expect(webSrcOf(layout, "wiki")).toBe(join(root, "web", "src", "wiki"));
+	});
+
+	it("web/<name>/entry.ts 识别为 flat，产物落 build/", () => {
+		const root = newRoot();
+		writeFile(root, "web/home/entry.ts", "export default {};\n");
+		writeFile(root, "web/home/__client/api.ts", "export {};\n");
+
+		const layout = resolveLayout(root);
+		expect(layout.kind).toBe("flat");
+		expect(layout.modulesSrc).toBe(join(root, "web"));
+		expect(layout.distDir).toBe(join(root, "build"));
+		expect(webSrcOf(layout, "home")).toBe(join(root, "web", "home"));
+	});
+
+	it("历史布局不支持 scanModules（顺序由 web.config.ts 决定）", () => {
+		const root = newRoot();
+		writeFile(root, "web/src/wiki/entry.ts", "export default {};\n");
+		expect(() => scanModules(resolveLayout(root))).toThrow(/只适用于 module-root/);
+	});
+});
+
+describe("resolveLayout / 互斥与缺省", () => {
+	it("两套源码树同时存在时报错，而不是静默选一个", () => {
+		const root = newModuleRootProject();
+		writeFile(root, "web/src/legacy/entry.ts", "export default {};\n");
+		expect(() => resolveLayout(root)).toThrow(/同时存在两套模块源码树/);
+	});
+
+	it("什么布局都没有时报错并列出两种合法形状", () => {
+		const root = newRoot();
+		expect(() => resolveLayout(root)).toThrow(/未发现模块源码/);
+	});
+});
+
+describe("config 落点", () => {
+	it("module-root：config 与证书目录都在仓库根", () => {
+		const root = newModuleRootProject();
+		expect(resolveConfigPath(root)).toBe(join(root, "config.yaml"));
+		expect(resolveCertDir(root)).toBe(join(root, "config"));
+	});
+
+	it("module-root 仍把 config 留在 api/ 时报错（回退会让路由静默消失）", () => {
+		const root = newRoot();
+		writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+		writeFile(root, "api/config.yaml", "server:\n  port: 9778\n");
+		expect(() => resolveConfigPath(root)).toThrow(/仍在 api\/ 下/);
+	});
+
+	it("历史布局：config 与证书目录仍在 api/ 下", () => {
+		const root = newRoot();
+		writeFile(root, "web/src/wiki/entry.ts", "export default {};\n");
+		writeFile(root, "api/config.yaml", "server:\n  port: 9778\n");
+		expect(resolveConfigPath(root)).toBe(join(root, "api", "config.yaml"));
+		expect(resolveCertDir(root)).toBe(join(root, "api", "config"));
+	});
+
+	it("空目录（init 目标）不报错：落默认位置供脚手架写入", () => {
+		const root = newRoot();
+		expect(resolveConfigPath(root)).toBe(join(root, "api", "config.yaml"));
+	});
+});
+
+describe("路径取值函数", () => {
+	it("module-root：moduleDir / apiSrcOf / webSrcOf 都在 src/<name>/ 之下", () => {
+		const layout = resolveLayout(newModuleRootProject());
+		expect(moduleDir(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki"));
+		expect(apiSrcOf(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki", "api"));
+		expect(webSrcOf(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki", "web"));
+	});
+});

package/src/__tests__/module-list.test.ts

@@ -0,0 +1,66 @@
+// 前端模块清单 spec（设计 D3：扫描为准 + web.config.ts 可选覆盖）。
+//
+// 关键不变量是**并集而不是替换**：新增一个模块目录后忘了登记，也必须被构建；
+// 反过来登记了一个已经不存在的目录，必须报错而不是静默少一个模块。
+import { describe, expect, it } from "vitest";
+
+import { mergeModuleList } from "../config";
+
+const ROOT = "/proj";
+
+function scanned(...names: string[]) {
+	return names.map(name => ({ name, webSrc: `${ROOT}/src/${name}/web` }));
+}
+
+describe("mergeModuleList", () => {
+	it("无覆盖时按扫描顺序（layout 已按名字排序）", () => {
+		expect(mergeModuleList(scanned("about", "home", "wiki"), undefined, ROOT)).toEqual([
+			{ name: "about", entry: "src/about/web/entry.ts", enabled: true },
+			{ name: "home", entry: "src/home/web/entry.ts", enabled: true },
+			{ name: "wiki", entry: "src/wiki/web/entry.ts", enabled: true },
+		]);
+	});
+
+	it("覆盖项按声明顺序排前，未登记的按扫描顺序追加（并集）", () => {
+		const list = mergeModuleList(scanned("about", "home", "wiki"), [
+			{ name: "home", entry: "ignored" },
+			{ name: "wiki", entry: "ignored" },
+		], ROOT);
+		expect(list.map(m => m.name)).toEqual(["home", "wiki", "about"]);
+	});
+
+	it("enabled:false 仍生效（覆盖项与未登记项都按自己的声明走）", () => {
+		const list = mergeModuleList(scanned("about", "home"), [
+			{ name: "home", entry: "x", enabled: false },
+		], ROOT);
+		expect(list).toEqual([
+			{ name: "home", entry: "src/home/web/entry.ts", enabled: false },
+			{ name: "about", entry: "src/about/web/entry.ts", enabled: true },
+		]);
+	});
+
+	it("登记了不存在的模块 → 报错并提示以目录为准", () => {
+		expect(() => mergeModuleList(scanned("home"), [
+			{ name: "gone", entry: "src/gone/web/entry.ts" },
+		], ROOT)).toThrow(/src\/gone\/web\/entry\.ts 不存在/);
+	});
+
+	it("纯后端模块（无 web/entry.ts）不进前端清单", () => {
+		const list = mergeModuleList([
+			{ name: "auth" }, // 纯后端：只有 api/manifest.yaml，扫描结果没有 webSrc
+			{ name: "home", webSrc: `${ROOT}/src/home/web` },
+		], undefined, ROOT);
+		expect(list.map(m => m.name)).toEqual(["home"]);
+	});
+
+	it("登记一个纯后端模块也算错（该目录没有前端入口）", () => {
+		expect(() => mergeModuleList([
+			{ name: "auth" },
+		], [{ name: "auth", entry: "x" }], ROOT)).toThrow(/不存在/);
+	});
+
+	it("entry 用相对工程根的路径（与 web.config.ts 历史口径一致）", () => {
+		const [only] = mergeModuleList(scanned("wiki"), [{ name: "wiki", entry: "/abs/should-be-ignored" }], ROOT);
+		expect(only.entry).toBe("src/wiki/web/entry.ts");
+	});
+});

package/src/__tests__/oj-caps.test.ts

@@ -0,0 +1,114 @@
+// oj 能力探针 spec：双探的第二探（设计 202610220010 §7）。
+//
+// 失败方式很隐蔽：能力缺失却在构建入口回落到旧布局，会得到「源码搬了、产物还是旧的」
+// 半坏状态。这里钉住三件事：解析只看整词旗标、缓存按二进制指纹失效、缺失即抛且带版本。
+import { mkdirSync, mkdtempSync, readFileSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { CAPS_FILE, probeOjCaps, readCapsCache, requireModuleRootCapability, writeCapsCache } from "../oj-caps";
+
+function newProject(): { root: string, ojBin: string } {
+	const root = mkdtempSync(join(tmpdir(), "ojm-caps-"));
+	mkdirSync(join(root, "bin"), { recursive: true });
+	const ojBin = join(root, "bin", "oj");
+	writeFileSync(ojBin, "#!/bin/sh\necho fake\n", { mode: 0o755 });
+	return { root, ojBin };
+}
+
+const HELP_WITH = "Options:\n  -d, --dir <DIR>  源码目录\n      --module-root <GLOB>  模块根 glob\n";
+const HELP_WITHOUT = "Options:\n  -d, --dir <DIR>  源码目录\n";
+
+describe("probeOjCaps", () => {
+	it("帮助里有 --module-root 即支持", () => {
+		const { ojBin } = newProject();
+		expect(probeOjCaps(ojBin, () => HELP_WITH).moduleRoot).toBe(true);
+	});
+
+	it("帮助里没有则不支持", () => {
+		const { ojBin } = newProject();
+		expect(probeOjCaps(ojBin, () => HELP_WITHOUT).moduleRoot).toBe(false);
+	});
+
+	it("同名前缀不算命中（--module-rooted 之类的说明文字）", () => {
+		const { ojBin } = newProject();
+		expect(probeOjCaps(ojBin, () => "--module-rooted 是别的意思\n").moduleRoot).toBe(false);
+	});
+
+	it("探测本身失败时报错带处置命令", () => {
+		const { ojBin } = newProject();
+		expect(() => probeOjCaps(ojBin, () => {
+			throw new Error("boom");
+		})).toThrow(/ojm vendor/);
+	});
+});
+
+describe("能力缓存", () => {
+	it("写入后能读回", () => {
+		const { ojBin } = newProject();
+		writeCapsCache(ojBin, { moduleRoot: true });
+		expect(readCapsCache(ojBin)).toEqual({ moduleRoot: true });
+	});
+
+	it("换二进制（size 变）后缓存失效", () => {
+		const { ojBin } = newProject();
+		writeCapsCache(ojBin, { moduleRoot: true });
+		writeFileSync(ojBin, "#!/bin/sh\necho replaced-and-longer\n", { mode: 0o755 });
+		expect(readCapsCache(ojBin)).toBeNull();
+	});
+
+	it("mtime 变（同尺寸手替）后缓存失效", () => {
+		const { ojBin } = newProject();
+		writeCapsCache(ojBin, { moduleRoot: true });
+		const future = new Date(Date.now() + 60_000);
+		utimesSync(ojBin, future, future);
+		expect(readCapsCache(ojBin)).toBeNull();
+	});
+
+	it("缓存文件损坏不影响主流程（视为未缓存）", () => {
+		const { root, ojBin } = newProject();
+		writeFileSync(join(root, "bin", CAPS_FILE), "{not json", "utf-8");
+		expect(readCapsCache(ojBin)).toBeNull();
+	});
+});
+
+describe("requireModuleRootCapability", () => {
+	it("支持时通过并落缓存，第二次不再探测", () => {
+		const { root } = newProject();
+		let calls = 0;
+		const run = () => {
+			calls += 1;
+			return HELP_WITH;
+		};
+		expect(requireModuleRootCapability(root, run).moduleRoot).toBe(true);
+		expect(requireModuleRootCapability(root, run).moduleRoot).toBe(true);
+		expect(calls).toBe(1);
+		expect(readFileSync(join(root, "bin", CAPS_FILE), "utf-8")).toContain("\"moduleRoot\": true");
+	});
+
+	it("二进制缺失时报错指向 ojm vendor", () => {
+		const { root } = newProject();
+		const run = () => HELP_WITH;
+		expect(() => requireModuleRootCapability(join(root, "nope"), run)).toThrow(/ojm vendor/);
+	});
+
+	it("能力缺失时抛错，文案含现场版本与两种处置", () => {
+		const { root } = newProject();
+		const run = (_bin: string, args: string[]) =>
+			args[0] === "-V" ? "oj 0.1.84\n" : HELP_WITHOUT;
+		expect(() => requireModuleRootCapability(root, run)).toThrow(/oj 0\.1\.84/);
+		expect(() => requireModuleRootCapability(root, run)).toThrow(/ojm vendor/);
+	});
+
+	it("能力缺失也写缓存（避免每次构建重探），换二进制后指纹变化自动重探", () => {
+		const { root, ojBin } = newProject();
+		expect(() => requireModuleRootCapability(root, (_b, args) => (args[0] === "-V" ? "oj 0.1.84" : HELP_WITHOUT))).toThrow();
+		expect(readCapsCache(ojBin)?.moduleRoot).toBe(false);
+		// 二进制更新后指纹变化 → 重探，能力补齐即放行
+		const before = statSync(ojBin).size;
+		writeFileSync(ojBin, "#!/bin/sh\necho upgraded\n", { mode: 0o755 });
+		expect(statSync(ojBin).size).not.toBe(before);
+		expect(requireModuleRootCapability(root, () => HELP_WITH).moduleRoot).toBe(true);
+	});
+});

package/src/alias-paths.ts

@@ -0,0 +1,102 @@
+/**
+ * oj 原生别名 `#/<模块名>/…` 在 TS 侧的投影（生成 `<project>/tsconfig.paths.json`）。
+ *
+ * 为什么必须生成而不能手写一条通配：oj 的 `#/<name>/<tail>` 锚定「目标模块根」，在
+ * `src/<name>/{api,web}` 布局下即 `src/<name>/api`。tsconfig 的 `paths` 做不了这件事：
+ *   - 每条规则的替换值只允许一个 `*`——想用单条 `"#/*"` 同时匹配模块名与尾路径，会被
+ *     TS 以 TS5062 直接拒掉（两处通配只能二选一）；
+ *   - `paths` 是静态全局映射，表达不了 `#x`（本模块根，随引用方变化）。
+ * 所以只能**按模块逐条枚举** `"#/<name>/*": ["./src/<name>/api/*"]`。模块清单必须与
+ * `src/<name>/api/manifest.yaml` 同源，手写必然漂移 → 由 `ojm init` / `ojm build` / `ojm dev` 生成。
+ *
+ * 生成物只被 `src/tsconfig.json`（后端）`extends`：前端 tsconfig 不引，因为 web 侧
+ * 没有 `#` 解析（`build.ts` 的 esbuild/vite 不认别名），让编辑器「能过」而打包失败
+ * 比漏补 path 更坏。
+ *
+ * 模式串用 manifest 的 `name`（oj 的身份口径，v0.1.85 起与目录名脱钩），替换值用
+ * **目录名**——两者在正常工程里同值，但真分叉时只有按此口径才不会一边错位。
+ */
+import type { ProjectLayout } from "./layout";
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+import { tryResolveLayout } from "./layout";
+
+/** 生成物文件名（工程根）。`src/tsconfig.json` 以 `../tsconfig.paths.json` 引用 */
+export const ALIAS_PATHS_FILE = "tsconfig.paths.json";
+
+/** 生成物头注释：tsconfig 允许注释，且这是唯一会被 `ojm` 覆写的 tsconfig */
+const HEADER = [
+	"// 由 ojm 生成：ojm init / ojm build / ojm dev 会按 src/*/api/manifest.yaml 重写本文件，请勿手改。",
+	"//",
+	"// oj 别名 `#/<模块名>/…` 锚在目标模块根（本布局下即 src/<模块名>/api）。tsconfig 的",
+	"// paths 只能静态全局映射，且每条规则的替换值只允许一个 `*`（`./src/*/api/*` 会被 TS",
+	"// 以 TS5062 拒掉），故按模块逐条枚举。",
+].join("\n");
+
+/** 读模块根 manifest 的 `name`（oj 的模块身份）；读不到/格式坏时回落到目录名 */
+function manifestName(apiDir: string, fallback: string): string {
+	try {
+		const doc: unknown = parse(fs.readFileSync(path.join(apiDir, "manifest.yaml"), "utf-8"));
+		if (doc && typeof doc === "object" && "name" in doc) {
+			const name = (doc as { name?: unknown }).name;
+			if (typeof name === "string" && name.trim())
+				return name.trim();
+		}
+	}
+	catch {}
+	return fallback;
+}
+
+/**
+ * 模块名 → tsconfig `paths` 规则（仅 module-root 布局）。
+ *
+ * 键序按目录名排序（`scanModules` 已排序），保证同布局两次生成字节一致——
+ * 否则「生成物是否过期」的比对会因文件系统枚举顺序抖动而误报。
+ */
+export function aliasPathEntries(layout: ProjectLayout): Record<string, string[]> {
+	if (layout.kind !== "module-root")
+		return {};
+	const entries: Record<string, string[]> = {};
+	for (const mod of fs.readdirSync(layout.modulesSrc, { withFileTypes: true })) {
+		if (!mod.isDirectory() || mod.name.startsWith("."))
+			continue;
+		const apiDir = path.join(layout.modulesSrc, mod.name, "api");
+		if (!fs.existsSync(path.join(apiDir, "manifest.yaml")))
+			continue;
+		const name = manifestName(apiDir, mod.name);
+		entries[`#/${name}/*`] = [`./${path.posix.join("src", mod.name, "api", "*")}`];
+	}
+	return entries;
+}
+
+/** 渲染 `tsconfig.paths.json`（含头注释；tsconfig 解析器接受 JSONC） */
+export function renderAliasPaths(layout: ProjectLayout): string {
+	const entries = Object.entries(aliasPathEntries(layout));
+	const body = entries.length === 0
+		? "\t\t\"paths\": {}"
+		: `\t\t"paths": {\n${
+			entries
+				.map(([pattern, targets]) => `\t\t\t${JSON.stringify(pattern)}: [${targets.map(t => JSON.stringify(t)).join(", ")}]`)
+				.join(",\n")
+		}\n\t\t}`;
+	return `${HEADER}\n{\n\t"compilerOptions": {\n${body}\n\t}\n}\n`;
+}
+
+/**
+ * 按当前模块清单同步生成物，**内容未变则不写**（避免每次 build 都产生无意义 diff）。
+ *
+ * 返回 `skipped` 表示不是 module-root 布局（历史布局的别名口径不同，不在此生成）。
+ */
+export function syncAliasPaths(projectRoot: string): "created" | "updated" | "unchanged" | "skipped" {
+	const layout = tryResolveLayout(projectRoot);
+	if (layout?.kind !== "module-root")
+		return "skipped";
+	const file = path.join(projectRoot, ALIAS_PATHS_FILE);
+	const next = renderAliasPaths(layout);
+	const prev = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : null;
+	if (prev === next)
+		return "unchanged";
+	fs.writeFileSync(file, next);
+	return prev === null ? "created" : "updated";
+}

package/src/args.ts

@@ -40,13 +40,16 @@ export function parseApiArgs(argv: string[]): { dir: string, check: boolean, doc
 
 /**
  * `ojm build [--bundle] [--out <dir>]`。
- * `--bundle`：方案包构建（manifest.yaml 契约校验 → 确定性 tgz + sha256），
- * 与站点级 `ojm build`（后端 oj build + 模块产物合并）互斥分工（devkit 手册「打包与分发」）。
+ * `--bundle`：方案包构建（契约校验 → 确定性 tgz + sha256）。bundle 级契约位置：优先工程根
+ * `solution.yaml`、或 `src/<模块>/solution.yaml`（模块级方案，契约与所打包模块同位）；旧方案回退
+ * `manifest.yaml`（同两处位置）。与站点级 `ojm build`（后端 oj build + 模块产物合并）互斥分工
+ * （devkit 手册「打包与分发」）。
  * `--out` 的值不得以 `--` 开头（同 parseApiArgs 的消费式扫描，P6 同款坑）。
  */
-export function parseBuildArgs(argv: string[]): { bundle: boolean, out?: string } {
+export function parseBuildArgs(argv: string[]): { bundle: boolean, bundleName?: string, out?: string } {
 	const flags = new Set<string>();
 	let out: string | undefined;
+	let bundleName: string | undefined;
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i];
 		if (a === "--out") {
@@ -54,11 +57,58 @@ export function parseBuildArgs(argv: string[]): { bundle: boolean, out?: string
 			i++; // 消费紧随的值，不被当 flag
 			continue;
 		}
+		// --bundle <name> / --bundle=<name>：只打这一份方案（无值 = 全部用户方案）
+		if (a === "--bundle") {
+			flags.add(a);
+			const next = argv[i + 1];
+			if (next !== undefined && !next.startsWith("--")) {
+				bundleName = next;
+				i++;
+			}
+			continue;
+		}
+		if (a.startsWith("--bundle=")) {
+			flags.add("--bundle");
+			bundleName = a.slice("--bundle=".length);
+			continue;
+		}
 		if (a.startsWith("--")) {
 			flags.add(a);
 		}
 	}
-	return { bundle: flags.has("--bundle"), out };
+	return { bundle: flags.has("--bundle"), bundleName, out };
+}
+
+/**
+ * `ojm new <name> [--layout container|none] [--api]`：新方案骨架生成参数。
+ * name 为首个非 flag 位置参数（必填，由调用方判空——非交互/CI 友好）。
+ */
+export function parseNewArgs(argv: string[]): { name?: string, layout?: "container" | "none", api?: boolean } {
+	let name: string | undefined;
+	let layout: "container" | "none" | undefined;
+	let api = false;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--layout") {
+			const v = argv[i + 1];
+			if (v !== "container" && v !== "none")
+				throw new Error(`[ojm] --layout 只接受 container | none（实际：${v}）`);
+			layout = v;
+			i++;
+			continue;
+		}
+		if (a === "--api") {
+			api = true;
+			continue;
+		}
+		if (a !== undefined && !a.startsWith("--")) {
+			if (name !== undefined)
+				throw new Error(`[ojm] ojm new 只接受一个方案名（多余参数：${a}）`);
+			name = a;
+			continue;
+		}
+	}
+	return { name, layout, api };
 }
 
 /**

package/src/build.ts

@@ -10,8 +10,10 @@ import { pathToFileURL } from "node:url";
 import tailwindcss from "@tailwindcss/vite";
 import { build as esbuild } from "esbuild";
 import { build } from "vite";
-import { loadModulesConfig, resolveModuleEntry } from "./config";
-import { resolveConfigPath, resolveLayout } from "./layout";
+import { ALIAS_PATHS_FILE, syncAliasPaths } from "./alias-paths";
+import { assertModuleList, loadSiteConfig, mergeModuleList, resolveModuleEntry } from "./config";
+import { resolveConfigPath, resolveLayout, scanModules, tryResolveLayout } from "./layout";
+import { requireModuleRootCapability } from "./oj-caps";
 import { isSharedDep, SHARED_DEPS } from "./shared-deps";
 import { normalizeSiteBase, rewriteIndexHtml } from "./site-base";
 import { resolveOjBin } from "./vendor";
@@ -494,18 +496,33 @@ function assertResolvableSpecifiers(
  * 无后端源码返回 false（纯前端工程跳过）。
  */
 export async function buildBackend(projectRoot: string): Promise<boolean> {
-	const apiSrc = path.join(projectRoot, "api/src");
+	// 没有模块源码的工程（如 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] 找到 api/src 但缺少 ${oj}。\n`
+			`[ojm] 找到 ${path.relative(projectRoot, apiSrc) || "."} 但缺少 ${oj}。\n`
 			+ "请重跑 ojm init 幂等补缺（不会覆盖 config 与用户代码）。",
 		);
 	}
-	const apiDist = path.join(projectRoot, "api/dist");
+	// 能力闸门先于任何写入：失败时磁盘上不留半成品
+	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, "api", "dist");
 	console.log("[ojm] oj build（后端）…");
 	// 必须显式给 -c：oj build 的 -c 缺省是 ./config.yaml（相对 CWD），而 config 在
 	// <project>/config/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
@@ -518,7 +535,17 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	//   2) `if (cond) x = y` → 压成 `cond && x = y`，赋值作 && 右项缺括号 →
 	//      SyntaxError: Invalid left-hand side in assignment（端点 500）。
 	// 0.1.32 / 0.1.50 均复现。产物体积换正确性，等上游修好再撤这个旗标。
-	execFileSync(oj, ["build", ...configArgs, "-d", apiSrc, "-o", apiDist, "--no-minify"], { stdio: "inherit" });
+	// 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];
+	execFileSync(oj, [
+		"build",
+		...configArgs,
+		...sourceArgs,
+		"-o",
+		apiDist,
+		"--no-minify",
+	], { stdio: "inherit" });
 	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 web/dist（mergeShellSite），
 	// 而方案安装器读的是 `<api>/dist/versions.json`（B-11：与 manifests.yaml 同层，用于
 	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
@@ -569,8 +596,13 @@ export async function buildModules(
 	projectRoot: string,
 	opts: { mergeSite?: boolean } = {},
 ): Promise<BuiltModule[]> {
-	const config = await loadModulesConfig(projectRoot);
 	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 ?? "";
 
@@ -584,7 +616,7 @@ export async function buildModules(
 
 	const built: BuiltModule[] = [];
 
-	for (const item of config.modules) {
+	for (const item of modules) {
 		if (item.enabled === false) {
 			console.log(`[ojm] 跳过已禁用模块 ${item.name}`);
 			continue;
@@ -595,7 +627,7 @@ export async function buildModules(
 
 		if (definition.name !== item.name) {
 			throw new Error(
-				`模块名不一致：web.config.ts 中为 "${item.name}"，entry.ts 中为 "${definition.name}"`,
+				`模块名不一致：${layout.kind === "module-root" ? `src/${item.name}` : "web.config.ts"} 中为 "${item.name}"，entry.ts 中为 "${definition.name}"`,
 			);
 		}