@oj-module/cli 0.2.18 → 0.2.20

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/oj-caps.ts

@@ -0,0 +1,133 @@
+/**
+ * oj 二进制**能力**探针（设计 202610220010 §7「双探」）。
+ *
+ * 为什么不能只看版本号：`bin/oj` 允许手改/手替（vendor.ts:143 的逃生门），
+ * `bin/.oj-version` 标记会漂移；且 vendor.ts:102-110 已实证「`oj -V` 正常但
+ * JsRuntime 能力缺失」真实存在。版本号是声明，能跑通才是事实。
+ *
+ * 为什么单独探 `--module-root`：module-root 布局（`src/<name>/{api,web}`）依赖
+ * oj 的模块根可配置。能力缺失时必须 fail-fast 并给处置命令——回落旧布局会让
+ * 「源码搬了、构建产物还是旧的」这种半坏状态长期存在，比直接失败难排查得多。
+ *
+ * 缓存：`bin/.oj-caps`，以二进制的 size+mtime 为指纹。指纹变了就重探，
+ * 所以手替 `bin/oj` 不会吃到旧缓存。
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveOjBin } from "./vendor";
+
+export interface OjCaps {
+	/** `oj build --help` 是否接受 `--module-root <DIR>`（源码树根，与 `-d` 互斥） */
+	moduleRoot: boolean
+}
+
+/** 探针执行器（测试注入）：执行 oj 子命令并返回合并输出 */
+export type OjProbeRun = (ojBin: string, args: string[]) => string;
+
+const defaultRun: OjProbeRun = (ojBin, args) =>
+	execFileSync(ojBin, args, { encoding: "utf-8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
+
+export const CAPS_FILE = ".oj-caps";
+
+/** 二进制指纹：size + mtime 足以识别「换了文件」，比哈希便宜且无 IO 放大 */
+function fingerprint(ojBin: string): string {
+	const st = fs.statSync(ojBin);
+	return `${st.size}:${Math.floor(st.mtimeMs)}`;
+}
+
+function capsPath(binDir: string): string {
+	return path.join(binDir, CAPS_FILE);
+}
+
+/** 缓存文件形状：指纹 + 能力位 */
+interface CapsCache {
+	fingerprint?: string
+	caps?: Partial<OjCaps>
+}
+
+/** 读缓存；指纹不匹配或结构不对 → null（重探） */
+export function readCapsCache(ojBin: string): OjCaps | null {
+	try {
+		const raw = JSON.parse(fs.readFileSync(capsPath(path.dirname(ojBin)), "utf-8")) as CapsCache | null;
+		if (!raw || raw.fingerprint !== fingerprint(ojBin) || typeof raw.caps?.moduleRoot !== "boolean")
+			return null;
+		return { moduleRoot: raw.caps.moduleRoot };
+	}
+	catch {
+		return null;
+	}
+}
+
+/** 写缓存（失败不影响主流程：缓存只是加速，不是正确性来源） */
+export function writeCapsCache(ojBin: string, caps: OjCaps): void {
+	try {
+		fs.writeFileSync(
+			capsPath(path.dirname(ojBin)),
+			`${JSON.stringify({ fingerprint: fingerprint(ojBin), caps }, null, 2)}\n`,
+			"utf-8",
+		);
+	}
+	catch {
+		// 只读目录 / 权限不足：忽略
+	}
+}
+
+/** 现场探测：解析 `oj build --help` 的旗标列表（不缓存） */
+export function probeOjCaps(ojBin: string, run: OjProbeRun = defaultRun): OjCaps {
+	let help = "";
+	try {
+		help = run(ojBin, ["build", "--help"]);
+	}
+	catch (error) {
+		throw new Error(
+			`[ojm] 无法执行 ${ojBin} build --help：${(error as Error).message}\n`
+			+ "处置：`ojm vendor` 重装 oj 二进制。",
+		);
+	}
+	// 只认长旗标整词：`--module-root <DIR>`；避免帮助文本里的说明文字误命中
+	return { moduleRoot: /--module-root\b/.test(help) };
+}
+
+/**
+ * module-root 布局的能力闸门：缺失即抛，文案给处置命令。
+ * 有缓存走缓存（热路径每次 build/dev 都会经过这里）。
+ */
+export function requireModuleRootCapability(
+	projectRoot: string,
+	run: OjProbeRun = defaultRun,
+): OjCaps {
+	const ojBin = resolveOjBin(projectRoot);
+	if (!fs.existsSync(ojBin)) {
+		throw new Error(
+			`[ojm] 缺少 ${ojBin}：module-root 布局需要 oj 提供 --module-root。\n`
+			+ "处置：`ojm vendor` 安装 oj 二进制。",
+		);
+	}
+
+	const caps = readCapsCache(ojBin) ?? (() => {
+		const probed = probeOjCaps(ojBin, run);
+		writeCapsCache(ojBin, probed);
+		return probed;
+	})();
+
+	if (caps.moduleRoot)
+		return caps;
+
+	const version = (() => {
+		try {
+			return run(ojBin, ["-V"]).trim() || "(未知)";
+		}
+		catch {
+			return "(不可探测)";
+		}
+	})();
+	throw new Error(
+		`[ojm] 当前 oj 不支持 --module-root（版本 ${version}），无法构建 src/<name>/{api,web} 布局。\n`
+		+ "原因：module-root 布局要求 oj build / serve 的模块根可配置；本版 oj 只认 `-d` 首层子目录为模块。\n"
+		+ "处置：升级 oj 后重试——`ojm vendor <tag>`（需 >= 支持 --module-root 的版本），"
+		+ "或把工程改回 web/src/<name> 布局。\n"
+		+ `缓存：${capsPath(path.dirname(ojBin))}（换二进制后指纹变化会自动重探）。`,
+	);
+}

package/src/oj.ts

@@ -40,17 +40,40 @@ export interface StartOjPoll {
 	timeoutMs?: number
 }
 
+/**
+ * 工程根：从 config 所在目录向上找最近的含 `bin/` 的目录（ojm 的 vendor 布局）。
+ *
+ * 两种布局：
+ *   <root>/api/config.yaml → <root>/bin/oj     （历史布局，命中第二层）
+ *   <root>/config.yaml     → <root>/bin/oj     （module-root，命中第一层）
+ * 找不到 `bin/` 时退回旧的「往上两级」，保持既有报错行为（缺 bin/oj 的文案不变）。
+ */
+function resolveProjectRoot(configPath: string): string {
+	const configDir = path.dirname(configPath);
+	for (const dir of [configDir, path.dirname(configDir)]) {
+		if (fs.existsSync(path.join(dir, "bin")))
+			return dir;
+	}
+	return path.dirname(configDir);
+}
+
 export function startOj(
 	configPath: string,
 	base: string,
-	apiSrcPath: string,
+	apiSource: string | string[],
 	poll: StartOjPoll = {},
 	extraArgs: string[] = [],
 ): OjProcess {
 	const port = readOjPort(configPath);
-	// 约定：config 在 <project>/api/config.yaml，vendor 二进制在 <project>/bin/oj
-	const projectRoot = path.dirname(path.dirname(configPath));
+	// 约定：vendor 二进制在 <project>/bin/oj。工程根不能按「config 往上两级」算：
+	// module-root 布局的 config 在仓库根（<project>/config.yaml），往上两级会越过工程，
+	// 落到父目录找 bin/oj。改为「向上找最近的含 bin/ 的目录」，两种布局都成立。
+	const projectRoot = resolveProjectRoot(configPath);
 	const binPath = resolveOjBin(projectRoot);
+	// 后端源码参数二选一（oj v0.1.85：`--api-path` 与 `--module-root` 互斥，同时给会被
+	// clap 拒掉）：历史布局传目录 → `--api-path <dir>`；module-root 布局传**已拼好的
+	// 旗标数组** → `["--module-root", "<project>/src"]`。
+	const apiArgs = Array.isArray(apiSource) ? apiSource : ["--api-path", apiSource];
 	const healthUrl = `http://127.0.0.1:${port}${base}/health`;
 
 	// 插件目录发现显式化：oj 的 resolve_plugins_dir 依赖 current_exe() 启发式，而
@@ -69,7 +92,7 @@ export function startOj(
 	let stderrTail = "";
 	// --console-log：oj 新版终端默认静默（console_log 缺省 false，只落 logs/），
 	// ojm dev/preview 的 [oj] 透传管道必须显式打开终端输出才能看到日志（手册 §10）。
-	const child = spawn(binPath, ["serve", "-c", configPath, "-b", base, "--api-path", apiSrcPath, "--console-log", ...extraArgs], {
+	const child = spawn(binPath, ["serve", "-c", configPath, "-b", base, ...apiArgs, "--console-log", ...extraArgs], {
 		stdio: ["ignore", "pipe", "pipe"],
 		...(env ? { env } : {}),
 	});

package/src/preview-config.ts

@@ -44,7 +44,7 @@ export interface DerivePreviewConfigOptions {
 	apiRoot?: string
 	/** 显式端口时覆盖 server.port；缺省沿用原 config（oj 代码默认 9778） */
 	port?: number
-	/** 原 config 文本（测试注入）；缺省读 api/config.yaml */
+	/** 原 config 文本（测试注入）；缺省读 config.yaml */
 	configText?: string
 }
 

package/src/preview.ts

@@ -59,7 +59,8 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 	const siteDir = opts.siteDir ?? layout.distDir;
 	const ojBin = resolveOjBin(projectRoot);
 	const configPath = resolveConfigPath(projectRoot);
-	const apiDist = path.join(projectRoot, "api", "dist");
+	// release 根恒为扁平 api/dist（module-root 只改源码布局，不改产物形状——设计 C-3/C-7）
+	const apiDist = layout.apiDist;
 
 	// fail-fast 四查：缺一即提示对应补救（init 幂等补缺 / ojm build 产物）
 	if (!existsSync(ojBin))

package/src/site.ts

@@ -6,7 +6,7 @@
 
 import process from "node:process";
 
-/** 任务记录（线形状镜像；真源 templates/api/src/_platform/_lifecycle/types.ts:65，客户端不 import 模板内部） */
+/** 任务记录（线形状镜像；真源 templates/src/_platform/api/_lifecycle/types.ts:65，客户端不 import 模板内部） */
 export interface TaskRecord {
 	/**
 	 * 记录 schema 版本（P2-10 线形状镜像）：缺省（undefined）=旧记录=v1 语义照常渲染；
@@ -30,7 +30,7 @@ export interface TaskRecord {
 	finishedAt?: number
 }
 
-/** 模板 serve 缺省端口（templates/api/config.yaml server.port: 9778；host 显式钉 127.0.0.1） */
+/** 模板 serve 缺省端口（templates/config.yaml server.port: 9778；host 显式钉 127.0.0.1） */
 export const DEFAULT_SITE_URL = "http://127.0.0.1:9778";
 
 /** 本 CLI 已知的任务记录 schema 版本（P2-10；与服务端 tasks.ts TASK_SCHEMA_VERSION 手工同步，更高版本触发降级提示） */

package/src/usage.ts

@@ -27,7 +27,7 @@ export function usageText(): string {
   ojm api [dir] [--check] [--docs] [--exempt <path>]
         契约代码生成（client / routes / openapi / stub）
         --check   四重对账（生成物同步 / route 双向 / routes.js / WS 路由鉴权）
-        --exempt <path>  指定豁免清单，覆盖默认 api/.ojm-api-exempt.json
+        --exempt <path>  指定豁免清单，覆盖默认 .ojm-api-exempt.json（工程根；历史布局在 api/ 下）
         --docs    出自包含文档站（单文件离线可看）
   ojm info
         输出版本矩阵与模块清单（报障用，US-7）
@@ -68,7 +68,7 @@ export function usageText(): string {
         --check 离线自检两份索引签名
   ojm market setup [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]
         把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由
-        api/config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin
+        config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin
         must_change=1），会自动改密换全权 token 后再写入。
   ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]
         把方案包落进 cdn/：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz
@@ -86,7 +86,7 @@ export function usageText(): string {
         在一次性隔离站点（随机端口 + 一次性 DB/密钥/凭据/信任库/CDN）里跑完整安装，
         跑完即毁；--keep 保留现场供排查。用于确认「这个包到底能不能装」，不污染你的工程。
   ojm test|exec|openapi|migrate|schema [args...]
-        透传给 oj 同名子命令（自动补 -c <project>/api/config.yaml；其余参数原样转发）
+        透传给 oj 同名子命令（自动补 -c <project>/config.yaml；其余参数原样转发）
         例：ojm test --anonymous / ojm migrate --db report / ojm openapi --check
 `;
 }
@@ -104,7 +104,7 @@ const COMMAND_HELP: Record<string, string> = {
   开发模式快捷键（仅 TTY 终端，类 Vite）：
     r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开
     q  退出（后端 oj 一并终止）
-  port 缺省 5174（oj 后端端口以 api/config.yaml 的 server.port 为准）`,
+  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）`,
 	"build": `ojm build [--bundle] [--out <dir>]
   构建后端（oj build）与模块产物（含全站合并）
   --bundle   方案包构建：manifest.yaml 契约校验（fail-fast）→ 确定性 tgz
@@ -117,7 +117,7 @@ const COMMAND_HELP: Record<string, string> = {
 	"api": `ojm api [dir] [--check] [--docs] [--exempt <path>]
   契约代码生成（client / routes / openapi / stub）
   --check   四重对账（生成物同步 / route 双向 / routes.js / WS 路由鉴权）
-  --exempt <path>  指定豁免清单，覆盖默认 api/.ojm-api-exempt.json
+  --exempt <path>  指定豁免清单，覆盖默认 .ojm-api-exempt.json（工程根；历史布局在 api/ 下）
   --docs    出自包含文档站（单文件离线可看）
   dir 缺省当前目录；显式目录须先存在`,
 	"info": `ojm info
@@ -168,7 +168,7 @@ const COMMAND_HELP: Record<string, string> = {
   本地模拟 CDN 与市场链路子命令：setup / publish / build-index / verify / trial
   详见各子命令帮助：ojm market setup --help 等`,
 	"market setup": `ojm market setup [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]
-  把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由 api/config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin must_change=1），会自动改密换全权 token 后再写入`,
+  把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由 config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin must_change=1），会自动改密换全权 token 后再写入`,
 	"market publish": `ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]
   把方案包落进 cdn/：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz → 包级 detached 签名 <name>-<version>.tgz.sig
   不碰索引（索引由 build-index 扫描重建，多人发布才不会互相覆盖）`,

package/src/vendor.ts

@@ -35,8 +35,12 @@ export const NPM_PKG = "@oj-bin/oj";
  * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。**0.2.13 抬到 0.1.81**：
  * 模板侧 `solution-perms.ts` 权限级联清理用 `startswith` 操作键（v0.1.81 补齐，
  * 构造器迁移收尾），oj < 0.1.81 时卸载方案报 `unknown variant startswith` fail-closed。
+ * **本版抬到 0.1.85**：`src/<name>/{web,api}` 布局依赖 `--module-root <DIR>`（源码树根，
+ * 与 `-d`/`--api-path` 互斥）；旧版收到该旗标即报错。0.1.85 同时落地了
+ * `manifest.name` 与目录名脱钩、`#/m/x` 按 name 解析（见
+ * docs/prd/202610220010-layout-module-root-design.md §5）。
  */
-export const MIN_OJ_VERSION = "0.1.81";
+export const MIN_OJ_VERSION = "0.1.85";
 
 /** 按段数值比较（字符串比较会把 0.1.9 判成大于 0.1.69）；非数字段按 0 处理 */
 export function isSupportedOjVersion(version: string): boolean {

package/templates/{api/config.yaml → config.yaml}

@@ -2,7 +2,7 @@
 # 本文件由 ojm init 生成；config 内相对路径相对本文件所在目录。
 # 更多能力见手册 §10：vars / broker / tasks / oidc / ws / html_meta / secrets。
 #
-# ---- 证书与密钥的唯一落点：`./config/`（= api/config/，本文件同级的子目录）----
+# ---- 证书与密钥的唯一落点：`./config/`（= 工程根/config/，本文件同级的子目录）----
 # 三件套由 `ojm init` 现场签发（dev 缺证时 `ojm dev` 也会补签），逐把的作用与后果：
 #
 #   ① private.pem —— 证书签发私钥（RSA 2048）。只用来给 ③ 签名，**oj 不读它**，
@@ -25,19 +25,24 @@
 # 站点挂载（oj v0.1.58 起顶层扁平表：一行=一个 URL 前缀+一个目录，api/web 恰好其一）。
 # 被删除的 server.api_prefix / app_spa_fallback 已由 mounts 取代；
 # ojm dev 的 SPA 深链回落由 ojm 自建静态层负责；ojm preview 为单服务形态，
-# 现场生成派生 config（api/.ojm-preview.yaml，注入下面的 web 挂载 + spa: true），无需手改。
+# 现场生成派生 config（.ojm-preview.yaml，注入下面的 web 挂载 + spa: true），无需手改。
+#
+# **这里没有 api 挂载是有意的**：本工程是 `src/<name>/{api,web}` 布局，模块分散在
+# `src/<name>/api` 下，而 mounts 的 api 项按 `<目录>/<模块>/manifest.yaml` 单层解析、
+# 不会递归（实测报 `module 'x' missing manifest.yaml`）。源码形态由 `ojm dev` 用
+# `--module-root src` 供给，产物形态由 `ojm preview` 用 `--api-path api/dist` 供给；
+# 两者与 mounts 的 api 项同时出现还会报「module declared in multiple places」。
+# 手写部署（不经 ojm）时才需要自己加回一条 `- prefix: /api` + `api: dist`。
 mounts:
-  - prefix: /api # api 挂载：/api/<module>/...（目录相对 config 所在目录 → api/src）
-    api: src
   # 本地模拟 CDN：直出工程根 cdn/（内容见 cdn/README.md）。
   # 红线：生产请删掉这一条挂载，并把 system 设置 framework.market_cdn_url 指向真 CDN。
   # 不得给此挂载设 spa——缺文件必须返回 404，回落 index.html 会让市场解析崩。
   - prefix: /cdn
-    web: ../cdn
+    web: ./cdn
   # 生产若由 oj 直出前端（前后端同进程，即 ojm preview 的生产形态），
   # 取消下一行注释并先 build 出 web/dist（preview 会自动注入等价挂载，无需手改）：
   # - prefix: "/"
-  #   web: "../web/dist"   # 相对 api/config.yaml → 项目根/web/dist
+  #   web: "./web/dist"   # 相对 config.yaml → 工程根/web/dist
   #   spa: true
   # 嵌套 handler 组（oj v0.1.64）无需配置开关，组织方式见 api.ts 顶部注释。
 
@@ -84,8 +89,8 @@ platform:
   # 平台特权模块名单：方案安装器的 reloading 段调 server.reloadConfig 触发热更。
   # 缺这条 → 装在最后一步报 NotCapable: module '_platform' is not platform-privileged。
   modules: [_platform]
-  # 受控挂载根 = api 挂载目录（dev 形态 src）。ojm preview 派生 config 时会改写为 dist，
-  # 保持与 `--api-path` 同源；手写部署请按实际模块根填写。
+  # 受控根 = 后端模块源码根（`src/<name>/api` 的父目录，即 src）。ojm preview 派生 config
+  # 时会改写为 dist，保持与 `--api-path` 同源；手写部署请按实际模块根填写。
   root: src
   # ---- U6 信任库加固（P3-1；P2-2 红线 spike 结论）----
   # 威胁：devkit 0.1.75 语义下 fs: 段对全部模块生效（jail = fs.root），且 trusted_paths 只增不减——

package/templates/global.d.ts

@@ -840,11 +840,12 @@ interface OjRabbitClient {
 	metadata: () => Promise<any>
 }
 
-// oj 的导入别名 `#x`（本模块根）/ `#/m/x`（src 根）是「引用方所在模块」相对的，
-// tsconfig 的 `paths` 无法表达模块相对解析，只能枚举模块目录（见 tsconfig.json），
-// 因此仅能命中**已存在**的文件。无法静态定位的别名（如尚未创建的 `#_shared/view`）
-// 由 `types/oj-modules.d.ts`（非模块，真 ambient `declare module "#*"`）兜底为 `any`
-// 而非报 TS2307；已存在、能被 `paths` 命中的别名仍走真实文件类型。运行时由 oj 的
-// loader 解析，本文件与该兜底只影响编辑器 / tsc。
+// oj 的导入别名 `#x`（本模块根）/ `#/<模块名>/x`（目标模块根）是「引用方所在模块」
+// 相对的，tsconfig 的 `paths` 表达不了模块相对解析，只能按模块枚举
+// （`tsconfig.paths.json`，由 `ojm init` / `ojm build` / `ojm dev` 按 `src/*/api/manifest.yaml`
+// 生成，被 `src/tsconfig.json` extends），因此仅能命中**已存在**的文件。无法静态定位
+// 的别名（如尚未创建的 `#_shared/view`）由 `types/oj-modules.d.ts`（非模块，真 ambient
+// `declare module "#*"`）兜底为 `any` 而非报 TS2307；已存在、能被 `paths` 命中的别名
+// 仍走真实文件类型。运行时由 oj 的 loader 解析，本文件与该兜底只影响编辑器 / tsc。
 
 export {};

package/templates/init.include.yaml

@@ -8,7 +8,7 @@
 #  2. 模板自运行专属文件——templates 本身也是一个可 `pnpm dev` 的工程，
 #     它的 package.json / node_modules / bin / lock 绝不能泄漏进用户工程；
 #     package.json 由 init 现场生成（钉死真实版本，不带 workspace:/catalog:）。
-#  3. 构建与运行期产物——api/dist、web/dist、api/logs、签发的私钥与 sqlite；
+#  3. 构建与运行期产物——api/dist、web/dist、logs、签发的私钥与 sqlite；
 #     模板跑过 build/dev 后会留在本地，既不进用户工程，更不该让所有工程
 #     共享同一把私钥。
 #  4. 模板自用元数据——本清单自身。
@@ -32,43 +32,48 @@ include:
   - tsconfig.json
   - global.d.ts
   - env.d.ts
+  # 别名类型兜底（`declare module "#*"`，非模块文件）。`tsconfig.paths.json` 不在此列：
+  # 它由 init 按目标工程的模块清单**现场生成**（模板兼作 demo 工程，多出的模块不该带过去）
+  - types
   - web.config.ts
   - openapi.json
-  - web/src/styles.css
-  # —— api 后端：配置 / 种子 / 测试 / 默认模块 ——
-  - api/config.yaml
-  - api/.ojm-api-exempt.json
-  - api/seed.mysql.sql
-  - api/seed.pg.sql
-  - api/vitest.config.ts
-  - api/tests
-  - api/src/_platform
-  - api/src/auth
-  - api/src/notification
-  - api/src/personal-center
-  - api/src/system
-  - api/src/web
+  - src/styles.css
+  # 后端 typecheck 工程（package.json 的 typecheck:api 指向它）；只收后端、排除 web
+  - src/tsconfig.json
+  # —— 后端：配置 / 种子 / 测试 / 默认模块（模块源码在 src/<name>/api）——
+  - config.yaml
+  - .ojm-api-exempt.json
+  - seed.mysql.sql
+  - seed.pg.sql
+  - vitest.config.ts
+  - tests
+  - src/_platform/api
+  - src/auth/api
+  - src/notification/api
+  - src/personal-center/api
+  - src/system/api
+  - src/web/api
   # —— web 前端模块（demo/home 只列页面源码，__client 见顶部说明）——
-  - web/src/_platform
-  - web/src/auth
-  - web/src/demo/entry.ts
-  - web/src/demo/locales
-  - web/src/demo/pages
-  - web/src/home/entry.ts
-  - web/src/home/locales
-  - web/src/home/pages
-  - web/src/login
-  - web/src/notification
+  - src/_platform/web
+  - src/auth/web
+  - src/demo/web/entry.ts
+  - src/demo/web/locales
+  - src/demo/web/pages
+  - src/home/web/entry.ts
+  - src/home/web/locales
+  - src/home/web/pages
+  - src/login/web
+  - src/notification/web
   # 解决方案市场：默认第一方能力。逐子路径收录——__tests__ 不进脚手架
   # （用户工程无 web 侧 vitest 基建，拷了是死文件）
-  - web/src/oj-market/entry.ts
-  - web/src/oj-market/types.ts
-  - web/src/oj-market/api
-  - web/src/oj-market/components
-  - web/src/oj-market/hooks
-  - web/src/oj-market/locales
-  - web/src/oj-market/pages
-  - web/src/oj-market/utils
-  - web/src/personal-center
-  - web/src/system
-  - web/src/web
+  - src/oj-market/web/entry.ts
+  - src/oj-market/web/types.ts
+  - src/oj-market/web/api
+  - src/oj-market/web/components
+  - src/oj-market/web/hooks
+  - src/oj-market/web/locales
+  - src/oj-market/web/pages
+  - src/oj-market/web/utils
+  - src/personal-center/web
+  - src/system/web
+  - src/web/web