@oj-module/cli 0.2.18 → 0.2.23

package/src/new.ts

@@ -0,0 +1,208 @@
+/**
+ * `ojm new <name>` —— 脚手架内快速生成用户方案骨架（多方案 phase 3，设计 v2 §C）。
+ *
+ * 生成 module-root 布局的 `src/<name>/{api,web}` 最小骨架：solution.yaml（方案契约，
+ * `ojm build --bundle` 入口）+ web（entry.ts 示例路由 / 占位页 / 双语 locales）+
+ * 可选 api（oj 七键 manifest + ping 示例 handler）。生成物补产物后即过打包校验
+ * （round-trip 承诺，N1 用例钉死）。
+ *
+ * 前置守卫（全 fail-fast，顺序即排查顺序）：
+ *   1. N0 非 ojm 工程（无 web.config.ts / src/）→ 指向 `ojm init`；
+ *   2. N6 历史布局（new/flat）→ 拒绝 + 迁移指引（生成 module-root 骨架会触发
+ *      双源码树互斥，把 build/dev 打挂——宁可拒绝不留半套）；
+ *   3. N3 名字四查：kebab-case 正则（与契约 C2-01 同条）→ 保留名 → 框架自带名
+ *      （`src/.ojm-builtin.json`）→ 目录已存在；
+ *   4. N7 原子性：任一步失败 best-effort 删除已建 `src/<name>/`，不留半截目录
+ *      （半截目录会触发 scanModuleRoot 的坏模块报错）。
+ *
+ * 刻意不做：web.config.ts 登记——module-root 布局以 `src/<name>/web/entry.ts`
+ * 扫描为真源（0.2.20 起登记只是可选排序覆盖），生成即被扫描收录，向用户 TS 源文件
+ * 做文本插入既脆弱又零收益（六方评审一致结论）。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { readBuiltinModules } from "./builtin";
+import { tryResolveLayout } from "./layout";
+import { assertValidSolutionName, RESERVED_NAMES } from "./manifest-contract";
+
+export interface NewSolutionOptions {
+	/** 示例路由布局（默认 container；none = 无外壳裸页面） */
+	layout?: "container" | "none"
+	/** 同时生成 api 骨架（oj 七键 manifest + ping 示例 handler） */
+	api?: boolean
+}
+
+export interface NewSolutionResult {
+	/** 生成的方案目录（src/<name>） */
+	dir: string
+	/** 相对工程根的文件清单 */
+	files: string[]
+}
+
+export function createSolution(projectRoot: string, name: string, opts: NewSolutionOptions = {}): NewSolutionResult {
+	// N0：工程判定（web.config.ts 与 src/ 至少要有一个——空目录跑 new 是最常见误用）
+	const hasConfig = fs.existsSync(path.join(projectRoot, "web.config.ts"));
+	const hasSrc = fs.existsSync(path.join(projectRoot, "src"));
+	if (!hasConfig && !hasSrc) {
+		throw new Error(
+			`[ojm] ${projectRoot} 不是 ojm 工程（没有 web.config.ts / src/）。`
+			+ "先 `ojm init` 创建脚手架，再在里面 `ojm new <name>`。",
+		);
+	}
+
+	// N6：布局守卫。tryResolveLayout 自带双树互斥/坏目录的人话报错，直接传播；
+	// 历史布局（new/flat）拒绝——module-root 骨架落进去会触发互斥，把 build/dev 打挂
+	const layout = tryResolveLayout(projectRoot);
+	if (layout !== null && layout.kind !== "module-root") {
+		throw new Error(
+			`[ojm] ojm new 只支持 module-root 布局工程（src/<name>/{api,web}），当前为 ${layout.kind} 历史布局。`
+			+ "在历史布局工程里生成骨架会触发两套源码树互斥、把 build/dev 打挂，故拒绝。"
+			+ "请先迁移布局，或在新脚手架工程（ojm init）里使用。",
+		);
+	}
+
+	// N3：名字四查
+	assertValidSolutionName(name, "ojm new <name>");
+	if (RESERVED_NAMES.has(name)) {
+		throw new Error(
+			`[ojm] 「${name}」是保留名（框架功能命名空间，如 system/auth/market），不能用作方案名。`
+			+ "换一个不与框架能力撞名的名字。",
+		);
+	}
+	if (readBuiltinModules(projectRoot).has(name)) {
+		throw new Error(
+			`[ojm] 「${name}」是框架自带方案（见 src/.ojm-builtin.json；ojm info --all 可看全名单）。`
+			+ "想改造自带模块：`ojm new <新名>` 生成骨架后把代码复制过去（自带身份按目录名判定，复制即脱离）。",
+		);
+	}
+	const dir = path.join(projectRoot, "src", name);
+	if (fs.existsSync(dir))
+		throw new Error(`[ojm] src/${name}/ 已存在。换个名字，或删掉该目录后重试。`);
+
+	const shell = opts.layout ?? "container";
+	const files: string[] = [];
+	try {
+		put(projectRoot, files, path.join(dir, "solution.yaml"), solutionYaml(name, opts.api));
+		put(projectRoot, files, path.join(dir, "web", "entry.ts"), entryTs(name, shell));
+		put(projectRoot, files, path.join(dir, "web", "pages", "index.tsx"), pageTsx(name));
+		put(projectRoot, files, path.join(dir, "web", "locales", "zh-CN.json"), `${JSON.stringify({ menu: { main: `${name} 方案` } }, null, "\t")}\n`);
+		put(projectRoot, files, path.join(dir, "web", "locales", "en-US.json"), `${JSON.stringify({ menu: { main: name } }, null, "\t")}\n`);
+		if (opts.api) {
+			put(projectRoot, files, path.join(dir, "api", "manifest.yaml"), apiManifest(name));
+			put(projectRoot, files, path.join(dir, "api", "api.ts"), apiTs(name));
+		}
+	}
+	catch (error) {
+		// N7：不留半截目录（scanModuleRoot 会把「有 api/ 或 web/ 但缺标记」的目录判成坏模块）
+		fs.rmSync(dir, { recursive: true, force: true });
+		throw error;
+	}
+	return { dir, files };
+}
+
+function put(projectRoot: string, files: string[], p: string, content: string): void {
+	fs.mkdirSync(path.dirname(p), { recursive: true });
+	fs.writeFileSync(p, content);
+	files.push(path.relative(projectRoot, p));
+}
+
+function solutionYaml(name: string, withApi: boolean | undefined): string {
+	const api = withApi
+		? [
+			"api:",
+			`  module: ${name}`,
+			`  prefix: /api/${name}`,
+			"",
+		].join("\n")
+		: "";
+	return `# 方案契约：ojm build --bundle 的入口（字段规范见 devkit 手册 §11.1；
+# 优先级：本文件 > 工程根 solution.yaml > 同名 manifest.yaml 回退）。
+name: ${name}
+version: 0.1.0
+title: ${name}
+summary: ${name} 方案（ojm new 生成的骨架，替换为你的描述）
+changelog:
+  - 0.1.0 首个版本（ojm new 生成）
+${api}web:
+  route_prefix: /${name}
+  entry: modules/${name}/0.1.0/entry.js
+`;
+}
+
+function entryTs(name: string, shell: "container" | "none"): string {
+	return `import { defineModule } from "@oj-module/runtime";
+import { lazy } from "react";
+
+const Index = lazy(() => import("./pages/index"));
+
+/**
+ * ${name} 方案：\`ojm new\` 生成的最小骨架。
+ * 菜单顺序由 handle.order 决定（≥0 主菜单区升序；<0 底部固定区）；
+ * 标题键对应 locales/<lang>.json 的 menu.main。
+ */
+export default defineModule({
+	name: "${name}",
+	description: "${name} 方案",
+	version: "0.1.0",
+	peerRuntime: ">=0.0.0",
+	routes: [
+		{
+			path: "/${name}",
+			handle: { layout: "${shell}", order: 200, title: "${name}:menu.main" },
+			children: [
+				{
+					index: true,
+					Component: Index,
+					handle: { title: "${name}:menu.main" },
+				},
+			],
+		},
+	],
+	i18n: {
+		"zh-CN": () => import("./locales/zh-CN.json"),
+		"en-US": () => import("./locales/en-US.json"),
+	},
+});
+`;
+}
+
+function pageTsx(name: string): string {
+	return `import { BasicContent } from "@oj-module/runtime";
+import { Card, Typography } from "antd";
+
+/** ${name} 方案首页：\`ojm new\` 生成的占位页，替换为你的实现。 */
+export default function IndexPage() {
+	return (
+		<BasicContent>
+			<Card>
+				<Typography.Title level={4} style={{ marginTop: 0 }}>
+					${name}
+				</Typography.Title>
+				<Typography.Text type="secondary">
+					由 ojm new 生成的方案骨架——从这里开始你的实现。
+				</Typography.Text>
+			</Card>
+		</BasicContent>
+	);
+}
+`;
+}
+
+function apiManifest(name: string): string {
+	return `# oj 原生七键清单：oj 按 src/<name>/api/manifest.yaml 枚举发现后端模块，
+# 与方案契约（上级 solution.yaml）是两条互不干扰的枚举（devkit 手册 §1.2）。
+name: ${name}
+desc: ${name} 方案后端（ojm new 生成的骨架）
+version: 0.1.0
+tables: []
+`;
+}
+
+function apiTs(name: string): string {
+	return `// GET /api/${name}/ping —— 健康探针示例（保存即热更；出参挂平级 .response 即入 openapi.json）。
+export async function ping() {
+	json.ok({ pong: true, module: "${name}" });
+}
+`;
+}

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

