@oj-module/cli 0.2.6 → 0.2.14

package/src/market/build-index.ts

@@ -0,0 +1,159 @@
+/**
+ * `ojm market build-index`（T4）：扫描 `cdn/*.tgz` → 提取内嵌 manifest → 全量重建两份索引并签名。
+ *
+ * 为什么不增量合并：索引是**共享可变单文件**，多人发布时读-改-写天然 TOCTOU，且索引签名会被
+ * 后发者覆盖。而 `market/api.ts verifyIndexSig` 注释已写明「索引签名只做完整性，信任由 TOFU/
+ * 信任库承载」——索引本就不是信任锚，那就把它降级为派生产物：谁都能重建，重建结果只取决于目录内容。
+ */
+
+import type { IndexedPackage } from "./index-builder";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { stringify as yamlStringify } from "yaml";
+import { recomputeIndex, signIndex } from "../publish";
+import { resolveCdnLayout } from "./cdn-layout";
+import { buildIndexData } from "./index-builder";
+import { readEmbeddedManifest } from "./scan";
+
+export interface BuildIndexOptions {
+	projectRoot?: string
+	id?: string
+	key?: string
+	privateKeyPem?: string
+	/** 重建后离线自检（verifyCanonical 复核两份索引签名） */
+	check?: boolean
+}
+
+export interface BuildIndexResult {
+	bundlesPath: string
+	manifestsPath: string
+	bundlesSigPath: string
+	manifestsSigPath: string
+	/** 入索引的方案数 */
+	solutions: number
+	/** 因缺内嵌 manifest 等原因被跳过的文件名 */
+	skipped: string[]
+	checkPassed?: boolean
+}
+
+export async function buildIndex(opts: BuildIndexOptions = {}): Promise<BuildIndexResult> {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const layout = resolveCdnLayout(projectRoot);
+	if (!fs.existsSync(layout.dir))
+		throw new Error(`[ojm] CDN 目录不存在：${layout.dir}（先跑 ojm market publish，或检查 config 的 /cdn 挂载）`);
+
+	const files = fs.readdirSync(layout.dir).filter(f => f.endsWith(".tgz")).sort();
+	const packages: IndexedPackage[] = [];
+	const skipped: string[] = [];
+	for (const file of files) {
+		const abs = path.join(layout.dir, file);
+		const bytes = new Uint8Array(fs.readFileSync(abs));
+		let manifest: Record<string, unknown> | null = null;
+		try {
+			manifest = readEmbeddedManifest(bytes);
+		}
+		catch (error) {
+			console.warn(`[ojm] 跳过 ${file}：${(error as Error).message}`);
+		}
+		const name = typeof manifest?.name === "string" ? manifest.name as string : "";
+		const version = typeof manifest?.version === "string" ? manifest.version as string : "";
+		if (manifest === null || name === "" || version === "") {
+			skipped.push(file);
+			console.warn(`[ojm] 跳过 ${file}：包内缺 manifest.yaml 或缺少 name/version`);
+			continue;
+		}
+		packages.push({
+			name,
+			version,
+			file,
+			sha256: createHash("sha256").update(bytes).digest("hex"),
+			size: bytes.byteLength,
+			manifest,
+			signature: readSidecarSig(abs),
+		});
+	}
+
+	const data = buildIndexData(packages);
+	const bundlesText = normalizeYaml(data.bundles);
+	const manifestsText = normalizeYaml(data.manifests);
+	const bundlesPath = path.join(layout.dir, "bundles.yaml");
+	const manifestsPath = path.join(layout.dir, "manifests.yaml");
+	fs.writeFileSync(bundlesPath, bundlesText);
+	fs.writeFileSync(manifestsPath, manifestsText);
+
+	// 索引是多人协作产物：格式再 determinism 一次（recomputeIndex 即 sortKeysDeep + 确定性 stringify）
+	const signed = signIndexes({ bundlesPath, manifestsPath, id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem });
+
+	console.log(`[ojm] 索引已重建：${data.bundles.solutions.length} 个方案 / ${packages.length} 个版本（来源 ${files.length} 个 tgz）`);
+	if (skipped.length > 0)
+		console.warn(`[ojm] ${skipped.length} 个包被跳过：${skipped.join(", ")}`);
+
+	return {
+		bundlesPath,
+		manifestsPath,
+		bundlesSigPath: signed.bundlesSigPath,
+		manifestsSigPath: signed.manifestsSigPath,
+		solutions: data.bundles.solutions.length,
+		skipped,
+	};
+}
+
+/**
+ * 读包级 detached 签名侧车（`<tgz>.sig`），转成 Form B `archive.signature`。
+ *
+ * 为什么非读不可：安装器 verifying 段只认 Form B 的 archive.signature（同目录侧车不参与判定），
+ * 没有它一律 `sig_missing` 硬 fail-closed——索引是「包 + 签名」的聚合视图，少带签名等于把包报成不可装。
+ */
+function readSidecarSig(tgzPath: string): Record<string, unknown> | undefined {
+	const sigPath = `${tgzPath}.sig`;
+	if (!fs.existsSync(sigPath))
+		return undefined;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(sigPath, "utf-8")) as unknown;
+		return isObj(parsed) ? parsed as Record<string, unknown> : undefined;
+	}
+	catch {
+		console.warn(`[ojm] ${sigPath} 不是合法 JSON，已按无签名处理（该包会被安装器以 sig_missing 拒装）`);
+		return undefined;
+	}
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** 确定性 stringify：键序归一 + 无软换行，和既有 publish 的索引口径逐字一致 */
+function normalizeYaml(value: unknown): string {
+	return recomputeIndex(yamlStringify(value, { lineWidth: 0 }));
+}
+
+function signIndexes(args: { bundlesPath: string, manifestsPath: string, id?: string, key?: string, privateKeyPem?: string }): { bundlesSigPath: string, manifestsSigPath: string } {
+	const pem = args.privateKeyPem ?? readPemFrom(args.id, args.key);
+	const keyId = args.id ?? "";
+	if (keyId === "")
+		throw new Error("[ojm] 重建索引须给签名身份：--id <publisher.id>（.sig 的发布方标识；C2-37 命名空间）");
+	const bundlesText = fs.readFileSync(args.bundlesPath, "utf-8");
+	const manifestsText = fs.readFileSync(args.manifestsPath, "utf-8");
+	const bundlesSig = signIndex("bundles", bundlesText, pem, keyId);
+	const manifestsSig = signIndex("manifests", manifestsText, pem, keyId);
+	const bundlesSigPath = `${args.bundlesPath}.sig`;
+	const manifestsSigPath = `${args.manifestsPath}.sig`;
+	fs.writeFileSync(bundlesSigPath, `${JSON.stringify(bundlesSig, null, 2)}\n`);
+	fs.writeFileSync(manifestsSigPath, `${JSON.stringify(manifestsSig, null, 2)}\n`);
+	console.log(`[ojm] 索引签名已写出（发布方 ${keyId}）`);
+	return { bundlesSigPath, manifestsSigPath };
+}
+
+/** 从身份目录或私钥文件读出 PEM（磁盘路径是常规场景；隔离场景应直接传内存 PEM） */
+function readPemFrom(id?: string, key?: string): string {
+	const fsKey = key ?? (id === undefined ? undefined : path.join(os.homedir(), ".ojm", "keys", id, "private.pem"));
+	if (fsKey === undefined)
+		throw new Error("[ojm] 缺少签名身份：--id <publisher.id> 或 --key <pem 路径>");
+	if (!fs.existsSync(fsKey))
+		throw new Error(`[ojm] 私钥文件不存在：${fsKey}（用 ojm keygen --id ${id} 生成）`);
+	return fs.readFileSync(fsKey, "utf-8");
+}

