@oj-module/cli 0.2.8 → 0.2.14

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.8",
-  "@oj-module/runtime/contract": "0.2.8",
-  "@oj-module/runtime/contract/errors": "0.2.8",
+  "@oj-module/runtime": "0.2.14",
+  "@oj-module/runtime/contract": "0.2.14",
+  "@oj-module/runtime/contract/errors": "0.2.14",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/build-backend.test.ts

@@ -0,0 +1,64 @@
+// buildBackend spec：宿主 versions.json 双落点（方案安装的 C2-09 前置）。
+//
+// 安装器按 B-11 布局读 `<api>/dist/versions.json`（与 manifests.yaml 同层）做 peerRuntime
+// 强制比对；而站点壳的 versions.json 落在 web/dist。两者不同源时，新工程 `ojm build`
+// 完仍会在 preflight 被 C2-09 拒装——这条用例钉住「同源双写」，防止回归。
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { buildBackend } from "../build";
+
+/**
+ * 假 oj 二进制：只需成功退出——本 spec 验的是 buildBackend 在 oj build 之后的收尾动作
+ * （versions.json 同源落地），oj build 自身的产物由用例预先放好模拟。
+ */
+function fakeOj(projectRoot: string): void {
+	mkdirSync(join(projectRoot, "bin"), { recursive: true });
+	const bin = join(projectRoot, "bin", "oj");
+	writeFileSync(bin, "#!/bin/sh\nexit 0\n");
+	chmodSync(bin, 0o755);
+}
+
+function newProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-"));
+	mkdirSync(join(root, "api", "src", "demo"), { recursive: true });
+	writeFileSync(join(root, "api", "src", "demo", "manifest.yaml"), "name: demo\nversion: 0.1.0\n", "utf-8");
+	writeFileSync(join(root, "api", "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+	// 模拟 oj build 已产出的 manifests.yaml（验证收尾动作不破坏既有产物）
+	mkdirSync(join(root, "api", "dist"), { recursive: true });
+	writeFileSync(join(root, "api", "dist", "manifests.yaml"), "demo: 0.1.0\n", "utf-8");
+	fakeOj(root);
+	return root;
+}
+
+describe("given 宿主工程有 api/src When ojm build 后端", () => {
+	it("then api/dist/versions.json 与 shell-dist 同源落地（安装器 C2-09 前置）", async () => {
+		const root = newProject();
+
+		await buildBackend(root);
+
+		const hostVersions = join(root, "api", "dist", "versions.json");
+		expect(existsSync(hostVersions)).toBe(true);
+		const parsed = JSON.parse(readFileSync(hostVersions, "utf-8")) as Record<string, string>;
+		expect(typeof parsed["@oj-module/runtime"]).toBe("string");
+	});
+
+	it("then 既有 oj build 产物不被覆盖（manifests.yaml 原样保留）", async () => {
+		const root = newProject();
+
+		await buildBackend(root);
+
+		expect(readFileSync(join(root, "api", "dist", "manifests.yaml"), "utf-8")).toBe("demo: 0.1.0\n");
+	});
+});
+
+describe("given 纯前端工程（无 api/src）When ojm build 后端", () => {
+	it("then 跳过构建、不产出 api/dist", async () => {
+		const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-fe-"));
+
+		expect(await buildBackend(root)).toBe(false);
+		expect(existsSync(join(root, "api", "dist"))).toBe(false);
+	});
+});

package/src/__tests__/versions.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { hostArtifactFreshnessError } from "../versions";
+
+describe("hostArtifactFreshnessError（源码形态宿主产物过期守卫）", () => {
+	it("版本一致 → 通过", () => {
+		expect(hostArtifactFreshnessError("0.2.11", "0.2.11")).toBeUndefined();
+	});
+
+	it("任一侧缺失 → 跳过守卫", () => {
+		expect(hostArtifactFreshnessError(undefined, "0.2.11")).toBeUndefined();
+		expect(hostArtifactFreshnessError("0.2.11", undefined)).toBeUndefined();
+	});
+
+	it("宿主产物落后于 workspace runtime → 报真因并指向 build:shell", () => {
+		const err = hostArtifactFreshnessError("0.2.10", "0.2.11");
+		expect(err).toContain("shell-dist/versions.json）过期");
+		expect(err).toContain("0.2.10");
+		expect(err).toContain("0.2.11");
+		expect(err).toContain("build:shell");
+	});
+
+	it("宿主产物领先（跨仓消费旧版 runtime）→ 同样拦截", () => {
+		expect(hostArtifactFreshnessError("0.2.12", "0.2.11")).toContain("过期");
+	});
+});

package/src/build.ts

@@ -511,6 +511,15 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	//      SyntaxError: Invalid left-hand side in assignment（端点 500）。
 	// 0.1.32 / 0.1.50 均复现。产物体积换正确性，等上游修好再撤这个旗标。
 	execFileSync(oj, ["build", ...configArgs, "-d", apiSrc, "-o", apiDist, "--no-minify"], { stdio: "inherit" });
+	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 web/dist（mergeShellSite），
+	// 而方案安装器读的是 `<api>/dist/versions.json`（B-11：与 manifests.yaml 同层，用于
+	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
+	// preflight 直接 C2-09 fail-closed「无法读取宿主 runtime 版本」。
+	const versionsSrc = path.join(resolveShellDist(), "versions.json");
+	if (fs.existsSync(versionsSrc)) {
+		fs.mkdirSync(apiDist, { recursive: true });
+		fs.copyFileSync(versionsSrc, path.join(apiDist, "versions.json"));
+	}
 	return true;
 }
 

