@oj-module/cli 0.2.18 → 0.2.23

package/src/index.ts

@@ -1,12 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { parseApiArgs, parseBuildArgs, parseInitArgs, parseLifecycleArgs, parseVendorArgs } from "./args";
+import { parseApiArgs, parseBuildArgs, parseInitArgs, parseLifecycleArgs, parseNewArgs, 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 { createSolution } from "./new";
 import { runPreview } from "./preview";
 import { getCommandHelp, resolveHelpRequest, usageText } from "./usage";
 import { vendorCommand } from "./vendor";
@@ -50,10 +51,13 @@ async function main() {
 
 	switch (command) {
 		case "build": {
-			const { bundle, out } = parseBuildArgs(process.argv.slice(3));
+			const { bundle, bundleName, out } = parseBuildArgs(process.argv.slice(3));
 			if (bundle) {
 				// 方案包构建（P1-11）：契约校验 fail-fast → 确定性 tgz + sha256（消费方：市场安装器）
-				await buildBundle(projectRoot, { out });
+				// 多方案：无 bundleName 打全部用户方案（自带排除），有则只打 name 那一份
+				const results = await buildBundle(projectRoot, { out, name: bundleName });
+				if (results.length > 1)
+					console.log(`[ojm] 共打包 ${results.length} 份方案包（逐包签名：ojm sign dist/<name>-<version>.tgz --id <publisher>.<key> --check）`);
 				break;
 			}
 			// 设计 §5：后端 oj build（零 DB 副作用）→ 前端全站合并（仅 build 清场合并）
@@ -61,6 +65,19 @@ async function main() {
 			await buildModules(projectRoot, { mergeSite: true });
 			break;
 		}
+		case "new": {
+			const { name, layout, api } = parseNewArgs(process.argv.slice(3));
+			if (!name) {
+				console.error("[ojm] 用法：ojm new <name> [--layout container|none] [--api]（非交互环境必须显式给 name）");
+				process.exit(1);
+			}
+			const created = createSolution(projectRoot, name, { layout, api });
+			console.log(`[ojm] 已生成方案骨架：${path.relative(process.cwd(), created.dir)}`);
+			for (const f of created.files)
+				console.log(`[ojm]   + ${f}`);
+			console.log(`[ojm] 下一步：pnpm dev 看效果 → ojm build && ojm build --bundle ${name} 打包`);
+			break;
+		}
 		case "init": {
 			const { dest, yes } = parseInitArgs(process.argv.slice(3));
 			await initProject(dest ? path.resolve(dest) : projectRoot, { yes });
@@ -79,7 +96,7 @@ async function main() {
 			break;
 		}
 		case "info":
-			await printInfo(projectRoot);
+			await printInfo(projectRoot, undefined, { all: process.argv.slice(3).includes("--all") });
 			break;
 		case "vendor": {
 			const { force, tag } = parseVendorArgs(process.argv.slice(3));
@@ -100,7 +117,7 @@ async function main() {
 			}
 			if (check) {
 				const { checkApi } = await import("./contract/check");
-				// --exempt <path>：相对路径按项目根解析；缺省回退 api/.ojm-api-exempt.json
+				// --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)
@@ -197,7 +214,10 @@ async function main() {
 
 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)}`);
+	// （旧名 RAM_DEBUG 一并读，兼容既有排障习惯）。
+	// 文案常自带 [ojm] 前缀（bundle/publish/sign 等抛出的错误），顶层不再叠一个，否则变 [ojm] [ojm]。
+	const isDebug = !!(process.env.OJM_DEBUG ?? process.env.RAM_DEBUG);
+	const body = error instanceof Error ? (isDebug ? error.stack ?? error.message : error.message) : String(error);
+	console.error(/^\[ojm/.test(body) ? body : `[ojm] ${body}`);
 	process.exit(1);
 });

package/src/info.ts

@@ -12,9 +12,11 @@ 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";
 import { isSupportedOjVersion, MIN_OJ_VERSION, readLocalVersion, resolveOjBin } from "./vendor";
 import { readHostVersions, resolveShellDist } from "./versions";
@@ -90,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"));
 
@@ -106,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}）`;
@@ -150,21 +193,37 @@ export async function printInfo(projectRoot: string, oj: OjObservability = realO
 			: "证书状态:  无法探测（服务未运行时属正常；ojm dev/preview 起服后可测）";
 
 		const markerShort = markerVersion?.replace(/^v/, "");
-		const drift = markerShort && siteVersion.includes(markerShort)
+		// 版本门禁以**现场版本**为准，标记只用来报漂移：`bin/oj` 允许手替（vendor.ts 逃生门），
+		// 只看标记会把「标记新、二进制旧」判成健康（设计 §7「双探」第 1 条）。
+		const liveShort = /(\d+\.\d+\.\d+)/.exec(siteVersion)?.[1];
+		const drift = markerShort && (liveShort ?? siteVersion).includes(markerShort)
 			? ""
 			: markerShort
 				? `\n  [!] 现场版本与安装标记（${markerVersion}）不一致，请核对（ojm vendor --force 重装）`
 				: "";
+		const gateShort = liveShort ?? markerShort;
 		// 最低版本门禁：ojm 只与 >= MIN_OJ_VERSION 的 oj 组合可用（子命令 serve 等契约）
-		const outdated = markerShort && !isSupportedOjVersion(markerShort)
+		const outdated = gateShort && !isSupportedOjVersion(gateShort)
 			? `\n  [!] 低于 ojm 要求的最低版本 v${MIN_OJ_VERSION}（oj v0.1.32 起启动子命令 server → serve）——请升级：ojm vendor v${MIN_OJ_VERSION}`
 			: "";
+		// 能力探针（§7 第 2 条）：版本号是声明，能跑通才是事实
+		const capsLine = fs.existsSync(ojBin)
+			? (() => {
+				try {
+					return `--module-root ${probeOjCaps(ojBin).moduleRoot ? "可用" : `不可用（src/<name>/{api,web} 布局需 oj >= v0.1.85；ojm vendor v${MIN_OJ_VERSION}）`}`;
+				}
+				catch (error) {
+					return `探测失败（${(error as Error).message}）`;
+				}
+			})()
+			: "未知（bin/oj 不存在，ojm vendor 安装）";
 		backendBlock = `
 后端（oj）:
   安装标记:  ${markerVersion ?? "未知（缺 bin/.oj-version，ojm vendor 重装）"}
   现场版本:  ${siteVersion}${drift}${outdated}
   版本要求:  >= v${MIN_OJ_VERSION}（ojm 以最新 oj 为准，不做兼容分支）
-  端口/base: ${port} / ${base}（api/config.yaml）
+  能力探针:  ${capsLine}
+  端口/base: ${port} / ${base}（config.yaml）
   ${certLine}
 `;
 	}

package/src/init.ts

@@ -1,12 +1,12 @@
 /**
  * `ojm init` —— 前后端一体化工程脚手架（设计 §3，D1/D3/D6/D10）。
  *
- * 产物：api/（oj 后端 + seed）、config/（config.yaml + 现场签发证书，与 api/、web/ 同级）、
- * web/src/（前端模块）、bin/（从 everpan/only-js 最新 release 联网下载：oj + plugins + devkit）、
- * 工程配置文件。
+ * 产物（布局 `src/<name>/{api,web}`）：src/（模块源码单树）、config.yaml + config/（现场签发证书）、
+ * seed.*.sql / tests / vitest.config.ts（后端工程面，与 config.yaml 同级）、
+ * bin/（从 everpan/only-js 最新 release 联网下载：oj + plugins + devkit）、工程配置文件。
  *
- * 幂等补缺：对既有工程重跑只补缺失文件（bin/oj 已在则跳过下载），config.yaml 与
- * 用户文件永不覆盖——「重新 init 覆盖脚手架」是审阅记录二明令禁止的行为。
+ * 幂等补缺：对既有工程重跑只补缺失文件（bin/oj 已在则跳过下载，但先过 §7 能力闸门），
+ * config.yaml 与用户文件永不覆盖——「重新 init 覆盖脚手架」是审阅记录二明令禁止的行为。
  */
 
 import { execFileSync } from "node:child_process";
@@ -16,9 +16,12 @@ import path from "node:path";
 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";
-import { resolveOjBin, vendorCommand } from "./vendor";
+import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
 
 export interface InitOptions {
@@ -33,6 +36,7 @@ export interface InitOptions {
 interface InitReport {
 	created: string[]
 	skipped: string[]
+	warnings: string[]
 }
 
 /**
@@ -41,6 +45,59 @@ interface InitReport {
  */
 export type Sealer = (destDir: string, plainSecret: string) => Promise<string | null>;
 
+/**
+ * 既有 `bin/oj` 的能力预检（设计 §7「双探」；评审 BLOCKING #8）。
+ *
+ * 只查**已存在**的二进制：刚由 `vendorCommand` 装下的那份已被 `MIN_OJ_VERSION` 挡过一遍，
+ * 而「从别处拷来的旧二进制」正是这条闸门要拦的形态。
+ *
+ * 三档处置：
+ *   - `-V` 读不出版本（桩/损坏二进制）→ 告警放行，不阻断幂等补缺；
+ *   - 版本 < MIN_OJ_VERSION → 抛错（`ojm vendor --force` 可覆盖标记）；
+ *   - 版本够但 `--module-root` 缺失 → 抛错，这是「声明新、能力旧」的真实形态。
+ */
+function assertExistingOjUsable(destDir: string, report: InitReport): void {
+	const ojBin = resolveOjBin(destDir);
+	if (!fs.existsSync(ojBin))
+		return;
+
+	let printed: string;
+	try {
+		printed = execFileSync(ojBin, ["-V"], { encoding: "utf-8", timeout: 10_000 }).trim();
+	}
+	catch (error) {
+		report.warnings.push(`无法执行 ${ojBin} -V（${(error as Error).message}），跳过版本校验`);
+		return;
+	}
+
+	const version = /(\d+\.\d+\.\d+)/.exec(printed)?.[1];
+	if (!version) {
+		report.warnings.push(`无法解析 ${ojBin} -V 的输出（${printed || "空"}），跳过版本校验`);
+		return;
+	}
+	if (!isSupportedOjVersion(version)) {
+		throw new Error(
+			`[ojm] ${ojBin} 是 v${version}，低于 ojm 要求的最低版本 v${MIN_OJ_VERSION}。\n`
+			+ "原因：init 不再对已存在的 bin/oj 静默跳过——旧二进制生成的新布局工程会在 `ojm build` 时才失败。\n"
+			+ `处置：\`ojm vendor --force v${MIN_OJ_VERSION}\` 重装，或删除 ${ojBin} 后重跑 init。`,
+		);
+	}
+
+	try {
+		if (probeOjCaps(ojBin).moduleRoot)
+			return;
+	}
+	catch (error) {
+		report.warnings.push(`能力探针失败（${(error as Error).message}），跳过 --module-root 校验`);
+		return;
+	}
+	throw new Error(
+		`[ojm] ${ojBin}（v${version}）不接受 --module-root，无法支撑 src/<name>/{api,web} 布局。\n`
+		+ "原因：版本号是声明，能跑通才是事实——`oj build --help` 里没有该旗标。\n"
+		+ `处置：\`ojm vendor --force v${MIN_OJ_VERSION}\` 重装。`,
+	);
+}
+
 export async function initProject(destDir: string, opts: InitOptions = {}): Promise<void> {
 	fs.mkdirSync(destDir, { recursive: true });
 	const existing = fs.readdirSync(destDir);
@@ -51,9 +108,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		);
 	}
 
-	const report: InitReport = { created: [], skipped: [] };
+	const report: InitReport = { created: [], skipped: [], warnings: [] };
 	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
 
+	// 0) 已有 bin/oj 先过能力闸门（评审 BLOCKING #8）：早前「bin/oj 存在即跳过」
+	//    会让从旧工程带来的 0.1.84 静默过关，等 `ojm build` 才死在 --module-root 不认。
+	assertExistingOjUsable(destDir, report);
+
 	// 1) 模板（占位符替换 + 幂等跳过）
 	const templatesDir = path.join(cliRoot, "templates");
 	const jwtSecret = crypto.randomBytes(32).toString("hex");
@@ -65,14 +126,29 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	}, report, include, templatesDir);
 	pruneUnincludedApiPaths(destDir, include, report);
 
-	// 2) 证书三件套（现场签发，D6）——落点即 resolveCertDir()（config.yaml 同级的 config/）
+	// 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 指向不存在的目录。
+	if (syncAliasPaths(destDir) === "created")
+		report.created.push(ALIAS_PATHS_FILE);
+
+	// 2) 证书三件套（现场签发，D6）——落点即 resolveCertDir()（config.yaml 同级的 config/；
+	//    新布局 config.yaml 在工程根，故为 <工程根>/config/）
 	const certDir = resolveCertDir(destDir);
 	if (fs.existsSync(path.join(certDir, "cert.jws"))) {
-		report.skipped.push("api/config/cert.jws");
+		report.skipped.push("config/cert.jws");
 	}
 	else {
 		await mintDevCert(certDir);
-		report.created.push("api/config/{private.pem,public.pem,cert.jws}");
+		report.created.push("config/{private.pem,public.pem,cert.jws}");
 	}
 
 	// 3) oj 二进制：从最新 release 联网下载（sha256 校验 → tar 解包 → chmod），
@@ -164,7 +240,9 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	console.log(`[ojm]   新增 ${report.created.length} 项，跳过（已存在）${report.skipped.length} 项`);
 	for (const item of report.skipped)
 		console.log(`[ojm]   · 跳过 ${item}`);
-	console.log("[ojm] 下一步：pnpm install && pnpm dev（登录 admin / 123456）");
+	for (const item of report.warnings)
+		console.warn(`[ojm]   ! ${item}`);
+	console.log("[ojm] 下一步：pnpm install && pnpm dev（登录 superadmin / 123456，角色账号见 devkit 手册 §1.1）");
 }
 
 /** 默认密封器：bin/oj secret keygen + seal（失败返回 null，不抛） */
@@ -213,7 +291,7 @@ async function sealJwtSecret(destDir: string, report: InitReport, seal: Sealer =
 	// secrets 段：私钥只放部署机，路径相对 config 目录（config.yaml 同级）
 	const withSecrets = `${next.trimEnd()}\nsecrets:\n  private_key_path: ./config/secrets-private.pem\n  public_key_path: ./config/secrets-public.pem\n`;
 	fs.writeFileSync(configPath, withSecrets);
-	report.created.push("api/config/{secrets-private.pem,secrets-public.pem} + auth.jwt_secret 已密封（ENC[...]）");
+	report.created.push("config/{secrets-private.pem,secrets-public.pem} + auth.jwt_secret 已密封（ENC[...]）");
 }
 
 /**
@@ -318,9 +396,10 @@ function pruneUnincludedApiPaths(destDir: string, include: Set<string>, report:
 	// 只裁本次新建的 openapi.json：init 是幂等补缺，不改动既有工程文件
 	if (!report.created.includes("openapi.json"))
 		return;
+	// 白名单里 `src/<name>/api` 这条（整模块收录）决定「脚手架有哪些后端模块」
 	const mods = new Set([...include]
-		.map(p => (p.startsWith("api/src/") ? p.slice("api/src/".length) : null))
-		.filter((m): m is string => !!m && !m.includes("/")));
+		.map(p => /^src\/([^/]+)\/api$/.exec(p)?.[1])
+		.filter((m): m is string => !!m));
 	if (mods.size === 0)
 		return;
 	const openapiPath = path.join(destDir, "openapi.json");
@@ -401,15 +480,15 @@ node_modules/
 bin/
 .ojm-tmp-*
 # ojm preview 的派生 config（临时产物，进程退出即删；见 preview-config.ts）
-api/.ojm-preview.yaml
-# 本地 sqlite 与运行日志
-api/db.sqlite
-api/db.sqlite-shm
-api/db.sqlite-wal
-api/logs/
+.ojm-preview.yaml
+# 本地 sqlite 与运行日志（config.yaml 在工程根，路径都相对工程根）
+db.sqlite
+db.sqlite-shm
+db.sqlite-wal
+logs/
 # 现场签发的开发证书与凭据私钥（ojm dev 缺证时自动签发，见 oj-cert.ts）；私钥绝不入仓
-api/config/*.pem
-api/config/cert.jws
+config/*.pem
+config/cert.jws
 # 构建产物
 api/dist/
 web/dist/
@@ -506,7 +585,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"));
 
@@ -556,11 +636,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,
 	};