@@ -16,18 +16,22 @@ export function usageText(): string {
         开发模式快捷键（仅 TTY 终端，类 Vite）:
           r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开
           q  退出（后端 oj 一并终止）
-  ojm build [--bundle] [--out <dir>]
+  ojm build [--bundle [name]] [--out <dir>]
         构建后端（oj build）与模块产物（含全站合并）
-        --bundle   方案包构建：manifest.yaml 契约校验（C2，fail-fast）→ 确定性 tgz
+        --bundle   方案包构建：契约校验（fail-fast）→ 确定性 tgz
                    → dist/<name>-<version>.tgz + sha256（市场安装器的上游产物）
+        --bundle <name>  只打这一份方案（无参 = 全部用户方案，框架自带自动排除）
         --out <dir>  --bundle 输出目录（缺省 dist/）
+  ojm new <name> [--layout container|none] [--api]
+        脚手架内生成用户方案骨架（src/<name>/{api,web} + solution.yaml；
+        module-root 扫描自动收录，无需登记 web.config.ts）
   ojm preview [port]
         生产形态预览（migrate → oj serve 单服务：API 与静态 SPA 同进程，深链回落）
         静态由 oj web 挂载直出；ojm 不起第二个服务、不做反代
   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 +72,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 +90,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,12 +108,19 @@ const COMMAND_HELP: Record<string, string> = {
   开发模式快捷键（仅 TTY 终端，类 Vite）：
     r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开
     q  退出（后端 oj 一并终止）
-  port 缺省 5174（oj 后端端口以 api/config.yaml 的 server.port 为准）`,
-	"build": `ojm build [--bundle] [--out <dir>]
+  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）`,
+	"build": `ojm build [--bundle [name]] [--out <dir>]
   构建后端（oj build）与模块产物（含全站合并）
-  --bundle   方案包构建：manifest.yaml 契约校验（fail-fast）→ 确定性 tgz
+  --bundle   方案包构建：契约校验（fail-fast，两段式全绿才写盘）→ 确定性 tgz
              → dist/<name>-<version>.tgz + sha256（市场安装器的上游产物）
+  --bundle <name> / --bundle=<name>  只打这一份方案；无参 = 全部用户方案
+             （src/<name>/solution.yaml；框架自带方案自动排除并逐条日志）
   --out <dir>  --bundle 输出目录（缺省 dist/）`,
+	"new": `ojm new <name> [--layout container|none] [--api]
+  脚手架内生成用户方案骨架：src/<name>/solution.yaml（契约，build --bundle 入口）
+  + web（entry.ts 示例路由/占位页/双语 locales）+ 可选 api（oj 七键 manifest + ping 示例）
+  守卫：非 ojm 工程 / 历史布局 / 非法名 / 保留名 / 框架自带名 / 重名一律拒绝（零写入）
+  module-root 布局以 src/<name>/web/entry.ts 扫描收录，无需登记 web.config.ts`,
 	"preview": `ojm preview [port]
   生产形态预览（migrate → oj serve 单服务：API 与静态 SPA 同进程，深链回落）
   静态由 oj web 挂载直出；ojm 不起第二个服务、不做反代
@@ -117,11 +128,12 @@ 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
-  输出版本矩阵与模块清单（报障用）`,
+	"info": `ojm info [--all]
+  输出版本矩阵与模块清单（报障用）
+  --all  展开框架自带模块（默认折叠为一行计数；名单见 src/.ojm-builtin.json）`,
 	"vendor": `ojm vendor [tag] [--force]
   下载/重装 oj vendor（经 npm 包 @oj-bin/oj；tag 缺省取最新，形如 v0.1.13）
   --force  即使已存在也重新下载`,
@@ -168,7 +180,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 {};