@oj-module/cli 0.2.1 → 0.2.5

package/src/lifecycle/__tests__/manifest-contract.test.ts

@@ -0,0 +1,228 @@
+import type { InstallContext } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+
+// BDD：bundle 级 manifest.yaml 契约校验（P1-11，C2 规则构建列）。
+// 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md（C2-01~33 构建列，§4.1 矩阵）；
+// 期望真源：同目录 fixtures/（fixture-valid 零违规、fixture-invalid 七码齐报）。
+// 实现纪律（契约 §0/夹具 README）：收集全部违规后统一报出，不在首条违规停。
+// 双端一致：同一夹具既跑本侧 validateContract，也跑 isolate 侧 preflight——两份实现由夹具钉住。
+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";
+// 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
+// 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
+import { preflight } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, validateContract } from "../../manifest-contract";
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
+const readText = (p: string) => readFileSync(join(FIXTURES, p), "utf8");
+
+const VALID = parse(readText("fixture-valid/manifest.yaml")) as Record<string, unknown>;
+const INVALID = parse(readText("fixture-invalid/manifest.yaml")) as Record<string, unknown>;
+
+/** fixture-invalid 期望违规码（夹具 README/EXPECTED-VIOLATIONS 逐字） */
+const INVALID_CODES = ["C2-01", "C2-02", "C2-16", "C2-17", "C2-22", "C2-23", "C2-26"];
+
+function clauseOf(violations: string[]): string[] {
+	return violations.map(v => /【([^】]+)】/.exec(v)?.[1] ?? "");
+}
+
+// ── 双端一致：同一夹具，Node validateContract 与 isolate preflight 互认 ──
+
+describe("双端一致（夹具 §5：DRY 于夹具而非运行时）", () => {
+	it("fixture-valid：validateContract 零违规，preflight 也通过", async () => {
+		expect(validateContract(VALID)).toEqual([]);
+		const r = await preflight(makeCtx(structuredClone(VALID)));
+		expect(r.ok).toBe(true);
+	});
+
+	it("fixture-invalid：两端均拒绝，且 validateContract 报出七码全集", async () => {
+		const violations = validateContract(INVALID);
+		expect(violations.length).toBeGreaterThan(0);
+		expect(clauseOf(violations)).toEqual(expect.arrayContaining(INVALID_CODES));
+		const r = await preflight(makeCtx(structuredClone(INVALID)));
+		expect(r.ok).toBe(false);
+		for (const code of INVALID_CODES)
+			expect(r.message).toContain(code);
+	});
+});
+
+// ── 表驱动：每规则一拒例（单点变异合法夹具）+ 共享过例 ──
+
+interface RuleCase {
+	rule: string
+	clause: string
+	/** 违规串中除编号外必须出现的关键词（防「编号出现但语义报错」的假绿） */
+	keyword: string
+	mutate: (m: any) => void
+}
+
+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: "version 禁下划线（契约收紧）", clause: "C2-02", keyword: "version", mutate: (m) => { m.version = "1.0.0_beta"; } },
+	{ rule: "title ≤100", clause: "C2-03", keyword: "title", mutate: (m) => { m.title = "x".repeat(101); } },
+	{ rule: "summary 必填", clause: "C2-04", keyword: "summary", mutate: (m) => { delete m.summary; } },
+	{ rule: "summary 必须单行", clause: "C2-04", keyword: "单行", mutate: (m) => { m.summary = "第一行\n第二行"; } },
+	{ rule: "description ≤2000", clause: "C2-05", keyword: "description", mutate: (m) => { m.description = "x".repeat(2001); } },
+	{ rule: "icon 语法（http(s)/ 绝对路径）", clause: "C2-06", keyword: "icon", mutate: (m) => { m.icon = "ftp://x/y.svg"; } },
+	{ rule: "license SPDX 简化式", clause: "C2-07", keyword: "license", mutate: (m) => { m.license = "没有空格的中文许可证!"; } },
+	{ rule: "homepage http(s)", clause: "C2-07", keyword: "homepage", mutate: (m) => { m.homepage = "example.com"; } },
+	{ rule: "keywords 项语法", clause: "C2-07", keyword: "keywords", mutate: (m) => { m.keywords = ["合法", "ok2"]; } },
+	{ rule: "keywords ≤10", clause: "C2-07", keyword: "keywords", mutate: (m) => { m.keywords = Array.from({ length: 11 }, (_, i) => `k${i}`); } },
+	{ rule: "changelog 必填（R27）", clause: "C2-08", keyword: "changelog", mutate: (m) => { delete m.changelog; } },
+	{ rule: "changelog 数组条目非空", clause: "C2-08", keyword: "changelog", mutate: (m) => { m.changelog = [""]; } },
+	{ rule: "changelog ≤50 条", clause: "C2-08", keyword: "changelog", mutate: (m) => { m.changelog = Array.from({ length: 51 }, (_, i) => `v${i}`); } },
+	{ rule: "peerRuntime 暂不支持算子（<= 构建期即拒）", clause: "C2-09", keyword: "范围算子", mutate: (m) => { m.peerRuntime = "<=0.1.0"; } },
+	{ rule: "peerRuntime 语法（version 部分遵守 C2-02）", clause: "C2-09", keyword: "peerRuntime", mutate: (m) => { m.peerRuntime = ">=beta1"; } },
+	{ rule: "peerOj 语法（P1 声明不强制，语法由构建期负责）", clause: "C2-10", keyword: "peerOj", mutate: (m) => { m.peerOj = "1.0.0+build"; } },
+	{ rule: "peerFramework 语法", clause: "C2-10", keyword: "peerFramework", mutate: (m) => { m.peerFramework = ">=^0.2"; } },
+	{ rule: "peerPlatform 语法", clause: "C2-11", keyword: "peerPlatform", mutate: (m) => { m.peerPlatform = "1.0.0_beta"; } },
+	{ rule: "api.module 存在时必须 === name", clause: "C2-12", keyword: "api.module", mutate: (m) => { m.api.module = "other-solution"; } },
+	{ rule: "api.prefix 语法", clause: "C2-13", keyword: "api.prefix", mutate: (m) => { m.api.prefix = "/api/Demo"; } },
+	{ rule: "api.prefix 保留段（system）", clause: "C2-13", keyword: "保留名", mutate: (m) => { m.api.prefix = "/api/system"; } },
+	{ rule: "api.tables 项语法", clause: "C2-12a", keyword: "api.tables", mutate: (m) => { m.api.tables = ["1Bad"]; } },
+	{ rule: "api.deps 键语法", clause: "C2-12b", keyword: "api.deps", mutate: (m) => { m.api.deps = { Bad_Key: ">=0.1.0" }; } },
+	{ rule: "api.deps 值暂不支持算子", clause: "C2-12b", keyword: "范围算子", mutate: (m) => { m.api.deps = { other: "<1.0.0" }; } },
+	{ rule: "anonymous 越段（R8 段内收敛）", 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: "anonymous 语法（前导斜杠拒绝）", clause: "C2-26", keyword: "语法", mutate: (m) => { m.api.anonymous = ["/demo-solution/ping"]; } },
+	{ rule: "web.route_prefix 保留段", clause: "C2-14", keyword: "保留名", mutate: (m) => { m.web.route_prefix = "/system"; } },
+	{ rule: "web.entry 版本段必须 === version", clause: "C2-27", keyword: "web.entry", mutate: (m) => { m.web.entry = "modules/demo-solution/9.9.9/entry.js"; } },
+	{ rule: "web.css 后缀与版本段", clause: "C2-27", keyword: "web.css", mutate: (m) => { m.web.css = ["modules/demo-solution/9.9.9/x.css"]; } },
+	{ rule: "web.integrity 形态（sha384-64base64）", clause: "C2-28", keyword: "web.integrity", mutate: (m) => { m.web.integrity = "md5-AAAA"; } },
+	{ rule: "permission code 强制 <name>. 前缀", clause: "C2-15", keyword: "code", mutate: (m) => { m.permissions[0].code = "other.view"; } },
+	{ rule: "permission title_key 命名空间", clause: "C2-15", keyword: "title_key", mutate: (m) => { m.permissions[0].title_key = "other:perm.view"; } },
+	{ rule: "role name <name>.<role>", clause: "C2-16", keyword: "role", mutate: (m) => { m.roles[0].name = "demo-solution.Admin"; } },
+	{ rule: "role permissions 悬空引用", clause: "C2-16", keyword: "悬空", mutate: (m) => { m.roles[0].permissions = ["demo-solution.absent"]; } },
+	{ 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: "路由 order 必填整数", clause: "C2-17", keyword: "order", mutate: (m) => { delete m.routes[0].order; } },
+	{ rule: "required_permission 悬空（C2-21）", clause: "C2-21", keyword: "required_permission", mutate: (m) => { m.routes[1].required_permission = "demo-solution.absent"; } },
+	{ rule: "设置组标识语法", clause: "C2-22", keyword: "设置组", mutate: (m) => { m.settings.groups[0].group = "Display"; } },
+	{ rule: "设置组 label_key 必填", clause: "C2-22", keyword: "label_key", mutate: (m) => { delete m.settings.groups[0].label_key; } },
+	{ rule: "设置组 items 非空", clause: "C2-22", keyword: "items", mutate: (m) => { m.settings.groups[0].items = []; } },
+	{ rule: "设置键所有权 moduleOf(key)===name（R24）", clause: "C2-23", keyword: "所有权", mutate: (m) => { m.settings.groups[0].items[0].key = "framework.site_title"; } },
+	{ rule: "设置项 type 枚举", clause: "C2-24", keyword: "type", mutate: (m) => { m.settings.groups[0].items[0].type = "varchar"; } },
+	{ 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: "设置项 default 必须字符串", clause: "C2-24", keyword: "default", mutate: (m) => { m.settings.groups[0].items[0].default = 20; } },
+	{ rule: "设置项 label_key 命名空间", clause: "C2-24", keyword: "label_key", mutate: (m) => { m.settings.groups[0].items[0].label_key = "framework:settings.x"; } },
+	{ rule: "health 须为本方案路由或其子路径", clause: "C2-33", keyword: "路由", mutate: (m) => { m.health = "/other-thing"; } },
+	{ rule: "archive Form A 禁 sha256（自引用悖论，附录 B-2）", clause: "C2-29", keyword: "sha256", mutate: (m) => { m.archive.sha256 = "a".repeat(64); } },
+	{ rule: "archive Form A 禁 signature", clause: "C2-29", keyword: "signature", mutate: (m) => { m.archive.signature = { alg: "Ed25519" }; } },
+	{ rule: "archive.file 命名", clause: "C2-29", keyword: "archive.file", mutate: (m) => { m.archive.file = "wrong.tgz"; } },
+	{ rule: "顶层未知键拒绝（防拼写漂移静默失效）", clause: "§1", keyword: "未知", mutate: (m) => { m.visibility = "public"; } },
+];
+
+describe("validateContract 规则表（每规则一拒例）", () => {
+	it("共享过例：未变异的 fixture-valid 零违规", () => {
+		expect(validateContract(VALID)).toEqual([]);
+	});
+
+	it("非对象 manifest：统一报出单条可读违规", () => {
+		for (const bad of [null, "x", 42, []]) {
+			const v = validateContract(bad);
+			expect(v.length).toBeGreaterThan(0);
+			expect(v[0]).toContain("manifest");
+		}
+	});
+
+	for (const c of RULES) {
+		it(`拒例【${c.clause}】${c.rule}`, () => {
+			const m = structuredClone(VALID);
+			c.mutate(m);
+			const violations = validateContract(m);
+			const hit = violations.find(v => v.includes(c.clause));
+			expect(hit, `期望包含【${c.clause}】的违规，实际：\n${violations.join("\n")}`).toBeTruthy();
+			expect(hit).toContain(c.keyword);
+		});
+	}
+});
+
+// ── parseManifest ──
+
+describe("parseManifest", () => {
+	it("合法 yaml → ok:true 且返回对象", () => {
+		const r = parseManifest(readText("fixture-valid/manifest.yaml"));
+		expect(r.ok).toBe(true);
+		if (r.ok)
+			expect(r.manifest.name).toBe("demo-solution");
+	});
+
+	it("非法 yaml 语法 → ok:false 可读错误（不含堆栈噪音）", () => {
+		const r = parseManifest("name: [unclosed");
+		expect(r.ok).toBe(false);
+		if (!r.ok)
+			expect(r.error).toContain("manifest.yaml");
+	});
+
+	it("顶层非映射（数组/标量）→ ok:false", () => {
+		for (const bad of ["- a\n- b\n", "42\n", "null\n"]) {
+			const r = parseManifest(bad);
+			expect(r.ok).toBe(false);
+		}
+	});
+});
+
+// ── 文件面契约（构建期专属执行点；纯内容入参，fs 在 bundle.ts）──
+
+describe("checkTablesAgainstSchema（C2-12a：构建 ✅ 对照 schema.yaml）", () => {
+	const SCHEMA = readText("fixture-valid/api/src/demo-solution/schema.yaml");
+
+	it("fixture-valid tables [note] 与 schema.yaml 表集一致 → 零违规", () => {
+		expect(checkTablesAgainstSchema(structuredClone(VALID), SCHEMA)).toEqual([]);
+	});
+
+	it("tables 与 schema.yaml 表集不一致 → C2-12a 且指明差额", () => {
+		const m = structuredClone(VALID);
+		(m.api as any).tables = ["note", "ghost"];
+		const v = checkTablesAgainstSchema(m, SCHEMA);
+		expect(v[0]).toContain("C2-12a");
+		expect(v[0]).toContain("ghost");
+	});
+});
+
+describe("checkLocalesComplete（C2-25：构建期缺 key fail-fast）", () => {
+	const ZH = readText("fixture-valid/web/src/demo-solution/locales/zh-CN.json");
+	const EN = readText("fixture-valid/web/src/demo-solution/locales/en-US.json");
+
+	it("fixture-valid 双语齐备 → 零违规", () => {
+		expect(checkLocalesComplete(structuredClone(VALID), ZH, EN)).toEqual([]);
+	});
+
+	it("zh-CN 缺引用 key → C2-25 且指明 key 与语言", () => {
+		const zh = JSON.parse(ZH) as any;
+		delete zh.settings.group.display;
+		const v = checkLocalesComplete(structuredClone(VALID), JSON.stringify(zh), EN);
+		expect(v[0]).toContain("C2-25");
+		expect(v[0]).toContain("zh-CN");
+		expect(v[0]).toContain("demo-solution:settings.group.display");
+	});
+
+	it("en-US 缺引用 key → C2-25 指明 en-US", () => {
+		const en = JSON.parse(EN) as any;
+		delete en.perm.view;
+		const v = checkLocalesComplete(structuredClone(VALID), ZH, JSON.stringify(en));
+		expect(v[0]).toContain("C2-25");
+		expect(v[0]).toContain("en-US");
+	});
+});
+
+// ── isolate 侧 preflight 复用助手（与 templates/api/tests/lifecycle/preflight.spec.ts 同构）──
+
+function makeCtx(manifest: unknown): InstallContext {
+	return {
+		manifest,
+		name: typeof (manifest as any)?.name === "string" ? (manifest as any).name : "demo-solution",
+		version: typeof (manifest as any)?.version === "string" ? (manifest as any).version : "0.1.0",
+		state: { read: () => ({ solutions: {} }), write: async () => {} },
+		hostVersions: { "@oj-module/runtime": "0.1.80" },
+		hostApiVersion: "0.1.0", // C2-11 真源（= market/api.ts API_VERSION；与 fixture-valid peerPlatform '>=0.1.0' 配套）
+	};
+}

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

