@oj-module/cli 0.2.20 → 0.2.23

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

@@ -0,0 +1,129 @@
+// BDD：`ojm new <name>` 方案骨架生成（docs/plans/2026-10-22-1640-multi-solution-bundle-design.md §C）。
+// N0 非工程拒绝 / N1 骨架 round-trip（生成→补产物→buildBundle 直接过）/ N2 --api
+// N3 非法·保留·内置·重名拒绝 / N5 空名拒绝 / N6 历史布局拒绝 / N7 失败清理
+import fs, { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, writeFileSync as writeFileSyncOrig } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildBundle } from "../../bundle";
+import { createSolution } from "../../new";
+
+let project: string;
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-new-"));
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+/** 最小 module-root 工程面：web.config.ts + src/（含一个自带模块 home 与内置名单） */
+function makeModuleRootProject(builtin = true): void {
+	mkdirSync(join(project, "src", "home", "web"), { recursive: true });
+	writeFileSync(join(project, "src", "home", "web", "entry.ts"), "export default { name: \"home\" };\n");
+	writeFileSync(join(project, "web.config.ts"), "export default { baseUrl: \"\", modules: [] };\n");
+	if (builtin)
+		writeFileSync(join(project, "src", ".ojm-builtin.json"), JSON.stringify({ modules: ["home"] }));
+}
+
+/** 给已生成的方案补站点产物，模拟「ojm build 之后」的打包前置 */
+function addWebArtifacts(name: string, version = "0.1.0"): void {
+	const webDist = join(project, "web/dist/modules", name, version);
+	mkdirSync(webDist, { recursive: true });
+	writeFileSync(join(webDist, "entry.js"), "export default {};\n");
+}
+
+describe("createSolution · 守卫", () => {
+	it("n0 非 ojm 工程（无 web.config.ts / src/）→ 拒绝且零写入", () => {
+		expect(() => createSolution(project, "crm")).toThrow(/不是 ojm 工程/);
+		expect(existsSync(join(project, "src"))).toBe(false);
+	});
+
+	it("n6 历史布局工程（web/src 树）→ 拒绝 + 迁移指引", () => {
+		mkdirSync(join(project, "web", "src", "old"), { recursive: true });
+		writeFileSync(join(project, "web.config.ts"), "export default { modules: [] };\n");
+		expect(() => createSolution(project, "crm")).toThrow(/module-root/);
+		expect(existsSync(join(project, "src", "crm"))).toBe(false);
+	});
+
+	it("n3 非法名（大写/数字开头/路径穿越）→ 拒绝", () => {
+		makeModuleRootProject();
+		for (const bad of ["Crm", "9crm", "../crm", "bad name"])
+			expect(() => createSolution(project, bad)).toThrow(/非法/);
+	});
+
+	it("n3 保留名（system）与内置名（home）→ 拒绝 + 指引", () => {
+		makeModuleRootProject();
+		expect(() => createSolution(project, "system")).toThrow(/保留名/);
+		expect(() => createSolution(project, "home")).toThrow(/框架自带/);
+	});
+
+	it("n3 目录已存在（非内置共享目录撞名）→ 拒绝", () => {
+		makeModuleRootProject();
+		mkdirSync(join(project, "src", "crm"), { recursive: true });
+		expect(() => createSolution(project, "crm")).toThrow(/已存在/);
+	});
+
+	it("n5 空名 → 拒绝", () => {
+		makeModuleRootProject();
+		expect(() => createSolution(project, "")).toThrow(/非法/);
+	});
+});
+
+describe("createSolution · 生成", () => {
+	it("n1 生成 web 骨架：solution.yaml/entry.ts/页面/双语 locales 齐备，layout 写进 handle", () => {
+		makeModuleRootProject();
+		const r = createSolution(project, "crm", { layout: "container" });
+		expect(r.files).toHaveLength(5);
+		const entry = readFileSync(join(project, "src/crm/web/entry.ts"), "utf-8");
+		expect(entry).toContain("layout: \"container\"");
+		expect(entry).toContain("crm:menu.main");
+		expect(readFileSync(join(project, "src/crm/solution.yaml"), "utf-8")).toContain("name: crm");
+		expect(JSON.parse(readFileSync(join(project, "src/crm/web/locales/zh-CN.json"), "utf-8")).menu.main).toBeTruthy();
+		expect(JSON.parse(readFileSync(join(project, "src/crm/web/locales/en-US.json"), "utf-8")).menu.main).toBeTruthy();
+		// --layout none
+		createSolution(project, "erp", { layout: "none" });
+		expect(readFileSync(join(project, "src/erp/web/entry.ts"), "utf-8")).toContain("layout: \"none\"");
+	});
+
+	it("n1 round-trip：生成的骨架补产物后 buildBundle({ name }) 直接过", async () => {
+		makeModuleRootProject();
+		createSolution(project, "crm");
+		addWebArtifacts("crm");
+		const results = await buildBundle(project, { out: join(project, "dist"), name: "crm" });
+		expect(results.map(r => r.name)).toEqual(["crm"]);
+		expect(existsSync(results[0]!.tgz)).toBe(true);
+	});
+
+	it("n2 --api：额外生成 api 骨架且 solution.yaml 含 api 段", () => {
+		makeModuleRootProject();
+		createSolution(project, "crm", { api: true });
+		expect(existsSync(join(project, "src/crm/api/manifest.yaml"))).toBe(true);
+		expect(readFileSync(join(project, "src/crm/api/manifest.yaml"), "utf-8")).toContain("name: crm");
+		expect(readFileSync(join(project, "src/crm/api/api.ts"), "utf-8")).toContain("/api/crm/ping");
+		const sol = readFileSync(join(project, "src/crm/solution.yaml"), "utf-8");
+		expect(sol).toContain("api:");
+		expect(sol).toContain("prefix: /api/crm");
+	});
+
+	it("n7 生成中途失败 → 不残留半截 src/<name>/", () => {
+		makeModuleRootProject();
+		// 让第二次写盘（entry.ts）必失败：首写（solution.yaml）成功后触发清理路径——
+		// 预置冲突文件会先在「目录已存在」守卫被拒，测不到 rmSync 回滚（审查发现 n7 旧用例假绿）
+		let calls = 0;
+		const spy = vi.spyOn(fs, "writeFileSync").mockImplementation(((...args: unknown[]) => {
+			calls++;
+			if (calls === 2)
+				throw new Error("ENOSPC: disk full");
+			return (writeFileSyncOrig as (...a: unknown[]) => unknown)(...args);
+		}) as typeof fs.writeFileSync);
+		try {
+			expect(() => createSolution(project, "crm")).toThrow(/disk full/);
+		}
+		finally {
+			spy.mockRestore();
+		}
+		expect(existsSync(join(project, "src", "crm"))).toBe(false);
+	});
+});

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

