@oj-module/cli 0.2.2 → 0.2.6

package/src/layout.ts

@@ -52,3 +52,34 @@ export function resolveLayout(projectRoot: string): ProjectLayout {
 export function resolveWatchTarget(projectRoot: string): string {
 	return resolveLayout(projectRoot).watchTarget;
 }
+
+/**
+ * 定位工程 config.yaml。
+ *
+ * 唯一规范位置：`<project>/api/config.yaml`。
+ *
+ * 不能挪到与 api/ 同级的 config/ 目录：oj 的模块解析把「项目根」锚定在
+ * **config 文件所在目录**，且相对 import 被钳制在该根内（devkit 手册第 5 章）。
+ * config 一进 `config/` 子目录，`api/src` 就整体落到项目根之外，凡是带 `../`
+ * 相对 import 的 handler（模板的 system/auth/_platform 依赖 `_shared/`）在
+ * `ojm dev` 下会被判 `escapes project root` 而整条路由加载失败
+ * （实测：26 个 api 文件 → 只剩 8 个，18 条路由被跳过）。
+ */
+export function resolveConfigPath(projectRoot: string): string {
+	return path.join(projectRoot, "api", "config.yaml");
+}
+
+/**
+ * 证书与密钥的唯一落点：`<project>/api/config/`（config.yaml 同级的 config/ 子目录）。
+ *
+ * 三个入口都指向这里，别再各自手拼：
+ *   ① `server.public_key_path`     → ./config/public.pem（oj 验签公钥）
+ *   ② `server.certificate_path`    → ./config/cert.jws（oj 拒启闸门）
+ *   ③ `secrets.private/public_key_path` → ./config/secrets-{private,public}.pem（jwt_secret 密封密钥对）
+ * 另加签发私钥 `private.pem`（config 不引用，仅 mintDevCert 产出）。
+ *
+ * 由 config 位置派生，config 若挪位这里自动跟随——不需要第二处硬编码。
+ */
+export function resolveCertDir(projectRoot: string): string {
+	return path.join(path.dirname(resolveConfigPath(projectRoot)), "config");
+}

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

@@ -0,0 +1,109 @@
+// BDD：`ojm keygen` / `ojm sign`（P2-4 作者工具链，Ed25519 自备版 stopgap）。
+// 上游 PR 合入 `oj secret keygen --alg ed25519` 后，这两个命令将收敛为壳调用（计划台账已记）。
+// 私钥红线 / 命名空间 / 离线自检 / detached .sig 五字段为本次覆盖重点。
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { DEFAULT_KEY_ID, isValidKeyId, keygenCommand, parseKeygenArgs } from "../../keygen";
+import { parseSignArgs, signCommand } from "../../sign";
+import { readPrivateKeyPem } from "../keygen";
+import { fingerprintOfPublicKey, signCanonical as signCanonicalLocal, verifyCanonical } from "../sign";
+
+const tmp = path.join(os.tmpdir(), `ojm-authoring-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+
+beforeEach(() => {
+	fs.mkdirSync(tmp, { recursive: true });
+});
+afterEach(() => {
+	fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("ojm keygen 参数解析 + key_id 命名空间（C2-37）", () => {
+	it("parseKeygenArgs：--id/--out 值式消费 + --yes 独立", () => {
+		expect(parseKeygenArgs(["--id", "acme.market", "--out", "./k", "--yes"]))
+			.toEqual({ id: "acme.market", out: "./k", yes: true });
+	});
+	it("isValidKeyId：<publisher>.<id> 合法 / 裸名·大写·空非法", () => {
+		expect(isValidKeyId("acme.market")).toBe(true);
+		expect(isValidKeyId("acme.dev.key-1")).toBe(true);
+		expect(isValidKeyId("local")).toBe(false);
+		expect(isValidKeyId("Acme.Market")).toBe(false);
+		expect(isValidKeyId("")).toBe(false);
+	});
+});
+
+describe("ojm keygen 命令体（Ed25519 落盘 + 私钥红线）", () => {
+	it("缺省 key_id=local.dev，五产物齐全且私钥 0600、公钥 64hex、指纹一致", () => {
+		const r = keygenCommand({ cwd: tmp });
+		expect(r.keyId).toBe(DEFAULT_KEY_ID);
+		expect(r.publicKeyHex).toMatch(/^[0-9a-f]{64}$/);
+		expect(r.fingerprint).toBe(fingerprintOfPublicKey(r.publicKeyHex));
+		expect(fs.statSync(r.privateKeyPath).mode & 0o777).toBe(0o600);
+		expect(fs.readFileSync(r.publicKeyPath, "utf8").trim()).toBe(r.publicKeyHex);
+	});
+
+	it("落盘私钥可还原并用于签验（证明是 Ed25519 而非 X25519）", () => {
+		const r = keygenCommand({ cwd: tmp });
+		const pem = readPrivateKeyPem(r.privateKeyPath);
+		const canon = `demo@0.1.0:${"0".repeat(64)}`;
+		const sig = signCanonicalLocal(pem, canon);
+		expect(verifyCanonical(r.publicKeyHex, canon, sig)).toBe(true);
+	});
+
+	it("工程树内落盘无 --yes → 抛「私钥入仓」拒绝", () => {
+		expect(() => keygenCommand({ out: "./keys", cwd: tmp })).toThrow(/私钥入仓/);
+	});
+	it("工程树内落盘带 --yes → 放行", () => {
+		const r = keygenCommand({ out: "./keys", yes: true, cwd: tmp });
+		expect(fs.existsSync(r.privateKeyPath)).toBe(true);
+	});
+	it("非法 key_id 命名空间 → 直接拒（C2-37）", () => {
+		expect(() => keygenCommand({ id: "local", cwd: tmp })).toThrow(/key_id 命名空间非法/);
+	});
+});
+
+describe("ojm sign 参数解析", () => {
+	it("parseSignArgs：位置参数 + --id/--key 值式消费 + --check 独立", () => {
+		expect(parseSignArgs(["pkg.tgz", "--id", "acme.market", "--key", "k.pem", "--check"]))
+			.toEqual({ positionals: ["pkg.tgz"], id: "acme.market", key: "k.pem", check: true });
+	});
+});
+
+describe("ojm sign 命令体（detached .sig，G4 载体）", () => {
+	const TGZ = path.join(tmp, "demo-solution-0.1.0.tgz");
+
+	beforeEach(() => {
+		fs.writeFileSync(TGZ, "demo-archive-bytes\n");
+	});
+
+	it("签名产出 .sig 五字段（alg/key_id/public_key/value/canon），且 verifyCanonical 通过", () => {
+		const kp = keygenCommand({ id: "acme.market", out: path.join(tmp, "k"), yes: true, cwd: tmp });
+		const r = signCommand(TGZ, { id: "acme.market", key: kp.privateKeyPath });
+		const sig = JSON.parse(fs.readFileSync(r.sigPath, "utf8"));
+		expect(sig.alg).toBe("Ed25519");
+		expect(sig.key_id).toBe("acme.market");
+		expect(sig.public_key).toBe(kp.publicKeyHex);
+		expect(sig.canon).toBe("v1");
+		expect(verifyCanonical(sig.public_key, r.canonical, sig.value)).toBe(true);
+	});
+
+	it("--check 离线自检：真签名通过（checkPassed=true）；--key+--id 自定义位置", () => {
+		const kp = keygenCommand({ id: "acme.market", out: path.join(tmp, "k"), yes: true, cwd: tmp });
+		const r = signCommand(TGZ, { id: "acme.market", key: kp.privateKeyPath, check: true });
+		expect(r.checkPassed).toBe(true);
+	});
+
+	it("缺 --id 且未给 --key → 拒绝并指引先 keygen", () => {
+		expect(() => signCommand(TGZ, {})).toThrow(/缺少签名身份/);
+	});
+	it("非法 key_id 命名空间 → 拒绝（C2-37）", () => {
+		const kp = keygenCommand({ id: "acme.market", out: path.join(tmp, "k"), yes: true, cwd: tmp });
+		expect(() => signCommand(TGZ, { id: "local", key: kp.privateKeyPath })).toThrow(/key_id 命名空间非法/);
+	});
+	it("非 .tgz 目标 → 拒绝", () => {
+		const kp = keygenCommand({ id: "acme.market", out: path.join(tmp, "k"), yes: true, cwd: tmp });
+		expect(() => signCommand(path.join(tmp, "x.zip"), { id: "acme.market", key: kp.privateKeyPath }))
+			.toThrow(/\.tgz/);
+	});
+});

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

@@ -0,0 +1,150 @@
+// BDD：`ojm build --bundle` 方案包组装（P1-11）。
+// 组装契约（对齐 tgz 内布局，契约 §2.9 + P1-9 staging copy 源定版）：
+//   <root>/manifest.yaml                          ← 必填，契约校验 fail-fast 先于打包
+//   api/dist/<name>-<version>/                    ← oj build 产物原样 → tgz 内 api/<name>-<version>/（C2-31 分层核对）
+//   web/dist/modules/                             ← 站点构建模块产物 → tgz 内 web/modules/（web.entry 存在性复核）
+// 禁携 modules.json（C2-31 红线）；产物确定性（C2-32）由 deterministic-tar 承担，此处断言端到端复现。
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { parse, stringify } from "yaml";
+import { buildBundle } from "../../bundle";
+
+const FIXTURE_VALID = join(dirname(fileURLToPath(import.meta.url)), "fixtures/fixture-valid");
+
+let project: string;
+let out: string;
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-bundle-proj-"));
+	out = mkdtempSync(join(tmpdir(), "ojm-bundle-out-"));
+	cpSync(FIXTURE_VALID, project, { recursive: true });
+	makePrebuiltArtifacts();
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+	rmSync(out, { recursive: true, force: true });
+});
+
+/** 预置「已构建」产物：oj build（api/dist/<name>-<version>/）与站点构建（web/dist/modules/） */
+function makePrebuiltArtifacts(): void {
+	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version/desc 与 bundle 级逐一相等，C2-31）
+	const apiDist = join(project, "api/dist/demo-solution-0.1.0");
+	mkdirSync(join(apiDist, "ping"), { recursive: true });
+	mkdirSync(join(apiDist, "migrations"), { recursive: true });
+	writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - note\n");
+	writeFileSync(join(apiDist, "schema.yaml"), "tables:\n  note: {}\n");
+	writeFileSync(join(apiDist, "routes.js"), "export {};\n");
+	writeFileSync(join(apiDist, "ping/api.js"), "export async function ping() {}\n");
+	// 站点构建产物（web/dist/modules/<name>/<version>/entry.js + css，对应 web.entry/css 声明）
+	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 pack = () => buildBundle(project, { out });
+
+describe("buildBundle · 正路径", () => {
+	it("产出 out/<name>-<version>.tgz + 64 位 sha256，布局单根三分（manifest/api/web）", async () => {
+		const r = await pack();
+		expect(r.tgz).toBe(join(out, "demo-solution-0.1.0.tgz"));
+		expect(existsSync(r.tgz)).toBe(true);
+		expect(r.sha256).toMatch(/^[a-f0-9]{64}$/);
+		const names = tarList(r.tgz);
+		// 顶层目录成员（仅一个斜杠且在末尾）恰为单根，且居首（字典序）
+		expect(names.filter(n => n.endsWith("/") && n.indexOf("/") === n.length - 1)).toEqual(["demo-solution-0.1.0/"]);
+		expect(names[0]).toBe("demo-solution-0.1.0/");
+		for (const member of ["manifest.yaml", "api/demo-solution-0.1.0/manifest.yaml", "web/modules/demo-solution/0.1.0/entry.js", "web/modules/demo-solution/0.1.0/demo-solution.css"])
+			expect(names, `缺成员 ${member}`).toContain(`demo-solution-0.1.0/${member}`);
+	});
+
+	it("端到端确定性：同一工程两次打包 sha256 相等（C2-32）", async () => {
+		const r1 = await pack();
+		const r2 = await pack();
+		expect(r1.sha256).toBe(r2.sha256);
+	});
+
+	it("tgz 内任何位置无 modules.json（C2-31：清单由安装器在目标站点 upsert）", async () => {
+		const r = await pack();
+		expect(tarList(r.tgz).some(n => n.endsWith("/modules.json"))).toBe(false);
+	});
+
+	it("产物树混入 modules.json → 打包自检拒绝（C2-31 红线）", async () => {
+		writeFileSync(join(project, "web/dist/modules/demo-solution/0.1.0/modules.json"), "[]");
+		await expect(pack()).rejects.toThrow(/modules\.json/);
+	});
+
+	it("私钥/凭证混入包树 → 打包自检拒绝（P2-4 入包红线：*.pem/*.key/.env/id_ed25519/id_rsa）", async () => {
+		writeFileSync(join(project, "api/dist/demo-solution-0.1.0/signing.pem"), "-----BEGIN PRIVATE KEY-----\n");
+		await expect(pack()).rejects.toThrow(/私钥\/凭证/);
+		rmSync(join(project, "api/dist/demo-solution-0.1.0/signing.pem"));
+		writeFileSync(join(project, "web/dist/modules/demo-solution/0.1.0/.env"), "SECRET=1\n");
+		await expect(pack()).rejects.toThrow(/私钥\/凭证/);
+	});
+});
+
+describe("buildBundle · 校验先于打包（fail-fast）", () => {
+	it("契约违规：抛可读清单（编号逐条），且不产出 tgz", async () => {
+		writeFileSync(join(project, "manifest.yaml"), "name: Demo\nversion: 1.0.0+build.5\nsummary: x\nchangelog: x\n");
+		await expect(pack()).rejects.toThrow(/C2-01[\s\S]*C2-02/);
+		expect(existsSync(join(out, "Demo-1.0.0+build.5.tgz"))).toBe(false);
+	});
+
+	it("manifest.yaml 缺失：可读报错指明期望路径", async () => {
+		rmSync(join(project, "manifest.yaml"));
+		await expect(pack()).rejects.toThrow(/manifest\.yaml/);
+	});
+
+	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 拒绝", async () => {
+		writeFileSync(join(project, "api/dist/demo-solution-0.1.0/manifest.yaml"), "name: demo-solution\ndesc: 不一致描述\nversion: 0.1.0\n");
+		await expect(pack()).rejects.toThrow(/C2-31/);
+	});
+
+	it("c2-31 分层核对：api/dist 缺 <name>-<version>/ → 可读报错指明期望产物路径", async () => {
+		rmSync(join(project, "api/dist"), { recursive: true, force: true });
+		await expect(pack()).rejects.toThrow(/api\/dist\/demo-solution-0\.1\.0/);
+	});
+
+	it("web 段存在但站点产物缺失 → 可读报错指引先构建", async () => {
+		rmSync(join(project, "web/dist"), { recursive: true, force: true });
+		await expect(pack()).rejects.toThrow(/web\/dist\/modules/);
+	});
+
+	it("c2-12a：api.tables 与 schema.yaml 表集不一致 → 构建期拒绝", async () => {
+		const m = readManifest();
+		m.api.tables = ["note", "ghost"];
+		writeManifest(m);
+		await expect(pack()).rejects.toThrow(/C2-12a/);
+	});
+
+	it("c2-25：locales 缺引用 key → 构建期 fail-fast", async () => {
+		const m = readManifest();
+		m.roles[0].title_key = "demo-solution:role.absent";
+		writeManifest(m);
+		await expect(pack()).rejects.toThrow(/C2-25/);
+	});
+});
+
+// ── 助手 ──
+
+function readManifest(): any {
+	return parse(readFileSync(join(project, "manifest.yaml"), "utf8"));
+}
+
+function writeManifest(m: unknown): void {
+	writeFileSync(join(project, "manifest.yaml"), stringify(m));
+}
+
+function tarList(tgz: string): string[] {
+	return execFileSync("tar", ["-tvzf", tgz], { encoding: "utf8" })
+		// 铁律②（P1-6）：tar 输出恒带尾随换行，trim 后再 split
+		.trim()
+		.split("\n")
+		.map(line => line.split(" ").pop()!);
+}

package/src/lifecycle/__tests__/deterministic-tar.test.ts

@@ -0,0 +1,145 @@
+// BDD：确定性 tgz（P1-11，契约 C2-32/C2-30）。
+// 硬验收（简报逐字）：同一目录两次打包 sha256 必须相等——mtime/umask/遍历序不得泄漏进产物。
+// 打包自检（C2-30 构建列）：symlink/硬链接成员拒绝；产物可被系统 tar -tvzf/-xzf 消费
+// （安装侧 extract 段即系统 tar，P1-6 铁律①——本侧产物与彼侧输入契约互为镜像）。
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createDeterministicTgz } from "../../deterministic-tar";
+
+let dir: string;
+let outDir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "ojm-dtar-src-"));
+	outDir = mkdtempSync(join(tmpdir(), "ojm-dtar-out-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+	rmSync(outDir, { recursive: true, force: true });
+});
+
+/** 组装样例树（单根 pkg/ = bundle staging 形态）：文件（多目录嵌套）/空目录/utf-8 内容；b-dir 先创建（创建序 ≠ 字典序） */
+function makeTree(root: string): void {
+	const p = join(root, "pkg");
+	mkdirSync(join(p, "b-dir/sub"), { recursive: true });
+	mkdirSync(join(p, "a-dir"), { recursive: true });
+	writeFileSync(join(p, "b-dir/sub/entry.js"), "export default 1;\n");
+	writeFileSync(join(p, "b-dir/zh.txt"), "中文内容\n");
+	writeFileSync(join(p, "root.txt"), "root\n");
+	writeFileSync(join(p, "a-dir/first.css"), ".a{}\n");
+	mkdirSync(join(p, "b-dir/empty-dir"), { recursive: true }); // 空目录（fixture migrations/ 同形态）
+}
+
+/** 全树设置指定 mtime（确定性负对照：mtime 不得泄漏进包） */
+function setTreeMtime(root: string, mtime: Date): void {
+	const walk = (p: string) => {
+		utimesSync(p, mtime, mtime);
+		if (!statSync(p).isDirectory())
+			return;
+		for (const e of readdirSync(p))
+			walk(join(p, e));
+	};
+	walk(root);
+}
+
+/** 打包 + 以系统 `tar -tvzf` 读回成员名列表（安装侧 extract 段同款消费面） */
+async function packAndList(tgz: string): Promise<{ names: string[], listing: string[], sha256: string }> {
+	const sha256 = await createDeterministicTgz(dir, join(outDir, tgz));
+	const listing = tarList(join(outDir, tgz));
+	return { names: memberNames(listing), listing, sha256 };
+}
+
+describe("createDeterministicTgz · 确定性（C2-32 硬验收）", () => {
+	it("同目录两次打包 sha256 相等（mtime/遍历序不泄漏）", async () => {
+		makeTree(dir);
+		setTreeMtime(dir, new Date(1_700_000_000_000));
+		const sha1 = await createDeterministicTgz(dir, join(outDir, "a.tgz"));
+		setTreeMtime(dir, new Date(1_800_000_000_000));
+		const sha2 = await createDeterministicTgz(dir, join(outDir, "b.tgz"));
+		expect(sha1).toMatch(/^[a-f0-9]{64}$/);
+		expect(sha1).toBe(sha2);
+	});
+
+	it("内容变化 → sha256 变化（负对照：不是恒等哈希）", async () => {
+		makeTree(dir);
+		const sha1 = await createDeterministicTgz(dir, join(outDir, "a.tgz"));
+		writeFileSync(join(dir, "root.txt"), "changed\n");
+		const sha2 = await createDeterministicTgz(dir, join(outDir, "b.tgz"));
+		expect(sha1).not.toBe(sha2);
+	});
+
+	it("成员按路径字典序（创建顺序无关）、单根居首", async () => {
+		makeTree(dir);
+		const { names } = await packAndList("a.tgz");
+		const sorted = [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+		expect(names).toEqual(sorted);
+		expect(names[0]).toMatch(/\/$/); // 唯一顶层目录成员居首
+	});
+});
+
+describe("createDeterministicTgz · 产物可被系统 tar 消费（extract 段输入契约）", () => {
+	it("tar -tvzf：单根、含空目录成员、mtime 显示 1970（=0）", async () => {
+		makeTree(dir);
+		const { names, listing } = await packAndList("a.tgz");
+		const topDirs = names.filter(n => n.endsWith("/") && !n.slice(0, -1).includes("/"));
+		expect(topDirs).toHaveLength(1);
+		expect(names).toContain(`${topDirs[0]}b-dir/empty-dir/`);
+		expect(listing.join("\n")).toContain("1970");
+	});
+
+	it("tar -xzf 解压还原：内容一致、权限 0644/0755（umask 无关）、空目录还原", async () => {
+		makeTree(dir);
+		const { names } = await packAndList("a.tgz");
+		const extractDir = join(outDir, "unpacked");
+		mkdirSync(extractDir);
+		execFileSync("tar", ["-xzf", join(outDir, "a.tgz"), "-C", extractDir]);
+		const root = join(extractDir, names[0]!.slice(0, -1));
+		expect(readFileSync(join(root, "b-dir/zh.txt"), "utf8")).toBe("中文内容\n");
+		expect(existsSync(join(root, "b-dir/empty-dir"))).toBe(true);
+		expect(statSync(join(root, "b-dir/sub/entry.js")).mode & 0o777).toBe(0o644);
+		expect(statSync(join(root, "b-dir")).mode & 0o777).toBe(0o755);
+	});
+});
+
+describe("createDeterministicTgz · 打包自检（C2-30 构建列）", () => {
+	it("symlink 成员拒绝（tar 忠实还原链接，校验为安全必需）", async () => {
+		makeTree(dir);
+		symlinkSync(join(dir, "root.txt"), join(dir, "evil-link"));
+		await expect(createDeterministicTgz(dir, join(outDir, "a.tgz"))).rejects.toThrow(/symlink|链接/i);
+	});
+
+	it("超长路径（ustar name+prefix 容量外）拒绝且可读", async () => {
+		// 单文件名 250 字符（fs 文件名上限内、无 "/" 可拆 prefix）→ ustar 必然容量外
+		writeFileSync(join(dir, "x".repeat(250)), "x");
+		await expect(createDeterministicTgz(dir, join(outDir, "a.tgz"))).rejects.toThrow(/路径|155|100/);
+	});
+
+	it("输出自动建父目录并落盘", async () => {
+		makeTree(dir);
+		const out = join(outDir, "deep/nested/pkg.tgz");
+		await createDeterministicTgz(dir, out);
+		expect(existsSync(out)).toBe(true);
+	});
+});
+
+// ── 助手 ──
+
+function tarList(tgz: string): string[] {
+	return execFileSync("tar", ["-tvzf", tgz], { encoding: "utf8" })
+		// 铁律②（P1-6）：tar 输出恒带尾随换行，trim 后再 split
+		.trim()
+		.split("\n");
+}
+
+/** 从 `tar -tvzf` 行提取成员名（bsdtar：`-rw-r--r-- 0/0 2026-.. name`；成员名不含空格——确定性产物） */
+function memberNames(listing: string[]): string[] {
+	return listing.map((line) => {
+		const m = /\s(?:\d+|\S[^\s/]*\/\S+)\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?::\d{2})?\s(.+)$/.exec(line);
+		return m ? m[1]! : line.split(" ").pop()!;
+	});
+}

package/src/lifecycle/__tests__/fixtures/README.md

@@ -0,0 +1,59 @@
+# lifecycle 测试夹具（C2 交付物 · 双端唯一共同真源）
+
+契约：[`docs/prd/solution/202610171254-lifecycle-manifest-contract.md`](../../../../../docs/prd/solution/202610171254-lifecycle-manifest-contract.md)（规则编号 C2-01~C2-33）。
+
+## 用途
+
+manifest.yaml 契约在两个运行时各有一份实现（计划 §1「两运行时取舍」——Node CLI 构建期与 oj isolate 安装预检之间无共享模块机制）：
+
+| 端 | 实现（P1） | 消费夹具的测试 |
+|---|---|---|
+| Node（构建期，`ojm build --bundle`） | `packages/cli/src/manifest-contract.ts` → `validateContract(m): string[]` | `packages/cli/src/lifecycle/__tests__/manifest-contract.test.ts`（P1-11） |
+| oj isolate（安装期 preflight） | `templates/api/src/_platform/_lifecycle/steps/preflight.ts` | `templates/api/tests/lifecycle/preflight.spec.ts`（P1-5） |
+
+**DRY 于夹具而非运行时**：两份实现的一致性由同一组夹具钉住——任何一端正则/规则变更，必须先改契约文档对应条款，再同步另一端与夹具，双端测试全绿后方可提交。
+
+## 夹具清单
+
+```
+fixtures/
+├── README.md                          # 本文件
+├── fixture-valid/                     # 合法样例：双端零违规
+│   ├── manifest.yaml                  # bundle 级契约（全字段合法）
+│   ├── api/src/demo-solution/         # oj 模块源（manifest/schema/ping 路由/0001__init.sql 建表迁移）
+│   └── web/src/demo-solution/         # entry.ts + locales（zh-CN/en-US 全 key 双语）
+└── fixture-invalid/                   # 非法样例：双端七码齐报
+    ├── manifest.yaml                  # 故意触发 V1–V7
+    ├── EXPECTED-VIOLATIONS.md         # 每条违规 ↔ 契约条款对照（P1-5 期望真源）
+    ├── api/src/Demo/
+    └── web/src/Demo/
+```
+
+## 双端测试约定
+
+1. `fixture-valid/manifest.yaml`：`validateContract` 与 `preflight` 均断言**零违规**。
+2. `fixture-invalid/manifest.yaml`：两端均断言违规码集合 **⊇** `{C2-01, C2-02, C2-16, C2-17, C2-22, C2-23, C2-26}`，逐条依据见 `fixture-invalid/EXPECTED-VIOLATIONS.md`；衍生违规（name 非法导致的 `demo:*` 命名空间连锁失配）不计入断言。
+3. 断言前提：两端实现均**收集全部违规后统一报出**（返回违规列表而非首个即抛），否则截断会使后续码无法报出——此为实现纪律，随 P1-5/P1-11 测试钉住。
+
+## 夹具断言范围之外（勿在此过度断言）
+
+- `web.integrity` 的安装期重算比对（C2-28/R10）针对**构建产物 tgz**，源树夹具中该值为格式样例；
+- prefix 占用检测、peerRuntime 对宿主 `versions.json`（C2-09）等需要站点/宿主状态的规则，由 P1-5/P1-11 各自的运行时夹具（内存 state/versions 假数据）覆盖；
+- 恶意 tgz 成员（`..`/symlink）用例属 P1-2 `tgz-guard`，独立构造，不入本目录。
+
+## 签名链夹具（`sig/`，v1.3 / P2-0）
+
+```
+fixtures/sig/
+├── gen-signed-fixtures.mjs            # 确定性生成器（自包含 .mjs，两端可 import/spawn；私钥不入仓）
+├── gen-signed-fixtures.d.mts          # 类型声明（供 TS 测试 import）
+├── demo-solution-0.2.0.tgz            # 共用包体（Form A，确定性 ustar + gzip）
+├── demo-solution-0.2.0.tgz.sig        # 已签（TRUSTED_KEY = ojm.test）
+├── demo-solution-0.2.0.tgz.bad.sig    # 篡改（value 首字符翻转 → tampered）
+└── demo-solution-0.2.0.tgz.unknown.sig # 未知发布方（UNKNOWN_KEY = stranger.unknown）
+```
+
+- 再生：`node gen-signed-fixtures.mjs`（幂等确定，与提交产物字节一致，由双端 spec 钉住）；
+- 测试 key 由公开 seed 常量派生（SHA-256 → 32B → PKCS#8 DER → Ed25519），**无保密性、私钥永不入仓**（P2-12「模板/夹具不得含私钥」的前提）；
+- 双端消费：CLI 面 `src/lifecycle/__tests__/sig-fixtures.test.ts`；templates 面 `tests/lifecycle/sig-fixtures.spec.ts`（跨 root import 生成器）；
+- P2-3 起 isolate 六码/TOFU 全链以同组夹具为锚（`steps/verify.ts` + `CryptoFace.verifyEd25519`）。

package/src/lifecycle/__tests__/fixtures/fixture-invalid/EXPECTED-VIOLATIONS.md

@@ -0,0 +1,27 @@
+# fixture-invalid · 期望违规清单（P1-5/P1-11 测试的期望真源）
+
+夹具 `manifest.yaml` 故意触发 7 条**内在违规**——定义为「对任意合法 name/version 取值均违规」，与 name 非法引起的连锁衍生失配（如 `demo:*` 命名空间字段）区分开。
+
+## 测试断言约定
+
+1. 双端（Node `validateContract` / isolate `preflight`）各自解析本夹具，断言违规码集合 **⊇** 下表 7 码；不断言「恰好等于」（衍生违规允许存在，允许 fail-fast 提前截断——但被断言的码必须在其截断前可报出，故双端实现均要求**收集全部违规后统一报出**，见契约 §0 唯一真源纪律）。
+2. `fixture-valid` 同规则跑双端，断言**零违规**（防误报）。
+3. 衍生违规（`demo:menu.demo` 等 namespace 失配）不计入断言，不要求报出或不报出。
+
+## 违规对照表
+
+| ID | 触发点 | 期望违规码 | 契约条款 | 上游依据 | 内在性说明 |
+|---|---|---|---|---|---|
+| V1 | `name: Demo`（大写） | C2-01 | §2.1 身份 name 白名单 `^[a-z][a-z0-9-]{0,63}$`（契约 §2.1 现行式） | R7 预检白名单 | 大写对任意取值均违规 |
+| V2 | `version: 1.0.0+build.5` | C2-02 | §2.1 version 禁 `+`（oj validate_version 字符集 `[A-Za-z0-9._-]` 无 `+`） | 契约附录 B-1（oj 相容排除） | `+` 恒被 oj 拒装 |
+| V3 | `api.anonymous: [system/health]` | C2-26 | §2.4 匿名路径段内收敛（首段必须 = 本方案段；`system`/`_system` 恒非本方案段） | R8 越段匿名化 + `_system` 禁入 | `system/health` 对任意 name 均越段 |
+| V4 | `routes[0].category: personal` | C2-17 | §2.6 路由 category ∈ main\|admin\|hidden（D4 三值） | D4（PRD §5.2 五值废弃） | `personal` 为已删除值 |
+| V5 | `settings.groups[0]` 缺 `label_key` | C2-22 | §2.7 组 label_key 必填，指向 `<name>:settings.group.*` | D4 设置组标题契约 | 必填字段缺失 |
+| V6 | `settings.groups[0].items[0].key: framework.site_title` | C2-23 | §2.7 键所有权 `moduleOf(key) === name` | R24（防 `framework.*` 污染，跨模块提权同类洞） | `framework.` 前缀对任意方案 name 均越空间 |
+| V7 | `roles[0].permissions: [demo.manage]`（未声明） | C2-16 | §2.5 角色 permissions ⊆ permissions[].code | §2.5 悬空引用双端拒绝 | `demo.manage` 不在 permissions[] 中，对任意 name 均悬空 |
+
+## 关联文件
+
+- 契约：`docs/prd/solution/202610171254-lifecycle-manifest-contract.md`（规则编号 §2/§4）
+- 合法对照：`../fixture-valid/manifest.yaml`（全字段合法，双端零违规）
+- 双端测试约定：`../README.md`

package/src/lifecycle/__tests__/fixtures/fixture-invalid/api/src/Demo/manifest.yaml

@@ -0,0 +1,6 @@
+# oj 模块级 manifest（负例夹具）：与 bundle 级同错（name 大写、version 含 `+`）。
+# oj validate_module 允许大写、validate_version 拒绝 `+`——仅后者为 oj 侧真实拒装点；
+# 契约双端均拒（C2-01/C2-02）。
+name: Demo
+desc: 契约非法夹具（预检负例真源）
+version: 1.0.0+build.5

package/src/lifecycle/__tests__/fixtures/fixture-invalid/manifest.yaml

@@ -0,0 +1,40 @@
+# ── C2 契约非法夹具（fixture-invalid）──────────────────────────────────
+# 故意触发 7 条契约违规（V1–V7），逐条对照同目录 EXPECTED-VIOLATIONS.md。
+# 双端测试期望：Node 侧 validateContract 与 isolate 侧 preflight 均报告
+# 违规码集合 ⊇ {C2-01, C2-02, C2-16, C2-17, C2-22, C2-23, C2-26}。
+# 说明：name/version 非法会连锁触发 demo:* 命名空间字段的失配（衍生违规），
+# 衍生项不计入断言集——V1–V7 均为「对任意合法 name/version 均违规」的内在违规。
+name: Demo # V1 违 C2-01（大写，白名单 ^[a-z][a-z0-9-]{0,63}$）
+version: 1.0.0+build.5 # V2 违 C2-02（`+` 为 oj validate_version 拒绝字符）
+summary: 契约非法夹具（预检负例真源）
+changelog: 负例夹具，禁止安装到任何站点
+
+api:
+  prefix: /api/demo
+  anonymous:
+    - system/health # V3 违 C2-26（越段：首段 system ≠ 本方案段，R8；_system 同理禁入）
+
+routes:
+  - path: /demo
+    category: personal # V4 违 C2-17（D4 已删除该值，三值 main|admin|hidden）
+    order: 30
+    title_key: demo:menu.demo
+  - path: /demo/admin
+    category: admin
+    order: 200
+    title_key: demo:menu.admin
+
+permissions:
+  - {code: demo.view, title_key: demo:perm.view}
+
+roles:
+  - name: demo.admin
+    title_key: demo:role.admin
+    permissions: [demo.manage] # V7 违 C2-16（悬空引用：demo.manage 未在 permissions[] 声明）
+
+settings:
+  groups:
+    - group: display
+      items: # V5 违 C2-22（label_key 必填缺失）
+        - key: framework.site_title # V6 违 C2-23（moduleOf(key)=framework ≠ name，R24 越空间污染）
+          type: string

package/src/lifecycle/__tests__/fixtures/fixture-invalid/web/src/Demo/entry.ts

@@ -0,0 +1,14 @@
+// 夹具 entry 占位（负例）：结构对齐 fixture-valid，仅承载 manifest 违规断言所需最小形态。
+const entry = {
+	name: "Demo",
+	description: "契约非法夹具（预检负例真源）",
+	version: "1.0.0+build.5",
+	routes: [
+		{
+			path: "/demo",
+			handle: { layout: "container", order: 30, title: "demo:menu.demo" },
+		},
+	],
+};
+
+export default entry;

package/src/lifecycle/__tests__/fixtures/fixture-invalid/web/src/Demo/locales/en-US.json

@@ -0,0 +1,12 @@
+{
+	"menu": {
+		"demo": "Invalid Fixture",
+		"admin": "Invalid Fixture Admin"
+	},
+	"perm": {
+		"view": "View invalid fixture"
+	},
+	"role": {
+		"admin": "Invalid Fixture Admin Role"
+	}
+}

package/src/lifecycle/__tests__/fixtures/fixture-invalid/web/src/Demo/locales/zh-CN.json

@@ -0,0 +1,12 @@
+{
+	"menu": {
+		"demo": "非法夹具",
+		"admin": "非法夹具管理"
+	},
+	"perm": {
+		"view": "查看非法夹具"
+	},
+	"role": {
+		"admin": "非法夹具管理员"
+	}
+}

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/manifest.yaml

@@ -0,0 +1,9 @@
+# oj 模块级 manifest（安装后由 oj 真实解析；oj/src/manifest.rs 7-22）。
+# 与 bundle 级 manifest.yaml 分层：仅 oj 原生七键（name/desc/version/config/db/tables/deps），
+# 禁携带 bundle 字段（契约 §3 分层红线 OJ-X）。
+# 构建期核对：name === bundle name、version === bundle version、desc === bundle summary（C2-31）。
+name: demo-solution
+desc: manifest.yaml 契约全字段合法夹具
+version: 0.1.0
+tables:
+  - note

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/migrations/0001__init.sql

@@ -0,0 +1,6 @@
+-- 0001__init：建 note 表（与 schema.yaml 列集一致；oj migrate 按 seq 升序执行）
+CREATE TABLE IF NOT EXISTS note (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  create_time INTEGER NOT NULL
+);

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/ping/api.ts

@@ -0,0 +1,9 @@
+// 夹具路由占位（对应 manifest api.anonymous 条目 demo-solution/ping）。
+// 形态示例：不参与构建、不引用 oj isolate 全局（json/http/exec）。
+const ping = {
+	async get() {
+		return { pong: true, module: "demo-solution" };
+	},
+};
+
+export default ping;