@@ -0,0 +1,80 @@
+// publish 命令 spec（P3-5/6/7）：重算索引 + detached .sig 签名写回 + 离线自检。
+// 纯 Node 侧（与 ojm sign 同签名原语 lifecycle/sign.ts），验证侧用 verifyCanonical 复核。
+import { existsSync, mkdtempSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { indexCanonical, publishCommand, recomputeIndex, signIndex } from "../../publish";
+import { verifyCanonical } from "../sign";
+import { defaultTestKey } from "./helpers";
+
+const BUNDLES = `solutions:
+  - name: demo-solution
+    latest: 0.1.0
+    versions:
+      - version: 0.1.0
+        file: demo-solution-0.1.0.tgz
+`;
+const MANIFESTS = `- name: demo-solution
+  version: 0.1.0
+  author: acme
+  changelog: initial
+`;
+
+let dir: string;
+let keyPath: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "ojm-publish-"));
+	writeFileSync(join(dir, "bundles.yaml"), BUNDLES);
+	writeFileSync(join(dir, "manifests.yaml"), MANIFESTS);
+	keyPath = join(dir, "key.pem");
+	writeFileSync(keyPath, defaultTestKey().privateKeyPem);
+});
+
+afterEach(() => {
+	// 临时目录由 OS 回收（测试用 tmpdir，无需手动 rm）
+});
+
+describe("ojm publish 索引重算 + 签名（P3-5/6/7）", () => {
+	it("重算两份索引并产出 detached .sig，签名可被 verifyCanonical 复核通过", () => {
+		const res = publishCommand(dir, { key: keyPath, id: "test.publisher" });
+		expect(existsSync(res.bundlesSigPath)).toBe(true);
+		expect(existsSync(res.manifestsSigPath)).toBe(true);
+		expect(res.keyId).toBe("test.publisher");
+
+		const bundlesText = readFileSync(res.bundlesPath, "utf8");
+		const manifestsText = readFileSync(res.manifestsPath, "utf8");
+		const bundlesSig = JSON.parse(readFileSync(res.bundlesSigPath, "utf8"));
+		const manifestsSig = JSON.parse(readFileSync(res.manifestsSigPath, "utf8"));
+
+		expect(bundlesSig.alg).toBe("Ed25519");
+		expect(bundlesSig.key_id).toBe("test.publisher");
+		expect(bundlesSig.canon).toBe("v1");
+		expect(verifyCanonical(res.publicKeyHex, indexCanonical("bundles", bundlesText), bundlesSig.value)).toBe(true);
+		expect(verifyCanonical(res.publicKeyHex, indexCanonical("manifests", manifestsText), manifestsSig.value)).toBe(true);
+	});
+
+	it("--check 离线自检通过（checkPassed === true）", () => {
+		const res = publishCommand(dir, { key: keyPath, id: "test.publisher", check: true });
+		expect(res.checkPassed).toBe(true);
+	});
+
+	it("重算使索引确定性化（同内容重排后 sha256 稳定可签）", () => {
+		const a = recomputeIndex("x: 1\ny: 2\n");
+		const b = recomputeIndex("y: 2\nx: 1\n");
+		expect(a).toBe(b);
+		// 重算文本可被 signIndex 正常签出五字段
+		const sig = signIndex("bundles", a, defaultTestKey().privateKeyPem, "test.publisher");
+		expect(verifyCanonical(defaultTestKey().publicKeyHex, indexCanonical("bundles", a), sig.value)).toBe(true);
+	});
+
+	it("缺索引文件 → 抛错（不发半成品 .sig）", () => {
+		unlinkSync(join(dir, "bundles.yaml"));
+		expect(() => publishCommand(dir, { key: keyPath, id: "test.publisher" })).toThrow(/须含 bundles\.yaml 与 manifests\.yaml/);
+	});
+
+	it("私钥缺失 → 抛错（fail-closed，不静默）", () => {
+		expect(() => publishCommand(dir, { key: join(dir, "nope.pem"), id: "test.publisher" })).toThrow(/私钥文件不存在/);
+	});
+});

