@oj-module/cli 0.2.6 → 0.2.14

package/src/market/index-builder.ts

@@ -0,0 +1,76 @@
+/**
+ * Form B 索引聚合（T4）：把「一批已扫出的包」变成 bundles.yaml / manifests.yaml 的数据形状。
+ *
+ * 纯数据变换，不落 IO、不签名——IO 与签名归 `build-index.ts`。形状严格对齐安装侧的消费口径
+ * （`market/api.ts resolveCdn`）：`file` 必须逐字 `<name>-<version>.tgz`，否则安装侧 P2-11 会
+ * 判索引投毒直接 502。
+ */
+
+export interface IndexedPackage {
+	name: string
+	version: string
+	/** tgz 文件名（由 name+version 派生，逐字约束在此处一次成型） */
+	file: string
+	sha256: string
+	size: number
+	/** 包内 manifest（Form A），入 manifests.yaml 时补成 Form B */
+	manifest: Record<string, unknown>
+	/** 包级 detached 签名（`<tgz>.sig` 五字段）；缺则 Form B 不带 signature，安装侧按 sig_missing 拒装 */
+	signature?: Record<string, unknown>
+}
+
+export interface BuiltIndex {
+	bundles: { solutions: Array<Record<string, unknown>> }
+	manifests: Array<Record<string, unknown>>
+}
+
+export function buildIndexData(packages: IndexedPackage[]): BuiltIndex {
+	const byName = new Map<string, IndexedPackage[]>();
+	for (const pkg of packages) {
+		const list = byName.get(pkg.name) ?? [];
+		list.push(pkg);
+		byName.set(pkg.name, list);
+	}
+
+	const solutions: Array<Record<string, unknown>> = [];
+	const manifests: Array<Record<string, unknown>> = [];
+	for (const name of [...byName.keys()].sort()) {
+		const list = [...byName.get(name)!].sort((a, b) => compareVersion(a.version, b.version));
+		solutions.push({
+			name,
+			latest: list[list.length - 1]!.version,
+			versions: list.map(v => ({ file: `${v.name}-${v.version}.tgz`, sha256: v.sha256, size: v.size, version: v.version })),
+		});
+		for (const pkg of list) {
+			const file = `${name}-${pkg.version}.tgz`;
+			manifests.push({
+				...pkg.manifest,
+				name,
+				version: pkg.version,
+				archive: {
+					file,
+					sha256: pkg.sha256,
+					size: pkg.size,
+					...(pkg.signature === undefined ? {} : { signature: pkg.signature }),
+				},
+			});
+		}
+	}
+	return { bundles: { solutions }, manifests };
+}
+
+/** semver 数值比较（够用的子集：只比较 `x.y.z` 的数值段，非数字段按 0 计） */
+export function compareVersion(a: string, b: string): number {
+	const pa = numeric(a);
+	const pb = numeric(b);
+	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+		const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+		if (diff !== 0)
+			return diff;
+	}
+	return 0;
+}
+
+function numeric(version: string): number[] {
+	return version.replace(/^v/, "").split(".").map(part => Number.parseInt(part, 10) || 0);
+}

package/src/market/publish.ts