@@ -49,7 +49,8 @@ describe.skipIf(!smokeReady)("真机冒烟（需 OJM_SMOKE_URL/OJM_SMOKE_USER/OJ
 		mkdirSync(webDist, { recursive: true });
 		writeFileSync(join(webDist, "entry.js"), "export default {};\n");
 		writeFileSync(join(webDist, "demo-solution.css"), ".demo{}\n");
-		const { tgz } = await buildBundle(project, { out: join(project, "dist") });
+		const [built] = await buildBundle(project, { out: join(project, "dist") });
+		const { tgz } = built!;
 
 		const record = await installCommand(tgz, { url: SMOKE_URL ?? DEFAULT_SITE_URL, user: SMOKE_USER, pass: SMOKE_PASS });
 		expect(record.status).toBe("done");

package/src/manifest-contract.ts

@@ -16,11 +16,24 @@ export type ParseResult = { ok: true, manifest: BundleManifest } | { ok: false,
 
 // ── 契约 §2/§4 正则与清单（与 preflight.ts 逐字对应；改动须先改契约再同步双端与夹具）──
 
-/** C2-01：name 白名单 */
-const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+/** C2-01：name 白名单（导出供 ojm new/--bundle <name> 入口校验共用，DRY） */
+export const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+/**
+ * 方案名入口校验（`--bundle <name>` / `ojm new <name>` 共用，先校验再拼路径）：
+ * 与契约 C2-01 同一条正则；入口先给可读错误，契约校验再做正式判罚。
+ * 放在这里而非 bundle.ts——new 入口不应拖入打包模块图（esbuild/deterministic-tar 等）。
+ */
+export function assertValidSolutionName(name: string, where: string): void {
+	if (!NAME_RE.test(name)) {
+		throw new Error(
+			`[ojm] ${where}：「${name}」非法——须为 kebab-case（小写字母/数字/连字符，首字符为小写字母）。`,
+		);
+	}
+}
 
 /** §4.2 保留名清单（C2-01/13/14 共用；market 经 R9 恢复保留） */
-const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market", "framework", "health", "plugins", "_system"]);
+export const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market", "framework", "health", "plugins", "_system"]);
 
 /** C2-02 字符集：[0-9A-Za-z.-]（禁 +——oj validate_version 拒装，附录 B-1；禁 _——契约收紧） */
 const VERSION_CHARS_RE = /^[0-9A-Z.-]+$/i;

package/src/market/publish.ts

@@ -118,9 +118,17 @@ async function buildFixture(args: { fixture?: string, staging: string, cdnDir: s
 	return { name: spec.name, version: spec.version, tgzPath, sha256, preExisted: before.exists };
 }
 
-/** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录 */
+/** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录（一次只发一份：多方案工程请显式指定） */
 async function buildRealPackage(solutionRoot: string, staging: string, cdnDir: string): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
-	const built = await buildBundle(solutionRoot, { out: staging });
+	const builtList = await buildBundle(solutionRoot, { out: staging });
+	if (builtList.length !== 1) {
+		throw new Error(
+			`[ojm] market publish --real 一次只发布一份方案，但该工程打出了 ${builtList.length} 份用户方案。`
+			+ "请改用显式链路：在方案工程里 `ojm build --bundle <name>`，再 `ojm sign dist/<name>-<version>.tgz --id <publisher>.<key>`，"
+			+ "把 tgz + .sig 放进 cdn/ 后 `ojm market build-index`。",
+		);
+	}
+	const built = builtList[0]!;
 	const tgzPath = path.join(cdnDir, `${built.name}-${built.version}.tgz`);
 	const before = captureExisting(tgzPath);
 

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/usage.ts

@@ -16,11 +16,15 @@ 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 不起第二个服务、不做反代
@@ -105,11 +109,18 @@ const COMMAND_HELP: Record<string, string> = {
     r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开
     q  退出（后端 oj 一并终止）
   port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）`,
-	"build": `ojm build [--bundle] [--out <dir>]
+	"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 不起第二个服务、不做反代
@@ -120,8 +131,9 @@ const COMMAND_HELP: Record<string, string> = {
   --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  即使已存在也重新下载`,

package/templates/package.json

@@ -9,7 +9,9 @@
 		"preview": "ojm preview",
 		"info": "ojm info",
 		"typecheck": "tsc --noEmit -p tsconfig.json",
-		"typecheck:api": "tsc --noEmit -p src/tsconfig.json"
+		"typecheck:api": "tsc --noEmit -p src/tsconfig.json",
+		"bundle": "ojm build --bundle",
+		"new": "ojm new"
 	},
 	"devDependencies": {
 		"@ant-design/cssinjs": "catalog:",

package/templates/src/_platform/api/fixtures/l1-test-user.sql

@@ -1,10 +1,9 @@
 -- L1 测试账号（仅 `oj test` 经 fixtures 灌入，不进 release 产物）。
 --
--- 为什么不能用 seed 的 admin 跑 L1 登录：
---   ① seed 的 admin 是 must_change=1 首登改密态（D12 生产语义），且初始口令 123456
---      只是开发便利——用户在 dev 库改过口令后（产品主动引导），admin 口令即漂移，
---      L1 若绑 admin/123456 会随机 401（本地实测踩过：dev 库口令被改成 12345678）。
---   ② 判权类端点（currentAccess/assertPermission）对 must_change=1 恒 403。
+-- 为什么不能用 seed 的开发账号（admin/superadmin 等）跑 L1 登录：
+--   ① seed 账号初始口令 123456 只是开发便利——用户在 dev 库改过口令后，口令即漂移，
+--      L1 若绑 seed 账号会随机 401（本地实测踩过：dev 库口令被改成 12345678）。
+--   ② 不用 must_change 解释：seed 账号现均为 0（2026-10-22 口径）；真正的原因是 ①。
 -- 故 additive 建一个专用账号：INSERT OR IGNORE 幂等，反复重放终态一致，
 -- 不碰 admin 既有行（用户的口令/状态不受 `oj test` 影响）。
 -- 按分号朴素切分（S006）：语句内不得含分号字面量。

package/templates/src/_platform/api/seed.mysql.sql

@@ -1,8 +1,16 @@
 -- _platform 种子数据 mysql 方言覆盖（方言覆盖文件必胜；INSERT OR IGNORE → INSERT IGNORE）。
--- 语句分号切分与注释纪律同基线 seed.sql。
-INSERT IGNORE INTO users (username, password_hash, must_change) VALUES ('admin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 1);
+-- 语句分号切分与注释纪律同基线 seed.sql；账号口径同基线（账号名=角色名，must_change=0）。
+INSERT IGNORE INTO users (username, password_hash, must_change) VALUES ('superadmin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+INSERT IGNORE INTO users (username, password_hash, must_change) VALUES ('admin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+INSERT IGNORE INTO users (username, password_hash, must_change) VALUES ('editor', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+INSERT IGNORE INTO users (username, password_hash, must_change) VALUES ('viewer', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+DELETE FROM sys_user_role WHERE role_name = 'superadmin' AND user_id = (SELECT id FROM users WHERE username = 'admin');
+UPDATE users SET must_change = 0 WHERE username IN ('superadmin', 'admin', 'editor', 'viewer');
 INSERT IGNORE INTO sys_role (name, module, title, builtin) VALUES ('superadmin', 'framework', '超级管理员', 1);
 INSERT IGNORE INTO sys_role (name, module, title, builtin) VALUES ('admin', 'framework', '系统管理员', 1);
 INSERT IGNORE INTO sys_role (name, module, title, builtin) VALUES ('editor', 'framework', '编辑', 1);
 INSERT IGNORE INTO sys_role (name, module, title, builtin) VALUES ('viewer', 'framework', '访客', 1);
-INSERT IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'admin';
+INSERT IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'superadmin';
+INSERT IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'admin' FROM users WHERE username = 'admin';
+INSERT IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'editor' FROM users WHERE username = 'editor';
+INSERT IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'viewer' FROM users WHERE username = 'viewer';

package/templates/src/_platform/api/seed.pg.sql

@@ -1,8 +1,16 @@
 -- _platform 种子数据 pg 方言覆盖（方言覆盖文件必胜；INSERT OR IGNORE → ON CONFLICT DO NOTHING）。
--- 语句分号切分与注释纪律同基线 seed.sql。
-INSERT INTO users (username, password_hash, must_change) VALUES ('admin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 1) ON CONFLICT DO NOTHING;
+-- 语句分号切分与注释纪律同基线 seed.sql；账号口径同基线（账号名=角色名，must_change=0）。
+INSERT INTO users (username, password_hash, must_change) VALUES ('superadmin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0) ON CONFLICT DO NOTHING;
+INSERT INTO users (username, password_hash, must_change) VALUES ('admin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0) ON CONFLICT DO NOTHING;
+INSERT INTO users (username, password_hash, must_change) VALUES ('editor', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0) ON CONFLICT DO NOTHING;
+INSERT INTO users (username, password_hash, must_change) VALUES ('viewer', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0) ON CONFLICT DO NOTHING;
+DELETE FROM sys_user_role WHERE role_name = 'superadmin' AND user_id = (SELECT id FROM users WHERE username = 'admin');
+UPDATE users SET must_change = 0 WHERE username IN ('superadmin', 'admin', 'editor', 'viewer');
 INSERT INTO sys_role (name, module, title, builtin) VALUES ('superadmin', 'framework', '超级管理员', 1) ON CONFLICT DO NOTHING;
 INSERT INTO sys_role (name, module, title, builtin) VALUES ('admin', 'framework', '系统管理员', 1) ON CONFLICT DO NOTHING;
 INSERT INTO sys_role (name, module, title, builtin) VALUES ('editor', 'framework', '编辑', 1) ON CONFLICT DO NOTHING;
 INSERT INTO sys_role (name, module, title, builtin) VALUES ('viewer', 'framework', '访客', 1) ON CONFLICT DO NOTHING;
-INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'admin' ON CONFLICT DO NOTHING;
+INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'superadmin' ON CONFLICT DO NOTHING;
+INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'admin' FROM users WHERE username = 'admin' ON CONFLICT DO NOTHING;
+INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'editor' FROM users WHERE username = 'editor' ON CONFLICT DO NOTHING;
+INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'viewer' FROM users WHERE username = 'viewer' ON CONFLICT DO NOTHING;

package/templates/src/_platform/api/seed.sql

@@ -1,16 +1,27 @@
 -- _platform 种子数据（只放数据，DDL 归 migrations/，S006 纪律）。
 -- 方言覆盖：seed.mysql.sql / seed.pg.sql（INSERT OR IGNORE 为 sqlite 专属语法，方言文件必胜，同迁移约定）。
 -- 注意：seed 按英文分号朴素切分语句，注释里也不要出现英文分号。
--- 账号生命周期 D12：admin 为 seed 超管（superadmin），must_change=1 首登强制改密——
--- 初始口令 123456 仅为开发便利，must_change 闭环兜底默认凭据窗口（口令不随机生成的取舍见计划 A2 阶段小结）
-INSERT OR IGNORE INTO users (username, password_hash, must_change) VALUES ('admin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 1);
+-- 账号生命周期 D12（2026-10-22 调整）：四个内置角色各一个开发账号，**账号名=角色名**
+-- （superadmin/admin/editor/viewer，避免心智负担），口令均 123456，must_change=0 免首登改密——
+-- 纯开发便利（默认凭据不随机生成的取舍见计划 A2 阶段小结），生产部署须改密或删除
+INSERT OR IGNORE INTO users (username, password_hash, must_change) VALUES ('superadmin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+INSERT OR IGNORE INTO users (username, password_hash, must_change) VALUES ('admin', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+INSERT OR IGNORE INTO users (username, password_hash, must_change) VALUES ('editor', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+INSERT OR IGNORE INTO users (username, password_hash, must_change) VALUES ('viewer', '$2y$10$ylE2NdjnYiuEcq54W/KxH.bhvGaQQg3rbmYI3mcEHX6LdQEAqixeC', 0);
+-- 历史 seed 把 admin 绑在 superadmin 上；收敛为账号名=角色名（幂等 DELETE，每次重放生效）。
+-- 已存在库中 admin 行可能残留 must_change=1，UPDATE 统一收敛为 0（四个均为 seed 自有开发账号）
+DELETE FROM sys_user_role WHERE role_name = 'superadmin' AND user_id = (SELECT id FROM users WHERE username = 'admin');
+UPDATE users SET must_change = 0 WHERE username IN ('superadmin', 'admin', 'editor', 'viewer');
 -- 框架内置角色（ROLES 单一真相：superadmin 安全敏感项 / admin 日常管理 / editor、viewer 页面门）
 INSERT OR IGNORE INTO sys_role (name, module, title, builtin) VALUES ('superadmin', 'framework', '超级管理员', 1);
 INSERT OR IGNORE INTO sys_role (name, module, title, builtin) VALUES ('admin', 'framework', '系统管理员', 1);
 INSERT OR IGNORE INTO sys_role (name, module, title, builtin) VALUES ('editor', 'framework', '编辑', 1);
 INSERT OR IGNORE INTO sys_role (name, module, title, builtin) VALUES ('viewer', 'framework', '访客', 1);
--- seed 超管绑定（sys_user_role 唯一权威源，D10）
-INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'admin';
+-- 角色绑定（sys_user_role 唯一权威源，D10）：账号名=角色名一一对应
+INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'superadmin';
+INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'admin' FROM users WHERE username = 'admin';
+INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'editor' FROM users WHERE username = 'editor';
+INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'viewer' FROM users WHERE username = 'viewer';
 -- 系统设置默认值（PRD §4.3；C4 设置页 / C5 登录方式发现的数据源；framework.market_cdn_url 安全组仅 superadmin 可改）
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'React Antd Admin', 'React Antd Admin', 'system:setting.site_title', 0, 0);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.market_cdn_url', 'framework', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0);

package/templates/src/oj-market/web/api/context.ts

@@ -1,5 +1,5 @@
 import type { MarketClient } from "./client";
-import { createContext, useContext } from "react";
+import { createContext, use } from "react";
 import { httpMarketClient } from "./defaultClient";
 
 /** 市场客户端上下文（依赖注入位；默认 = 运行时 HTTP 实现，测试可替换为内存 fake） */
@@ -7,5 +7,5 @@ export const MarketClientContext = createContext<MarketClient>(httpMarketClient)
 
 /** 组件/hooks 取客户端（默认注入运行时实现） */
 export function useMarketClient(): MarketClient {
-	return useContext(MarketClientContext);
+	return use(MarketClientContext);
 }

package/templates/src/oj-market/web/components/InstallDialog.tsx

@@ -44,7 +44,7 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 	// onDone 对同一任务只通告一次：父级每次渲染都会换 onDone 身份，若只靠 deps 触发，
 	// 终态后 onDone → index.retry() → 父级重渲染 → onDone 身份变 → 再触发，会形成
 	// 无限请求循环（浏览器侧表现为 ERR_INSUFFICIENT_RESOURCES）。
-	const notifiedTaskId = useRef<string | null>(null);
+	const notifiedTaskIdRef = useRef<string | null>(null);
 
 	const targetVersion = version ?? row?.latest ?? null;
 	const title
@@ -54,9 +54,13 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 				? t("oj-market:card:upgrade")
 				: t("oj-market:task:installing");
 
-	// 打开即触发安装（version 缺省取 latest；已装视为升级；显式 version = 回滚降级安装）
+	// 打开即触发安装（version 缺省取 latest；已装视为升级；显式 version = 回滚降级安装）。
+	// 注：下面的同步 set 均为「弹窗打开/关闭生命周期」的有意重置与触发守卫；
+	// 曾尝试渲染期派生重置，但同组件 notifier effect 里的 onDone?.(record) 会触发
+	// eslint-react set-state-in-effect 的误判（prop 回调被解析回组件函数），故保留原结构。
 	useEffect(() => {
 		if (open && row && !started) {
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：打开弹窗时置「已触发」守卫，保证安装只发起一次
 			setStarted(true);
 			client
 				.install({ name: row.name, version: targetVersion, source: "cdn" })
@@ -64,19 +68,22 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 				.catch(e => setTaskId(`__error__${e instanceof Error ? e.message : String(e)}`));
 		}
 		if (!open) {
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：关闭弹窗时清空任务，下次打开是全新一次安装
 			setTaskId(null);
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：关闭时复位触发守卫，配合上行清场
 			setStarted(false);
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：关闭时清掉信任错误，避免残留到下次打开
 			setTrustError(null);
-			notifiedTaskId.current = null;
+			notifiedTaskIdRef.current = null;
 		}
 	}, [open, row, started, client, targetVersion]);
 
 	useEffect(() => {
 		if (!record || !isTerminal(record) || !done)
 			return;
-		if (notifiedTaskId.current === record.id)
+		if (notifiedTaskIdRef.current === record.id)
 			return;
-		notifiedTaskId.current = record.id;
+		notifiedTaskIdRef.current = record.id;
 		onDone?.(record);
 	}, [record, done, onDone]);
 
@@ -88,7 +95,7 @@ export function InstallDialog({ row, open, onClose, onDone, version, mode }: Ins
 		setTrustError(null);
 		try {
 			await client.trust(taskId);
-			notifiedTaskId.current = null;
+			notifiedTaskIdRef.current = null;
 			setTaskId(null);
 			setStarted(false);
 		}