@oj-module/cli 0.2.20 → 0.2.25

package/src/index.ts

@@ -1,203 +1,43 @@
-import fs from "node:fs";
-import path from "node:path";
 import process from "node:process";
-import { parseApiArgs, parseBuildArgs, parseInitArgs, parseLifecycleArgs, parseVendorArgs } from "./args";
-import { buildBackend, buildModules } from "./build";
-import { buildBundle } from "./bundle";
-import { devServer } from "./dev";
-import { mergeManifests, printInfo } from "./info";
-import { initProject } from "./init";
-import { runPreview } from "./preview";
-import { getCommandHelp, resolveHelpRequest, usageText } from "./usage";
-import { vendorCommand } from "./vendor";
+import { buildCli, localizeCacError, reportCliError, rewriteHelpArgv, unknownCommandResult } from "./cli";
+import { isKnownCommand, resolveLang, usageText } from "./usage";
 import { readCliVersion } from "./versions";
 
-/** ojm → oj 透传子命令（其余参数原样转发，见 src/oj-cmd.ts） */
-const OJ_PASSTHROUGH = new Set(["test", "exec", "openapi", "migrate", "schema"]);
-
-const [command] = process.argv.slice(2);
-
-function usage(): never {
-	console.log(usageText());
-	process.exit(command ? 1 : 0);
-}
-
 async function main() {
-	const projectRoot = process.cwd();
-
-	// 帮助请求：`ojm <cmd> --help` / `ojm help <cmd>` / 顶层 `ojm --help`
-	// 必须在 switch 之前拦截，否则会真正执行子命令（如 `ojm market setup --help` 会去建 CDN）。
-	const helpReq = resolveHelpRequest();
-	if (helpReq !== null) {
-		if (!helpReq.cmd) {
-			console.log(usageText());
-			return;
-		}
-		const text = getCommandHelp(helpReq.cmd, helpReq.sub);
-		if (text) {
-			console.log(text);
-			return;
-		}
-		console.error(`[ojm] 未知命令：${helpReq.cmd}${helpReq.sub ? ` ${helpReq.sub}` : ""}`);
-		process.exit(1);
-	}
+	const lang = resolveLang();
+	const argv = process.argv.slice(2);
 
-	// 顶层 --version / -V：打印 cli 包版本（与 `ojm info` 的 cli 版本同源）
-	if (command === "--version" || command === "-V") {
+	// 顶层 --version / -V：裸版本号（与 ojm info 同源）；不经 cac，避免其 platformInfo 后缀
+	if (argv[0] === "--version" || argv[0] === "-V") {
 		console.log(readCliVersion());
 		return;
 	}
 
-	switch (command) {
-		case "build": {
-			const { bundle, out } = parseBuildArgs(process.argv.slice(3));
-			if (bundle) {
-				// 方案包构建（P1-11）：契约校验 fail-fast → 确定性 tgz + sha256（消费方：市场安装器）
-				await buildBundle(projectRoot, { out });
-				break;
-			}
-			// 设计 §5：后端 oj build（零 DB 副作用）→ 前端全站合并（仅 build 清场合并）
-			await buildBackend(projectRoot);
-			await buildModules(projectRoot, { mergeSite: true });
-			break;
-		}
-		case "init": {
-			const { dest, yes } = parseInitArgs(process.argv.slice(3));
-			await initProject(dest ? path.resolve(dest) : projectRoot, { yes });
-			break;
-		}
-		case "preview": {
-			const previewPortArg = Number(process.argv[3]);
-			const previewPort = Number.isInteger(previewPortArg) && previewPortArg > 0 ? previewPortArg : undefined;
-			await runPreview(projectRoot, { port: previewPort });
-			break;
-		}
-		case "dev": {
-			const portArg = Number(process.argv[3]);
-			const port = Number.isFinite(portArg) && portArg > 0 ? portArg : 5174;
-			await devServer(projectRoot, { port });
-			break;
-		}
-		case "info":
-			await printInfo(projectRoot);
-			break;
-		case "vendor": {
-			const { force, tag } = parseVendorArgs(process.argv.slice(3));
-			await vendorCommand(projectRoot, { force, tag });
-			break;
-		}
-		case "api": {
-			const { dir, check, docs, exempt } = parseApiArgs(process.argv.slice(3));
-			// S5：显式目录必须先存在——否则静默在错的目录下生成/对账
-			if (dir && !fs.existsSync(path.resolve(dir)))
-				throw new Error(`[ojm-api] 项目目录不存在：${dir}`);
-			const apiRoot = dir ? path.resolve(dir) : projectRoot;
-			if (docs) {
-				const { runApiDocs } = await import("./contract/run");
-				const out = await runApiDocs(apiRoot);
-				console.log(`[ojm-api] 文档站已生成：${path.relative(projectRoot, out)}（浏览器直接打开即可）`);
-				break;
-			}
-			if (check) {
-				const { checkApi } = await import("./contract/check");
-				// --exempt <path>：相对路径按项目根解析；缺省按布局找 .ojm-api-exempt.json（工程根 → api/）
-				// （旧名 api/.ram-api-exempt.json 仍被读取，R4）
-				const { violations, hints } = await checkApi({ cwd: apiRoot, exempt: exempt ? path.resolve(projectRoot, exempt) : undefined });
-				for (const v of violations)
-					console[v.level === "error" ? "error" : "warn"](`${v.level === "error" ? "✗" : "⚠"} ${v.message}`);
-				for (const h of hints)
-					console.log(h);
-				if (violations.length === 0)
-					console.log("[ojm-api] --check 通过：生成物同步、route 双向对账、routes.js 均无 drift。");
-				const errors = violations.filter(v => v.level === "error").length;
-				console.log(`[ojm-api] --check 结果：${errors} error / ${violations.length - errors} warn`);
-				if (errors > 0)
-					process.exit(1);
-				break;
-			}
-			const { runApi } = await import("./contract/run");
-			const result = await runApi({ cwd: apiRoot });
-			console.log(`[ojm-api] 契约 ${result.contracts} 份；写入 ${result.written.length} 个文件，跳过（未变）${result.skipped.length} 个；stub 新建 ${result.stubs.created} / 更新 ${result.stubs.updated} / 跳过 ${result.stubs.skipped}`);
-			for (const p of result.written)
-				console.log(`  + ${path.relative(apiRoot, p)}`);
-			break;
-		}
-		case "merge":
-			await mergeManifests(process.argv[3] ?? "", process.argv.slice(4));
-			break;
-		case "keygen": {
-			// 签名密钥对生成（P2-4，作者工具链）：缺省 ~/.ojm/keys/<id>，工程树内落盘需 --yes
-			const { parseKeygenArgs } = await import("./keygen");
-			const { keygenCommand } = await import("./keygen");
-			const { id, out, yes } = parseKeygenArgs(process.argv.slice(3));
-			keygenCommand({ id, out, yes });
-			break;
-		}
-		case "sign": {
-			// detached 侧车签名（P2-4，G4 载体）：ojm sign <tgz> [--id <publisher.id>] [--key <pem>] [--check]
-			const { parseSignArgs } = await import("./sign");
-			const { signCommand } = await import("./sign");
-			const { positionals, id, key, check } = parseSignArgs(process.argv.slice(3));
-			signCommand(positionals[0] ?? "", { id, key, check });
-			break;
-		}
-		case "install": {
-			// 方案包安装瘦客户端（P1-13，D6）：file 上传 / CDN 市场源 → 轮询任务至终态
-			const { positionals, url, user, pass, locale, name, version } = parseLifecycleArgs(process.argv.slice(3));
-			const { installCommand } = await import("./install");
-			await installCommand(positionals[0] ?? "", { url, user, pass, locale, name, version });
-			break;
-		}
-		case "enable":
-		case "disable": {
-			// 生命周期开关瘦客户端（P1-13，D8）：站点侧 setEnabled 四处同写
-			const { positionals, url, user, pass } = parseLifecycleArgs(process.argv.slice(3));
-			const { setEnabledCommand } = await import("./enable");
-			await setEnabledCommand(positionals[0] ?? "", command === "enable", { url, user, pass });
-			break;
-		}
-		case "uninstall": {
-			// 卸载瘦客户端（P1-15a，缺口 B）：站点侧 runUninstall 四处同删 + 权限级联
-			const { positionals, url, user, pass } = parseLifecycleArgs(process.argv.slice(3));
-			const { uninstallCommand } = await import("./uninstall");
-			await uninstallCommand(positionals[0] ?? "", { url, user, pass });
-			break;
-		}
-		case "trust": {
-			// 信任库运维瘦客户端（P2-2，C2-38/39）：ls / add <key_id> <pubkey_hex> / revoke <key_id> / confirm --task
-			const { positionals, url, user, pass, task } = parseLifecycleArgs(process.argv.slice(3));
-			const { trustCommand } = await import("./trust");
-			await trustCommand(positionals[0] ?? "", positionals.slice(1), { url, user, pass, task });
-			break;
-		}
-		case "publish": {
-			// 索引发布（P3-5/6/7，作者工具链）：重算 bundles/manifests 索引 + detached .sig 签名写回
-			const { parsePublishArgs } = await import("./publish");
-			const { publishCommand } = await import("./publish");
-			const { positionals, id, key, check } = parsePublishArgs(process.argv.slice(3));
-			publishCommand(positionals[0] ?? "", { id, key, check });
-			break;
-		}
-		case "market": {
-			// 本地模拟 CDN 与市场链路（setup / publish / build-index）
-			const { runMarket } = await import("./market/command");
-			await runMarket(process.argv.slice(3));
-			break;
-		}
-		default: {
-			if (command && OJ_PASSTHROUGH.has(command)) {
-				const { runOjSubcommand } = await import("./oj-cmd");
-				runOjSubcommand(projectRoot, command, process.argv.slice(3));
-				break;
-			}
-			usage();
-		}
+	const rewritten = rewriteHelpArgv(argv);
+	const cli = buildCli(process.cwd(), lang);
+	let unknown: string | undefined;
+	cli.on("command:*", () => {
+		// cac 在 --help 输出后会 unsetMatchedCommand 再发 command:*（args[0] 可能是子命令，如 verify）——
+		// 误判根源。按「首位置参数是否是已知命令」判定：market 等已知命令的子命令不误判，未知首参才兜底
+		const first = rewritten.find(a => !a.startsWith("-"));
+		if (first !== undefined && !isKnownCommand(first))
+			unknown = first;
+	});
+	cli.parse(["node", "ojm", ...rewritten]);
+
+	// 未知命令：help 形态报「未知命令」、否则打帮助；均 exit 1（裸 ojm 打帮助退 0 不变）
+	if (unknown !== undefined) {
+		const r = unknownCommandResult(unknown, lang, !!cli.options.help);
+		if (cli.options.help)
+			console.error(r.text);
+		else
+			console.log(r.text);
+		process.exit(r.code);
 	}
+	if (argv.length === 0)
+		console.log(usageText(lang));
 }
 
-main().catch((error: unknown) => {
-	// Error 的 message 已是人话（含修复指引）；堆栈默认是噪音，OJM_DEBUG=1 才输出
-	// （旧名 RAM_DEBUG 一并读，兼容既有排障习惯）
-	console.error(`[ojm] ${error instanceof Error ? ((process.env.OJM_DEBUG ?? process.env.RAM_DEBUG) ? error.stack : error.message) : String(error)}`);
-	process.exit(1);
-});
+main().catch((error: unknown) => reportCliError(localizeCacError(error, resolveLang()), (code) => {
+	process.exit(code);
+}));

package/src/info.ts

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

package/src/init.ts

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

package/src/keygen.ts

@@ -24,25 +24,6 @@ export interface KeygenOptions {
 
 export const DEFAULT_KEY_ID = "local.dev";
 
-/** `ojm keygen [--id <publisher.id>] [--out <dir>] [--yes]` 参数解析（值式 flag 逐项消费，P6 同款纪律） */
-export function parseKeygenArgs(argv: string[]): { id?: string, out?: string, yes?: boolean } {
-	const values: Record<string, string> = {};
-	let yes = false;
-	for (let i = 0; i < argv.length; i++) {
-		const a = argv[i]!;
-		if (a === "--yes") {
-			yes = true;
-			continue;
-		}
-		if (a === "--id" || a === "--out") {
-			values[a] = argv[i + 1] ?? "";
-			i++;
-			continue;
-		}
-	}
-	return { id: values["--id"], out: values["--out"], yes };
-}
-
 /** C2-37 key_id 命名空间（与 isolate 侧 trust.ts isValidKeyId 同规则；禁裸通用名单段） */
 export function isValidKeyId(keyId: string): boolean {
 	return /^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)+$/.test(keyId);

package/src/layout.ts

@@ -14,12 +14,12 @@
  * `src/<x>/api/manifest.yaml` 与 `src/<x>/web/entry.ts` 是唯一真源（设计 C-6：
  * 一侧可缺省，两侧皆无则不是模块）。
  *
- * 产物根在两套布局里语义相同、位置不变：
- *   api/dist   oj 扁平 release 根（<name>-<version>/ 同层兄弟 + manifests.yaml）
- *   web/dist   站点产物（shell + modules/ + modules.json）
+ * 产物根（2026-10-22 起收进工程根单一 dist/，原 {web,api}/dist 与源码混树）：
+ *   dist/api   oj 扁平 release 根（<name>-<version>/ 同层兄弟 + manifests.yaml），三种布局一致
+ *   dist/web   站点产物（shell + modules/ + modules.json）；flat 例外：框架根仓维持 build/
  * 产物按模块聚合已被设计 §2.2 否决（实证见该节），禁止在此引入第二套形状。
  *
- * watch 目标绝不含产物目录：若 watch `web/`，重建产物（web/dist）
+ * watch 目标绝不含产物目录：若 watch `web/`，重建产物（dist/web）
  * 会反过来触发重建，形成自触发循环（设计 §4）。
  */
 
@@ -42,9 +42,9 @@ export interface ProjectLayout {
 	projectRoot: string
 	/** 模块源码目录：module-root → `<project>/src`；new → `<project>/web/src`；flat → `<project>/web` */
 	modulesSrc: string
-	/** 站点产物根：module-root / new → `<project>/web/dist`；flat → `<project>/build` */
+	/** 站点产物根：module-root / new → `<project>/dist/web`；flat → `<project>/build`（框架根仓约定） */
 	distDir: string
-	/** oj 扁平 release 根：恒为 `<project>/api/dist`（设计 C-3/C-7，不随布局变化） */
+	/** oj 扁平 release 根：恒为 `<project>/dist/api`（不随布局变化；无布局回退同值） */
 	apiDist: string
 	/** fs.watch 目标（纯源码，永不落产物） */
 	watchTarget: string
@@ -161,8 +161,8 @@ export function tryResolveLayout(projectRoot: string): ProjectLayout | null {
 			kind: "module-root",
 			projectRoot,
 			modulesSrc: path.join(projectRoot, "src"),
-			distDir: path.join(projectRoot, "web", "dist"),
-			apiDist: path.join(projectRoot, "api", "dist"),
+			distDir: path.join(projectRoot, "dist", "web"),
+			apiDist: path.join(projectRoot, "dist", "api"),
 			watchTarget: path.join(projectRoot, "src"),
 			moduleRoot: path.join(projectRoot, "src"),
 		};
@@ -173,8 +173,8 @@ export function tryResolveLayout(projectRoot: string): ProjectLayout | null {
 			kind: "new",
 			projectRoot,
 			modulesSrc: path.join(projectRoot, "web", "src"),
-			distDir: path.join(projectRoot, "web", "dist"),
-			apiDist: path.join(projectRoot, "api", "dist"),
+			distDir: path.join(projectRoot, "dist", "web"),
+			apiDist: path.join(projectRoot, "dist", "api"),
 			watchTarget: path.join(projectRoot, "web", "src"),
 		};
 	}
@@ -186,7 +186,7 @@ export function tryResolveLayout(projectRoot: string): ProjectLayout | null {
 			projectRoot,
 			modulesSrc: path.join(projectRoot, "web"),
 			distDir: path.join(projectRoot, "build"),
-			apiDist: path.join(projectRoot, "api", "dist"),
+			apiDist: path.join(projectRoot, "dist", "api"),
 			watchTarget: path.join(projectRoot, "web"),
 		};
 	}

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

@@ -5,8 +5,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { DEFAULT_KEY_ID, isValidKeyId, keygenCommand, parseKeygenArgs } from "../../keygen";
-import { parseSignArgs, signCommand } from "../../sign";
+import { DEFAULT_KEY_ID, isValidKeyId, keygenCommand } from "../../keygen";
+import { signCommand } from "../../sign";
 import { readPrivateKeyPem } from "../keygen";
 import { fingerprintOfPublicKey, signCanonical as signCanonicalLocal, verifyCanonical } from "../sign";
 
@@ -19,11 +19,7 @@ afterEach(() => {
 	fs.rmSync(tmp, { recursive: true, force: true });
 });
 
-describe("ojm keygen 参数解析 + key_id 命名空间（C2-37）", () => {
-	it("parseKeygenArgs：--id/--out 值式消费 + --yes 独立", () => {
-		expect(parseKeygenArgs(["--id", "acme.market", "--out", "./k", "--yes"]))
-			.toEqual({ id: "acme.market", out: "./k", yes: true });
-	});
+describe("ojm keygen key_id 命名空间（C2-37）", () => {
 	it("isValidKeyId：<publisher>.<id> 合法 / 裸名·大写·空非法", () => {
 		expect(isValidKeyId("acme.market")).toBe(true);
 		expect(isValidKeyId("acme.dev.key-1")).toBe(true);
@@ -63,13 +59,6 @@ describe("ojm keygen 命令体（Ed25519 落盘 + 私钥红线）", () => {
 	});
 });
 
-describe("ojm sign 参数解析", () => {
-	it("parseSignArgs：位置参数 + --id/--key 值式消费 + --check 独立", () => {
-		expect(parseSignArgs(["pkg.tgz", "--id", "acme.market", "--key", "k.pem", "--check"]))
-			.toEqual({ positionals: ["pkg.tgz"], id: "acme.market", key: "k.pem", check: true });
-	});
-});
-
 describe("ojm sign 命令体（detached .sig，G4 载体）", () => {
 	const TGZ = path.join(tmp, "demo-solution-0.1.0.tgz");
 

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

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