@@ -0,0 +1,156 @@
+/**
+ * `ojm market publish`（T3）：把方案包落进 CDN 目录。
+ *
+ * 职责收窄到「落包 + 包级签名」（D-1）——**不碰索引**，索引由 `build-index` 扫描重建。
+ * 由此多人可并发发布：每人只写 `<name>-<version>.tgz`（名字含名+版本，天然不撞），
+ * 没有共享可变索引文件，也就没有 TOCTOU。
+ *
+ * 签名原语一行都不重写：11 复用 `ojm sign` 的 `signCommand`（规范串 `<name>@<version>:<sha256>`，
+ * detached `.tgz.sig` 五字段，与 Form B archive.signature 同源同构）。
+ */
+
+import { createHash } from "node:crypto";
+import fs, { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { buildBundle } from "../bundle";
+import { createDeterministicTgz } from "../deterministic-tar";
+import { signCommand } from "../sign";
+import { resolveCdnLayout } from "./cdn-layout";
+import { buildFixturePackage, parseFixtureSpec } from "./fixture";
+
+export interface MarketPublishOptions {
+	/** 站点工程根（含 api/config.yaml 与 cdn/）；缺省 process.cwd() */
+	projectRoot?: string
+	/** `--fixture <name>@<version>`；缺省 demo-solution@0.1.0 */
+	fixture?: string
+	/** `--real <方案工程根>`：走 ojm build --bundle 真构建（替代 fixture） */
+	real?: string
+	/** 发布方 key_id（C2-37） */
+	id?: string
+	/** 私钥 PEM 文件路径（与 privateKeyPem 二选一） */
+	key?: string
+	/** 内存私钥 PEM（一次性/隔离场景，不落盘） */
+	privateKeyPem?: string
+	/** 落包后离线自检（verifyCanonical 复核包级签名） */
+	check?: boolean
+}
+
+export interface MarketPublishResult {
+	name: string
+	version: string
+	tgzPath: string
+	sigPath: string
+	sha256: string
+	size: number
+	canonical: string
+	keyId: string
+	publicKeyHex: string
+	fingerprint: string
+}
+
+export async function publishPackage(opts: MarketPublishOptions = {}): Promise<MarketPublishResult> {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const layout = resolveCdnLayout(projectRoot);
+	if (!fs.existsSync(layout.dir)) {
+		fs.mkdirSync(layout.dir, { recursive: true });
+		console.log(`[ojm] 已建立 CDN 目录 ${path.relative(projectRoot, layout.dir)}`);
+	}
+
+	const staging = mkdtempSync(path.join(os.tmpdir(), "ojm-market-publish-"));
+	try {
+		const { name, version, tgzPath, sha256, preExisted } = opts.real !== undefined
+			? await buildRealPackage(opts.real, staging, layout.dir)
+			: await buildFixture({ fixture: opts.fixture, staging, cdnDir: layout.dir });
+
+		// 原子性：tgz 已落盘而后续环节失败时，新包必须捡回来，不留半成品
+		const rollbackPackage = () => {
+			if (!preExisted)
+				rmSync(tgzPath, { force: true });
+		};
+
+		let signed: ReturnType<typeof signCommand>;
+		try {
+			signed = signCommand(tgzPath, { id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem, check: opts.check });
+		}
+		catch (error) {
+			rollbackPackage();
+			throw error;
+		}
+		if (signed.checkPassed === false) {
+			rollbackPackage();
+			throw new Error(`[ojm] 包级签名自检失败，已移除未签通的包：${tgzPath}`);
+		}
+		const size = fs.statSync(tgzPath).size;
+		console.log(`[ojm] 包已落 CDN → ${path.relative(projectRoot, tgzPath)}（${size} 字节）`);
+		console.log(`[ojm] 发布方 ${signed.keyId}；指纹 ${signed.fingerprint}`);
+		console.log("[ojm] 索引未重建：多人场景请由维护者跑 ojm market build-index");
+
+		return {
+			name,
+			version,
+			tgzPath,
+			sigPath: signed.sigPath,
+			sha256,
+			size,
+			canonical: signed.canonical,
+			keyId: signed.keyId,
+			publicKeyHex: signed.publicKeyHex,
+			fingerprint: signed.fingerprint,
+		};
+	}
+	finally {
+		rmSync(staging, { recursive: true, force: true });
+	}
+}
+
+/** fixture 路径：合成 → 确定性打包 → 与既有同名版本比对 */
+async function buildFixture(args: { fixture?: string, staging: string, cdnDir: string }): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
+	const spec = parseFixtureSpec(args.fixture);
+	const pkg = buildFixturePackage({ stagingDir: args.staging, name: spec.name, version: spec.version });
+	const tgzPath = path.join(args.cdnDir, `${spec.name}-${spec.version}.tgz`);
+	const before = captureExisting(tgzPath);
+
+	const sha256 = await createDeterministicTgz(pkg.dir, tgzPath);
+	assertNoByteConflict(tgzPath, before, spec);
+	return { name: spec.name, version: spec.version, tgzPath, sha256, preExisted: before.exists };
+}
+
+/** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录 */
+async function buildRealPackage(solutionRoot: string, staging: string, cdnDir: string): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
+	const built = await buildBundle(solutionRoot, { out: staging });
+	const tgzPath = path.join(cdnDir, `${built.name}-${built.version}.tgz`);
+	const before = captureExisting(tgzPath);
+
+	fs.copyFileSync(built.tgz, tgzPath);
+	assertNoByteConflict(tgzPath, before, { name: built.name, version: built.version });
+	return { name: built.name, version: built.version, tgzPath, sha256: built.sha256, preExisted: before.exists };
+}
+
+/** 落包前先记下同名文件的指纹（可能不存在） */
+function captureExisting(tgzPath: string): { exists: boolean, sha256: string } {
+	if (!fs.existsSync(tgzPath))
+		return { exists: false, sha256: "" };
+	const bytes = new Uint8Array(fs.readFileSync(tgzPath));
+	return { exists: true, sha256: createHash("sha256").update(bytes).digest("hex") };
+}
+
+/**
+ * 同 name@version 重发：字节一致即幂等；字节不一致是真正的冲突——
+ * 同一个版本号出现两份不同的包会毁掉内容寻址前提，必须升 version 重发。
+ */
+function assertNoByteConflict(tgzPath: string, before: { exists: boolean, sha256: string }, spec: { name: string, version: string }): void {
+	if (!before.exists)
+		return;
+	const bytes = new Uint8Array(fs.readFileSync(tgzPath));
+	const after = createHash("sha256").update(bytes).digest("hex");
+	if (after === before.sha256)
+		return;
+	throw new Error(
+		`[ojm] 包冲突：${spec.name}@${spec.version} 已存在且字节不一致（${before.sha256.slice(0, 12)} vs ${after.slice(0, 12)}）。\n`
+		+ "下一步：内容有变更请升 version 后重发（同一版本号只允许一份字节）；"
+		+ "确需覆盖请先删除 CDN 目录里的旧 tgz。",
+	);
+}