package/src/market/cdn-layout.ts

@@ -0,0 +1,122 @@
+/**
+ * market CDN 的布局单点：**目录在哪 + 基址是什么**只在这里算（计划 §4.3 单一真相表）。
+ *
+ * 两条不能破的规矩：
+ * 1. **不许硬编码端口/主机/挂载路径**——全部从 `api/config.yaml` 读。
+ *    dev 形态下 `/cdn` 只在 oj 子进程（`server.port`）上成立，dev server 自己（5174）
+ *    会把 `/cdn/*` 交给静态层、未命中就回落 index.html（设计 §3.1.1）；写成相对路径或
+ *    写死 9778，市场页拿到的会是 HTML 而不是索引 YAML。
+ * 2. **基址无尾斜杠**——`market/api.ts` 按 `${base}/bundles.yaml` 拼。
+ *
+ * 文本版（`resolveCdnLayoutFromConfig`）与工程版（`resolveCdnLayout`）分工：前者纯函数便于单测，
+ * 后者负责读盘。取值口径只有前者一份，后者不重算。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as yamlParse } from "yaml";
+
+import { resolveConfigPath } from "../layout";
+
+/** 本地模拟 CDN 的挂载前缀（模板 api/config.yaml 随 Jinfirst 发布） */
+export const CDN_MOUNT_PREFIX = "/cdn";
+
+export interface CdnLayout {
+	/** cdn 目录绝对路径（由挂载的 `web` 相对 config 所在目录解析） */
+	dir: string
+	/** 挂载前缀，无尾斜杠（如 `/cdn`） */
+	prefix: string
+	/** 市场基址：`http://<host>:<port><prefix>`，无尾斜杠 */
+	baseUrl: string
+}
+
+/** 从工程根出发解析（会读 `api/config.yaml`） */
+export function resolveCdnLayout(projectRoot: string): CdnLayout {
+	const configPath = resolveConfigPath(projectRoot);
+	return resolveCdnLayoutFromConfig(fs.readFileSync(configPath, "utf-8"), configPath);
+}
+
+/** 从 config 文本解析（纯函数，不落 IO） */
+export function resolveCdnLayoutFromConfig(configText: string, configPath: string): CdnLayout {
+	const doc = isObj(yamlParse(configText)) ? yamlParse(configText) as Record<string, unknown> : {};
+	const mount = findCdnMount(mountsOf(doc), configPath);
+	const configDir = path.dirname(configPath);
+
+	const web = mount.web;
+	if (typeof web !== "string" || web.trim() === "") {
+		throw new Error(
+			`[ojm] ${configPath} 的 /cdn 挂载缺少 web 目录（当前是 api 挂载或目录为空）。\n`
+			+ "下一步：把这一条改成\n"
+			+ "  - prefix: /cdn\n"
+			+ "    web: ../cdn\n",
+		);
+	}
+
+	const prefix = normalizePrefix(String(mount.prefix));
+	const port = readPort(doc, configPath);
+	const host = readHost(doc);
+
+	return {
+		dir: path.resolve(configDir, web),
+		prefix,
+		baseUrl: `http://${host}:${port}${prefix}`,
+	};
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function mountsOf(doc: Record<string, unknown>): unknown[] {
+	const mounts = doc.mounts;
+	return Array.isArray(mounts) ? mounts : [];
+}
+
+/** 前缀归一化：补前导斜杠、去尾斜杠（拼接口径统一） */
+function normalizePrefix(raw: string): string {
+	let prefix = raw.trim();
+	if (!prefix.startsWith("/"))
+		prefix = `/${prefix}`;
+	while (prefix.length > 1 && prefix.endsWith("/"))
+		prefix = prefix.slice(0, -1);
+	return prefix;
+}
+
+function findCdnMount(mounts: unknown[], configPath: string): Record<string, unknown> {
+	const hit = mounts.find((entry) => {
+		if (!isObj(entry) || typeof entry.prefix !== "string")
+			return false;
+		return normalizePrefix(entry.prefix) === CDN_MOUNT_PREFIX;
+	});
+	if (hit)
+		return hit as Record<string, unknown>;
+
+	throw new Error(
+		`[ojm] ${configPath} 的 mounts 里没有 /cdn 条目——本地模拟 CDN 无处可挂。\n`
+		+ "出现这条错误说明该工程的 config 被手改过或来自旧模板。\n"
+		+ "下一步：把下面两行粘到 mounts: 段里（位置在 /api 之后、任何 `/` 之前）：\n"
+		+ "  - prefix: /cdn\n"
+		+ "    web: ../cdn\n",
+	);
+}
+
+/** 端口取自 config，口径与 oj-config.readOjPort 一致（缺失/非法即人称报错） */
+function readPort(doc: Record<string, unknown>, configPath: string): number {
+	const server = isObj(doc.server) ? doc.server as Record<string, unknown> : {};
+	const raw = server.port;
+	const port = typeof raw === "number" || typeof raw === "string" ? Number(raw) : Number.NaN;
+	if (!Number.isInteger(port) || port <= 0) {
+		throw new Error(
+			`[ojm] ${configPath} 缺少合法的 server.port。\n`
+			+ "该文件由 ojm init 生成，手动改动后请保留端口配置（oj 代码默认 9778）。",
+		);
+	}
+	return port;
+}
+
+/** 主机缺省回落到 oj 模板显式钉死的 127.0.0.1（config.yaml 注释解释过为何不用 localhost） */
+function readHost(doc: Record<string, unknown>): string {
+	const server = isObj(doc.server) ? doc.server as Record<string, unknown> : {};
+	const host = server.host;
+	return typeof host === "string" && host.trim() !== "" ? host.trim() : "127.0.0.1";
+}

package/src/market/command.ts

@@ -0,0 +1,139 @@
+/**
+ * `ojm market <sub>` 参数面（T3–T5 的命令入口）。
+ *
+ * 只做参数解析 + 调库函数：所有真逻辑都在同目录的 publish / build-index / setup 里，
+ * 这里不掺业务，便于测试直接打函数而不走 argv。
+ */
+
+import process from "node:process";
+
+import { buildIndex } from "./build-index";
+import { publishPackage } from "./publish";
+import { setupMarketUrl } from "./setup";
+import { trialCommand } from "./trial";
+import { verifyMarket } from "./verify";
+import { walkthroughCommand } from "./walkthrough";
+
+interface Flags {
+	id?: string
+	key?: string
+	fixture?: string
+	real?: string
+	url?: string
+	user?: string
+	pass?: string
+	newPass?: string
+	rebuildIndex?: boolean
+	check?: boolean
+}
+
+const VALUE_FLAGS = new Set(["--id", "--key", "--fixture", "--real", "--url", "--user", "--pass", "--new-pass"]);
+
+function parseFlags(argv: string[]): Flags {
+	const flags: Flags = {};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]!;
+		if (arg === "--rebuild-index") {
+			flags.rebuildIndex = true;
+			continue;
+		}
+		if (arg === "--check") {
+			flags.check = true;
+			continue;
+		}
+		if (VALUE_FLAGS.has(arg)) {
+			const value = argv[i + 1] ?? "";
+			i++;
+			if (arg === "--id")
+				flags.id = value;
+			else if (arg === "--key")
+				flags.key = value;
+			else if (arg === "--fixture")
+				flags.fixture = value;
+			else if (arg === "--real")
+				flags.real = value;
+			else if (arg === "--url")
+				flags.url = value;
+			else if (arg === "--user")
+				flags.user = value;
+			else if (arg === "--pass")
+				flags.pass = value;
+			else if (arg === "--new-pass")
+				flags.newPass = value;
+		}
+	}
+	return flags;
+}
+
+export async function marketCommand(sub: string, argv: string[]): Promise<void> {
+	const flags = parseFlags(argv);
+	switch (sub) {
+		case "publish": {
+			await publishPackage({
+				fixture: flags.fixture,
+				real: flags.real,
+				id: flags.id,
+				key: flags.key,
+				check: flags.check,
+			});
+			if (flags.rebuildIndex === true)
+				await buildIndex({ id: flags.id, key: flags.key, check: flags.check });
+			return;
+		}
+		case "verify": {
+			const result = verifyMarket({ file: flags.fixture === undefined ? undefined : flags.fixture, rebuildCheck: flags.rebuildIndex });
+			for (const check of result.checks)
+				console.log(`${check.ok ? "✓" : "✗"} ${check.item}：${check.detail}`);
+			if (result.drift !== undefined && result.drift.length > 0) {
+				for (const line of result.drift)
+					console.log(`✗ 索引漂移：${line}`);
+			}
+			console.log(result.conclusion);
+			if (!result.passed)
+				process.exitCode = 1;
+			return;
+		}
+		case "trial": {
+			await trialCommand(argv);
+			return;
+		}
+		case "walkthrough": {
+			await walkthroughCommand(argv);
+			return;
+		}
+		case "build-index": {
+			await buildIndex({ id: flags.id, key: flags.key, check: flags.check });
+			return;
+		}
+		case "setup": {
+			const result = await setupMarketUrl({ url: flags.url, user: flags.user, pass: flags.pass, newPass: flags.newPass });
+			console.log(`[ojm] 站点 ${result.siteUrl} 的市场地址已指向 ${result.cdnBaseUrl}`);
+			return;
+		}
+		default:
+			throw new Error(`[ojm] 未知子命令：ojm market ${sub}\n可用：setup / publish / build-index`);
+	}
+}
+
+/** `ojm market` 无子命令时的提示（与 usage.ts 同源风格） */
+export function marketUsage(): string {
+	return [
+		"ojm market setup   [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]   把市场地址指向本地 cdn/",
+		"ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--rebuild-index]",
+		"ojm market build-index           [--id <key>] [--check]                        扫描 cdn/ 重建索引",
+		"ojm market verify [--file <tgz>] [--rebuild-index]                             离线验包（不起站点、不装）",
+		"ojm market trial [--fixture <name>@<version>] [--keep]                          隔离站点试装（跑完即毁）",
+		"ojm market walkthrough [--only <op>] [--strict] [--keep]                        隔离站点跑全套市场操作并出 AC 表",
+	].join("\n");
+}
+
+/** 进程入口：从 argv 取子命令（index.ts 负责 dispatch 到此处） */
+export async function runMarket(argv: string[]): Promise<void> {
+	const sub = argv[0] ?? "";
+	if (sub === "" || sub === "--help" || sub === "-h") {
+		console.log(marketUsage());
+		return;
+	}
+	await marketCommand(sub, argv.slice(1));
+	void process;
+}

