@oj-module/cli 0.2.30 → 0.2.43

package/src/market/fixture.ts

@@ -23,6 +23,15 @@ export interface FixturePackage {
 export const DEFAULT_FIXTURE_NAME = "demo-solution";
 export const DEFAULT_FIXTURE_VERSION = "0.1.0";
 
+/** 方案名/版本的安全字符集（与 cdn 文件名、staging 目录名拼接，须杜绝路径穿越） */
+const SAFE_SPEC = /^[a-z0-9][\w.-]*$/i;
+
+/** fail-closed：name/version 仅允许字母数字 . _ -，且不可含 `..`，否则路径拼接会逃逸出 cdn/staging 目录 */
+function assertSafeSpec(part: string, label: string): void {
+	if (part === "" || !SAFE_SPEC.test(part) || part.includes(".."))
+		throw new Error(`[ojm] --fixture 的 ${label} 含非法字符（仅允许字母数字 . _ -，且不可含 ..）：${part}`);
+}
+
 /** 解析 `--fixture <name>@<version>`；缺省/缺段用默认值补齐 */
 export function parseFixtureSpec(spec?: string): { name: string, version: string } {
 	if (spec === undefined || spec.trim() === "" || spec === "latest")
@@ -32,7 +41,11 @@ export function parseFixtureSpec(spec?: string): { name: string, version: string
 		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 };
+	const safeName = name === "" ? DEFAULT_FIXTURE_NAME : name;
+	const safeVersion = version === "" ? DEFAULT_FIXTURE_VERSION : version;
+	assertSafeSpec(safeName, "name");
+	assertSafeSpec(safeVersion, "version");
+	return { name: safeName, version: safeVersion };
 }
 
 export function buildFixturePackage(opts: { stagingDir: string, name?: string, version?: string }): FixturePackage {
@@ -113,8 +126,12 @@ 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> {
+/**
+ * 方案清单（Form A：archive 只写 file，sha256/size 由索引侧填 Form B）。
+ * 导出给 build-index 的体积实测用：需求 §7 估「单条 Form B ≈535–684B」偏乐观——本形态
+ * 实测 945B YAML、进索引 ≈1.2KB/条，SHARD_MAX_VERSIONS 的 1000 校准即以它为据。
+ */
+export function solutionManifest(name: string, version: string): Record<string, unknown> {
 	return {
 		name,
 		version,

package/src/market/index-builder.ts

@@ -1,30 +1,38 @@
 /**
- * Form B 索引聚合（T4）：把「一批已扫出的包」变成 bundles.yaml / manifests.yaml 的数据形状。
+ * Form B 索引聚合（T4 + REG-CS5 三级化）：把「一批已扫出的包」变成分片索引的数据形状。
  *
- * 纯数据变换，不落 IO、不签名——IO 与签名归 `build-index.ts`。形状严格对齐安装侧的消费口径
- * （`market/api.ts resolveCdn`）：`file` 必须逐字 `<name>-<version>.tgz`，否则安装侧 P2-11 会
- * 判索引投毒直接 502。
+ * 纯数据变换，不落 IO、不签名——IO 与签名归 `build-index.ts`（写入）与 `publish.ts`（补签）。
+ * 形状严格对齐安装侧的消费口径（`market/api.ts resolveCdn`）：`archive.file` 必须逐字
+ * `<name>-<version>.tgz`，否则安装侧 P2-11 会判索引投毒直接 502。
+ *
+ * REG-CS5：v2 起索引三级化——`catalog.yaml`（包名 → 分片号，无版本明细）+ `shards/<n>.yaml`
+ * （每片 ≤1000 版本）+ 版本条目内嵌 Form B manifest（原 manifests.yaml 的聚合清单并入分片，
+ * 装一个包只拉 1 catalog + 1 shard，不再有第三份全量清单）。版本条目即 Form B 条目：
+ * `archive` 带 file/sha256/size/signature，与旧 manifests.yaml 逐字同构，故安装侧
+ * 「取版本条目即取 manifest」，少一次全量拉取。
  */
 
-export interface IndexedPackage {
+import type { YankEntry } from "./yank-ledger";
+
+/** 分片内的方案条目：版本数组 = Form B manifest 条目（升序） */
+export interface BuiltSolution {
 	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>
+	latest: string
+	versions: Array<Record<string, unknown>>
 }
 
 export interface BuiltIndex {
-	bundles: { solutions: Array<Record<string, unknown>> }
-	manifests: Array<Record<string, unknown>>
+	solutions: BuiltSolution[]
 }
 
-export function buildIndexData(packages: IndexedPackage[]): BuiltIndex {
+/**
+ * 聚合索引数据（分片形态）。
+ *
+ * `yanked?`：yank 账本（`name@version -> 条目`，REG-CS4）。非零时：
+ * - 各版本条目带 `yanked: true` + `yanked_at`（epoch 秒），安装侧 resolveCdn 据此拒精确安装；
+ * - 该方案的 `latest` 跳过已下线版本（全部下线则降级取最高版，保证索引不空）。
+ */
+export function buildIndexData(packages: IndexedPackage[], yanked?: Map<string, YankEntry>): BuiltIndex {
 	const byName = new Map<string, IndexedPackage[]>();
 	for (const pkg of packages) {
 		const list = byName.get(pkg.name) ?? [];
@@ -32,45 +40,110 @@ export function buildIndexData(packages: IndexedPackage[]): BuiltIndex {
 		byName.set(pkg.name, list);
 	}
 
-	const solutions: Array<Record<string, unknown>> = [];
-	const manifests: Array<Record<string, unknown>> = [];
+	const solutions: BuiltSolution[] = [];
 	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,
+		const list = [...byName.get(name)!].sort((a, b) => compareSemver(a.version, b.version));
+		// latest 跳过 yanked（REG-CS4）：已下线的版本绝不成为默认升级目标；全下线降级取最高版
+		const live = list.filter(v => !isYanked(yanked, name, v.version));
+		const latestSource = live.length > 0 ? live : list;
+		const versions = list.map((v) => {
+			const key = yanked !== undefined && isYanked(yanked, name, v.version)
+				? { yanked: true, yanked_at: yanked.get(`${name}@${v.version}`)!.at }
+				: {};
+			// 版本条目 = Form B manifest 条目：name/version/archive 与旧 manifests.yaml 逐字同构，
+			// 顶层再并进版本裁决字段（yanked）。安装侧「取条目即取 manifest」。
+			return {
+				...v.manifest,
 				name,
-				version: pkg.version,
+				version: v.version,
 				archive: {
-					file,
-					sha256: pkg.sha256,
-					size: pkg.size,
-					...(pkg.signature === undefined ? {} : { signature: pkg.signature }),
+					file: `${v.name}-${v.version}.tgz`,
+					sha256: v.sha256,
+					size: v.size,
+					...(v.signature === undefined ? {} : { signature: v.signature }),
 				},
-			});
-		}
+				...key,
+			};
+		});
+		solutions.push({ name, latest: latestSource[latestSource.length - 1]!.version, versions });
 	}
-	return { bundles: { solutions }, manifests };
+	return { solutions };
 }
 
-/** 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);
+/** 入索引的包（扫描产物；manifest 为包内 Form A，进分片时补成 Form B） */
+export interface IndexedPackage {
+	name: string
+	version: string
+	/** tgz 文件名（由 name+version 派生，逐字约束在此处一次成型） */
+	file: string
+	sha256: string
+	size: number
+	/** 包内 manifest（Form A） */
+	manifest: Record<string, unknown>
+	/** 包级 detached 签名（`<tgz>.sig` 五字段）；缺则 Form B 不带 signature，安装侧按 sig_missing 拒装 */
+	signature?: Record<string, unknown>
+}
+
+function isYanked(yanked: Map<string, YankEntry> | undefined, name: string, version: string): boolean {
+	return yanked !== undefined && yanked.has(`${name}@${version}`);
+}
+
+/**
+ * semver 比较（与模板 `_lifecycle/semver.ts` 同源算法；prerelease 遵循 semver 2.0.0）：
+ * 数字标识符按数值、字母按字典序、数字 < 字母、标识符列表前缀相等时多者大；无 prerelease > 有 prerelease。
+ * 取代旧版纯数值比较（旧版对 `1.0.0-rc.1` 这类预发布版本按 `1.0.0.0` 处理，latest 计算失真——
+ * S2-0 红队 F 相关预发布序修复）。返回 -1|0|1，可直接作 Array.sort 比较器。
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+	const va = splitVersion(a);
+	const vb = splitVersion(b);
+	const len = Math.max(va.core.length, vb.core.length);
+	for (let i = 0; i < len; i++) {
+		const diff = (va.core[i] ?? 0) - (vb.core[i] ?? 0);
 		if (diff !== 0)
-			return diff;
+			return diff < 0 ? -1 : 1;
 	}
-	return 0;
+	return comparePrerelease(va.pre, vb.pre);
 }
 
-function numeric(version: string): number[] {
-	return version.replace(/^v/, "").split(".").map(part => Number.parseInt(part, 10) || 0);
+/** 兼容旧名（过渡期别名；新调用请用 compareSemver） */
+export const compareVersion = compareSemver;
+
+function splitVersion(v: string): { core: number[], pre: string[] | null } {
+	const hyphen = v.indexOf("-");
+	const core = hyphen === -1 ? v : v.slice(0, hyphen);
+	const prePart = hyphen === -1 ? null : v.slice(hyphen + 1);
+	return {
+		core: core.split(".").map(seg => Number.parseInt(seg, 10) || 0),
+		pre: prePart == null ? null : prePart.split("."),
+	};
+}
+
+function comparePrerelease(a: string[] | null, b: string[] | null): -1 | 0 | 1 {
+	if (a === null || b === null) {
+		return a === b ? 0 : a === null ? 1 : -1;
+	}
+	const len = Math.max(a.length, b.length);
+	for (let i = 0; i < len; i++) {
+		const ia = a[i];
+		const ib = b[i];
+		if (ia === undefined)
+			return -1;
+		if (ib === undefined)
+			return 1;
+		const na = /^\d+$/.test(ia);
+		const nb = /^\d+$/.test(ib);
+		if (na && nb) {
+			const diff = Number.parseInt(ia, 10) - Number.parseInt(ib, 10);
+			if (diff !== 0)
+				return diff < 0 ? -1 : 1;
+		}
+		else if (na !== nb) {
+			return na ? -1 : 1;
+		}
+		else if (ia !== ib) {
+			return ia < ib ? -1 : 1;
+		}
+	}
+	return 0;
 }

package/src/market/publish.ts

@@ -36,6 +36,8 @@ export interface MarketPublishOptions {
 	privateKeyPem?: string
 	/** 落包后离线自检（verifyCanonical 复核包级签名） */
 	check?: boolean
+	/** 签发方 registry 身份（REG-CS3 v2 防跨仓库重放；透传 signCommand --registry-id） */
+	registryId?: string
 }
 
 export interface MarketPublishResult {
@@ -73,7 +75,7 @@ export async function publishPackage(opts: MarketPublishOptions = {}): Promise<M
 
 		let signed: ReturnType<typeof signCommand>;
 		try {
-			signed = signCommand(tgzPath, { id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem, check: opts.check });
+			signed = signCommand(tgzPath, { id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem, check: opts.check, registryId: opts.registryId });
 		}
 		catch (error) {
 			rollbackPackage();

package/src/market/setup.ts

@@ -22,8 +22,8 @@ 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
+	/** 站点地址（缺省取 OJM_SITE_URL 或 http://127.0.0.1:9778） */
+	siteUrl?: string
 	user?: string
 	pass?: string
 	/** 新口令；不给则随机生成并只在终端打印一次（不落盘、不进日志） */
@@ -44,7 +44,7 @@ export interface SetupResult {
 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 site = resolveSite({ siteUrl: opts.siteUrl, 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);

package/src/market/sharding.ts

@@ -0,0 +1,94 @@
+/**
+ * REG-CS5 装箱（D3）：把「一批方案」装进分片，每片 ≤ `SHARD_MAX_VERSIONS` 个版本。
+ *
+ * 纯数据变换，不落 IO、不签名——编号与落盘归 `build-index.ts`。
+ *
+ * 三条策略（计划 §S2-1 子任务 2，D3 已定）：
+ * 1. **整包装箱**：一个方案不跨片，除非它自己的版本数就超限——那种极端包才按连续上限切片，
+ *    且仍占连续片号（读方按片号倒序试取，最高片装最新版，`latest` 安装只拉 1 片）。
+ * 2. **确定性**：输入方案顺序即输出顺序（调用方已按名称字典序排好），同样目录内容永远装出
+ *    同样结果——「索引只取决于目录内容」这条性质靠它成立。
+ * 3. **累加到上限开新片**：按版本数往当前片累加，放不下就开新片（计划原文「按版本数累加到
+ *    上限开新片」，上限值经执行期实测校准，见下）。已有包因此天然不换片：只在它前面的内容变了才被挤动。
+ *
+ * 体积口径（需求 §7，2026-10-25 执行期实测校准）：需求原文按「单条 Form B ≈535–684B」
+ * 估 2000 版本/片 ≈1.2MB；但本仓参考 manifest 形态（fixture.ts solutionManifest，945B YAML）
+ * 实测单条 Form B 条目 ≈1.2KB——2000/片 = 2.4MB，超计划 §S2-1「单片 ≤1.5MB」验收闸。
+ * 校准为 1000 版本/片：参考形态下 ≈1.2MB，正中需求目标；fat manifest 的最坏面也随砍半。
+ */
+
+import type { BuiltSolution } from "./index-builder";
+
+/** 单片最大版本数（REG-CS5：1000 版本 ≈1.2MB，计划验收 ≤1.5MB；实测依据见文件头） */
+export const SHARD_MAX_VERSIONS = 1000;
+
+/** 一个分片槽位（编号由 build-index 按内容匹配分配，这里只带内容） */
+export interface ShardSlot {
+	/** 片内方案（顺序 = 装配顺序；版本在各方案内升序） */
+	solutions: BuiltSolution[]
+	/** 片内版本总数（≤SHARD_MAX_VERSIONS；超限包独占多片时每片恰为上限） */
+	versions: number
+}
+
+/** 包名 → 所占片号（升序；读方倒序试取） */
+export type ShardAssignment = Map<string, number[]>;
+
+export interface PackedShards {
+	/** 槽位序列（顺序即装配顺序；编号未分配，见 ShardSlot） */
+	slots: ShardSlot[]
+	/** 包名 → 片号（升序） */
+	assignment: ShardAssignment
+}
+
+/**
+ * 装箱。调用方保证 `solutions` 已按名称字典序（buildIndexData 的产出即如此）。
+ *
+ * 超限包（版本数 > `SHARD_MAX_VERSIONS`）切片时每片都是完整方案条目（带 name/latest），`latest` 恒取
+ * 包级真值——读方片号倒序，最高片必含最新版本，`latest` 只在最高片被消费；低片里的
+ * `latest` 是自洽兜底（指向本片最高版），不会被安装路径读到。
+ */
+export function packShards(solutions: BuiltSolution[]): PackedShards {
+	const slots: ShardSlot[] = [];
+	const assignment: ShardAssignment = new Map();
+	let current: ShardSlot = { solutions: [], versions: 0 };
+
+	for (const solution of solutions) {
+		if (solution.versions.length > SHARD_MAX_VERSIONS) {
+			// 超限包：先把当前片收尾，再按连续上限独占多片
+			if (current.solutions.length > 0) {
+				slots.push(current);
+				current = { solutions: [], versions: 0 };
+			}
+			const nos: number[] = [];
+			for (let at = 0; at < solution.versions.length; at += SHARD_MAX_VERSIONS) {
+				const chunk: BuiltSolution = {
+					name: solution.name,
+					latest: solution.latest,
+					versions: solution.versions.slice(at, at + SHARD_MAX_VERSIONS),
+				};
+				slots.push({ solutions: [chunk], versions: chunk.versions.length });
+				nos.push(slots.length); // 片号 = 槽位序号（1 起）
+			}
+			assignment.set(solution.name, nos);
+			continue;
+		}
+		if (current.versions + solution.versions.length > SHARD_MAX_VERSIONS) {
+			slots.push(current);
+			current = { solutions: [], versions: 0 };
+		}
+		current.solutions.push(solution);
+		current.versions += solution.versions.length;
+		const nos = assignment.get(solution.name) ?? [];
+		nos.push(slots.length + 1); // 当前片编号 = 已收尾片数 + 1
+		assignment.set(solution.name, nos);
+	}
+	if (current.solutions.length > 0)
+		slots.push(current);
+
+	// 空索引也要有一个空片——catalog 的 shards 映射不为空，读方「拉 catalog 即知天下」
+	// （无片可拉时装任何包都走 404 分支，与空索引时代同语义）
+	if (slots.length === 0)
+		slots.push({ solutions: [], versions: 0 });
+
+	return { slots, assignment };
+}

package/src/market/trial.ts

@@ -55,7 +55,7 @@ export async function trialInstall(opts: TrialOptions = {}): Promise<TrialResult
 		const newPass = "trial-pass-1";
 		const setup = await setupMarketUrl({
 			projectRoot: site.root,
-			url: site.baseUrl,
+			siteUrl: site.baseUrl,
 			user: site.admin.user,
 			pass: site.admin.pass,
 			newPass,