package/src/market/report.ts

@@ -0,0 +1,67 @@
+/**
+ * walkthrough 报告落盘 + 白黑名单脱敏（T12 收尾，设计 §3.6.3）。
+ *
+ * 白名单（可落盘）：key_id、公钥、指纹、task_id、AC 表、阶段结果、sha256——报告常规内容。
+ * 黑名单（禁落盘，脱敏兜底）：Bearer token、JWT、私钥 PEM、jwt_secret 值——正常路径本不该
+ * 进报告（凭据只在内存），此处是第二道防线：即便某条 detail 意外带了敏感串，落盘前也被掩码。
+ */
+
+import type { FailurePlaybookEntry } from "./failure-playbook";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+/** 黑名单模式（g 旗标，replace 全局掩码） */
+const BLACKLIST: Array<{ re: RegExp, mask: string }> = [
+	{ re: /Bearer\s+[\w.~-]+/g, mask: "Bearer ***" },
+	{ re: /eyJ[\w-]+\.[\w-]+\.[\w-]+/g, mask: "***" }, // JWT 三段形态
+	{ re: /-----BEGIN [^-]+-----[\s\S]*?-----END [^-]+-----/g, mask: "[redacted PEM]" },
+	{ re: /(jwt_secret\s*[:=]\s*)\S+/g, mask: "$1***" },
+];
+
+/** 报告文本过黑名单（幂等：已掩码文本二次过检不再变化） */
+export function sanitizeReportText(text: string): string {
+	let out = text;
+	for (const { re, mask } of BLACKLIST)
+		out = out.replace(re, mask);
+	return out;
+}
+
+export interface WalkthroughReportRow {
+	key: string
+	title: string
+	ok: boolean
+	detail: string
+}
+
+/** 渲染 AC 表 + 汇总行 + 失败文案表，脱敏后落 `logs/walkthrough-<ts>.md`；返回落盘路径 */
+export function writeWalkthroughReport(opts: { rows: WalkthroughReportRow[], port: number, playbook: FailurePlaybookEntry[], logDir?: string }): string {
+	const dir = opts.logDir ?? path.join(process.cwd(), "logs");
+	mkdirSync(dir, { recursive: true });
+	const ts = new Date().toISOString().replace(/[:.]/g, "-");
+	const file = path.join(dir, `walkthrough-${ts}.md`);
+	const pass = opts.rows.filter(r => r.ok).length;
+	const failed = opts.rows.length - pass;
+	const lines = [
+		"# ojm market walkthrough 报告",
+		"",
+		`- 时间：${new Date().toISOString()}`,
+		`- 隔离站点端口：${opts.port}`,
+		`- 汇总：${opts.rows.length} 项 —— ${pass} PASS / ${failed} FAIL`,
+		"",
+		"## AC 表",
+		"",
+		"| op | 结果 | 说明 |",
+		"|---|---|---|",
+		...opts.rows.map(r => `| ${r.key} | ${r.ok ? "PASS" : "FAIL"} | ${r.ok ? r.title : `${r.title}——${r.detail}`} |`),
+		"",
+		"## 失败路径人话文案表",
+		"",
+		"| 失败码 | 阶段 | 成因 | 下一步 |",
+		"|---|---|---|---|",
+		...opts.playbook.map(e => `| ${e.code} | ${e.stage} | ${e.cause} | ${e.next} |`),
+		"",
+	];
+	writeFileSync(file, sanitizeReportText(lines.join("\n")));
+	return file;
+}