package/src/lifecycle/__tests__/sig-fixtures.test.ts

@@ -0,0 +1,100 @@
+// 签名链夹具 CLI 面断言（P2-0，契约 v1.3 §2.11/§2.12 + 附录 A.2）。
+// 锚点语义：夹具是双端唯一共同真源——本 spec 钉「规范串逐字 + 指纹值 + 验签结果」，
+// 与 P2-1 sign.ts（Node 对拍）、P2-3 steps/verify.ts（isolate 面 verifyEd25519）三方同语义。
+// 六码（sig_missing/sig_alg/sig_key/tampered/unknown_key/sig_format）的 isolate 实现与
+// TOFU 全链属 P2-3 验收；此处只钉夹具本身与 Node 面计算。
+import { Buffer } from "node:buffer";
+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";
+import {
+	CANON,
+	canonicalString,
+	fingerprintOf,
+	FIXTURE_NAME,
+	FIXTURE_VERSION,
+	generate,
+	TRUSTED_KEY,
+	UNKNOWN_KEY,
+	verifyCanonicalB64,
+} from "./fixtures/sig/gen-signed-fixtures.mjs";
+
+const SIG_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "sig");
+const tgzPath = path.join(SIG_DIR, `${FIXTURE_NAME}-${FIXTURE_VERSION}.tgz`);
+
+interface Sig {
+	alg: string
+	key_id: string
+	public_key: string
+	value: string
+	canon: string
+}
+
+const readSig = (suffix: string): Sig => JSON.parse(readFileSync(`${tgzPath}${suffix}`, "utf8")) as Sig;
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const STD_B64 = /^[A-Z0-9+/]+={0,2}$/i;
+// 契约 §2.11 key_id 命名空间：<publisher>.<id> 全小写，禁裸通用名单段
+const KEY_ID = /^[a-z][a-z0-9-]*\.[a-z0-9-]+$/;
+
+describe("签名链夹具（P2-0）", () => {
+	const tgz = readFileSync(tgzPath);
+	const sha256 = createHash("sha256").update(tgz).digest("hex");
+	const canonical = canonicalString(FIXTURE_NAME, FIXTURE_VERSION, sha256);
+	const good = readSig(".sig");
+	const bad = readSig(".bad.sig");
+	const unknownSig = readSig(".unknown.sig");
+
+	it("规范串逐字 = <name>@<version>:<sha256>（契约 §2.11 格式表）", () => {
+		expect(canonical).toBe(`${FIXTURE_NAME}@${FIXTURE_VERSION}:${sha256}`);
+		expect(canonical).toMatch(/^demo-solution@0\.2\.0:[0-9a-f]{64}$/);
+	});
+
+	it(".sig 五字段齐备且形态合法（alg 恒 Ed25519 / canon 恒 v1）", () => {
+		for (const sig of [good, bad, unknownSig]) {
+			expect(sig.alg).toBe("Ed25519");
+			expect(sig.canon).toBe(CANON);
+			expect(sig.public_key).toMatch(HEX64);
+			expect(sig.value).toMatch(STD_B64);
+			expect(sig.value).not.toMatch(/[-_]/); // 禁 base64url（§2.11 编码约束）
+			expect(sig.key_id).toMatch(KEY_ID);
+		}
+	});
+
+	it("指纹 = sha256Hex(publicKey) 全 64 hex", () => {
+		expect(fingerprintOf(good.public_key)).toMatch(HEX64);
+		expect(fingerprintOf(unknownSig.public_key)).toMatch(HEX64);
+		expect(fingerprintOf(good.public_key)).not.toBe(fingerprintOf(unknownSig.public_key));
+	});
+
+	it("已签夹具验签通过；篡改 value / 错 key / 篡改包体均拒", () => {
+		expect(verifyCanonicalB64(good.public_key, canonical, good.value)).toBe(true);
+		expect(verifyCanonicalB64(bad.public_key, canonical, bad.value)).toBe(false); // tampered
+		expect(verifyCanonicalB64(good.public_key, canonical, unknownSig.value)).toBe(false); // 错 key
+		const tampered = Buffer.from(tgz);
+		tampered[100] ^= 0xFF;
+		const sha2 = createHash("sha256").update(tampered).digest("hex");
+		expect(verifyCanonicalB64(good.public_key, canonicalString(FIXTURE_NAME, FIXTURE_VERSION, sha2), good.value)).toBe(false);
+	});
+
+	it("未知 key 夹具是真实签名但 key_id 不在信任库（TOFU 场景锚点）", () => {
+		expect(unknownSig.key_id).toBe(UNKNOWN_KEY.key_id);
+		expect(unknownSig.public_key).toBe(UNKNOWN_KEY.public_key_hex);
+		expect(verifyCanonicalB64(unknownSig.public_key, canonical, unknownSig.value)).toBe(true);
+		expect(unknownSig.key_id).not.toBe(TRUSTED_KEY.key_id);
+	});
+
+	it("生成器确定性：再生到 tmp 与提交产物字节一致", () => {
+		const out = path.join(os.tmpdir(), `ojm-sig-fixtures-${process.pid}`);
+		const r = generate(out);
+		expect(r.sha256).toBe(sha256);
+		expect(r.canonical).toBe(canonical);
+		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"));
+	});
+});

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

