@oj-module/cli 0.2.2 → 0.2.5

package/templates/api/tests/lifecycle/preflight.spec.ts

@@ -0,0 +1,255 @@
+import type { SolutionState, StateStore } from "../../src/_platform/_lifecycle/state";
+import type { InstallContext } from "../../src/_platform/_lifecycle/steps/preflight";
+// BDD：安装预检规则引擎（P1-5，R7/R8/R9/R24，十阶段状态机 stage 1）。
+// 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md（C2-01~33 安装列）；
+// 期望真源：packages/cli/src/lifecycle/__tests__/fixtures/（fixture-valid 零违规、fixture-invalid 七码齐报）。
+// 实现纪律（契约 §0/夹具 README）：收集全部违规后统一报出，不在首条违规停。
+// 表驱动：每条规则一拒例 + 一过例；过例复用 fixture-valid 全字段合法清单，拒例仅做单点变异。
+import { readFileSync } from "node:fs";
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import { preflight } from "../../src/_platform/_lifecycle/steps/preflight";
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "../../../../src/lifecycle/__tests__/fixtures");
+const VALID = parse(readFileSync(join(FIXTURES, "fixture-valid/manifest.yaml"), "utf8")) as any;
+
+/** 宿主 versions.json 假数据（C2-09 真源键：@oj-module/runtime，shell/src/manifest.ts P7.6） */
+const HOST_OK = { "@oj-module/runtime": "0.1.80" };
+
+function stateStore(solutions: SolutionState["solutions"] = {}): StateStore {
+	return { read: () => ({ solutions: { ...solutions } }), write: async () => {} };
+}
+
+function ctx(overrides: Partial<InstallContext> = {}): InstallContext {
+	return {
+		manifest: structuredClone(VALID),
+		name: "demo-solution",
+		version: "0.1.0",
+		state: stateStore(),
+		hostVersions: HOST_OK,
+		hostApiVersion: "0.1.0", // C2-11 真源默认值（= market/api.ts API_VERSION；C2-11 describe 内按用例覆盖）
+		...overrides,
+	};
+}
+
+interface RuleCase {
+	rule: string
+	clause: string
+	/** message 中除条款编号外必须出现的关键词（防「编号出现但语义报错」的假绿） */
+	keyword: string
+	mutate?: (m: any) => void
+	/** 拒例专用站点状态（占用检测注入已装方案） */
+	state?: SolutionState["solutions"]
+}
+
+const RULES: RuleCase[] = [
+	{ rule: "name 白名单（大写拒绝）", clause: "C2-01", keyword: "name", mutate: (m) => { m.name = "Demo"; } },
+	{ rule: "name 保留名（market，R9）", clause: "C2-01", keyword: "保留名", mutate: (m) => { m.name = "market"; } },
+	{ rule: "version 禁 +（oj 相容排除，附录 B-1）", clause: "C2-02", keyword: "version", mutate: (m) => { m.version = "1.0.0+build.5"; } },
+	{
+		rule: "方案名已被已装方案占用（拒装）",
+		clause: "C2-13/14",
+		keyword: "占用",
+		state: { "demo-solution": { version: "0.1.0", enabled: true, installedAt: 1730000000000 } },
+	},
+	{ rule: "api.prefix 保留段（system）", clause: "C2-13", keyword: "保留", mutate: (m) => { m.api.prefix = "/api/system"; } },
+	{ rule: "web.route_prefix 保留段（system）", clause: "C2-14", keyword: "保留", mutate: (m) => { m.web.route_prefix = "/system"; } },
+	{ rule: "peerRuntime 宿主 runtime 不满足", clause: "C2-09", keyword: "不满足", mutate: (m) => { m.peerRuntime = ">=9.9.9"; } },
+	{ rule: "anonymous 越段（R8 段内收敛）", clause: "C2-26", keyword: "首段", mutate: (m) => { m.api.anonymous = ["system/health"]; } },
+	{ rule: "anonymous _system 禁入（语法层拒绝）", clause: "C2-26", keyword: "语法", mutate: (m) => { m.api.anonymous = ["_system/health"]; } },
+	{ rule: "anonymous 登录端点禁令（R8/S1）", clause: "C2-26", keyword: "登录", mutate: (m) => { m.api.anonymous = ["demo-solution/login"]; } },
+	{ rule: "路由 category 三值（D4，personal 已废弃）", clause: "C2-17", keyword: "category", mutate: (m) => { m.routes[0].category = "personal"; } },
+	{ rule: "路由 path 语法（参数段拒绝）", clause: "C2-17", keyword: "path", mutate: (m) => { m.routes[0].path = "/demo-solution/:id"; } },
+	{ rule: "required_permission 悬空（C2-21）", clause: "C2-21", keyword: "required_permission", mutate: (m) => { m.routes[1].required_permission = "demo-solution.absent"; } },
+	{ rule: "permission code 强制 <name>. 前缀", clause: "C2-15", keyword: "code", mutate: (m) => { m.permissions[0].code = "other.view"; } },
+	{ rule: "role permissions 悬空引用", clause: "C2-16", keyword: "悬空", mutate: (m) => { m.roles[0].permissions = ["demo-solution.absent"]; } },
+	{ rule: "设置组 label_key 必填", clause: "C2-22", keyword: "label_key", mutate: (m) => { delete m.settings.groups[0].label_key; } },
+	{ rule: "设置键所有权 moduleOf(key)===name（R24）", clause: "C2-23", keyword: "所有权", mutate: (m) => { m.settings.groups[0].items[0].key = "framework.site_title"; } },
+	{
+		rule: "type=enum 缺 options",
+		clause: "C2-24",
+		keyword: "options",
+		mutate: (m) => {
+			m.settings.groups[0].items[0].type = "enum";
+			delete m.settings.groups[0].items[0].options;
+		},
+	},
+	{ rule: "health 须为本方案路由或其子路径", clause: "C2-33", keyword: "路由", mutate: (m) => { m.health = "/other-thing"; } },
+	{ rule: "web.entry 版本段必须 === version", clause: "C2-27", keyword: "entry", mutate: (m) => { m.web.entry = "modules/demo-solution/9.9.9/entry.js"; } },
+	{ rule: "api.module 存在时必须 === name", clause: "C2-12", keyword: "api.module", mutate: (m) => { m.api.module = "other-solution"; } },
+];
+
+describe("preflight 规则表（每规则一拒例 + 一过例）", () => {
+	for (const c of RULES) {
+		it(`拒例【${c.clause}】${c.rule}`, async () => {
+			const m = structuredClone(VALID);
+			c.mutate?.(m);
+			const r = await preflight(ctx({ manifest: m, state: stateStore(c.state) }));
+			expect(r.stage).toBe("preflight");
+			expect(r.ok).toBe(false);
+			expect(r.retryable).toBe(false);
+			expect(r.message).toContain(c.clause);
+			expect(r.message).toContain(c.keyword);
+		});
+
+		it(`过例【${c.clause}】${c.rule}`, async () => {
+			const r = await preflight(ctx({ state: stateStore(c.state ? {} : c.state) }));
+			expect(r.ok).toBe(true);
+		});
+	}
+});
+
+describe("preflight · C2-09 peerRuntime 范围算子语义", () => {
+	it("过例：^ 同主版本且 ≥（宿主 0.1.80 满足 ^0.1.0）", async () => {
+		const m = structuredClone(VALID);
+		m.peerRuntime = "^0.1.0";
+		expect((await preflight(ctx({ manifest: m }))).ok).toBe(true);
+	});
+
+	it("拒例：^ 主版本相同但低于基线（宿主 0.1.80 不满足 ^0.2.0）", async () => {
+		const m = structuredClone(VALID);
+		m.peerRuntime = "^0.2.0";
+		const r = await preflight(ctx({ manifest: m }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-09");
+	});
+
+	it("拒例：精确声明与宿主不符（=0.9.9）", async () => {
+		const m = structuredClone(VALID);
+		m.peerRuntime = "=0.9.9";
+		const r = await preflight(ctx({ manifest: m }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-09");
+	});
+
+	it("拒例：暂不支持的范围算子（<，P1 语义集外）", async () => {
+		const m = structuredClone(VALID);
+		m.peerRuntime = "<0.9.0";
+		const r = await preflight(ctx({ manifest: m }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-09");
+		expect(r.message).toContain("暂不支持");
+	});
+
+	it("拒例：语法非法（非范围算子字符串）", async () => {
+		const m = structuredClone(VALID);
+		m.peerRuntime = "latest";
+		const r = await preflight(ctx({ manifest: m }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-09");
+		expect(r.message).toContain("语法");
+	});
+
+	it("拒例：宿主 versions.json 缺失 → 强制比对 fail-closed", async () => {
+		const r = await preflight(ctx({ hostVersions: undefined }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-09");
+	});
+
+	it("过例：peerRuntime 缺省 → 不做比对（C2-09 可选字段）", async () => {
+		const m = structuredClone(VALID);
+		delete m.peerRuntime;
+		expect((await preflight(ctx({ manifest: m, hostVersions: undefined }))).ok).toBe(true);
+	});
+});
+
+describe("preflight · C2-11 peerPlatform 范围算子语义（^ 遵循 0.x 口径）", () => {
+	const HOST = "0.1.80";
+	it("过例：^ 同主版本且 ≥（宿主 0.1.80 满足 ^0.1.0）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "^0.1.0";
+		expect((await preflight(ctx({ manifest: m, hostApiVersion: HOST }))).ok).toBe(true);
+	});
+
+	it("拒例：^ 主版本相同但低于基线（宿主 0.1.80 不满足 ^0.2.0）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "^0.2.0";
+		const r = await preflight(ctx({ manifest: m, hostApiVersion: HOST }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-11");
+	});
+
+	it("拒例：0.x 口径——^0.1.0 不兼容 0.2.x（minor 不同即不兼容）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "^0.1.0";
+		const r = await preflight(ctx({ manifest: m, hostApiVersion: "0.2.3" }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-11");
+	});
+
+	it("过例：0.x 口径——^0.2.0 兼容 0.2.5（minor 相同，patch 更高）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "^0.2.0";
+		expect((await preflight(ctx({ manifest: m, hostApiVersion: "0.2.5" }))).ok).toBe(true);
+	});
+
+	it("过例：>= 跨 minor 满足（宿主 0.2.3 满足 >=0.1.0）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = ">=0.1.0";
+		expect((await preflight(ctx({ manifest: m, hostApiVersion: "0.2.3" }))).ok).toBe(true);
+	});
+
+	it("拒例：精确声明与宿主不符（=0.1.0 vs 宿主 0.1.80）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "=0.1.0";
+		const r = await preflight(ctx({ manifest: m, hostApiVersion: HOST }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-11");
+	});
+
+	it("拒例：暂不支持的范围算子（<，P1 语义集外）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "<0.9.0";
+		const r = await preflight(ctx({ manifest: m, hostApiVersion: HOST }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-11");
+		expect(r.message).toContain("暂不支持");
+	});
+
+	it("拒例：语法非法（非范围算子字符串）", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "latest";
+		const r = await preflight(ctx({ manifest: m, hostApiVersion: HOST }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-11");
+		expect(r.message).toContain("语法");
+	});
+
+	it("拒例：宿主 API 版本未注入 → 强制比对 fail-closed", async () => {
+		const m = structuredClone(VALID);
+		m.peerPlatform = "^0.1.0";
+		const r = await preflight(ctx({ manifest: m, hostApiVersion: undefined }));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("C2-11");
+	});
+
+	it("过例：peerPlatform 缺省 → 不做比对（C2-11 可选字段）", async () => {
+		const m = structuredClone(VALID);
+		delete m.peerPlatform;
+		expect((await preflight(ctx({ manifest: m, hostApiVersion: undefined }))).ok).toBe(true);
+	});
+});
+
+describe("preflight · C2 夹具（双端唯一真源）", () => {
+	it("fixture-valid：零违规通过", async () => {
+		const r = await preflight(ctx({}));
+		expect(r.ok).toBe(true);
+		expect(r.stage).toBe("preflight");
+		expect(r.message).toContain("预检通过");
+	});
+
+	it("fixture-invalid：七码齐报且全量列出（C2-01/02/16/17/22/23/26）", async () => {
+		const m = parse(readFileSync(join(FIXTURES, "fixture-invalid/manifest.yaml"), "utf8"));
+		const r = await preflight(ctx({ manifest: m, name: "Demo", version: "1.0.0+build.5" }));
+		expect(r.ok).toBe(false);
+		expect(r.retryable).toBe(false);
+		// 七码同现于同一条 message = 「收集全部违规后统一报出」纪律的实现证据
+		for (const code of ["C2-01", "C2-02", "C2-16", "C2-17", "C2-22", "C2-23", "C2-26"]) {
+			expect(r.message).toContain(code);
+		}
+	});
+});

package/templates/api/tests/lifecycle/register.spec.ts

@@ -0,0 +1,194 @@
+// BDD：注册步骤（P1-8，十阶段 stage registering，D10 唯一出口）。
+// 安装 = registerSolution 一次性把方案声明的 RBAC/设置/路由 upsert 进宿主库：
+// sys_role/sys_permission 经 upsertSolutionPerms 出口（AC2-1~6），sys_setting/sys_solution_route
+// 在本步收敛；声明消失 → 行保留标 deprecated=1（镜像 solution-perms），管理员改过的
+// value 永不被声明覆写（AC1-15 同纪律）。DB 级路由占用检查承接 P1-5 备案③（首段比较）。
+// queryRegistered 归一化快照（过滤 deprecated）供 P1-9 冒烟对账；auditOp 落 solution.register。
+// 夹具即真实库：真实迁移建表（0010 重构 sys_solution_route + sys_setting 补 deprecated）。
+/* eslint-disable test/prefer-lowercase-title -- 任务/AC 编号是验收锚点，保留大写（DB/P1-5） */
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { checkOccupancy, queryAllRegistered, queryRegistered, registerSolution } from "../../src/_platform/_lifecycle/steps/register";
+import { installDb } from "../fixture";
+
+let dbo: ReturnType<typeof installDb>;
+const g = globalThis as any;
+
+beforeAll(() => {
+	dbo = installDb();
+	g.http = {}; // 安装器系统侧：无 http 会话 → audit username='system'
+});
+
+afterEach(() => {
+	g.http = {};
+	dbo.exec("DELETE FROM sys_role_permission");
+	dbo.exec("DELETE FROM sys_user_role");
+	dbo.exec("DELETE FROM sys_permission");
+	dbo.exec("DELETE FROM sys_role");
+	dbo.exec("DELETE FROM sys_solution_route");
+	dbo.exec("DELETE FROM sys_setting");
+	dbo.exec("DELETE FROM sys_oplog");
+});
+
+function rows(sql: string) {
+	return dbo.prepare(sql).all() as Record<string, unknown>[];
+}
+
+function counts() {
+	const c = (t: string) => Number((rows(`SELECT COUNT(*) AS n FROM ${t}`)[0]).n);
+	return { role: c("sys_role"), perm: c("sys_permission"), setting: c("sys_setting"), route: c("sys_solution_route") };
+}
+
+/** wiki 1.0.0 声明切片：两角色一（含两权限点）、两设置项、两路由 */
+const WIKI_V1 = {
+	module: "wiki",
+	version: "1.0.0",
+	roles: [
+		{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.create", "wiki.space.create"] },
+	],
+	settings: [
+		{ key: "wiki.home.page", group: "wiki", type: "string", default_value: "start", label_key: "wiki:settings.home" },
+		{ key: "wiki.readonly", group: "wiki", type: "bool", default_value: "0" },
+	],
+	routes: [
+		{ path: "/wiki/docs", category: "main", order: 200, title_key: "wiki:menu.docs" },
+		{ path: "/wiki/admin", category: "admin", order: 300, title_key: "wiki:menu.admin", required_permission: "wiki.doc.create" },
+	],
+};
+
+describe("注册后四表行存在", () => {
+	it("注册一次落齐 sys_role/sys_permission/sys_setting/sys_solution_route，deprecated 为空", async () => {
+		const r = await registerSolution(WIKI_V1);
+		expect(r.ok).toBe(true);
+		expect(r.deprecated).toEqual([]);
+		expect(rows("SELECT * FROM sys_role WHERE name = 'wiki.admin'")).toHaveLength(1);
+		expect(rows("SELECT * FROM sys_permission")).toHaveLength(2);
+		const setting = rows("SELECT * FROM sys_setting WHERE key = 'wiki.home.page'")[0];
+		expect(setting.value).toBe("start"); // 首装 value = default_value
+		expect(setting.module).toBe("wiki");
+		expect(setting.label_key).toBe("wiki:settings.home");
+		const route = rows("SELECT * FROM sys_solution_route WHERE path = '/wiki/admin'")[0];
+		expect(route.module).toBe("wiki");
+		expect(route.category).toBe("admin");
+		expect(route.required_permission).toBe("wiki.doc.create");
+		expect(Number(route.deprecated)).toBe(0);
+	});
+});
+
+describe("重跑幂等", () => {
+	it("同 decl 跑两遍：四表行数不变；管理员改过的 value 不被覆写（AC1-15 同纪律），定义列照常更新", async () => {
+		await registerSolution(WIKI_V1);
+		dbo.exec("UPDATE sys_setting SET value = 'admin-changed' WHERE key = 'wiki.home.page'");
+		const before = counts();
+		const r = await registerSolution({
+			...WIKI_V1,
+			settings: [{ ...WIKI_V1.settings[0], default_value: "start-v2" }, WIKI_V1.settings[1]],
+		});
+		expect(r.ok).toBe(true);
+		expect(r.deprecated).toEqual([]);
+		expect(counts()).toEqual(before);
+		expect(rows("SELECT value, default_value FROM sys_setting WHERE key = 'wiki.home.page'")[0]).toEqual({ value: "admin-changed", default_value: "start-v2" });
+	});
+});
+
+describe("deprecated 语义（镜像 solution-perms AC2-3/4）", () => {
+	it("声明消失的 route/setting 旧行保留标 deprecated=1 并汇入清单；queryRegistered 快照不再含", async () => {
+		await registerSolution(WIKI_V1);
+		const r = await registerSolution({
+			...WIKI_V1,
+			version: "1.1.0",
+			roles: [{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.create"] }], // wiki.space.create 消失
+			settings: [WIKI_V1.settings[0]], // wiki.readonly 消失
+			routes: [WIKI_V1.routes[0]], // /wiki/admin 消失
+		});
+		expect(r.ok).toBe(true);
+		expect(r.deprecated).toEqual(["wiki.space.create", "wiki.readonly", "/wiki/admin"]);
+		// 旧行全保留且标 deprecated（判决不突变）
+		expect(Number(rows("SELECT deprecated FROM sys_permission WHERE code = 'wiki.space.create'")[0].deprecated)).toBe(1);
+		expect(rows("SELECT * FROM sys_setting WHERE key = 'wiki.readonly'")).toHaveLength(1);
+		expect(Number(rows("SELECT deprecated FROM sys_setting WHERE key = 'wiki.readonly'")[0].deprecated)).toBe(1);
+		expect(rows("SELECT * FROM sys_solution_route WHERE path = '/wiki/admin'")).toHaveLength(1);
+		expect(Number(rows("SELECT deprecated FROM sys_solution_route WHERE path = '/wiki/admin'")[0].deprecated)).toBe(1);
+		// 快照只含现行声明行
+		const snap = await queryRegistered("wiki");
+		expect(snap?.routes).toEqual(["/wiki/docs"]);
+		expect(snap?.settings).toEqual(["wiki.home.page"]);
+		expect(snap?.permissions).toEqual(["wiki.doc.create"]);
+	});
+});
+
+describe("DB 级路由占用（P1-5 备案③承接）", () => {
+	it("module B 声明 module A 已注册的首段 → ok=false 含占用者，A 的行原样", async () => {
+		await registerSolution({ module: "alpha", roles: [], routes: [{ path: "/alpha/x", category: "main", order: 200, title_key: "alpha:menu.x" }] });
+		const before = rows("SELECT * FROM sys_solution_route");
+		const r = await registerSolution({ module: "beta", roles: [], routes: [{ path: "/alpha/y", category: "main", order: 200, title_key: "beta:menu.y" }] });
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("alpha");
+		expect(rows("SELECT * FROM sys_solution_route")).toEqual(before);
+	});
+
+	it("checkOccupancy：同 module 重注册不报自占；他 module 首段冲突逐条报告", async () => {
+		await registerSolution({ module: "alpha", roles: [], routes: [{ path: "/alpha/x", category: "main", order: 200, title_key: "alpha:menu.x" }] });
+		expect(await checkOccupancy("alpha", ["/alpha/x", "/alpha/z"])).toEqual([]);
+		expect(await checkOccupancy("beta", ["/alpha/y", "/beta/own"])).toEqual(["/alpha/y"]);
+	});
+});
+
+describe("queryRegistered：冒烟对账快照", () => {
+	it("未注册返回 null；注册后四清单全排序、module 归一", async () => {
+		expect(await queryRegistered("nosuch")).toBeNull();
+		await registerSolution({
+			module: "sort",
+			roles: [{ name: "sort.b", title: "B" }, { name: "sort.a", title: "A" }],
+			settings: [
+				{ key: "sort.k2", group: "sort", type: "string", default_value: "2" },
+				{ key: "sort.k1", group: "sort", type: "string", default_value: "1" },
+			],
+			routes: [
+				{ path: "/sort/z", category: "hidden", order: 200 },
+				{ path: "/sort/m", category: "main", order: 201, title_key: "sort:menu.m" },
+			],
+		});
+		expect(await queryRegistered("sort")).toEqual({
+			module: "sort",
+			routes: ["/sort/m", "/sort/z"],
+			settings: ["sort.k1", "sort.k2"],
+			roles: ["sort.a", "sort.b"],
+			permissions: [],
+		});
+	});
+});
+
+describe("queryAllRegistered：全方案快照清单（P1-14 读端点辅助）", () => {
+	it("四表并集取模块名，按 module 排序逐个快照；无任何行 → 空数组", async () => {
+		expect(await queryAllRegistered()).toEqual([]);
+		await registerSolution({ module: "b-sol", roles: [], settings: [], routes: [{ path: "/b", category: "main", order: 200 }] });
+		await registerSolution({ module: "a-sol", roles: [], settings: [{ key: "a.k", group: "g", type: "string" }], routes: [] });
+		const all = await queryAllRegistered();
+		expect(all.map(s => s.module)).toEqual(["a-sol", "b-sol"]);
+		expect(all.find(s => s.module === "a-sol")).toMatchObject({ settings: ["a.k"], routes: [] });
+		expect(all.find(s => s.module === "b-sol")).toMatchObject({ routes: ["/b"] });
+	});
+
+	it("deprecated 行不计入存在性：唯一路由被声明消失标 deprecated 后方案不再列出", async () => {
+		await registerSolution({ module: "gone-sol", roles: [], settings: [], routes: [{ path: "/gone", category: "main", order: 200 }] });
+		// 重注册去掉 /gone → 旧行 deprecated=1，方案再无任何非 deprecated 行
+		await registerSolution({ module: "gone-sol", roles: [], settings: [], routes: [] });
+		const all = await queryAllRegistered();
+		expect(all.map(s => s.module)).toEqual([]);
+	});
+});
+
+describe("审计：auditOp 落 solution.register", () => {
+	it("注册成功落 oplog 一条（系统侧 username=system，含版本与 deprecated 明细）", async () => {
+		await registerSolution(WIKI_V1);
+		await vi.waitFor(() => expect(rows("SELECT * FROM sys_oplog")).toHaveLength(1));
+		const r = rows("SELECT * FROM sys_oplog")[0];
+		expect(r.action).toBe("solution.register");
+		expect(r.module).toBe("wiki");
+		expect(r.version).toBe("1.0.0");
+		expect(r.target).toBe("wiki");
+		expect(r.username).toBe("system");
+		expect(JSON.parse(String(r.detail))).toEqual({ routes: 2, settings: 2, deprecated: [] });
+	});
+});

package/templates/api/tests/lifecycle/semver.spec.ts

@@ -0,0 +1,43 @@
+// BDD：semver 比较器（R25，P1-1）。纯字符串解析、无依赖。
+// 语义边界：数字段数值比较；prerelease 标识符数字按数值、字母按字典序、数字 < 字母；
+// 无 prerelease > 有 prerelease；「1.0」「1.0.0」「1.0.0.0」视为相等（安装器容错口径）。
+import { describe, expect, it } from "vitest";
+
+import { compareVersions } from "../../src/_platform/_lifecycle/semver";
+
+const cases: Array<[a: string, b: string, expected: -1 | 0 | 1]> = [
+	// 主版本数值比较（非字典序）
+	["0.1.10", "0.1.9", 1],
+	["0.1.9", "0.1.10", -1],
+	["2.0.0", "10.0.0", -1],
+	// 相等
+	["1.0.0", "1.0.0", 0],
+	// 长度容错：缺省段视为 0
+	["1.0", "1.0.0", 0],
+	["1.0.0", "1.0.0.0", 0],
+	["1", "1.0.0", 0],
+	// prerelease：有 prerelease < 无 prerelease
+	["1.0.0-alpha", "1.0.0", -1],
+	["1.0.0", "1.0.0-alpha", 1],
+	// prerelease 数字标识符按数值比较
+	["1.0.0-alpha.2", "1.0.0-alpha.10", -1],
+	// prerelease 字母标识符按字典序
+	["1.0.0-alpha", "1.0.0-beta", -1],
+	// prerelease 数字 < 字母
+	["1.0.0-1", "1.0.0-alpha", -1],
+	// prerelease 标识符多的 > 标识符少的（前缀相同）
+	["1.0.0-alpha", "1.0.0-alpha.1", -1],
+	// 标识符内部数字段仍按数值：alpha.9 < alpha.10
+	["1.0.0-alpha.9", "1.0.0-alpha.10", -1],
+	// 多连字符 prerelease：首个 - 后整体为标识符串，不得截断静默判等
+	["1.0.0-alpha-beta", "1.0.0-alpha", 1],
+	["1.0.0-alpha-beta", "1.0.0-alpha.2", 1],
+];
+
+describe("compareVersions（R25）", () => {
+	for (const [a, b, expected] of cases) {
+		it(`${a} vs ${b} → ${expected}`, () => {
+			expect(compareVersions(a, b)).toBe(expected);
+		});
+	}
+});

package/templates/api/tests/lifecycle/sha384.spec.ts

@@ -0,0 +1,48 @@
+// BDD：纯 JS SHA-384（B-11 真机补面）。oj isolate 无 sha384 原语而契约 C2-28 钉死
+// `sha384-<base64>`——安装器（isolate 内）必须与 ojm build（Node 侧）同算法重算比对。
+// 向量真源 = FIPS 180-4 官方样例 + node:crypto 交叉验证（长度跨 0/128 字节块边界）。
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { bytesToBase64, sha384B64, sha384Bytes } from "../../src/_platform/_lifecycle/sha384";
+
+const hex = (bytes: Uint8Array): string => Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+
+describe("sha384Bytes（FIPS 180-4 向量）", () => {
+	it("空串", () => {
+		expect(hex(sha384Bytes(new Uint8Array(0)))).toBe("38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b");
+	});
+
+	it("\"abc\"（官方样例）", () => {
+		expect(hex(sha384Bytes(new TextEncoder().encode("abc")))).toBe("cb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7");
+	});
+
+	it("双块以上长输入（1129 字节伪随机）与 node:crypto 逐字一致", () => {
+		const data = new Uint8Array(1129);
+		for (let i = 0; i < data.length; i++) {
+			data[i] = (i * 131 + 7) & 0xFF;
+		}
+		const expected = createHash("sha384").update(data).digest("hex");
+		expect(hex(sha384Bytes(data))).toBe(expected);
+	});
+
+	it("块边界邻域（127/128/129/255/256 字节）与 node:crypto 交叉一致", () => {
+		for (const len of [1, 63, 64, 111, 112, 113, 127, 128, 129, 255, 256, 257]) {
+			const data = new Uint8Array(len).fill(0xA5);
+			expect(hex(sha384Bytes(data)), `len=${len}`).toBe(createHash("sha384").update(data).digest("hex"));
+		}
+	});
+});
+
+describe("sha384B64（C2-28 integrity 形态）", () => {
+	it("与 node:crypto 的 base64 摘要拼接一致：sha384-<b64>", () => {
+		const data = new TextEncoder().encode("demo-solution entry.js");
+		const expected = `sha384-${createHash("sha384").update(data).digest("base64")}`;
+		expect(sha384B64(data)).toBe(expected);
+		expect(sha384B64(data)).toMatch(/^sha384-[A-Za-z0-9+/]{64}$/);
+	});
+
+	it("bytesToBase64 与 Buffer base64 一致", () => {
+		expect(bytesToBase64(new Uint8Array([0, 1, 2, 250, 251]))).toBe(Buffer.from([0, 1, 2, 250, 251]).toString("base64"));
+	});
+});

package/templates/api/tests/lifecycle/sig-fixtures.spec.ts

@@ -0,0 +1,65 @@
+// 签名链夹具 templates 面断言（P2-0，契约 v1.3 §2.11/§2.12 + 附录 A.2）。
+// 与 CLI 面（packages/cli/src/lifecycle/__tests__/sig-fixtures.test.ts）共用同一组提交产物：
+// 本 spec 证明夹具从 templates 测试 root 可达、可再生且字节一致（双端三同一的夹具侧锚点）。
+// isolate 生产面（steps/verify.ts + CryptoFace.verifyEd25519）对同组夹具的六码/TOFU 断言属 P2-3。
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SIG_DIR = path.resolve(HERE, "../../../../src/lifecycle/__tests__/fixtures/sig");
+const GEN = path.join(SIG_DIR, "gen-signed-fixtures.mjs");
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const STD_B64 = /^[A-Z0-9+/]+={0,2}$/i;
+const KEY_ID = /^[a-z][a-z0-9-]*\.[a-z0-9-]+$/;
+
+const gen = (await import(GEN)) as {
+	FIXTURE_NAME: string
+	FIXTURE_VERSION: string
+	CANON: string
+	canonicalString: (name: string, version: string, sha256: string) => string
+	fingerprintOf: (publicKeyHex: string) => string
+	generate: (outDir: string) => { sha256: string, canonical: string, paths: Record<string, string> }
+};
+
+describe("签名链夹具 · templates 面可达性与再生一致性（P2-0）", () => {
+	const name = gen.FIXTURE_NAME;
+	const version = gen.FIXTURE_VERSION;
+	const tgzPath = path.join(SIG_DIR, `${name}-${version}.tgz`);
+	const tgz = readFileSync(tgzPath);
+	const sha256 = createHash("sha256").update(tgz).digest("hex");
+
+	it("三枚 .sig 从 templates 测试 root 可达且字段形态合法", () => {
+		for (const suffix of [".sig", ".bad.sig", ".unknown.sig"]) {
+			const sig = JSON.parse(readFileSync(`${tgzPath}${suffix}`, "utf8")) as Record<string, string>;
+			expect(sig.alg).toBe("Ed25519");
+			expect(sig.canon).toBe(gen.CANON);
+			expect(sig.public_key).toMatch(HEX64);
+			expect(sig.value).toMatch(STD_B64);
+			expect(sig.value).not.toMatch(/[-_]/);
+			expect(sig.key_id).toMatch(KEY_ID);
+		}
+	});
+
+	it("规范串与指纹从 templates 面计算与提交产物一致（三同一的夹具侧）", () => {
+		const canonical = gen.canonicalString(name, version, sha256);
+		expect(canonical).toBe(`${name}@${version}:${sha256}`);
+		const sig = JSON.parse(readFileSync(`${tgzPath}.sig`, "utf8")) as { public_key: string };
+		expect(gen.fingerprintOf(sig.public_key)).toMatch(HEX64);
+	});
+
+	it("生成器跨 root 再生到 tmp 与提交产物字节一致（双端共用同一生成逻辑）", () => {
+		const out = path.join(os.tmpdir(), `ojm-sig-fixtures-tpl-${process.pid}`);
+		const r = gen.generate(out);
+		expect(r.sha256).toBe(sha256);
+		expect(r.canonical).toBe(`${name}@${version}:${sha256}`);
+		expect(readFileSync(r.paths.tgz).equals(tgz)).toBe(true);
+		expect(readFileSync(r.paths.good, "utf8")).toBe(readFileSync(`${tgzPath}.sig`, "utf8"));
+		expect(readFileSync(r.paths.bad, "utf8")).toBe(readFileSync(`${tgzPath}.bad.sig`, "utf8"));
+		expect(readFileSync(r.paths.unknown, "utf8")).toBe(readFileSync(`${tgzPath}.unknown.sig`, "utf8"));
+	});
+});