package/src/bundle.ts

@@ -116,8 +116,14 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 	}
 }
 
-/** C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version/desc 与 bundle 级逐一相等（oj 启动强校验同源） */
-function checkModuleManifest(built: string, name: string, version: string, summary: string): string[] {
+/**
+ * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
+ * （oj 启动强校验同源）。
+ *
+ * 变更（2026-10-21）：`desc === summary` 的等值要求已移除（与安装侧 extract.ts 同步）——
+ * 那是构建期映射的产物而不是安全边界，保留它会让 desc 与 summary 一字之差的包直接装不上。
+ */
+function checkModuleManifest(built: string, name: string, version: string, _summary: string): string[] {
 	const p = path.join(built, "manifest.yaml");
 	let doc: unknown;
 	try {
@@ -137,9 +143,6 @@ function checkModuleManifest(built: string, name: string, version: string, summa
 	if (mm.version !== version) {
 		out.push(`模块级 version「${String(mm.version)}」必须 === bundle version「${version}」`);
 	}
-	if (mm.desc !== summary) {
-		out.push(`模块级 desc「${String(mm.desc)}」必须 === bundle summary「${summary}」（安装器写 desc 即取 summary）`);
-	}
 	return out;
 }
 

package/src/contract/__tests__/market-client.integration.test.ts

@@ -1,4 +1,6 @@
-import type { ScopedRequestLike } from "../../../templates/web/src/_platform/__client/api";
+// ScopedRequestLike 真源在 runtime contract（生成物 __client/api.ts 也从这里 import，
+// 自身不再 re-export——旧写法 type import 自 __client 会在再生后 TS2305）。
+import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
 
 // 集成回归：真实 httpMarketClient（统一后委托 ojm 生成 client）的委托行为。
 // 经 bindRequest 注入 mock request，验证每条 MarketClient 方法 → 正确 URL/body/query + 返回形状；
@@ -43,9 +45,8 @@ function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }
 		calls.push({ method, url, opts });
 		const r = responder({ method, url, opts });
 		if (r.status && r.status >= 400) {
-			const err: { response?: { status?: number } } = new Error(`HTTP ${r.status}`);
-			err.response = { status: r.status };
-			throw err;
+			// ky 形态：HTTPError 携带 response.status（httpMarketClient.isUnconfigured 依赖它）
+			throw Object.assign(new Error(`HTTP ${r.status}`), { response: { status: r.status } });
 		}
 		return { json: () => Promise.resolve({ code: 0, data: r.data ?? null }) };
 	};
@@ -61,14 +62,12 @@ function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }
 }
 
 // 让 index() 直连的 request 与生成 client 的 bindRequest 指向同一 mock，行为一致。