package/src/market/scan.ts

@@ -0,0 +1,99 @@
+/**
+ * tgz 读端（T4）：gunzip + 手写 ustar 解析，只为了从包里取出内嵌 `manifest.yaml`。
+ *
+ * 为什么手写而不用第三方 tar 库：写端 `deterministic-tar.ts` 就是手写 ustar（注释给了理由——
+ * 跨平台 tar 方言会毁掉确定性），读端与它对称才可预期；且这里只需要「按路径取一个成员」，
+ * 引一个通用 tar 库属于杀鸡用牛刀。相比「另存一份 manifest 到包外」的做法，
+ * 包内 manifest 是单一真相——不存在旁路文件与包内容漂移的可能。
+ */
+
+import { Buffer } from "node:buffer";
+import { gunzipSync } from "node:zlib";
+import { parse as yamlParse } from "yaml";
+
+const BLOCK = 512;
+
+export interface ScannedEntry {
+	name: string
+	size: number
+	content: Buffer
+}
+
+/** 把 .tgz 解开为可读成员列表（无视 EOF 末尾的零块与补齐 bytes） */
+export function readTgz(bytes: Uint8Array): ScannedEntry[] {
+	let raw: Buffer;
+	try {
+		raw = gunzipSync(Buffer.from(bytes));
+	}
+	catch (error) {
+		throw new Error(`不是合法的 gzip 包：${(error as Error).message}`);
+	}
+	const out: ScannedEntry[] = [];
+	let offset = 0;
+	while (offset + BLOCK <= raw.length) {
+		const header = raw.subarray(offset, offset + BLOCK);
+		if (isZeroBlock(header))
+			break;
+		const size = readOctal(header, 124, 12);
+		const typeflag = String.fromCharCode(header[156]!);
+		const name = entryName(header);
+		offset += BLOCK;
+		if (typeflag === "0" || typeflag === "\0") {
+			const content = raw.subarray(offset, offset + size);
+			out.push({ name, size, content });
+		}
+		else if (typeflag !== "5") {
+			// 其余类型（链接/设备等）不该出现在本地 CDN 包里；跳过即可，不因此拒绝整个包
+		}
+		const pad = (BLOCK - (size % BLOCK)) % BLOCK;
+		offset += size + pad;
+	}
+	return out;
+}
+
+/**
+ * 取包内 manifest.yaml；找不到返回 null（调用方决定跳过还是报错）。
+ *
+ * 两种布局都认：直接以方案目录为根打的包（`manifest.yaml`）与外层再套一层
+ * `<name>-<version>/` 的包——写端 `createDeterministicTgz` 的成员路径是相对传入目录的，
+ * 传方案目录即前者；手 tar 打包常是后者。只认顶层那一份，不认 api 子目录下的其他 manifest。
+ */
+export function readEmbeddedManifest(bytes: Uint8Array): Record<string, unknown> | null {
+	const hit = readTgz(bytes).find(e => /^(?:[^/]+\/)?manifest\.yaml$/.test(e.name));
+	if (hit === undefined)
+		return null;
+	// manifest 是完整 YAML（含 api/web/routes 嵌套结构），必须走真解析器：
+	// 它是索引的唯一真相源，解析不准就等于给下游喂假索引。
+	return (yamlParse(hit.content.toString("utf-8")) ?? null) as Record<string, unknown> | null;
+}
+
+function isZeroBlock(block: Buffer): boolean {
+	for (const byte of block) {
+		if (byte !== 0)
+			return false;
+	}
+	return true;
+}
+
+/** name(100) + prefix(155) 复原完整路径（与写端 splitUstarName 对称） */
+function entryName(header: Buffer): string {
+	const name = cstring(header, 0, 100);
+	const prefix = cstring(header, 345, 155);
+	if (prefix === "")
+		return name;
+	return `${prefix}/${name}`;
+}
+
+function cstring(buf: Buffer, offset: number, length: number): string {
+	const slice = buf.subarray(offset, offset + length);
+	const end = slice.indexOf(0);
+	return slice.subarray(0, end === -1 ? length : end).toString("utf-8");
+}
+
+function readOctal(buf: Buffer, offset: number, length: number): number {
+	const text = cstring(buf, offset, length).trim();
+	if (text === "")
+		return 0;
+	const value = Number.parseInt(text, 8);
+	return Number.isNaN(value) ? 0 : value;
+}

