@oj-module/cli 0.2.8 → 0.2.14

package/src/market/bootstrap.ts

@@ -0,0 +1,255 @@
+/**
+ * 隔离站点自举（T8）：`ojm market trial` / `walkthrough` 的地基。
+ *
+ * 目标：给你一个「别人家的站点」来试装——不碰你的工程、DB、信任库、端口。
+ * 隔离六项各有落点：
+ * - **端口**：临时根 config 写入空闲端口（startOj 从 config 读端口，故派生 config 是唯一真相）；
+ * - **DB**：oj 的 sqlite 按 config 所在目录解析，临时根内自然隔离（dbPath 暴露供断言）；
+ * - **密钥**：发布方 Ed25519 由公开 seed 经 SHA-256 派生（照 fixtures/sig 夹具手法），
+ *   私钥只在内存，临时根内无 PEM（站点自己的开发证书走 mintDevCert，属站点身份）；
+ * - **凭据**：隔离库是全新 seed，admin 口令即种子默认值，与真站点凭据零交集；
+ * - **信任库**：`.solutions/trusted-keys.yaml` 只在安装器写入时生成，全新根内不存在；
+ * - **CDN 目录**：临时根内 cdn/，由本模块自建（publish + build-index 直落）。
+ *
+ * 提库来源：`scripts/verify-solution-smoke/bootstrap-host.mjs`（同手法，脚本形态）；
+ * 本文件是它的 cli 内嵌版（计划 §9.1：phase1 从这里提库而非重写）。
+ */
+
+import type { OjProcess } from "../oj";
+import { Buffer } from "node:buffer";
+import { createHash, createPrivateKey, randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { buildBackend } from "../build";
+import { exportRawPublicKeyHex, fingerprintOfPublicKey } from "../lifecycle/sign";
+import { startOj } from "../oj";
+import { mintDevCert } from "../oj-cert";
+import { resolveOjBin } from "../vendor";
+import { buildIndex } from "./build-index";
+import { parseFixtureSpec } from "./fixture";
+import { publishPackage } from "./publish";
+
+/** 种子管理员（隔离库全新 seed；与 templates seed.sql 一致） */
+const SEED_ADMIN_USER = "admin";
+const SEED_ADMIN_PASS = "123456";
+
+/** Ed25519 PKCS#8 DER 前缀（RFC 8410 固定头；与 gen-signed-fixtures.mjs 同一手法） */
+const ED25519_PKCS8_PREFIX = "302e020100300506032b657004220420";
+
+export interface IsolatedPublisher {
+	keyId: string
+	privateKeyPem: string
+	publicKeyHex: string
+	fingerprint: string
+}
+
+export interface IsolatedSite {
+	/** 临时根（含 api/ bin/ cdn/） */
+	root: string
+	port: number
+	baseUrl: string
+	apiBase: string
+	cdnDir: string
+	cdnBaseUrl: string
+	/** sqlite 库路径（config 目录相对解析；断言隔离用） */
+	dbPath: string
+	/** 一次性发布方身份（私钥只在内存） */
+	publisher: IsolatedPublisher
+	/** 隔离库的种子管理员 */
+	admin: { user: string, pass: string }
+	/** 销毁隔离根与 oj 进程；幂等 */
+	cleanup: () => Promise<void>
+	/** 销毁清单（--keep 时给人看这里到底有什么） */
+	teardownReport: () => string[]
+}
+
+export interface BootstrapOptions {
+	/** 源工程（提供 bin/oj 与 cli 内置模板）；缺省 process.cwd() */
+	projectRoot?: string
+	/** 落进隔离 CDN 的 fixture；缺省 demo-solution@0.1.0 */
+	fixture?: string
+	/** 保留现场（cleanup 不删根，只打清单） */
+	keep?: boolean
+	/** 测试注入；缺省真 startOj */
+	starter?: (configPath: string, base: string, apiSrc: string) => OjProcess
+	/** 日志旁路（测试收集用） */
+	onLog?: (line: string) => void
+}
+
+export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promise<IsolatedSite> {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const log = (line: string) => (opts.onLog ?? ((l: string) => console.log(l)))(line);
+
+	const ojBin = resolveOjBin(projectRoot);
+	if (!existsSync(ojBin)) {
+		throw new Error(
+			`[ojm] 源工程未安装 oj 二进制：${ojBin}\n`
+			+ "下一步：在源工程目录跑一次 `ojm vendor`（经 npm 包 @oj-bin/oj 下载），再重试。",
+		);
+	}
+
+	const root = mkdtempSync(path.join(tmpdir(), "ojm-trial-"));
+	const apiDir = path.join(root, "api");
+	const configPath = path.join(apiDir, "config.yaml");
+	const cdnDir = path.join(root, "cdn");
+	const dbPath = path.join(apiDir, "db.sqlite");
+
+	// 1) api 树 + config（模板由 cli 包内置，init 同源；与 cli→templates 依赖红线不冲突——那是运行期文件而非 import）
+	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+	const templateApi = path.join(cliRoot, "templates", "api");
+	if (!existsSync(path.join(templateApi, "config.yaml"))) {
+		throw new Error(`[ojm] cli 内置模板缺失：${templateApi}（@oj-module/cli 安装不完整？）`);
+	}
+	cpSync(path.join(templateApi, "src"), path.join(apiDir, "src"), { recursive: true });
+	writeFileSync(configPath, readFileSync(path.join(templateApi, "config.yaml"), "utf-8"), "utf-8");
+
+	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj 解析；plugins 让 auth 插件可用）
+	mkdirSync(path.join(root, "bin"), { recursive: true });
+	cpSync(ojBin, path.join(root, "bin", "oj"), { recursive: true });
+	const versionMarker = path.join(projectRoot, "bin", ".oj-version");
+	if (existsSync(versionMarker)) {
+		cpSync(versionMarker, path.join(root, "bin", ".oj-version"));
+	}
+	const pluginsDir = path.join(projectRoot, "bin", "plugins");
+	if (existsSync(pluginsDir)) {
+		cpSync(pluginsDir, path.join(root, "bin", "plugins"), { recursive: true });
+	}
+
+	// 3) 派生 config：空闲端口 / 随机 jwt / CDN 挂载指绝对路径 / fs 段
+	const port = await freePort();
+	let cfg = readFileSync(configPath, "utf-8");
+	cfg = cfg.replace("port: 9778", `port: ${port}`);
+	if (!cfg.includes(`port: ${port}`)) {
+		throw new Error(`[ojm] 模板 config 未含 端口: 9778 字面（模板结构变了？）：${configPath}`);
+	}
+	cfg = cfg.replace("__JWT_SECRET__", randomBytes(32).toString("hex"));
+	// 最小 SPA 挂载：真实部署里前端路由（深检会逐条探活）由站点壳承接；没有 web 挂载时
+	// 这些路径一律 404，深检会判成 anomaly。这里放一个 index.html 就够（不构建前端）。
+	// 挂在 /cdn 之后（前缀特异性匹配，顺序无关，仅为可读）。
+	const siteDir = path.join(root, "site");
+	mkdirSync(siteDir, { recursive: true });
+	writeFileSync(path.join(siteDir, "index.html"), "<!doctype html><html><body>ojm trial site</body></html>\n", "utf-8");
+	cfg = cfg.replace("web: ../cdn", `web: ${cdnDir}\n  - prefix: /\n    web: ${siteDir}\n    spa: true`);
+	// 安装目标恒为 release 部署：装好的模块落在 api/dist，dev 形态（--api-path src）发现不了。
+	// 故隔离站点以 dist 起站，platform.root 同步改写（oj 校验 root 必须是生效的 api 挂载目录）。
+	cfg = cfg.replace("  root: src", "  root: dist");
+	// auth 守卫在装配期读 anonymous_paths，安装器注册的新匿名端点要重启才生效（首次安装 smoke 会 401）。
+	// 隔离站点直接预置被测方案的探活路径——与 scripts/verify-solution-smoke/bootstrap-host.mjs 同手法，
+	// 让 trial 验的是安装机制本身，而不是重启时序。
+	const healthPath = `/${parseFixtureSpec(opts.fixture).name}/ping`;
+	if (!cfg.includes(`- ${healthPath}`))
+		cfg = cfg.replace(/^(\s*)- \/system\/login-methods$/m, `$1- /system/login-methods\n$1- ${healthPath}`);
+	// fs 段：模板自 0.2.13 起已自带（安装器落盘面）；旧模板没有时才补，避免重复键
+	if (!/^fs:/m.test(cfg))
+		cfg = `${cfg.trimEnd()}\nfs:\n  root: .\n  readonly: false\n`;
+	writeFileSync(configPath, cfg, "utf-8");
+
+	// 4) 站点开发证书（oj serve 无绕过开关；mintDevCert 落 api/config 三件套）
+	await mintDevCert(path.join(apiDir, "config"));
+
+	// 5) 一次性发布方身份：seed 派生，私钥只在内存
+	const keyId = "trial.publisher";
+	const publisher = derivePublisherKey(randomBytes(16).toString("hex"));
+
+	// 6) 隔离 CDN：落 fixture 包 + 重建索引（publish/buildIndex 直落临时根）
+	mkdirSync(cdnDir, { recursive: true });
+	await publishPackage({ projectRoot: root, fixture: opts.fixture, id: keyId, privateKeyPem: publisher.privateKeyPem });
+	await buildIndex({ projectRoot: root, id: keyId, privateKeyPem: publisher.privateKeyPem });
+
+	// 7) 后端构建（api/dist + versions.json；安装与 reloading 都依赖它）
+	await buildBackend(root);
+
+	// 7b) 起 oj（starter 注入供测试）；ready 失败即整体作废，不留孤儿
+	const starter = opts.starter ?? ((cfgPath: string, base: string, apiSrc: string) => startOj(cfgPath, base, apiSrc));
+	let oj: OjProcess;
+	try {
+		oj = starter(configPath, "/api", path.join(apiDir, "dist"));
+		await oj.ready;
+	}
+	catch (error) {
+		rmSync(root, { recursive: true, force: true });
+		throw error;
+	}
+	log(`[ojm] 隔离站点就绪：http://127.0.0.1:${port}（根 ${root}）`);
+
+	// 8) cleanup：停进程 → 按 keep 决定删不删根 → 摘信号；全程幂等
+	let done = false;
+	let cleanup: () => Promise<void>;
+	const onSignal = () => {
+		void cleanup();
+	};
+	cleanup = async () => {
+		if (done) {
+			return;
+		}
+		done = true;
+		process.off("SIGINT", onSignal);
+		process.off("SIGTERM", onSignal);
+		await oj.stop().catch(() => {});
+		if (opts.keep === true) {
+			log(`[ojm] --keep：隔离根保留在 ${root}（内容见销毁清单）`);
+			return;
+		}
+		rmSync(root, { recursive: true, force: true });
+		log("[ojm] 隔离站点已销毁");
+	};
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+
+	return {
+		root,
+		port,
+		baseUrl: `http://127.0.0.1:${port}`,
+		apiBase: "/api",
+		cdnDir,
+		cdnBaseUrl: `http://127.0.0.1:${port}/cdn`,
+		dbPath,
+		publisher: { keyId, privateKeyPem: publisher.privateKeyPem, publicKeyHex: publisher.publicKeyHex, fingerprint: fingerprintOfPublicKey(publisher.publicKeyHex) },
+		admin: { user: SEED_ADMIN_USER, pass: SEED_ADMIN_PASS },
+		cleanup,
+		teardownReport: () => teardownReport(root, port),
+	};
+}
+
+/**
+ * seed 派生一次性 Ed25519 身份（照 fixtures/sig 夹具手法：公开 seed → SHA-256 → PKCS#8 DER）。
+ * 私钥只在内存；label 每次随机，故每次 trial 都是不同身份（不会与任何既有信任库条目撞）。
+ * 导出供 walkthrough 的 neg-stranger op 派生「未登记 key」（DRY：不重写派生手法）。
+ */
+export function derivePublisherKey(label: string): { privateKeyPem: string, publicKeyHex: string } {
+	const seed = createHash("sha256").update(`ojm-trial-publisher:${label}`).digest();
+	const der = Buffer.concat([Buffer.from(ED25519_PKCS8_PREFIX, "hex"), seed]);
+	const key = createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+	const privateKeyPem = key.export({ type: "pkcs8", format: "pem" }).toString();
+	return { privateKeyPem, publicKeyHex: exportRawPublicKeyHex(privateKeyPem) };
+}
+/** 空闲端口：listen(0) 取端口后立刻归还（本地一次性使用，竞态可接受） */
+function freePort(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const server = net.createServer();
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			const port = typeof address === "object" && address !== null ? address.port : 0;
+			server.close(() => resolve(port));
+		});
+	});
+}
+
+/** 销毁清单：--keep 时告诉人这里到底有什么、怎么手动清 */
+function teardownReport(root: string, port: number): string[] {
+	const lines = [
+		`隔离根：${root}`,
+		"  api/    站点树（src + config.yaml + config/ 证书 + db.sqlite）",
+		"  bin/    oj 二进制与插件（拷贝自源工程）",
+		"  cdn/    隔离 CDN（fixture 包 + 两份索引 + 签名）",
+		`监听端口：127.0.0.1:${port}（进程已停）`,
+		`手动清理：rm -rf ${root}`,
+	];
+	return lines;
+}

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;
+}