@oj-module/cli 0.2.8 → 0.2.14

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

package/src/market/verify.ts

@@ -0,0 +1,298 @@
+/**
+ * `ojm market verify`（T7）：离线验包——不起站点、不装、不要凭据、不要 DB。
+ *
+ * 分四类列结果（包级与索引级**分开**，因为语义不同）：
+ * - 完整性：tgz 实际 sha256 与索引声明的 archive.sha256 是否一致；
+ * - 包级签名：`<tgz>.sig` 能否用包内公钥复核规范串 `<name>@<version>:<sha256>`——**这是信任锚**；
+ * - 索引签名：索引字节与其 `.sig`——只是完整性层（防目录/索引被改），不是信任锚；
+ * - manifest 结构：必填字段、内嵌原生清单 desc 是否非空（oj 装配面必填）、同方案各版本 0001 迁移是否逐字节一致。
+ *
+ * 复用既有原语，一行密码学都不重写：`lifecycle/sign.ts` 的 canonicalString/verifyCanonical、
+ * `publish.ts` 的 indexCanonical、`node:crypto` 的 sha256。
+ */
+
+import type { IndexedPackage } from "./index-builder";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { parse as yamlParse } from "yaml";
+import { canonicalString, verifyCanonical } from "../lifecycle/sign";
+import { indexCanonical } from "../publish";
+import { resolveCdnLayout } from "./cdn-layout";
+import { readTgz } from "./scan";
+
+export interface VerifyCheck {
+	item: string
+	ok: boolean
+	detail: string
+}
+
+export interface VerifyOptions {
+	projectRoot?: string
+	/** 验指定的 tgz（缺省扫 cdn/ 下全部包） */
+	file?: string
+	/** 比对扫描重建出的索引与盘上索引，检出漂移 */
+	rebuildCheck?: boolean
+}
+
+export interface VerifyResult {
+	checks: VerifyCheck[]
+	passed: boolean
+	conclusion: string
+	/** `--rebuild-check` 的漂移描述；未传该开关时为 undefined */
+	drift?: string[]
+}
+
+const BOUNDARY = "完整性 / 来源校验通过——不构成内容安全性背书";
+
+export function verifyMarket(opts: VerifyOptions = {}): VerifyResult {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const layout = resolveCdnLayout(projectRoot);
+	const checks: VerifyCheck[] = [];
+	const drift: string[] = [];
+
+	const bundlesText = readOptional(path.join(layout.dir, "bundles.yaml"));
+	const manifestsText = readOptional(path.join(layout.dir, "manifests.yaml"));
+	const declared = declaredHashes(manifestsText);
+
+	const tgzFiles = opts.file !== undefined
+		? [opts.file]
+		: fs.existsSync(layout.dir) ? fs.readdirSync(layout.dir).filter(f => f.endsWith(".tgz")).sort() : [];
+
+	for (const file of tgzFiles) {
+		const tgzPath = path.isAbsolute(file) ? file : path.join(layout.dir, file);
+		if (!fs.existsSync(tgzPath)) {
+			checks.push({ item: "完整性", ok: false, detail: `${file}：文件不存在` });
+			continue;
+		}
+		const bytes = new Uint8Array(fs.readFileSync(tgzPath));
+		const sha256 = createHash("sha256").update(bytes).digest("hex");
+		const name = nameOf(file);
+		const version = versionOf(file);
+
+		const want = declared.get(`${name}@${version}`);
+		checks.push({
+			item: "完整性",
+			ok: want === undefined || want === sha256,
+			detail: want === undefined
+				? `${file}：索引未声明该版本，只做了摘要计算（${sha256.slice(0, 12)}…）`
+				: `${file}：${want === sha256 ? `sha256 与索引一致（${sha256.slice(0, 12)}…）` : `sha256 不一致（索引 ${want.slice(0, 12)}… vs 实际 ${sha256.slice(0, 12)}…）`}`,
+		});
+
+		checks.push(signatureCheck(tgzPath, name, version, sha256));
+		checks.push(...structureCheck(bytes, file));
+	}
+
+	checks.push(indexSigCheck(layout.dir, "bundles", bundlesText));
+	checks.push(indexSigCheck(layout.dir, "manifests", manifestsText));
+	checks.push(...migrationConsistencyCheck(layout.dir, tgzFiles));
+
+	if (opts.rebuildCheck === true)
+		drift.push(...driftOf(layout.dir));
+
+	const passed = checks.every(c => c.ok) && drift.length === 0;
+	return {
+		checks,
+		passed,
+		conclusion: passed
+			? `全部校验通过（${checks.length} 项）。${BOUNDARY}——验签过只说明来源与完整性，不说明代码无害。`
+			: `存在未通过项。${BOUNDARY}：未通过项须逐条排查后再发布。`,
+		drift: opts.rebuildCheck === true ? drift : undefined,
+	};
+}
+
+/**
+ * `.sig` 里验签只用到 public_key / value 两字段；缺任一即不可复核。
+ * 抽成类型守卫：包级与索引级两处验签共用（DRY），也顺带让调用点的布尔式保持单行
+ * （本仓 indent-binary-ops 与 no-mixed-spaces-and-tabs 对续行缩进的要求互相打架）。
+ */
+function hasSigFields(sig: { public_key?: string, value?: string }): sig is { public_key: string, value: string } {
+	return typeof sig.public_key === "string" && typeof sig.value === "string";
+}
+
+/** 包级 detached 验签：`<tgz>.sig` 的公钥复核规范串 */
+function signatureCheck(tgzPath: string, name: string, version: string, sha256: string): VerifyCheck {
+	const sigPath = `${tgzPath}.sig`;
+	if (!fs.existsSync(sigPath))
+		return { item: "包级签名", ok: false, detail: `${path.basename(tgzPath)}：缺 .tgz.sig（sig_missing）——用 ojm market publish 重发，或向发布方索取签名包` };
+	try {
+		const sig = JSON.parse(fs.readFileSync(sigPath, "utf-8")) as { public_key?: string, value?: string };
+		const canonical = canonicalString(name, version, sha256);
+		const ok = hasSigFields(sig) && verifyCanonical(sig.public_key, canonical, sig.value);
+		return {
+			item: "包级签名",
+			ok,
+			detail: ok
+				? `${path.basename(tgzPath)}：Ed25519 验签通过（规范串 ${name}@${version}:${sha256.slice(0, 12)}…）`
+				: `${path.basename(tgzPath)}：验签失败——包体被改或签名不匹配`,
+		};
+	}
+	catch (error) {
+		return { item: "包级签名", ok: false, detail: `${path.basename(sigPath)} 不可解析：${(error as Error).message}` };
+	}
+}
+
+/** 索引级验签（完整性层） */
+function indexSigCheck(cdnDir: string, kind: "bundles" | "manifests", text: string | null): VerifyCheck {
+	if (text === null)
+		return { item: "索引签名", ok: true, detail: `${kind}.yaml 不存在，跳过` };
+	const sigPath = path.join(cdnDir, `${kind}.yaml.sig`);
+	if (!fs.existsSync(sigPath))
+		return { item: "索引签名", ok: true, detail: `${kind}.yaml.sig 缺失——运行期容忍（滚动发布期），完整性无保障` };
+	try {
+		const sig = JSON.parse(fs.readFileSync(sigPath, "utf-8")) as { public_key?: string, value?: string };
+		const ok = hasSigFields(sig) && verifyCanonical(sig.public_key, indexCanonical(kind, text), sig.value);
+		return { item: "索引签名", ok, detail: ok ? `${kind}.yaml 验签通过` : `${kind}.yaml 验签失败——索引被改或签名不符` };
+	}
+	catch (error) {
+		return { item: "索引签名", ok: false, detail: `${kind}.yaml.sig 不可解析：${(error as Error).message}` };
+	}
+}
+
+/** manifest 结构：必填字段 + 内嵌原生清单 desc 非空（等值要求已移除，见 §9.3） */
+function structureCheck(bytes: Uint8Array, file: string): VerifyCheck[] {
+	let entries: ReturnType<typeof readTgz>;
+	try {
+		entries = readTgz(bytes);
+	}
+	catch (error) {
+		return [{ item: "manifest 结构", ok: false, detail: `${file}：包无法解开（${(error as Error).message}）` }];
+	}
+	const root = entries.find(e => /^(?:[^/]+\/)?manifest\.yaml$/.test(e.name));
+	if (root === undefined)
+		return [{ item: "manifest 结构", ok: false, detail: `${file}：包内缺 manifest.yaml` }];
+	const manifest = (yamlParse(root.content.toString("utf-8")) ?? {}) as Record<string, unknown>;
+	const missing = ["name", "version", "summary", "peerRuntime", "archive"].filter(k => manifest[k] === undefined);
+	const out: VerifyCheck[] = [{
+		item: "manifest 结构",
+		ok: missing.length === 0,
+		detail: missing.length === 0
+			? `${file}：必填字段齐备（name/version/summary/peerRuntime/archive）`
+			: `${file}：缺必填字段 ${missing.join(", ")}`,
+	}];
+
+	const inner = entries.find(e => /^api\/[^/]+\/manifest\.yaml$/.test(e.name));
+	if (inner !== undefined) {
+		const innerManifest = (yamlParse(inner.content.toString("utf-8")) ?? {}) as Record<string, unknown>;
+		const desc = innerManifest.desc;
+		const ok = typeof desc === "string" && desc.trim() !== "";
+		out.push({
+			item: "manifest 结构",
+			ok,
+			detail: ok
+				? `${file}：原生清单 desc 非空（oj 装配面必填）`
+				: `${file}：原生清单 desc 缺失或空白——oj 启动装配会失败`,
+		});
+	}
+	return out;
+}
+
+/** 同方案各版本的 0001 迁移必须逐字节一致（否则升级链的迁移校验会假失败） */
+function migrationConsistencyCheck(cdnDir: string, files: string[]): VerifyCheck[] {
+	const byName = new Map<string, Array<{ version: string, bytes: string }>>();
+	for (const file of files) {
+		const abs = path.isAbsolute(file) ? file : path.join(cdnDir, file);
+		if (!fs.existsSync(abs))
+			continue;
+		let entries: ReturnType<typeof readTgz>;
+		try {
+			entries = readTgz(new Uint8Array(fs.readFileSync(abs)));
+		}
+		catch {
+			continue;
+		}
+		const mig = entries.find(e => /\/migrations\/0001[^/]*\.sql$/.test(e.name));
+		if (mig === undefined)
+			continue;
+		const name = nameOf(file);
+		const list = byName.get(name) ?? [];
+		list.push({ version: versionOf(file), bytes: createHash("sha256").update(mig.content).digest("hex") });
+		byName.set(name, list);
+	}
+	const out: VerifyCheck[] = [];
+	for (const [name, list] of byName) {
+		if (list.length < 2)
+			continue;
+		const first = list[0]!.bytes;
+		const bad = list.filter(v => v.bytes !== first).map(v => v.version);
+		out.push({
+			item: "manifest 结构",
+			ok: bad.length === 0,
+			detail: bad.length === 0
+				? `${name}：各版本 0001 迁移逐字节一致`
+				: `${name}：0001 迁移在版本 ${bad.join(", ")} 与首版不一致——升级链会报迁移缺失，须只增不改`,
+		});
+	}
+	return out;
+}
+
+/** 扫描重建出的索引与盘上索引比对，检出「落了包没重建 / 索引被手改」 */
+function driftOf(cdnDir: string): string[] {
+	const out: string[] = [];
+	const files = fs.readdirSync(cdnDir).filter(f => f.endsWith(".tgz")).sort();
+	const scanned: IndexedPackage[] = [];
+	for (const file of files) {
+		const bytes = new Uint8Array(fs.readFileSync(path.join(cdnDir, file)));
+		const entries = readTgz(bytes);
+		const root = entries.find(e => /^(?:[^/]+\/)?manifest\.yaml$/.test(e.name));
+		if (root === undefined)
+			continue;
+		const manifest = (yamlParse(root.content.toString("utf-8")) ?? {}) as Record<string, unknown>;
+		const name = String(manifest.name ?? "");
+		const version = String(manifest.version ?? "");
+		if (name === "" || version === "")
+			continue;
+		scanned.push({ name, version, file, sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength, manifest });
+	}
+	const onDisk = readOptional(path.join(cdnDir, "bundles.yaml"));
+	if (onDisk === null) {
+		if (scanned.length > 0)
+			out.push(`盘上没有 bundles.yaml，但目录里有 ${scanned.length} 个包——索引从未重建`);
+		return out;
+	}
+	const parsed = (yamlParse(onDisk) ?? { solutions: [] }) as { solutions?: Array<Record<string, unknown>> };
+	const inIndex = new Set<string>();
+	for (const solution of parsed.solutions ?? []) {
+		const name = String(solution.name ?? "");
+		for (const v of (solution.versions ?? []) as Array<Record<string, unknown>>)
+			inIndex.add(`${name}@${String(v.version ?? "")}`);
+	}
+	for (const pkg of scanned) {
+		if (!inIndex.has(`${pkg.name}@${pkg.version}`))
+			out.push(`索引缺条目：${pkg.name}@${pkg.version}（${pkg.file}）——落了包但没跑 ojm market build-index`);
+	}
+	return out;
+}
+
+function declaredHashes(manifestsText: string | null): Map<string, string> {
+	const out = new Map<string, string>();
+	if (manifestsText === null)
+		return out;
+	const list = (yamlParse(manifestsText) ?? []) as Array<Record<string, unknown>>;
+	for (const item of Array.isArray(list) ? list : []) {
+		const archive = item.archive as Record<string, unknown> | undefined;
+		const sha = archive?.sha256;
+		if (typeof sha === "string")
+			out.set(`${String(item.name ?? "")}@${String(item.version ?? "")}`, sha);
+	}
+	return out;
+}
+
+function readOptional(file: string): string | null {
+	return fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : null;
+}
+
+/** `<name>-<version>.tgz` → name（取最后一个 - 之前，版本段不含 -） */
+function nameOf(file: string): string {
+	const base = path.basename(file).replace(/\.tgz$/, "");
+	const at = base.lastIndexOf("-");
+	return at === -1 ? base : base.slice(0, at);
+}
+
+function versionOf(file: string): string {
+	const base = path.basename(file).replace(/\.tgz$/, "");
+	const at = base.lastIndexOf("-");
+	return at === -1 ? "" : base.slice(at + 1);
+}