package/src/market/setup.ts

@@ -0,0 +1,144 @@
+/**
+ * `ojm market setup`（T5）：把 `framework.market_cdn_url` 指向本地模拟 CDN。
+ *
+ * 两件容易踩的事都收在这一处：
+ * 1. **地址必须是绝对的**，且端口来自 config 的 `server.port`——dev 形态下 dev server（5174）
+ *    只会把 `/api` 反代给 oj 子进程，`/cdn/*` 会被静态层回落成 index.html（设计 §3.1.1）。
+ * 2. **首跑凭据悬挂**：seed admin `must_change=1`，登录拿的是限权 token，写不了 system 设置；
+ *    须先 `PUT /api/auth/password` 改密换全权 token（该端点是悬挂期唯一可用写端）。
+ */
+
+import { randomBytes } from "node:crypto";
+import process from "node:process";
+
+import { resolveSite } from "../site";
+import { resolveCdnLayout } from "./cdn-layout";
+
+export const MARKET_CDN_URL_SETTING = "framework.market_cdn_url";
+
+export interface SetupOptions {
+	projectRoot?: string
+	/** 站点地址（缺省取 OJM_URL 或 http://127.0.0.1:9778） */
+	url?: string
+	user?: string
+	pass?: string
+	/** 新口令；不给则随机生成并只在终端打印一次（不落盘、不进日志） */
+	newPass?: string
+	/** 测试注入；缺省全局 fetch */
+	fetchFn?: typeof fetch
+}
+
+export interface SetupResult {
+	siteUrl: string
+	cdnBaseUrl: string
+	/** 是否走了改密闭环（must_change 悬挂期） */
+	changedPassword: boolean
+	/** 随机生成的新口令（仅当未显式给 newPass 时才有值） */
+	generatedPassword?: string
+}
+
+export async function setupMarketUrl(opts: SetupOptions = {}): Promise<SetupResult> {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const layout = resolveCdnLayout(projectRoot);
+	const site = resolveSite({ url: opts.url, user: opts.user, pass: opts.pass });
+	const fetchFn = opts.fetchFn ?? fetch;
+
+	const token = await obtainToken(fetchFn, site.base, site.user, site.pass, opts.newPass, projectRoot);
+
+	await putSetting(fetchFn, site.base, token.value, MARKET_CDN_URL_SETTING, layout.baseUrl);
+	console.log(`[ojm] 市场地址已设置：${layout.baseUrl}`);
+	console.log(`[ojm] 市场页刷新后即可看到 ${pathOf(layout.dir)} 里的方案卡片`);
+	return {
+		siteUrl: site.base,
+		cdnBaseUrl: layout.baseUrl,
+		changedPassword: token.changedPassword,
+		generatedPassword: token.generatedPassword,
+	};
+}
+
+/** 登录并在必要时走改密闭环，返回可用 token */
+async function obtainToken(fetchFn: typeof fetch, base: string, user: string, pass: string, newPass: string | undefined, projectRoot: string): Promise<{ value: string, changedPassword: boolean, generatedPassword?: string }> {
+	let login: { access_token?: string, restricted?: boolean };
+	try {
+		login = await postJson(fetchFn, `${base}/api/auth/login`, { username: user, password: pass });
+	}
+	catch (error) {
+		throw new Error(
+			`[ojm] 连不上站点 ${base}：${(error as Error).message}\n`
+			+ "下一步：先起站点（ojm dev），再跑本命令。",
+		);
+	}
+	const token = String(login.access_token ?? "");
+	if (token === "")
+		throw new Error("[ojm] 登录响应缺 access_token——核对站点版本与账号");
+	if (login.restricted !== true)
+		return { value: token, changedPassword: false };
+
+	// must_change 悬挂期：限权 token 写不了 system 设置，先改密换全权 token
+	const next = newPass ?? randomBytes(9).toString("base64url");
+	const bundle = await putJson(fetchFn, `${base}/api/auth/password`, token, { old_password: pass, new_password: next });
+	const full = String(bundle.access_token ?? "");
+	if (full === "") {
+		throw new Error(
+			"[ojm] 改密后未取得全权 token——账号仍处于 must_change 悬挂期。\n"
+			+ "下一步：用浏览器登录一次完成改密，或换一个已完成改密的超管账号重试。",
+		);
+	}
+	console.log(`[ojm] 账号处于首次改密期，已改密并换取全权 token（新口令：${newPass === undefined ? next : "<由 --new-pass 指定>"}）`);
+	if (newPass === undefined)
+		console.log("[ojm] 该口令仅此一次显示，不入日志不入盘——请自行留存");
+	void projectRoot;
+	return { value: full, changedPassword: true, generatedPassword: newPass === undefined ? next : undefined };
+}
+
+async function putSetting(fetchFn: typeof fetch, base: string, token: string, key: string, value: string): Promise<void> {
+	try {
+		await putJson(fetchFn, `${base}/api/system/settings`, token, { key, value });
+	}
+	catch (error) {
+		const message = (error as Error).message;
+		throw new Error(
+			`[ojm] 写入系统设置 ${key} 失败：${message}\n`
+			+ "下一步：确认账号是系统管理员（非仅超管模块权限），或用浏览器在「系统设置」里手动填写同一地址。",
+		);
+	}
+}
+
+async function postJson(fetchFn: typeof fetch, url: string, body: unknown): Promise<Record<string, unknown>> {
+	const res = await fetchFn(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body),
+	});
+	return (await unwrap(res)) as Record<string, unknown>;
+}
+
+async function putJson(fetchFn: typeof fetch, url: string, token: string, body: unknown): Promise<Record<string, unknown>> {
+	const res = await fetchFn(url, {
+		method: "PUT",
+		headers: { "content-type": "application/json", "authorization": `Bearer ${token}` },
+		body: JSON.stringify(body),
+	});
+	return (await unwrap(res)) as Record<string, unknown>;
+}
+
+/** oj 信封解包（{code,msg,data}，code=0 为成） */
+async function unwrap(res: Response): Promise<unknown> {
+	const text = await res.text();
+	let env: { code?: number, msg?: string, data?: unknown } | null = null;
+	try {
+		env = JSON.parse(text) as { code?: number, msg?: string, data?: unknown };
+	}
+	catch {
+		throw new Error(`[ojm] 站点响应不可解析（HTTP ${res.status}）：${text.slice(0, 200)}`);
+	}
+	if (env === null || typeof env.code !== "number")
+		throw new Error(`[ojm] 站点响应缺 code 字段：${text.slice(0, 200)}`);
+	if (env.code !== 0)
+		throw new Error(`code=${env.code}：${env.msg ?? "未知错误"}`);
+	return env.data;
+}
+
+function pathOf(dir: string): string {
+	return dir;
+}