@@ -0,0 +1,131 @@
+// 签名纯函数 spec（P2-1，契约 v1.3 §2.11 / C2-34~36）。BDD 五场景 + 夹具对拍锚点。
+import { Buffer } from "node:buffer";
+import { createHash, createPublicKey, verify as nodeVerify } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { generateKeyPair } from "../keygen";
+import { CANON, canonicalString, exportRawPublicKeyHex, fingerprintOfPublicKey, SIG_ALG, signCanonical, verifyCanonical } from "../sign";
+import { FIXTURE_NAME, FIXTURE_VERSION, TRUSTED_KEY, UNKNOWN_KEY } from "./fixtures/sig/gen-signed-fixtures.mjs";
+import { defaultTestKey, signedArchiveFor } from "./helpers";
+
+const SHA_A = "a".repeat(64);
+
+describe("规范串（C2-34）", () => {
+	it("拼接式逐字 <name>@<version>:<sha256>（契约 §2.11 格式表）", () => {
+		expect(canonicalString("demo-solution", "0.2.0", SHA_A)).toBe(`demo-solution@0.2.0:${SHA_A}`);
+	});
+
+	it("sha256 形态非法不拦截（规范化属调用方结构校验序，P2-3）", () => {
+		// 纯函数只负责拼接；sha256 合法性由 verify 段比对时保证（C2-29 fail-closed）
+		expect(canonicalString("a", "1", "short")).toBe("a@1:short");
+	});
+});
+
+describe("签验往返与对拍", () => {
+	const key = generateKeyPair();
+	const canonical = canonicalString("demo-solution", "0.1.0", SHA_A);
+
+	it("sign → verifyCanonical 往返 true；篡改 canonical 一字符 → false", () => {
+		const sig = signCanonical(key.privateKeyPem, canonical);
+		expect(verifyCanonical(key.publicKeyHex, canonical, sig)).toBe(true);
+		const tampered = `${canonical.slice(0, -1)}${canonical.at(-1) === "a" ? "b" : "a"}`;
+		expect(verifyCanonical(key.publicKeyHex, tampered, sig)).toBe(false);
+	});
+
+	it("node crypto.verify 对拍：同 key 同 canonical 同 value，结果一致", () => {
+		const sig = signCanonical(key.privateKeyPem, canonical);
+		const pub = createPublicKey({
+			key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), Buffer.from(key.publicKeyHex, "hex")]),
+			format: "der",
+			type: "spki",
+		});
+		expect(nodeVerify(null, Buffer.from(canonical, "utf8"), pub, Buffer.from(sig, "base64"))).toBe(
+			verifyCanonical(key.publicKeyHex, canonical, sig),
+		);
+		expect(nodeVerify(null, Buffer.from(canonical, "utf8"), pub, Buffer.from(sig, "base64"))).toBe(true);
+	});
+
+	it("确定性：Ed25519 同 key 同 canonical 两次签名相同", () => {
+		expect(signCanonical(key.privateKeyPem, canonical)).toBe(signCanonical(key.privateKeyPem, canonical));
+	});
+
+	it("公钥导出与指纹：exportRawPublicKeyHex === generateKeyPair.publicKeyHex，指纹 64hex", () => {
+		expect(exportRawPublicKeyHex(key.privateKeyPem)).toBe(key.publicKeyHex);
+		expect(fingerprintOfPublicKey(key.publicKeyHex)).toMatch(/^[0-9a-f]{64}$/);
+	});
+});
+
+describe("编码面严格拒（C2-36，禁归一）", () => {
+	const key = generateKeyPair();
+	const canonical = canonicalString("demo-solution", "0.1.0", SHA_A);
+	const good = signCanonical(key.privateKeyPem, canonical);
+
+	it("value 含 -/_（base64url 变体）→ false", () => {
+		// 必须挑一把 base64 表示里**确实含 +/** 的签名再转 base64url：64 字节签名的
+		// base64 有 ~7% 概率不含 +/（88 字符各 2/64），此时 base64url 与原值只差被
+		// 抹掉的 padding，而 Node 的 base64 解码对缺 padding 宽容，会还原出同一串
+		// 字节使校验返回 true——用例以 ~7% 概率偶发失败（实测 2000 次 7.2%），
+		// 且那时「禁归一」的本意根本没被测到。换 key 直到形态真的不同。
+		let key = generateKeyPair();
+		let sig = signCanonical(key.privateKeyPem, canonical);
+		for (let i = 0; !/[+/]/.test(Buffer.from(sig, "base64").toString("base64")) && i < 64; i++) {
+			key = generateKeyPair();
+			sig = signCanonical(key.privateKeyPem, canonical);
+		}
+		const b64url = Buffer.from(sig, "base64").toString("base64url");
+		expect(b64url).toMatch(/[-_]/); // 形态确实是 base64url（-/_ 替换已发生）
+		expect(b64url).not.toBe(sig);
+		expect(verifyCanonical(key.publicKeyHex, canonical, b64url)).toBe(false);
+	});
+
+	it("public_key 非 64hex（63/65/PEM 串）→ false", () => {
+		expect(verifyCanonical(key.publicKeyHex.slice(1), canonical, good)).toBe(false);
+		expect(verifyCanonical(`${key.publicKeyHex}0`, canonical, good)).toBe(false);
+		expect(verifyCanonical("-----BEGIN PUBLIC KEY-----", canonical, good)).toBe(false);
+	});
+
+	it("value 非标准 base64（空串/含 !）→ false", () => {
+		expect(verifyCanonical(key.publicKeyHex, canonical, "")).toBe(false);
+		expect(verifyCanonical(key.publicKeyHex, canonical, `${good}!`)).toBe(false);
+	});
+
+	it("错 key 签名 → false", () => {
+		const other = generateKeyPair();
+		expect(verifyCanonical(other.publicKeyHex, canonical, good)).toBe(false);
+	});
+});
+
+describe("p2-0 夹具对拍（双端三同一锚点）", () => {
+	const SIG_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "sig");
+	const tgz = readFileSync(path.join(SIG_DIR, `${FIXTURE_NAME}-${FIXTURE_VERSION}.tgz`));
+	const sha256 = createHash("sha256").update(tgz).digest("hex");
+	const canonical = canonicalString(FIXTURE_NAME, FIXTURE_VERSION, sha256);
+	const readSig = (suffix: string) => JSON.parse(readFileSync(path.join(SIG_DIR, `${FIXTURE_NAME}-${FIXTURE_VERSION}.tgz${suffix}`), "utf8")) as { key_id: string, public_key: string, value: string, canon: string, alg: string };
+
+	it("已签/篡改/未知 key 三态经 sign.ts 验签结果与生成器一致", () => {
+		const good = readSig(".sig");
+		const bad = readSig(".bad.sig");
+		const unknownSig = readSig(".unknown.sig");
+		expect([good.alg, good.canon]).toEqual([SIG_ALG, CANON]);
+		expect([good.key_id, good.public_key]).toEqual([TRUSTED_KEY.key_id, TRUSTED_KEY.public_key_hex]);
+		expect(verifyCanonical(good.public_key, canonical, good.value)).toBe(true);
+		expect(verifyCanonical(bad.public_key, canonical, bad.value)).toBe(false);
+		expect([unknownSig.key_id, unknownSig.public_key]).toEqual([UNKNOWN_KEY.key_id, UNKNOWN_KEY.public_key_hex]);
+		expect(verifyCanonical(unknownSig.public_key, canonical, unknownSig.value)).toBe(true);
+	});
+
+	it("signedArchiveFor 对夹具包体重签：验签过且指纹与公钥对应", () => {
+		const signed = signedArchiveFor(new Uint8Array(tgz), FIXTURE_NAME, FIXTURE_VERSION);
+		expect(signed.sig.canon).toBe(CANON);
+		expect(signed.sig.alg).toBe(SIG_ALG);
+		expect(signed.sig.public_key).toMatch(/^[0-9a-f]{64}$/);
+		expect(verifyCanonical(signed.publicKeyHex, canonical, signed.sig.value)).toBe(true);
+		expect(signed.fingerprint).toBe(fingerprintOfPublicKey(signed.publicKeyHex));
+	});
+
+	it("defaultTestKey 进程内稳定（同文件多次调用同 key）", () => {
+		expect(defaultTestKey().publicKeyHex).toBe(defaultTestKey().publicKeyHex);
+	});
+});

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