package/src/market/failure-playbook.ts

@@ -0,0 +1,57 @@
+/**
+ * 失败路径人话文案表（T12 收尾，对标 `keygen.ts` 双段式：成因一句 + 下一步一句）。
+ *
+ * 逐失败码/阶段一条，随 walkthrough 报告落盘（`logs/walkthrough-<ts>.md` 的文案表段落）。
+ * traceability：`__tests__/failure-playbook.test.ts` 守着 REQUIRED_CODES——每个 neg 场景
+ * 预期命中的失败码都必须有条目，补新 neg op 时同步加行。
+ */
+
+export interface FailurePlaybookEntry {
+	/** 失败码（六码 reason 或阶段级签名） */
+	code: string
+	/** 预期失败阶段（"安装前" 表示 POST 即被拒、任务未创建） */
+	stage: string
+	/** 成因一句（发生了什么） */
+	cause: string
+	/** 下一步一句（怎么办） */
+	next: string
+}
+
+export const FAILURE_PLAYBOOK: FailurePlaybookEntry[] = [
+	{
+		code: "sig_missing",
+		stage: "verifying",
+		cause: "分发包未签名：发布方未做 detached 签名，或 CDN 目录里 .sig 被裁剪",
+		next: "请发布方重发 `ojm market publish --check` 复核签名后重建索引",
+	},
+	{
+		code: "tampered",
+		stage: "verifying",
+		cause: "包体或签名与索引不符：分发包被篡改，或同版本号被换包重发",
+		next: "从可信源重新获取分发包；发布方应升版本号重发（同版本号只允许一份字节）",
+	},
+	{
+		code: "unknown_key",
+		stage: "verifying",
+		cause: "发布方 key 不在宿主信任库，安装停在 needs_trust 待确认",
+		next: "核对指纹后 `ojm trust confirm --task <task_id>` 入库，再重装即可",
+	},
+	{
+		code: "rollback_guard",
+		stage: "migrating",
+		cause: "包内迁移最大 seq 低于账本 head：禁降版部署（OJ-9 红线），库保持原状",
+		next: "正道是升级到新版本；确需回退请联系运维走对账自愈，勿强行降版",
+	},
+	{
+		code: "index_sig",
+		stage: "安装前（索引解析）",
+		cause: "市场索引签名校验失败：bundles/manifests.yaml 被篡改或签名与字节不符",
+		next: "重建索引并签名 `ojm market build-index`；同时核对 CDN 目录写入来源",
+	},
+	{
+		code: "zip_slip",
+		stage: "安装前（上传校验）",
+		cause: "分发包含越界成员（../ 或绝对路径），R1 zip-slip 防护拒在解包前",
+		next: "勿安装来路不明的包；发布方检查打包脚本，成员名必须是包内相对路径",
+	},
+];

