@oj-module/cli 0.2.8 → 0.2.14

package/src/market/walkthrough.ts

@@ -0,0 +1,506 @@
+/**
+ * `ojm market walkthrough`（T10–T12）：在隔离站点上把市场主链路跑一遍，逐项给 AC。
+ *
+ * 每个 op 的形状固定：setup → act → assert → cleanup（cleanup 在 finally）。`--only <op>` 可单跑，
+ * 每个 op 的 setup 自己建立前置态（不依赖前序 op 的残留）——这是「原子」的可测定义。
+ *
+ * 输出是一张 AC 表 + 汇总行；有 FAIL 即退出码 1。`--strict` 首败即停（调试用）。
+ *
+ * T12 追加：upgrade / rollback（主链路）与 neg-tamper / nosig / badindex / stranger（负向）。
+ * neg-* 统一用 9.9.9 版本与主链路隔离；篡改的文件在 finally 里回抄原始字节（不重签），
+ * 收尾摘包重铺索引——否则后续 op 全挂。
+ */
+
+import type { TaskRecord } from "../site";
+import type { IsolatedSite } from "./bootstrap";
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+
+import path from "node:path";
+import process from "node:process";
+import { signCommand } from "../sign";
+import { callApi, login, pollTask, unwrapEnvelope } from "../site";
+import { bootstrapIsolatedSite, derivePublisherKey } from "./bootstrap";
+import { buildIndex } from "./build-index";
+import { FAILURE_PLAYBOOK } from "./failure-playbook";
+import { buildEvilZipSlipTgz, parseFixtureSpec } from "./fixture";
+import { publishPackage } from "./publish";
+import { writeWalkthroughReport } from "./report";
+import { setupMarketUrl } from "./setup";
+
+interface Ctx {
+	site: IsolatedSite
+	base: string
+	token: string
+	name: string
+	version: string
+	log: (line: string) => void
+}
+
+interface OpResult {
+	ok: boolean
+	detail: string
+}
+
+interface Op {
+	/** 命令里 --only 用的名字 */
+	key: string
+	title: string
+	run: (ctx: Ctx) => Promise<OpResult>
+}
+
+export interface WalkthroughOptions {
+	projectRoot?: string
+	fixture?: string
+	/** 只跑某个 op */
+	only?: string
+	/** 保留隔离现场 */
+	keep?: boolean
+	/** 首败即停 */
+	strict?: boolean
+	onLog?: (line: string) => void
+}
+
+export interface WalkthroughResult {
+	ok: boolean
+	rows: Array<{ key: string, title: string, ok: boolean, detail: string }>
+	port: number
+}
+
+/** neg-* 专用版本：与主链路（0.1.0/0.2.0）完全隔离，收尾整包摘除 */
+const NEG_VERSION = "9.9.9";
+
+const OPS: Op[] = [
+	{
+		key: "index",
+		title: "市场索引出卡片",
+		run: async (ctx) => {
+			const rows = await callApi<Array<Record<string, unknown>>>(fetch, ctx.base, ctx.token, "GET", "/api/_platform/market/index");
+			const hit = (rows ?? []).find(r => r.name === ctx.name);
+			return hit === undefined
+				? { ok: false, detail: `索引里没有 ${ctx.name}（拿到 ${(rows ?? []).length} 张卡）` }
+				: { ok: true, detail: `${ctx.name} 在列，latest=${String(hit.latest)}，available=${JSON.stringify(hit.available ?? [])}` };
+		},
+	},
+	{
+		key: "install",
+		title: "安装（11 段）",
+		run: async (ctx) => {
+			const task = await install(ctx, ctx.version);
+			const done = task.status === "done";
+			return { ok: done, detail: done ? `${task.stages.length} 段全 ok` : `status=${task.status} stage=${task.stage ?? "?"}：${task.message}` };
+		},
+	},
+	{
+		key: "reinstall",
+		title: "同版本重装走重装路径",
+		run: async (ctx) => {
+			await ensureInstalled(ctx);
+			const task = await install(ctx, ctx.version);
+			const ok = task.status === "done";
+			return { ok, detail: ok ? "重装成功（未报方案名占用）" : `status=${task.status}：${task.message}` };
+		},
+	},
+	{
+		key: "enable",
+		title: "禁用 / 启用",
+		run: async (ctx) => {
+			await ensureInstalled(ctx);
+			const off = await callApi<{ ok?: boolean, message?: string }>(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/enable", { name: ctx.name, enabled: false });
+			if (off.ok !== true)
+				return { ok: false, detail: `禁用被拒：${off.message ?? "?"}` };
+			const on = await callApi<{ ok?: boolean, message?: string }>(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/enable", { name: ctx.name, enabled: true });
+			return on.ok === true
+				? { ok: true, detail: "disable → enable 双向成功" }
+				: { ok: false, detail: `启用被拒：${on.message ?? "?"}` };
+		},
+	},
+	{
+		key: "verify",
+		title: "站点深检",
+		run: async (ctx) => {
+			await ensureInstalled(ctx);
+			const res = await callApi<{ ok?: boolean, checks?: Array<{ id?: string, severity?: string }>, advise?: unknown }>(fetch, ctx.base, ctx.token, "POST", `/api/_platform/solutions/verify?name=${encodeURIComponent(ctx.name)}`);
+			// 本 op 断言「深检可用且报告结构完整」，不做裁决。checks 是问题清单：pitfall 10 修复后
+			// 全绿站点恒为空数组——空是健康态不是端点异常（此前的非空断言其实寄生在 ledger.stale 误报上）。
+			if (typeof res.ok !== "boolean" || !Array.isArray(res.checks) || !Array.isArray(res.advise))
+				return { ok: false, detail: "深检报告结构破损（缺 ok/checks/advise 字段）" };
+			const errors = res.checks.filter(c => c.severity === "error").map(c => c.id ?? "?");
+			return {
+				ok: true,
+				detail: res.checks.length === 0
+					? "报告结构完整，checks 为零问题（账本/RBAC/设置/路由/web 全绿）"
+					: `报告结构完整（${res.checks.length} 项问题）；error 项：${[...new Set(errors)].join("/") || "无"}`,
+			};
+		},
+	},
+	{
+		key: "history",
+		title: "操作历史可读",
+		run: async (ctx) => {
+			const rows = await callApi<unknown[]>(fetch, ctx.base, ctx.token, "GET", "/api/_platform/market/history");
+			const n = Array.isArray(rows) ? rows.length : 0;
+			return n > 0 ? { ok: true, detail: `历史 ${n} 条` } : { ok: false, detail: "历史为空" };
+		},
+	},
+	{
+		key: "upgrade",
+		title: "升级（0.1.0 → 0.2.0）",
+		run: async (ctx) => {
+			await ensureInstalled(ctx); // 前置：0.1.0 在列（账本 head=1）
+			await publishVersion(ctx, "0.2.0");
+			const task = await install(ctx, "0.2.0");
+			if (task.status !== "done")
+				return { ok: false, detail: `升级安装未 done：status=${task.status} stage=${task.stage ?? "?"}：${task.message}` };
+			const card = await indexCard(ctx);
+			const distDir = path.join(ctx.site.root, "api", "dist");
+			const dir010 = path.join(distDir, `${ctx.name}-0.1.0`);
+			const dir020 = path.join(distDir, `${ctx.name}-0.2.0`);
+			const mig010 = path.join(dir010, "migrations", "0001__init.sql");
+			const mig020 = path.join(dir020, "migrations", "0001__init.sql");
+			const installedOk = card?.installed === "0.2.0";
+			const bothAvailable = JSON.stringify(card?.available ?? []).includes("0.1.0") && JSON.stringify(card?.available ?? []).includes("0.2.0");
+			const dirsKept = fs.existsSync(dir010) && fs.existsSync(dir020);
+			const migSame = fs.existsSync(mig010) && fs.existsSync(mig020) && fs.readFileSync(mig010).equals(fs.readFileSync(mig020));
+			const ok = installedOk && bothAvailable && dirsKept && migSame;
+			return {
+				ok,
+				detail: ok
+					? "installed=0.2.0，双版本在列且目录共存（旧版不 prune），0001 迁移逐字节一致"
+					: `installedOk=${installedOk} bothAvailable=${bothAvailable} dirsKept=${dirsKept} migSame=${migSame}`,
+			};
+		},
+	},
+	{
+		key: "rollback",
+		title: "回滚拦截（账本超前，OJ-9）",
+		run: async (ctx) => {
+			// 前置：0.2.0 已装（账本 head=2）。--only 单跑时自建（upgrade op 不依赖前序残留，此处同纪律）。
+			let card = await indexCard(ctx);
+			if (card?.installed !== "0.2.0") {
+				await publishVersion(ctx, "0.2.0");
+				const pre = await install(ctx, "0.2.0");
+				if (pre.status !== "done")
+					return { ok: false, detail: `前置安装 0.2.0 未 done：status=${pre.status}：${pre.message}` };
+				card = await indexCard(ctx);
+			}
+			const distDir = path.join(ctx.site.root, "api", "dist");
+			const before = fs.readdirSync(distDir).sort(); // 零副作用基线：0.1.0 目录是前序合法安装的产物，不代表本次落盘
+			const task = await installOnce(ctx, "0.1.0"); // 包内最大 seq 1 < head 2
+			const blocked = task.status === "failed" && task.stage === "migrating";
+			const untouched = JSON.stringify(fs.readdirSync(distDir).sort()) === JSON.stringify(before);
+			const kept = card?.installed === "0.2.0";
+			const ok = blocked && untouched && kept;
+			return {
+				ok,
+				detail: ok
+					? "failed@migrating（宿主层/oj migrate 双层拦截之一），dist 内容零变化，installed 仍 0.2.0"
+					: `blocked=${blocked}（status=${task.status} stage=${task.stage}）untouched=${untouched} kept=${kept}：${task.message}`,
+			};
+		},
+	},
+	{
+		key: "uninstall",
+		title: "卸载清场",
+		run: async (ctx) => {
+			const card = await indexCard(ctx);
+			const installed = typeof card?.installed === "string" && card.installed !== "" ? card.installed : null;
+			if (installed === null)
+				await ensureInstalled(ctx); // 未装过：先装 ctx.version
+			const target = installed ?? ctx.version;
+			const res = await callApi<{ ok?: boolean, message?: string }>(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/uninstall", { name: ctx.name });
+			if (res.ok !== true)
+				return { ok: false, detail: `卸载被拒：${res.message ?? "?"}` };
+			const dir = path.join(ctx.site.root, "api", "dist", `${ctx.name}-${target}`);
+			return fs.existsSync(dir)
+				? { ok: false, detail: `卸载后目录仍在：${dir}` }
+				: { ok: true, detail: `${ctx.name}@${target} 锁 / 目录 / 注册面清场` };
+		},
+	},
+	{
+		key: "neg-tamper",
+		title: "负向：包体篡改（sha256 不符）",
+		run: async (ctx) => {
+			await publishVersion(ctx, NEG_VERSION);
+			const tgz = path.join(ctx.site.cdnDir, `${ctx.name}-${NEG_VERSION}.tgz`);
+			const orig = fs.readFileSync(tgz);
+			try {
+				const tampered = Buffer.from(orig);
+				tampered[Math.floor(tampered.length / 2)] ^= 0x01; // 翻转中间一个字节
+				fs.writeFileSync(tgz, tampered);
+				const task = await installOnce(ctx, NEG_VERSION);
+				const rejected = task.status === "failed" && task.stage === "verifying";
+				const noDrop = !fs.existsSync(path.join(ctx.site.root, "api", "dist", `${ctx.name}-${NEG_VERSION}`));
+				const ok = rejected && noDrop;
+				return {
+					ok,
+					detail: ok
+						? "failed@verifying（sha256 与索引不符，C2-29 fail-closed），零落盘"
+						: `status=${task.status} stage=${task.stage} noDrop=${noDrop}：${task.message}`,
+				};
+			}
+			finally {
+				fs.writeFileSync(tgz, orig); // 回抄原始字节，不重签
+				await removeVersion(ctx, NEG_VERSION);
+			}
+		},
+	},
+	{
+		key: "neg-nosig",
+		title: "负向：缺包级签名（sig_missing）",
+		run: async (ctx) => {
+			await publishVersion(ctx, NEG_VERSION);
+			const tgz = path.join(ctx.site.cdnDir, `${ctx.name}-${NEG_VERSION}.tgz`);
+			const sig = `${tgz}.sig`;
+			const origSig = fs.readFileSync(sig);
+			try {
+				fs.rmSync(sig);
+				await buildIndex({ projectRoot: ctx.site.root, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem }); // Form B 缺 archive.signature
+				const task = await installOnce(ctx, NEG_VERSION);
+				const reason = task.error?.reason ?? task.message;
+				const ok = task.status === "failed" && reason.includes("sig_missing");
+				return { ok, detail: ok ? "failed，失败码 sig_missing（G4 硬 fail-closed）" : `status=${task.status}：${reason}` };
+			}
+			finally {
+				fs.writeFileSync(sig, origSig); // 回抄原始字节
+				await removeVersion(ctx, NEG_VERSION);
+			}
+		},
+	},
+	{
+		key: "neg-badindex",
+		title: "负向：索引篡改（验签拒载）",
+		run: async (ctx) => {
+			await publishVersion(ctx, NEG_VERSION);
+			const bundles = path.join(ctx.site.cdnDir, "bundles.yaml");
+			const orig = fs.readFileSync(bundles);
+			try {
+				fs.appendFileSync(bundles, "# tampered\n"); // 索引字节变、签名失配
+				let msg = "";
+				try {
+					await installOnce(ctx, NEG_VERSION);
+				}
+				catch (error) {
+					msg = (error as Error).message; // 预期：安装 POST 即 502，任务都未创建
+				}
+				const ok = msg.includes("签名校验失败");
+				return { ok, detail: ok ? "安装 POST 即 502 拒载（G4 fail-closed），任务未创建" : `未按预期拒装：${msg === "" ? "安装竟成功" : msg}` };
+			}
+			finally {
+				fs.writeFileSync(bundles, orig); // 回抄原始字节
+				await removeVersion(ctx, NEG_VERSION);
+			}
+		},
+	},
+	{
+		key: "neg-stranger",
+		title: "负向：未登记 key（TOFU 闭环）",
+		run: async (ctx) => {
+			await publishVersion(ctx, NEG_VERSION);
+			const tgz = path.join(ctx.site.cdnDir, `${ctx.name}-${NEG_VERSION}.tgz`);
+			const sig = `${tgz}.sig`;
+			const orig = fs.readFileSync(tgz);
+			const origSig = fs.readFileSync(sig);
+			const stranger = derivePublisherKey(randomBytes(16).toString("hex")); // 未登记身份，私钥只在内存
+			const before = await trustKeys(ctx); // 信任库快照（F3 diff 基线）
+			try {
+				signCommand(tgz, { id: "stranger.publisher", privateKeyPem: stranger.privateKeyPem }); // 覆盖侧车签名
+				await buildIndex({ projectRoot: ctx.site.root, id: "stranger.publisher", privateKeyPem: stranger.privateKeyPem });
+				const first = await installOnce(ctx, NEG_VERSION);
+				if (first.status !== "needs_trust")
+					return { ok: false, detail: `未停 needs_trust：status=${first.status}：${first.message}` };
+				await callApi(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/trust", { task_id: first.id });
+				const second = await installOnce(ctx, NEG_VERSION);
+				if (second.status !== "done")
+					return { ok: false, detail: `确认后重装未 done：status=${second.status}：${second.message}` };
+				// 收尾（F3）：显式 revoke 陌生 key，快照 diff 断言无残留——不靠 uninstall 兜底（它本就不摘信任）
+				const del = await callApi<{ revoked?: boolean }>(fetch, ctx.base, ctx.token, "DELETE", `/api/_platform/market/trust/key?key_id=${encodeURIComponent("stranger.publisher")}`);
+				const after = await trustKeys(ctx);
+				const revoked = del.revoked === true;
+				const noResidue = JSON.stringify(after) === JSON.stringify(before);
+				const ok = revoked && noResidue;
+				return {
+					ok,
+					detail: ok
+						? "needs_trust → confirm → done；stranger key 已 revoke，信任库快照 diff 为空"
+						: `revoked=${revoked} noResidue=${noResidue}（before=${before.length} after=${after.length}）`,
+				};
+			}
+			finally {
+				fs.writeFileSync(tgz, orig); // 回抄原始字节，不重签
+				fs.writeFileSync(sig, origSig);
+				await removeVersion(ctx, NEG_VERSION);
+			}
+		},
+	},
+	{
+		key: "neg-evil",
+		title: "负向：zip-slip 越界包（R1 拒收）",
+		run: async (ctx) => {
+			const evil = path.join(ctx.site.cdnDir, `${ctx.name}-evil.tgz`);
+			buildEvilZipSlipTgz(evil); // 成员含 ../evil.sql，无需发布进索引（file 源直传）
+			const distDir = path.join(ctx.site.root, "api", "dist");
+			const before = fs.readdirSync(distDir).sort(); // 零副作用基线：9.9.9 目录可能是前序 neg-stranger 的合法产物
+			try {
+				let msg = "";
+				try {
+					await installFile(ctx, evil, NEG_VERSION);
+				}
+				catch (error) {
+					msg = (error as Error).message; // 预期：上传校验 400，任务未创建
+				}
+				const rejected = msg.includes("zip-slip");
+				const untouched = JSON.stringify(fs.readdirSync(distDir).sort()) === JSON.stringify(before);
+				const ok = rejected && untouched;
+				return {
+					ok,
+					detail: ok
+						? "上传即 400（R1 zip-slip 防护拒在解包前），dist 内容零变化"
+						: `rejected=${rejected} untouched=${untouched}：${msg === "" ? "安装竟成功" : msg}`,
+				};
+			}
+			finally {
+				fs.rmSync(evil, { force: true });
+			}
+		},
+	},
+];
+
+export async function walkthrough(opts: WalkthroughOptions = {}): Promise<WalkthroughResult> {
+	const log = opts.onLog ?? ((line: string) => console.log(line));
+	const spec = parseFixtureSpec(opts.fixture);
+	const site = await bootstrapIsolatedSite({ projectRoot: opts.projectRoot, fixture: opts.fixture, keep: opts.keep, onLog: log });
+	try {
+		const newPass = "trial-pass-1";
+		await setupMarketUrl({ projectRoot: site.root, url: site.baseUrl, user: site.admin.user, pass: site.admin.pass, newPass });
+		const token = await login(fetch, site.baseUrl, site.admin.user, newPass);
+		const ctx: Ctx = { site, base: site.baseUrl, token, name: spec.name, version: spec.version, log };
+
+		const selected = opts.only === undefined ? OPS : OPS.filter(op => op.key === opts.only);
+		if (selected.length === 0)
+			throw new Error(`[ojm] 未知 op「${opts.only}」——可用：${OPS.map(op => op.key).join(" / ")}`);
+
+		const rows: WalkthroughResult["rows"] = [];
+		for (const op of selected) {
+			let row: WalkthroughResult["rows"][number];
+			try {
+				const result = await op.run(ctx);
+				row = { key: op.key, title: op.title, ok: result.ok, detail: result.detail };
+			}
+			catch (error) {
+				row = { key: op.key, title: op.title, ok: false, detail: (error as Error).message };
+			}
+			rows.push(row);
+			log(`${row.ok ? "✓" : "✗"} ${op.key.padEnd(10)} ${op.title}${row.ok ? "" : ` —— ${row.detail}`}`);
+			if (!row.ok && opts.strict === true)
+				break;
+		}
+
+		const failed = rows.filter(r => !r.ok).length;
+		log(`\n${failed === 0 ? "全部通过" : `${failed} 项未过`}（${rows.length} 项）：${rows.filter(r => r.ok).length} PASS / ${failed} FAIL`);
+		// 报告落盘（白名单内容 + 黑名单脱敏兜底）：AC 表 + 汇总 + 失败文案表
+		const reportPath = writeWalkthroughReport({ rows, port: site.port, playbook: FAILURE_PLAYBOOK });
+		log(`[ojm] 报告已落盘 → ${reportPath}`);
+		return { ok: failed === 0, rows, port: site.port };
+	}
+	finally {
+		await site.cleanup();
+	}
+}
+
+/** 安装 + 轮询；needs_trust 时自动确认（隔离站点，无外部信任可言） */
+async function install(ctx: Ctx, version: string): Promise<TaskRecord> {
+	let task = await installOnce(ctx, version);
+	if (task.status === "needs_trust") {
+		await callApi(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/trust", { task_id: task.id });
+		task = await installOnce(ctx, version);
+	}
+	return task;
+}
+
+async function installOnce(ctx: Ctx, version: string): Promise<TaskRecord> {
+	const started = await callApi<{ task_id?: string, id?: string }>(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/install", { name: ctx.name, version, source: "cdn" });
+	const taskId = String(started.task_id ?? started.id ?? "");
+	if (taskId === "")
+		throw new Error("[ojm] 安装接口未返回 task id");
+	return pollTask(fetch, ctx.base, ctx.token, taskId, { interval0: 400, intervalMax: 2000, timeoutMs: 120_000 });
+}
+
+/** file 源 multipart 上传（与 install.ts 同形态；neg-evil 用它递 zip-slip 恶意包） */
+async function installFile(ctx: Ctx, tgzPath: string, version: string): Promise<void> {
+	const form = new FormData();
+	form.append("name", ctx.name);
+	form.append("version", version);
+	form.append("source", "file");
+	form.append("file", new Blob([fs.readFileSync(tgzPath)], { type: "application/gzip" }), path.basename(tgzPath));
+	const res = await fetch(`${ctx.base}/api/_platform/market/install`, {
+		method: "POST",
+		headers: { authorization: `Bearer ${ctx.token}` },
+		body: form,
+	});
+	await unwrapEnvelope(res); // 非 0 code 抛人话（400 zip-slip / 502 索引等）
+}
+
+/** 信任库 key_id 快照（GET /market/trust；neg-stranger 的 diff 断言用） */
+async function trustKeys(ctx: Ctx): Promise<string[]> {
+	const res = await callApi<{ keys?: Array<{ key_id?: string }> }>(fetch, ctx.base, ctx.token, "GET", "/api/_platform/market/trust");
+	return (res.keys ?? []).map(k => k.key_id ?? "").filter(id => id !== "").sort();
+}
+
+/** 前置态：保证目标版本已装（其他 op 不依赖前序 op 的残留） */
+async function ensureInstalled(ctx: Ctx): Promise<void> {
+	const card = await indexCard(ctx);
+	if (card?.installed === ctx.version)
+		return;
+	const task = await install(ctx, ctx.version);
+	if (task.status !== "done")
+		throw new Error(`前置安装失败：status=${task.status}：${task.message}`);
+}
+
+/** 索引卡片（本方案一行；upgrade/rollback/uninstall 与 index op 同一消费面） */
+async function indexCard(ctx: Ctx): Promise<Record<string, unknown> | undefined> {
+	const rows = await callApi<Array<Record<string, unknown>>>(fetch, ctx.base, ctx.token, "GET", "/api/_platform/market/index");
+	return (rows ?? []).find(r => r.name === ctx.name);
+}
+
+/** 发布某版本 fixture 进隔离 CDN 并重铺索引（upgrade/rollback/neg-* 的共用前置） */
+async function publishVersion(ctx: Ctx, version: string): Promise<void> {
+	await publishPackage({ projectRoot: ctx.site.root, fixture: `${ctx.name}@${version}`, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem });
+	await buildIndex({ projectRoot: ctx.site.root, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem });
+}
+
+/** neg op 收尾：整包摘除（tgz + 侧车签名）并重铺索引，恢复主链路原状 */
+async function removeVersion(ctx: Ctx, version: string): Promise<void> {
+	for (const file of [`${ctx.name}-${version}.tgz`, `${ctx.name}-${version}.tgz.sig`])
+		fs.rmSync(path.join(ctx.site.cdnDir, file), { force: true });
+	await buildIndex({ projectRoot: ctx.site.root, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem });
+}
+
+export const WALKTHROUGH_OPS = OPS.map(op => op.key);
+
+export async function walkthroughCommand(argv: string[]): Promise<void> {
+	const opts: WalkthroughOptions = {};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]!;
+		if (a === "--keep") {
+			opts.keep = true;
+			continue;
+		}
+		if (a === "--strict") {
+			opts.strict = true;
+			continue;
+		}
+		if (a === "--only" || a === "--fixture") {
+			const v = argv[i + 1] ?? "";
+			i++;
+			if (a === "--only")
+				opts.only = v;
+			else
+				opts.fixture = v;
+		}
+	}
+	const result = await walkthrough(opts);
+	if (!result.ok)
+		process.exitCode = 1;
+}

package/src/oj.ts

@@ -113,7 +113,9 @@ export function startOj(
 		});
 		// spawn 本身失败（如 ENOENT）只发 error 不发 exit，必须单独兜住
 		child.once("error", (err) => {
-			finish(new Error(`[ojm] 无法启动 oj（${binPath}）：${err.message}`));
+			const enoent = (err as NodeJS.ErrnoException).code === "ENOENT";
+			const hint = enoent ? "\n下一步：oj 二进制尚未安装（它在 .gitignore 里，不随仓库分发）。\n在本工程目录跑一次 `ojm vendor`（经 npm 包 @oj-bin/oj 下载），再重试本命令。" : "";
+			finish(new Error(`[ojm] 无法启动 oj（${binPath}）：${err.message}${hint}`));
 		});
 		const timeout = setTimeout(() => {
 			finish(new Error(

package/src/preview-config.ts

@@ -30,6 +30,12 @@ export const PREVIEW_CONFIG_NAME = ".ojm-preview.yaml";
 export interface DerivePreviewConfigOptions {
 	/** 全站产物目录（layout.distDir），写入 web 挂载的绝对路径 */
 	siteDir: string
+	/**
+	 * release 形态的后端模块根（api/dist）。给了且原 config 声明了 platform.modules 时，
+	 * 把 `platform.root` 一并改写到该目录——特权模块的受控根必须与 `--api-path` 同源，
+	 * 否则 release 下 reloadConfig 会按 dev 的 src 判定归属（装好的方案热更不生效）。
+	 */
+	apiRoot?: string
 	/** 显式端口时覆盖 server.port；缺省沿用原 config（oj 代码默认 9778） */
 	port?: number
 	/** 原 config 文本（测试注入）；缺省读 api/config.yaml */
@@ -120,6 +126,14 @@ export function derivePreviewConfigText(configText: string, opts: DerivePreviewC
 	}
 	doc.mounts = mounts;
 
+	// platform.root 跟随 api 挂载根：dev = src，release（preview）= dist
+	const platform = doc.platform;
+	if (opts.apiRoot !== undefined && platform !== null && typeof platform === "object" && !Array.isArray(platform)) {
+		const mods = (platform as Record<string, unknown>).modules;
+		if (Array.isArray(mods) && mods.length > 0)
+			(platform as Record<string, unknown>).root = opts.apiRoot;
+	}
+
 	if (opts.port !== undefined) {
 		const server = doc.server !== null && typeof doc.server === "object" && !Array.isArray(doc.server)
 			? { ...(doc.server as Record<string, unknown>) }

package/src/preview.ts

@@ -40,7 +40,7 @@ export interface PreviewOptions {
 	/** 注入桩 oj 进程；默认 startOj */
 	ojStarter?: (configPath: string, base: string, apiPath: string, extraArgs: string[]) => OjProcess
 	/** 注入桩派生 config 落盘（测试）；默认 writePreviewConfig */
-	configWriter?: (projectRoot: string, opts: { siteDir: string, port?: number }) => PreviewConfigFiles
+	configWriter?: (projectRoot: string, opts: { siteDir: string, port?: number, apiRoot?: string }) => PreviewConfigFiles
 }
 
 export interface PreviewHandle {
@@ -81,8 +81,9 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 
 	// 派生 config 在 migrate 成功后落盘：失败即退路径零残留
 	const base = readOjApiPrefix(configPath);
-	const writer = opts.configWriter ?? ((root: string, o: { siteDir: string, port?: number }) => writePreviewConfig(root, o));
-	const preview = writer(projectRoot, { siteDir, port: opts.port });
+	const writer = opts.configWriter ?? ((root: string, o: { siteDir: string, port?: number, apiRoot?: string }) => writePreviewConfig(root, o));
+	// apiRoot 交给派生器：release 下 platform.root 必须指向 api/dist（与 --api-path 同源）
+	const preview = writer(projectRoot, { siteDir, port: opts.port, apiRoot: apiDist });
 
 	// / api 挂载与注入的 / web 挂载配对时 oj 不开 SPA 回落（oj 语义，见 devkit 手册 §13）
 	if (hasRootApiMount(parseMounts(readFileSync(configPath, "utf-8"), configPath)))

package/src/sign.ts

@@ -17,6 +17,12 @@ export interface SignOptions {
 	id?: string
 	/** 私钥 PEM 文件（缺省 ~/.ojm/keys/<id>/private.pem） */
 	key?: string
+	/**
+	 * 内存私钥 PEM（一次性/隔离场景专用，与 --key 二选一）。
+	 * 用途：`ojm market trial` 的一次性 keypair 不落盘，经此直接传进来；
+	 * 给了它就跳过文件存在性检查，也永远不读真 ~/.ojm/keys（计划 §3.3.1）。
+	 */
+	privateKeyPem?: string
 	/** 写完离线自检（verifyCanonical 复核） */
 	check?: boolean
 	/** 测试注入；缺省 process.cwd() */
@@ -46,10 +52,17 @@ export function signCommand(tgz: string, opts: SignOptions = {}): SignResult {
 	if (!fs.existsSync(tgz))
 		throw new Error(`[ojm] 方案包不存在：${tgz}`);
 	const cwd = opts.cwd ?? process.cwd();
-	// key 解析：--key 显式文件优先；否则 ~/.ojm/keys/<id>/private.pem（--id 必填）
-	let keyFile: string;
+	// key 解析：内存 PEM（不落盘）> --key 显式文件 > ~/.ojm/keys/<id>/private.pem（--id 必填）
+	let keyFile = "";
 	let keyId: string;
-	if (opts.key !== undefined) {
+	let memoryPem: string | undefined;
+	if (opts.privateKeyPem !== undefined && opts.privateKeyPem !== "") {
+		memoryPem = opts.privateKeyPem;
+		keyId = opts.id ?? "";
+		if (keyId === "")
+			throw new Error("[ojm] 使用内存私钥时须同时给 --id <publisher.id>（.sig 的发布方标识；C2-37 命名空间）");
+	}
+	else if (opts.key !== undefined) {
 		keyFile = path.resolve(cwd, opts.key);
 		keyId = opts.id ?? keyIdFromKeyPath(path.relative(os.homedir(), keyFile)) ?? "";
 		if (keyId === "")
@@ -63,13 +76,15 @@ export function signCommand(tgz: string, opts: SignOptions = {}): SignResult {
 	}
 	if (!isValidKeyId(keyId))
 		throw new Error(`[ojm] key_id 命名空间非法（C2-37）：「${keyId}」`);
-	if (!fs.existsSync(keyFile))
-		throw new Error(`[ojm] 私钥文件不存在：${keyFile}（用 ojm keygen --id ${keyId} 生成，或 --key 指定）`);
+	if (memoryPem === undefined) {
+		if (!fs.existsSync(keyFile!))
+			throw new Error(`[ojm] 私钥文件不存在：${keyFile}（用 ojm keygen --id ${keyId} 生成，或 --key 指定）`);
+	}
 
 	const bytes = new Uint8Array(fs.readFileSync(tgz));
 	const sha256 = createHash("sha256").update(bytes).digest("hex");
 	const canonical = canonicalString(deriveName(tgz), deriveVersion(tgz), sha256);
-	const privateKeyPem = readPrivateKeyPem(keyFile);
+	const privateKeyPem = memoryPem ?? readPrivateKeyPem(keyFile!);
 	const value = signCanonical(privateKeyPem, canonical);
 	const publicKeyHex = exportRawPublicKeyHex(privateKeyPem);
 	const sig = { alg: SIG_ALG, key_id: keyId, public_key: publicKeyHex, value, canon: CANON };

package/src/usage.ts

@@ -65,6 +65,25 @@ export function usageText(): string {
         （与 archive .sig 同构，公钥取 ~/.ojm/keys/<id>/private.pem，缺省 --id 推导）→ 写回
         <dir>。CDN 侧 resolveCdn/index 拉取索引时校验签名（篡改/不符即拒，G4 fail-closed）。
         --check 离线自检两份索引签名
+  ojm market setup [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]
+        把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由
+        api/config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin
+        must_change=1），会自动改密换全权 token 后再写入。
+  ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]
+        把方案包落进 cdn/：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz
+        → 包级 detached 签名 <name>-<version>.tgz.sig。**不碰索引**（D-1：索引由
+        build-index 扫描重建，多人发布才不会互相覆盖）。
+  ojm market build-index [--id <key>] [--key <pem>] [--check]
+        扫描 cdn/*.tgz、提取包内 manifest，全量重建 bundles.yaml + manifests.yaml 并签名。
+        结果只取决于目录内容：连续执行字节一致。
+  ojm market verify [--file <tgz>] [--rebuild-index]
+        离线验包（不起站点、不装、不要凭据）：sha256 完整性 / 包级 Ed25519 验签 /
+        索引验签 / manifest 结构（含 C2-31 desc===summary、各版本 0001 迁移一致）分列输出。
+        --rebuild-index 额外比对「扫描重建的索引」与盘上索引，检出落了包却没重建的漂移。
+        注意：结论恒带边界声明——校验通过只说明来源与完整性，不构成内容安全性背书。
+  ojm market trial [--fixture <name>@<version>] [--keep]
+        在一次性隔离站点（随机端口 + 一次性 DB/密钥/凭据/信任库/CDN）里跑完整安装，
+        跑完即毁；--keep 保留现场供排查。用于确认「这个包到底能不能装」，不污染你的工程。
   ojm test|exec|openapi|migrate|schema [args...]
         透传给 oj 同名子命令（自动补 -c <project>/api/config.yaml；其余参数原样转发）
         例：ojm test --anonymous / ojm migrate --db report / ojm openapi --check

package/src/vendor.ts

@@ -32,9 +32,11 @@ export const NPM_PKG = "@oj-bin/oj";
  * docs/superpowers/specs/2026-10-14-ojm-0.1.18-design.md）；**0.1.20 抬到 0.1.73**：
  * 平级 `.response` 出参声明位自 oj v0.1.72 起、`oj openapi` 的 `del`→`delete`
  * 操作键归一自 v0.1.73 起，`ojm api` 的 openapi 流水线以这两者为前提
- * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。
+ * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。**0.2.13 抬到 0.1.81**：
+ * 模板侧 `solution-perms.ts` 权限级联清理用 `startswith` 操作键（v0.1.81 补齐，
+ * 构造器迁移收尾），oj < 0.1.81 时卸载方案报 `unknown variant startswith` fail-closed。
  */
-export const MIN_OJ_VERSION = "0.1.73";
+export const MIN_OJ_VERSION = "0.1.81";
 
 /** 按段数值比较（字符串比较会把 0.1.9 判成大于 0.1.69）；非数字段按 0 处理 */
 export function isSupportedOjVersion(version: string): boolean {