+// 桥接：占位方法零参签名 ↔ ScopedRequestLike 真实签名，经 any 双向打通（测试桩，无运行时差异）。
 function useMock(m: ReturnType<typeof mockRequest>) {
 	bindRequest(m.req);
-	requestImpl.get = m.req.get;
-	requestImpl.post = m.req.post;
-	requestImpl.put = m.req.put;
-	requestImpl.delete = m.req.delete;
-	requestImpl.patch = m.req.patch;
-	requestImpl.head = m.req.head;
+	const req = m.req as unknown as Record<keyof typeof requestImpl, () => never>;
+	for (const k of Object.keys(requestImpl) as Array<keyof typeof requestImpl>)
+		requestImpl[k] = req[k];
 }
 
 describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
@@ -101,6 +100,10 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 		useMock(mock);
 		const r = await httpMarketClient.index();
 		expect(r).toEqual([]);
+		// 503 是配置态而非故障：silentError 抑制全局 toast + retry:0 不重试（原
+		// market-client-unconfigured 用例的断言并入此处——工厂形态退役后唯一活口）
+		expect(mock.calls).toHaveLength(1);
+		expect(mock.calls[0].opts).toMatchObject({ silentError: true, retry: 0 });
 	});
 
 	it("install(input) → POST _platform/market/install，body 含 name/version/source", async () => {

package/src/index.ts

@@ -161,6 +161,12 @@ async function main() {
 			publishCommand(positionals[0] ?? "", { id, key, check });
 			break;
 		}
+		case "market": {
+			// 本地模拟 CDN 与市场链路（setup / publish / build-index）
+			const { runMarket } = await import("./market/command");
+			await runMarket(process.argv.slice(3));
+			break;
+		}
 		default: {
 			if (command && OJ_PASSTHROUGH.has(command)) {
 				const { runOjSubcommand } = await import("./oj-cmd");

package/src/init.ts

@@ -98,6 +98,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		fs.mkdirSync(skillDir, { recursive: true });
 		for (const name of ["SKILL.md", "api-manual.md"])
 			copyIfAbsent(path.join(devkit, name), path.join(skillDir, name), report);
+		// v0.1.82 起 devkit 新增两份专题指南（api-manual/SKILL 均引用它们）：
+		// SQL 构造器能力矩阵/方言差异、oj test L1 测试指南。它们是**增量文档**、
+		// 不影响 ojm 运行，故「有则拷、无则记跳过」——bin/devkit 来自用户本地
+		// oj 版本（MIN_OJ_VERSION 只钉到 0.1.73），旧版 devkit 没有这两个文件，
+		// 为两份文档把整个 init 打挂不值当（用户升 oj 后重跑 init 即补上）。
+		for (const name of ["sql-builder-guide.md", "oj-test-guide.md"])
+			copyIfPresent(path.join(devkit, name), path.join(skillDir, name), report);
 		copyIfAbsent(path.join(devkit, "global.d.ts"), path.join(destDir, "global.d.ts"), report);
 	}
 	else {
@@ -367,6 +374,21 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	report.created.push(path.relative(process.cwd(), dest) || path.basename(dest));
 }
 
+/**
+ * 同 copyIfAbsent，但**源缺失**时记一条跳过而非抛错。
+ *
+ * 用于从 bin/devkit 拷第三方版本化内容（两份专题指南）：devkit 随用户本地 oj
+ * 版本而变，旧版没有新文件属正常版本 skew，不是安装包损坏——缺了只少份文档，
+ * 不该让 init 失败。源在而目标已存在仍走 copyIfAbsent 的幂等跳过。
+ */
+function copyIfPresent(src: string, dest: string, report: InitReport): void {
+	if (!fs.existsSync(src)) {
+		report.skipped.push(`${path.basename(src)}（bin/devkit 无此文件，跳过）`);
+		return;
+	}
+	copyIfAbsent(src, dest, report);
+}
+
 /**
  * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
  *

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

@@ -33,7 +33,7 @@ afterEach(() => {
 
 /** 预置「已构建」产物：oj build（api/dist/<name>-<version>/）与站点构建（web/dist/modules/） */
 function makePrebuiltArtifacts(): void {
-	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version/desc 与 bundle 级逐一相等，C2-31）
+	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version 与 bundle 级逐一相等，C2-31）
 	const apiDist = join(project, "api/dist/demo-solution-0.1.0");
 	mkdirSync(join(apiDist, "ping"), { recursive: true });
 	mkdirSync(join(apiDist, "migrations"), { recursive: true });
@@ -101,9 +101,9 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 		await expect(pack()).rejects.toThrow(/manifest\.yaml/);
 	});
 
-	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 拒绝", async () => {
+	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 放行（等值要求已移除）", async () => {
 		writeFileSync(join(project, "api/dist/demo-solution-0.1.0/manifest.yaml"), "name: demo-solution\ndesc: 不一致描述\nversion: 0.1.0\n");
-		await expect(pack()).rejects.toThrow(/C2-31/);
+		await expect(pack()).resolves.toMatchObject({ name: "demo-solution" });
 	});
 
 	it("c2-31 分层核对：api/dist 缺 <name>-<version>/ → 可读报错指明期望产物路径", async () => {

package/src/market/__tests__/bootstrap.test.ts

@@ -0,0 +1,204 @@
+// market/bootstrap spec（T8）：隔离站点自举——「试装不心疼」的物理基础。
+//
+// 钉死隔离六项（端口 / DB / 密钥 / 凭据 / 信任库 / CDN 目录）逐项与真站点物理分离：
+// 任一项漏掉，trial 就不再是「隔离试装」而是「往自己工程里装」，信任库污染与端口
+// 冲突都是不可逆后果。故每条断言都直接查文件系统与配置内容，不靠口头约定。
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { bootstrapIsolatedSite } from "../bootstrap";
+
+/** 假 oj 进程：不起真进程，ready 立即就绪（与 dev.ts 的 ojStarter 注入同形态） */
+function fakeStarter() {
+	const started: Array<{ configPath: string, base: string, apiSrc: string }> = [];
+	const starter = (configPath: string, base: string, apiSrc: string) => {
+		started.push({ configPath, base, apiSrc });
+		return {
+			port: Number(/port: (\d+)/.exec(readFileSync(configPath, "utf-8"))?.[1] ?? "0"),
+			ready: Promise.resolve(),
+			stop: () => Promise.resolve(),
+		};
+	};
+	return { started, starter };
+}
+
+/** 造一个「有 oj 二进制与模板」的源工程：bin/oj + bin/plugins + api/config.yaml + api/src */
+function newSourceProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-bootstrap-src-"));
+	mkdirSync(join(root, "bin", "plugins"), { recursive: true });
+	writeFileSync(join(root, "bin", "oj"), "#!/bin/sh\necho fake-oj\n", { mode: 0o755 });
+	writeFileSync(join(root, "bin", ".oj-version"), "v0.1.84\n");
+	writeFileSync(join(root, "bin", "plugins", "auth.wasm"), "plugin", "utf-8");
+	mkdirSync(join(root, "api", "src", "_platform"), { recursive: true });
+	writeFileSync(join(root, "api", "src", "_platform", "seed.sql"), "-- seed\n", "utf-8");
+	writeFileSync(
+		join(root, "api", "config.yaml"),
+		[
+			"mounts:",
+			"  - prefix: /api",
+			"    api: src",
+			"server:",
+			"  host: 127.0.0.1",
+			"  port: 9778",
+			"  jwt_secret: __JWT_SECRET__",
+			"exec:",
+			"  _platform:",
+			"    allow: []",
+			"",
+		].join("\n"),
+		"utf-8",
+	);
+	return root;
+}
+
+describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点", () => {
+	it("then 产物全在临时根内：api 树 / bin/oj / bin/plugins 各就各位", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		expect(existsSync(join(site.root, "api", "src", "_platform", "seed.sql"))).toBe(true);
+		expect(existsSync(join(site.root, "bin", "oj"))).toBe(true);
+		expect(existsSync(join(site.root, "bin", "plugins", "auth.wasm"))).toBe(true);
+		expect(site.root).not.toBe(src);
+		await site.cleanup();
+	});
+
+	it("then 端口取自空闲端口且绝不与源工程 config 的 9778 相同", async () => {
+		const src = newSourceProject();
+		const { started, starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		expect(site.port).toBeGreaterThan(1024);
+		expect(site.port).not.toBe(9778);
+		expect(started[0]?.configPath).toBe(join(site.root, "api", "config.yaml"));
+		const cfg = readFileSync(join(site.root, "api", "config.yaml"), "utf-8");
+		expect(cfg).toContain(`port: ${site.port}`);
+		await site.cleanup();
+	});
+
+	it("then jwt_secret 被随机替换（模板占位符不得残留）", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		const cfg = readFileSync(join(site.root, "api", "config.yaml"), "utf-8");
+		expect(cfg).not.toContain("__JWT_SECRET__");
+		await site.cleanup();
+	});
+
+	it("then CDN 目录在临时根内且已落好 fixture 包与索引", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, fixture: "demo-solution@0.1.0", starter });
+
+		expect(site.cdnDir.startsWith(site.root)).toBe(true);
+		expect(existsSync(join(site.cdnDir, "demo-solution-0.1.0.tgz"))).toBe(true);
+		expect(existsSync(join(site.cdnDir, "bundles.yaml"))).toBe(true);
+		expect(site.cdnBaseUrl).toBe(`${site.baseUrl}/cdn`);
+		await site.cleanup();
+	});
+
+	it("then 发布方私钥只在内存：临时根内 CDN 与站点树查不到发布方 PEM", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, fixture: "demo-solution@0.1.0", starter });
+
+		expect(site.publisher.privateKeyPem).toContain("PRIVATE KEY");
+		const pemFiles = listFiles(site.root).filter(f => f.endsWith(".pem"));
+		const outside = pemFiles.filter(f => !f.includes("api/config"));
+		expect(outside).toEqual([]);
+		await site.cleanup();
+	});
+
+	it("then 信任库隔离：临时根内无 .solutions 信任库文件", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		expect(existsSync(join(site.root, ".solutions"))).toBe(false);
+		expect(listFiles(site.root).some(f => f.includes("trusted-keys"))).toBe(false);
+		await site.cleanup();
+	});
+
+	it("then DB 隔离：库文件路径落在临时根内（config 目录相对解析）", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		expect(site.dbPath.startsWith(site.root)).toBe(true);
+		expect(site.dbPath).toContain("db.sqlite");
+		await site.cleanup();
+	});
+});
+
+describe("given 源工程没装 oj 二进制 When 自举", () => {
+	it("then 人话报错指向 ojm vendor，且不留半成品临时根", async () => {
+		const root = mkdtempSync(join(tmpdir(), "ojm-bootstrap-nooj-"));
+		mkdirSync(join(root, "api"), { recursive: true });
+		writeFileSync(join(root, "api", "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+		const { starter } = fakeStarter();
+
+		await expect(bootstrapIsolatedSite({ projectRoot: root, starter }))
+			.rejects
+			.toThrow(/ojm vendor/);
+	});
+});
+
+describe("given 自举成功 When 执行 cleanup", () => {
+	it("then 临时根被销毁（默认不保留现场）", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		await site.cleanup();
+
+		expect(existsSync(site.root)).toBe(false);
+	});
+
+	it("then keep 模式下保留现场并打出销毁清单", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter, keep: true });
+
+		await site.cleanup();
+
+		expect(existsSync(site.root)).toBe(true);
+		expect(site.teardownReport().join("\n")).toContain(site.root);
+	});
+
+	it("then 重复 cleanup 幂等（不抛错）", async () => {
+		const src = newSourceProject();
+		const { starter } = fakeStarter();
+		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
+
+		await site.cleanup();
+		await expect(site.cleanup()).resolves.toBeUndefined();
+	});
+});
+
+/** 递归列出根下所有文件（相对路径） */
+function listFiles(root: string): string[] {
+	const out: string[] = [];
+	const walk = (dir: string, prefix: string) => {
+		for (const entry of readdirSync(dir)) {
+			const rel = prefix === "" ? entry : `${prefix}/${entry}`;
+			const abs = join(dir, entry);
+			if (statSync(abs).isDirectory())
+				walk(abs, rel);
+			else
+				out.push(rel);
+		}
+	};
+	walk(root, "");
+	return out;
+}