package/src/market/trial.ts

@@ -0,0 +1,121 @@
+/**
+ * `ojm market trial`（T9）：在一次性隔离站点里跑完整安装，验证「这个包能不能装」。
+ *
+ * 为什么需要它：开发态装不了自己（见 devkit 教学文档 §2），而真站点装了要清场、且首次会污染
+ * 信任库。trial 给你一个「别人家的站点」：随机端口 + 一次性 DB + 一次性发布方密钥 + 隔离
+ * CDN，跑完即毁（--keep 保留现场）。
+ *
+ * 复用纪律：站点生命周期全在 `bootstrap.ts`，站点调用四件套全在 `site.ts`——本文件只编排，
+ * 不重写登录/轮询/取证。
+ */
+
+import type { TaskRecord } from "../site";
+
+import process from "node:process";
+import { callApi, login, pollTask } from "../site";
+import { bootstrapIsolatedSite } from "./bootstrap";
+import { parseFixtureSpec } from "./fixture";
+import { setupMarketUrl } from "./setup";
+
+export interface TrialOptions {
+	/** 源工程（提供 bin/oj 与 cli 模板）；缺省 process.cwd() */
+	projectRoot?: string
+	/** 待试装的方案；缺省 demo-solution@0.1.0 */
+	fixture?: string
+	/** 保留隔离现场（排查用） */
+	keep?: boolean
+	/** 首败即停（默认也停——单次试装没有后续步骤可续） */
+	strict?: boolean
+	onLog?: (line: string) => void
+}
+
+export interface TrialResult {
+	ok: boolean
+	/** 隔离站点端口（keep 时供人工访问） */
+	port: number
+	root: string
+	stages: TaskRecord["stages"]
+	message: string
+}
+
+export async function trialInstall(opts: TrialOptions = {}): Promise<TrialResult> {
+	const log = opts.onLog ?? ((line: string) => console.log(line));
+	const spec = parseFixtureSpec(opts.fixture);
+	log(`[ojm] 试装 ${spec.name}@${spec.version}（隔离站点，跑完即毁）`);
+
+	const site = await bootstrapIsolatedSite({
+		projectRoot: opts.projectRoot,
+		fixture: opts.fixture,
+		keep: opts.keep,
+		onLog: log,
+	});
+
+	try {
+		// 1) 打开市场地址：隔离库是全新 seed，首登必然处于改密悬挂期 → setup 顺带完成改密
+		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);
+
+		// 2) 首次安装：预期停在 needs_trust（发布方是本次临时生成的身份）
+		let task = await installOnce(site.baseUrl, token, spec.name, spec.version);
+		if (task.status === "needs_trust") {
+			const fingerprint = task.trust?.fingerprint ?? "";
+			log(`[ojm] 待信任发布方 ${task.trust?.key_id ?? "?"}，指纹 ${fingerprint.slice(0, 16)}…（隔离站点，自动确认）`);
+			await callApi(fetch, site.baseUrl, token, "POST", "/api/_platform/market/trust", { task_id: task.id });
+			task = await installOnce(site.baseUrl, token, spec.name, spec.version);
+		}
+
+		const ok = task.status === "done";
+		log(ok
+			? `[ojm] 试装通过：${spec.name}@${spec.version} 在隔离站点装成（${task.stages.length} 段全 ok）`
+			: `[ojm] 试装失败：status=${task.status} stage=${task.stage ?? "?"}——${task.message}`);
+		return { ok, port: site.port, root: site.root, stages: task.stages, message: task.message };
+	}
+	finally {
+		await site.cleanup();
+	}
+}
+
+/** 一次安装 + 轮询到终态 */
+async function installOnce(base: string, token: string, name: string, version: string): Promise<TaskRecord> {
+	// 站点返回 {task_id}（安装同步跑完后回填）；mock 兼容 id 形态
+	const started = await callApi<{ task_id?: string, id?: string }>(fetch, base, token, "POST", "/api/_platform/market/install", {
+		name,
+		version,
+		source: "cdn",
+	});
+	const taskId = String(started.task_id ?? started.id ?? "");
+	if (taskId === "")
+		throw new Error("[ojm] 安装接口未返回 task id——站点版本与 ojm 不匹配？");
+	return pollTask(fetch, base, token, taskId, { interval0: 500, intervalMax: 2000, timeoutMs: 120_000 });
+}
+
+/** 进程入口：`ojm market trial [--fixture name@ver] [--keep]` */
+export async function trialCommand(argv: string[]): Promise<void> {
+	const opts: TrialOptions = {};
+	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 === "--fixture") {
+			opts.fixture = argv[i + 1] ?? "";
+			i++;
+		}
+	}
+	const result = await trialInstall(opts);
+	if (!result.ok)
+		process.exitCode = 1;
+}