package/src/market/fixture.ts

@@ -0,0 +1,138 @@
+/**
+ * fixture 方案包合成（T3）：生成一棵**能被安装器真正装下**的最小合法方案树。
+ *
+ * 形状取自 `scripts/verify-solution-smoke/make-solution.mjs`——那套字段组合已被真链路
+ * （oj serve 安装 + ping 端点）验证过，这里照抄布局而不是另发明一套（DRY）。
+ * 打包交给 `createDeterministicTgz`（同输入字节一致，不受 mtime/uid 影响）。
+ */
+
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+import { stringify as yamlStringify } from "yaml";
+
+export interface FixturePackage {
+	name: string
+	version: string
+	/** 方案树根目录：<staging>/<name>-<version> */
+	dir: string
+	manifestPath: string
+}
+
+export const DEFAULT_FIXTURE_NAME = "demo-solution";
+export const DEFAULT_FIXTURE_VERSION = "0.1.0";
+
+/** 解析 `--fixture <name>@<version>`；缺省/缺段用默认值补齐 */
+export function parseFixtureSpec(spec?: string): { name: string, version: string } {
+	if (spec === undefined || spec.trim() === "" || spec === "latest")
+		return { name: DEFAULT_FIXTURE_NAME, version: DEFAULT_FIXTURE_VERSION };
+	const at = spec.lastIndexOf("@");
+	if (at <= 0)
+		return { name: spec.trim(), version: DEFAULT_FIXTURE_VERSION };
+	const name = spec.slice(0, at).trim();
+	const version = spec.slice(at + 1).trim();
+	return { name: name === "" ? DEFAULT_FIXTURE_NAME : name, version: version === "" ? DEFAULT_FIXTURE_VERSION : version };
+}
+
+export function buildFixturePackage(opts: { stagingDir: string, name?: string, version?: string }): FixturePackage {
+	const name = opts.name ?? DEFAULT_FIXTURE_NAME;
+	const version = opts.version ?? DEFAULT_FIXTURE_VERSION;
+	const dir = path.join(opts.stagingDir, `${name}-${version}`);
+	const mod = path.join(dir, "api", `${name}-${version}`);
+	const webDir = path.join(dir, "web", "modules", name, version);
+	fs.mkdirSync(path.join(mod, "migrations"), { recursive: true });
+	fs.mkdirSync(path.join(mod, "ping"), { recursive: true });
+	fs.mkdirSync(webDir, { recursive: true });
+
+	fs.writeFileSync(path.join(dir, "manifest.yaml"), yamlStringify(solutionManifest(name, version)));
+	// oj 模块清单：oj 侧对齐 schema/迁移归属
+	fs.writeFileSync(path.join(mod, "manifest.yaml"), `name: ${name}\ndesc: ${name} ${version} 模块\nversion: ${version}\ntables:\n  - ${tableOf(name)}\n`);
+	fs.writeFileSync(path.join(mod, "routes.js"), `export default [{ method: "get", pattern: "${name}/ping", file: "ping/api.js" }];\n`);
+	// ping 处理器必须调 oj 运行时的全局 json.ok：直接 return 对象会被丢掉，装完看不到健康探针响应
+	fs.writeFileSync(path.join(mod, "ping", "api.js"), `export default { async get() { json.ok({ pong: true, module: "${name}", version: "${version}" }); } };\n`);
+	fs.writeFileSync(path.join(mod, "migrations", "0001__init.sql"), `CREATE TABLE ${tableOf(name)} (id INTEGER PRIMARY KEY, title TEXT NOT NULL);\n`);
+	// 迁移阶梯（T12）：minor ≥ 2 多一段 ALTER——upgrade 真的多走一段迁移，rollback 才有
+	// 「包内最大 seq < 账本 head」可拦（OJ-9 宿主层预锁拦截的物理前提）。确定性：内容只依赖 name。
+	if (minorOf(version) >= 2)
+		fs.writeFileSync(path.join(mod, "migrations", "0002__more.sql"), `ALTER TABLE ${tableOf(name)} ADD COLUMN body TEXT;\n`);
+	fs.writeFileSync(path.join(webDir, "entry.js"), `console.log("${name} ${version}");\n`);
+	fs.writeFileSync(path.join(webDir, "main.css"), `.${cssClassOf(name, version)} { color: red; }\n`);
+
+	return { name, version, dir, manifestPath: path.join(dir, "manifest.yaml") };
+}
+
+/** 表名：只允许标识符字符（fixture 名可能带连字符） */
+function tableOf(name: string): string {
+	return `${name.replace(/\W/g, "_")}_note`;
+}
+
+/** minor 段取数（迁移阶梯判定用；非 semver 形态一律按 0 处理） */
+function minorOf(version: string): number {
+	const m = /^\d+\.(\d+)/.exec(version);
+	return m === null ? 0 : Number(m[1]);
+}
+
+/**
+ * 手造 zip-slip 恶意 tgz（成员 `../evil.sql`）——neg-evil op 的上传载荷。
+ * 为什么不用 createDeterministicTgz：它只打包真实目录树，文件系统里造不出 `../` 成员；
+ * ustar 头是纯字节布局，手写 40 行可控成员名。确定性：mtime 置 0，同输入恒同字节。
+ */
+export function buildEvilZipSlipTgz(outPath: string): string {
+	const chunks: Buffer[] = [];
+	for (const [name, content] of [
+		["../evil.sql", "DROP TABLE users;"],
+		["manifest.yaml", "name: evil-solution\nversion: 9.9.9\n"],
+	] as Array<[string, string]>) {
+		const header = Buffer.alloc(512);
+		header.write(name, 0, "utf-8"); // name[100]
+		header.write("0000644\0", 100); // mode
+		header.write("0000000\0", 108); // uid
+		header.write("0000000\0", 116); // gid
+		header.write(`${content.length.toString(8).padStart(11, "0")}\0`, 124); // size[12]
+		header.write("00000000000\0", 136); // mtime[12] 置 0（确定性）
+		header.fill(0x20, 148, 156); // chksum 先填空格
+		header.write("0", 156); // typeflag：普通文件
+		header.write("ustar\0", 257); // magic
+		header.write("00", 263); // version
+		let sum = 0;
+		for (const b of header)
+			sum += b;
+		header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148); // chksum[8]
+		chunks.push(header, Buffer.from(content));
+		const pad = Math.ceil(content.length / 512) * 512 - content.length;
+		if (pad > 0)
+			chunks.push(Buffer.alloc(pad));
+	}
+	chunks.push(Buffer.alloc(1024)); // 尾零块
+	fs.writeFileSync(outPath, gzipSync(Buffer.concat(chunks)));
+	return outPath;
+}
+
+function cssClassOf(name: string, version: string): string {
+	return `${name}-v${version.replace(/[^0-9A-Z]/gi, "-")}`;
+}
+
+/** 方案清单（Form A：archive 只写 file，sha256/size 由索引侧填 Form B） */
+function solutionManifest(name: string, version: string): Record<string, unknown> {
+	return {
+		name,
+		version,
+		title: `${name} fixture`,
+		summary: `本地模拟 CDN 的 fixture 方案（${name} ${version}）`,
+		author: "ojm-market",
+		license: "MIT",
+		changelog: [`${version} fixture 初始版本`],
+		peerRuntime: ">=0.0.0",
+		health: `/${name}/ping`,
+		archive: { file: `${name}-${version}.tgz` },
+		api: { module: name, prefix: `/api/${name}`, tables: [tableOf(name)], anonymous: [`${name}/ping`] },
+		web: { entry: `modules/${name}/${version}/entry.js`, css: [`modules/${name}/${version}/main.css`] },
+		routes: [
+			{ path: `/${name}`, category: "main", order: 200, title_key: `${name}:menu.main` },
+			{ path: `/${name}/ping`, category: "hidden", order: 205, title_key: `${name}:menu.ping` },
+		],
+		permissions: [{ code: `${name}.view`, title_key: `${name}:perm.view` }],
+		roles: [{ name: `${name}.admin`, title_key: `${name}:role.admin`, permissions: [`${name}.view`] }],
+	};
+}