package/src/market/__tests__/build-index.test.ts

@@ -0,0 +1,154 @@
+// ojm market build-index spec（T4）：扫描 cdn/*.tgz → 全量重建 Form B 索引。
+//
+// 两条必守：① 结果只取决于目录里有什么（多次执行字节一致）；② bundles 的 file 必须逐字
+// `<name>-<version>.tgz`——安装侧 P2-11 会拿它挡索引投毒，写歪一个字符就会装不上。
+import { generateKeyPairSync } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parse as yamlParse } from "yaml";
+
+import { createDeterministicTgz } from "../../deterministic-tar";
+import { verifyCanonical } from "../../lifecycle/sign";
+import { indexCanonical } from "../../publish";
+import { buildIndex } from "../build-index";
+import { buildFixturePackage } from "../fixture";
+
+const MOUNTS = "  - prefix: /api\n    api: src\n  - prefix: /cdn\n    web: ../cdn\n";
+const CONFIG = `mounts:\n${MOUNTS}server:\n  host: 127.0.0.1\n  port: 9778\n`;
+const KEY_ID = "cdn.maintainer";
+
+function testPem(): string {
+	return generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+}
+
+function newProject(): { root: string, cdn: string } {
+	const root = mkdtempSync(join(tmpdir(), "ojm-market-index-"));
+	mkdirSync(join(root, "api"), { recursive: true });
+	writeFileSync(join(root, "api", "config.yaml"), CONFIG, "utf-8");
+	const cdn = join(root, "cdn");
+	mkdirSync(cdn, { recursive: true });
+	return { root, cdn };
+}
+
+/** 把一个 fixture 方案打进 cdn 目录，返回 tgz 文件名 */
+async function putPackage(cdn: string, staging: string, name: string, version: string): Promise<string> {
+	const pkg = buildFixturePackage({ stagingDir: staging, name, version });
+	const tgz = join(cdn, `${name}-${version}.tgz`);
+	await createDeterministicTgz(pkg.dir, tgz);
+	return `${name}-${version}.tgz`;
+}
+
+function readBundles(cdn: string): { solutions?: Array<Record<string, unknown>> } {
+	return yamlParse(readFileSync(join(cdn, "bundles.yaml"), "utf-8")) as { solutions?: Array<Record<string, unknown>> };
+}
+
+describe("given cdn/ 里有多个包与多个版本 When 重建索引", () => {
+	it("then 按 semver 聚合：版本全留、latest 取最大", async () => {
+		const { root, cdn } = newProject();
+		const staging = mkdtempSync(join(tmpdir(), "ojm-stage-"));
+		await putPackage(cdn, staging, "demo-solution", "0.1.0");
+		await putPackage(cdn, staging, "demo-solution", "0.2.0");
+		await putPackage(cdn, staging, "other-solution", "0.3.0");
+
+		const result = await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+
+		const bundles = readBundles(cdn);
+		expect(result.solutions).toBe(2);
+		const demo = bundles.solutions!.find(s => s.name === "demo-solution")!;
+		expect(demo.latest).toBe("0.2.0");
+		expect(demo.versions as unknown[]).toHaveLength(2);
+		const manifests = yamlParse(readFileSync(join(cdn, "manifests.yaml"), "utf-8")) as unknown[];
+		expect(manifests).toHaveLength(3);
+	});
+
+	it("then bundles 的 file 逐字为 <name>-<version>.tgz（安装侧 P2-11 加固前置）", async () => {
+		const { root, cdn } = newProject();
+		const staging = mkdtempSync(join(tmpdir(), "ojm-stage-"));
+		await putPackage(cdn, staging, "demo-solution", "0.1.0");
+
+		await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+
+		const demo = readBundles(cdn).solutions![0]!;
+		const hit = (demo.versions as Array<Record<string, unknown>>)[0]!;
+		expect(hit.file).toBe("demo-solution-0.1.0.tgz");
+		expect(hit.sha256).toMatch(/^[0-9a-f]{64}$/);
+		expect(hit.size).toBeGreaterThan(0);
+	});
+
+	it("then 索引只取决于目录内容：连续两次执行字节一致（幂等）", async () => {
+		const { root, cdn } = newProject();
+		const staging = mkdtempSync(join(tmpdir(), "ojm-stage-"));
+		await putPackage(cdn, staging, "demo-solution", "0.1.0");
+		const key = testPem();
+
+		await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: key });
+		const first = readFileSync(join(cdn, "bundles.yaml"), "utf-8");
+		await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: key });
+		const second = readFileSync(join(cdn, "bundles.yaml"), "utf-8");
+
+		expect(second).toBe(first);
+	});
+});
+
+describe("given cdn/ 为空 When 重建索引", () => {
+	it("then 产出空索引（不是缺 Solutions 段）——空目录也能验、也能装", async () => {
+		const { root, cdn } = newProject();
+
+		const result = await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+
+		expect(result.solutions).toBe(0);
+		const bundles = readBundles(cdn);
+		expect(bundles.solutions).toEqual([]);
+		expect(yamlParse(readFileSync(join(cdn, "manifests.yaml"), "utf-8"))).toEqual([]);
+	});
+});
+
+describe("given cdn/ 里有一个没有内嵌 manifest 的包 When 重建索引", () => {
+	it("then 跳过该包并给出可读警告，其余包照常入索引", async () => {
+		const { root, cdn } = newProject();
+		const staging = mkdtempSync(join(tmpdir(), "ojm-stage-"));
+		writeFileSync(join(cdn, "broken-0.1.0.tgz"), "garbage-not-a-tgz", "utf-8");
+		await putPackage(cdn, staging, "demo-solution", "0.1.0");
+
+		const result = await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+
+		expect(result.skipped).toContain("broken-0.1.0.tgz");
+		expect(result.solutions).toBe(1);
+	});
+});
+
+describe("given 包带包级 .sig 侧车 When 重建索引", () => {
+	it("then manifests 的 archive.signature 带上它（否则安装器按 sig_missing 拒装）", async () => {
+		const { root, cdn } = newProject();
+		const staging = mkdtempSync(join(tmpdir(), "ojm-stage-"));
+		const file = await putPackage(cdn, staging, "demo-solution", "0.1.0");
+		writeFileSync(`${join(cdn, file)}.sig`, JSON.stringify({ alg: "Ed25519", key_id: KEY_ID, public_key: "ab", value: "cd", canon: "v1" }), "utf-8");
+
+		await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+
+		const manifests = yamlParse(readFileSync(join(cdn, "manifests.yaml"), "utf-8")) as Array<Record<string, unknown>>;
+		const archive = manifests[0]!.archive as Record<string, unknown>;
+		expect(archive.signature).toMatchObject({ key_id: KEY_ID });
+	});
+});
+
+describe("given 给了签名身份 When 重建索引", () => {
+	it("then 两份索引各产出可复核的 .sig", async () => {
+		const { root, cdn } = newProject();
+		const staging = mkdtempSync(join(tmpdir(), "ojm-stage-"));
+		await putPackage(cdn, staging, "demo-solution", "0.1.0");
+
+		await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+
+		for (const kind of ["bundles", "manifests"] as const) {
+			const sigPath = join(cdn, `${kind}.yaml.sig`);
+			expect(existsSync(sigPath)).toBe(true);
+			const sig = JSON.parse(readFileSync(sigPath, "utf-8")) as { public_key: string, value: string, key_id: string };
+			expect(sig.key_id).toBe(KEY_ID);
+			const text = readFileSync(join(cdn, `${kind}.yaml`), "utf-8");
+			expect(verifyCanonical(sig.public_key, indexCanonical(kind, text), sig.value)).toBe(true);
+		}
+	});
+});