@@ -0,0 +1,61 @@
+// 真机冒烟（P1-13，skip-if-env-missing）：对真实站点 file 源安装 fixture-valid 包，断言终态 done。
+// 环境齐备才跑（OJM_SMOKE_URL / OJM_SMOKE_USER / OJM_SMOKE_PASS，站点需已有 superadmin 账号；
+// 站点起停属部署层职责——P1-16 e2e 钉定生产口径，此处不拉起进程），缺省整体跳过，CI 不红。
+import { cpSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { buildBundle } from "../../bundle";
+import { installCommand } from "../../install";
+import { DEFAULT_SITE_URL } from "../../site";
+
+const SMOKE_URL = process.env.OJM_SMOKE_URL;
+const SMOKE_USER = process.env.OJM_SMOKE_USER ?? process.env.OJM_USER;
+const SMOKE_PASS = process.env.OJM_SMOKE_PASS ?? process.env.OJM_PASS;
+const smokeReady = SMOKE_URL !== undefined && SMOKE_USER !== undefined && SMOKE_PASS !== undefined;
+
+const FIXTURE_VALID = join(dirname(fileURLToPath(import.meta.url)), "fixtures/fixture-valid");
+
+let project: string;
+
+beforeAll(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-smoke-proj-"));
+	cpSync(FIXTURE_VALID, project, { recursive: true });
+});
+
+afterEach(() => {
+	// 只清本测试的临时工程（站点侧安装产物不回滚——真机站点是外部环境）
+	if (project !== undefined)
+		rmSync(project, { recursive: true, force: true });
+	project = undefined as unknown as string;
+});
+
+describe.skipIf(!smokeReady)("真机冒烟（需 OJM_SMOKE_URL/OJM_SMOKE_USER/OJM_SMOKE_PASS）", () => {
+	it("file 源安装 fixture-valid 包 → 终态 done", { timeout: 600_000 }, async () => {
+		// 先出可安装 tgz（同 bundle.test.ts：预置已构建产物再 --bundle 组装）
+		const apiDist = join(project, "api/dist/demo-solution-0.1.0");
+		const { mkdirSync, writeFileSync } = await import("node:fs");
+		mkdirSync(join(apiDist, "ping"), { recursive: true });
+		// 迁移 SQL 随夹具 src 真源（0001__init.sql 建 note 表）；B-11 硬验收：appliedSeq > 0 可断言
+		cpSync(join(FIXTURE_VALID, "api/src/demo-solution/migrations"), join(apiDist, "migrations"), { recursive: true });
+		// schema.yaml 同随夹具真源（列集与迁移 SQL 一致）：oj migrate 在 apply 后跑 schema
+		// reconcile（migrate_cmd.rs migrate_one），声明缺列而实库多列 = Err——合成空列集会炸
+		writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - note\n");
+		cpSync(join(FIXTURE_VALID, "api/src/demo-solution/schema.yaml"), join(apiDist, "schema.yaml"));
+		writeFileSync(join(apiDist, "routes.js"), "export {};\n");
+		writeFileSync(join(apiDist, "ping/api.js"), "export async function ping() {}\n");
+		const webDist = join(project, "web/dist/modules/demo-solution/0.1.0");
+		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 record = await installCommand(tgz, { url: SMOKE_URL ?? DEFAULT_SITE_URL, user: SMOKE_USER, pass: SMOKE_PASS });
+		expect(record.status).toBe("done");
+		expect(record.name).toBe("demo-solution");
+		expect(record.version).toBe("0.1.0");
+		// B-11 硬验收：迁移真实执行过（oj migrate applied 非空），非 web-only 空跑
+		expect(record.appliedSeq).toBeGreaterThan(0);
+	});
+});