@oj-module/cli 0.2.8 → 0.2.14

package/src/market/failure-playbook.ts

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

package/src/market/fixture.ts

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

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