@oj-module/cli 0.2.29 → 0.2.42

package/src/enable.ts

@@ -4,7 +4,7 @@ import process from "node:process";
 import { callApi, login, resolveSite } from "./site";
 
 export interface EnableOptions {
-	url?: string
+	siteUrl?: string
 	user?: string
 	pass?: string
 	/** 测试注入；缺省 globalThis.fetch */

package/src/exit-codes.ts

@@ -0,0 +1,33 @@
+// 退出码契约（REG-R12）：0 成功 / 1 业务失败 / 2 用法错误。
+//
+// 为什么要三档而不是「非零即失败」：CI 里这两类失败的处置完全不同——
+//   · 1 = 命令跑通了、但业务说不（包不存在、签名不符、站点拒绝）→ 看输出修数据；
+//   · 2 = 命令根本没跑（选项拼错、必需参数缺失、互斥选项同时给）→ 改脚本。
+// 混在 1 里，CI 只能靠解析人话文案来分辨，而文案是会改的。
+//
+// 三类例外的边界（`exitCodeOf`）：
+//   · `UsageError` → 2（本文件显式构造的「用法」类错误，含 cac 的未知选项/未知命令）；
+//   · 其余一切 Error → 1（业务失败；未预期异常也归这里，不假装是用法问题）；
+//   · 成功 → 0（调用方不显式设置，进程自然退 0）。
+//
+// 纪律：只有**能指出改哪一行命令行**的错误才配 `UsageError`。拿不准就归 1——
+// 把业务失败误判成 2 会让 CI 去改脚本，比反过来更难查。
+
+export const EXIT_OK = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_USAGE = 2;
+
+/** 用法错误：消息必须是「怎么改命令行」的人话（含正确语法） */
+export class UsageError extends Error {
+	readonly exitCode = EXIT_USAGE;
+
+	constructor(message: string) {
+		super(message);
+		this.name = "UsageError";
+	}
+}
+
+/** 错误 → 退出码（`reportCliError` 与 index.ts 的兜底共用这一个判定） */
+export function exitCodeOf(error: unknown): number {
+	return error instanceof UsageError ? EXIT_USAGE : EXIT_FAILURE;
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 import process from "node:process";
-import { buildCli, localizeCacError, reportCliError, rewriteHelpArgv, unknownCommandResult } from "./cli";
+import { buildCli, localizeCacError, reportCliError, reportUnknownCommand, rewriteHelpArgv } from "./cli";
 import { isKnownCommand, resolveLang, usageText } from "./usage";
 import { readCliVersion } from "./versions";
 
@@ -14,7 +14,7 @@ async function main() {
 	}
 
 	const rewritten = rewriteHelpArgv(argv);
-	const cli = buildCli(process.cwd(), lang);
+	const cli = buildCli(process.cwd(), lang, { argv: rewritten });
 	let unknown: string | undefined;
 	cli.on("command:*", () => {
 		// cac 在 --help 输出后会 unsetMatchedCommand 再发 command:*（args[0] 可能是子命令，如 verify）——
@@ -25,13 +25,9 @@ async function main() {
 	});
 	cli.parse(["node", "ojm", ...rewritten]);
 
-	// 未知命令：help 形态报「未知命令」、否则打帮助；均 exit 1（裸 ojm 打帮助退 0 不变）
+	// 未知命令：help 形态报「未知命令」、否则打帮助；均 exit 2（裸 ojm 打帮助退 0 不变）
 	if (unknown !== undefined) {
-		const r = unknownCommandResult(unknown, lang, !!cli.options.help);
-		if (cli.options.help)
-			console.error(r.text);
-		else
-			console.log(r.text);
+		const r = reportUnknownCommand(unknown, lang, !!cli.options.help, rewritten);
 		process.exit(r.code);
 	}
 	if (argv.length === 0)
@@ -40,4 +36,4 @@ async function main() {
 
 main().catch((error: unknown) => reportCliError(localizeCacError(error, resolveLang()), (code) => {
 	process.exit(code);
-}));
+}, process.argv.slice(2)));

package/src/install.ts

@@ -8,8 +8,67 @@ import type { TaskRecord } from "./site";
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
+import { UsageError } from "./exit-codes";
+import { originOf, resolveRegistrySource } from "./registry-source";
 import { callApi, isFutureSchema, login, pollTask, resolveSite, TASK_SCHEMA_VERSION_KNOWN, unwrapEnvelope } from "./site";
 
+/**
+ * REG-R5 / S5-2②：安装目标的**唯一**归一点（grep 可证——全仓只有这一处把 `@scope/name`
+ * 换算成物理名 slug）。服务端 install 只认 slug（收到 `@`/`/` 即 400 `invalid_physical_name`），
+ * 所以「目录键 → 物理名」的换算必须只在 CLI 完成一次，绝不分层；服务端是最后一道闸。
+ *
+ * 形态：`@scope/name[@version]` / `scope/name[@version]` → slug=`scope-name`；裸 `slug[@version]`
+ * 视为已是物理名，原样透传。字符集与下游 `naming.ts` 的 `SEGMENT_RE`/`SLUG_RE` 同口径
+ * （小写字母开头 + 小写字母/数字/连字符，slug 上限 64），保证 CLI 推导的 slug 与发布侧落盘名逐字一致。
+ */
+const SEGMENT_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function parseRegistryTarget(raw: string): { slug: string, version: string | null } {
+	let rest = String(raw ?? "").trim().replace(/^@/, "");
+	if (rest === "")
+		throw new UsageError(`[ojm] 非法安装目标：「${raw}」（registry 源用法：ojm install @<scope>/<name>[@version] --registry <url>）`);
+	// 版本：尾随 @（与 scope 前缀的 @ 不冲突——先剥掉前缀 @ 再取 lastIndexOf）
+	let version: string | null = null;
+	const at = rest.lastIndexOf("@");
+	if (at > 0) {
+		version = rest.slice(at + 1);
+		rest = rest.slice(0, at);
+	}
+	if (rest.includes("/")) {
+		const slash = rest.indexOf("/");
+		const scope = rest.slice(0, slash);
+		const name = rest.slice(slash + 1);
+		if (!SEGMENT_RE.test(scope) || !SEGMENT_RE.test(name))
+			throw new UsageError(`[ojm] 目录键「${raw}」不合法：scope 与 name 都须匹配 ${SEGMENT_RE.source}（REG-R5）`);
+		const slug = `${scope}-${name}`;
+		if (!SLUG_RE.test(slug))
+			throw new UsageError(`[ojm] 物理名「${slug}」不合法：须匹配 ${SLUG_RE.source}（slug 上限 64 字符）`);
+		return { slug, version: version === "" ? null : version };
+	}
+	if (!SLUG_RE.test(rest))
+		throw new UsageError(`[ojm] 物理名「${rest}」不合法：须匹配 ${SLUG_RE.source}（裸 slug 须为小写字母开头的小写字母/数字/连字符）`);
+	return { slug: rest, version: version === "" ? null : version };
+}
+
+/**
+ * REG-R9② 旧站点拒：站点平台 API 版本是否 ≥ `min`。`undefined`（meta 端点缺失/未注入）按
+ * 旧版本处理——宁可不装，不静默降级到不支持 registry 源的站点。
+ */
+export function isSiteApiAtLeast(apiVersion: string | undefined, min: string): boolean {
+	if (apiVersion === undefined)
+		return false;
+	const parse = (v: string): [number, number, number] | null => {
+		const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+		return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])];
+	};
+	const a = parse(apiVersion);
+	const b = parse(min);
+	if (a === null || b === null)
+		return false;
+	return a[0] > b[0] || (a[0] === b[0] && (a[1] > b[1] || (a[1] === b[1] && a[2] >= b[2])));
+}
+
 export type Locale = "zh-CN" | "en-US";
 
 /** 契约附录 A 十阶段指引（zh/en 双语列；文案单一来源 = 契约附录 A 表，此处为渲染镜像） */
@@ -87,8 +146,8 @@ const VERIFY_CODE_COPY: Record<string, { reason: { zh: string, en: string }, hin
 	},
 	sig_format: {
 		reason: {
-			zh: "签名编码违规：公钥非 64 位 hex、签名非标准 base64（禁 base64url），或规范串版本标记非 v1",
-			en: "Signature encoding violation: public key is not 64-hex, signature is not standard base64 (base64url forbidden), or the canonical-version marker is not v1",
+			zh: "签名编码违规：公钥非 64 位 hex、签名非标准 base64（禁 base64url），或规范串版本标记非 v2",
+			en: "Signature encoding violation: public key is not 64-hex, signature is not standard base64 (base64url forbidden), or the canonical-version marker is not v2",
 		},
 		hint: {
 			zh: "请让发布方使用标准签名工具（ojm sign）重新签名",
@@ -184,7 +243,7 @@ export function parseTarget(target: string): InstallTarget {
 }
 
 export interface InstallOptions {
-	url?: string
+	siteUrl?: string
 	user?: string
 	pass?: string
 	/** file 源身份覆盖（文件名不可解析时的显式出口）；cdn 源同名冲突时报错提示二选一 */
@@ -193,6 +252,8 @@ export interface InstallOptions {
 	version?: string
 	/** 终态文案语言（缺省 zh-CN） */
 	locale?: string
+	/** REG-R9②：从指定 registry 源安装（白名单在服务端；旧站点 API < 0.2.0 不支持 → exit 1） */
+	registry?: string
 	/** 测试注入；缺省 globalThis.fetch */
 	fetchFn?: typeof fetch
 	/** 测试注入；缺省真睡 */
@@ -206,48 +267,69 @@ export interface InstallOptions {
  */
 export async function installCommand(target: string, opts: InstallOptions = {}): Promise<TaskRecord> {
 	const fetchFn = opts.fetchFn ?? globalThis.fetch;
-	const parsed = parseTarget(target);
 	const { base, user, pass } = resolveSite(opts);
 	const token = await login(fetchFn, base, user, pass);
 
 	let response: { task_id: string };
-	if (parsed.kind === "file") {
-		const name = opts.name ?? parsed.name;
-		if (name === null)
-			throw new Error(`[ojm] 无法从文件名推导方案名：${target}——请用 --name <name>（及 --version <version>）显式指定`);
-		const version = opts.version ?? parsed.version;
-		const bytes = new Uint8Array(fs.readFileSync(parsed.path));
-		const form = new FormData();
-		form.append("name", name);
-		if (version !== null)
-			form.append("version", version);
-		form.append("source", "file");
-		form.append("file", new Blob([bytes], { type: "application/gzip" }), path.basename(parsed.path));
-		// detached 侧车签名（P2-3，G4）：同目录 <tgz>.sig 自动探测随 multipart 第二文件上传——
-		// 缺签即被宿主 G4 拒（sig_missing 人话转述），与 Form B 同一信任模型
-		const sigPath = `${parsed.path}.sig`;
-		if (fs.existsSync(sigPath)) {
-			form.append("sig", new Blob([new Uint8Array(fs.readFileSync(sigPath))], { type: "application/json" }), path.basename(sigPath));
-			console.log(`[ojm] 已随包上传签名侧车：${path.basename(sigPath)}`);
-		}
-		else {
-			console.log(`[ojm] 未发现签名侧车（${path.basename(sigPath)}）——宿主验签硬 fail-closed，未签名包将被拒（sig_missing）；签名方法见 devkit「签名与信任」`);
-		}
-		const res = await fetchFn(`${base}/api/_platform/market/install`, {
-			method: "POST",
-			headers: { authorization: `Bearer ${token}` },
-			body: form,
+	if (opts.registry !== undefined) {
+		// REG-R9②：registry 源安装。归一（目录键 → slug）只在此一处；旧站点拒；白名单在服务端。
+		const src = resolveRegistrySource({ flag: opts.registry });
+		const { slug, version } = parseRegistryTarget(target);
+		if (opts.name !== undefined && opts.name !== slug)
+			throw new UsageError(`[ojm] --name「${opts.name}」与 registry 目标推导的物理名「${slug}」不一致——registry 源由目标推导身份，请二选一`);
+		// 旧站点拒：meta apiVersion < 0.2.0 不支持 registry 源（REG-R9② 升版反噬 F4 的人话面）
+		const meta = await callApi<{ apiVersion?: string }>(fetchFn, base, token, "GET", "/api/_platform/market/meta");
+		if (!isSiteApiAtLeast(meta.apiVersion, "0.2.0"))
+			throw new Error(`[ojm] 目标站点平台 API 版本过低（需 ≥ 0.2.0 才支持 --registry 源安装，实为 ${meta.apiVersion ?? "未知"}）——请升级目标站点的 oj-module，或改用 CDN/file 源`);
+		const registryOrigin = originOf(src.url) ?? src.url;
+		response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
+			name: slug,
+			version: opts.version ?? version,
+			source: "registry",
+			registry: registryOrigin,
 		});
-		response = await unwrapInstall(res);
+		console.log(`[ojm] 已从 registry 源提交安装任务（源 ${registryOrigin}，物理名 ${slug}）`);
 	}
 	else {
-		if (opts.name !== undefined && opts.name !== parsed.name)
-			throw new Error(`[ojm] --name「${opts.name}」与目标「${parsed.name}」不一致——请二选一`);
-		response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
-			name: parsed.name,
-			version: opts.version ?? parsed.version,
-			source: "cdn",
-		});
+		const parsed = parseTarget(target);
+		if (parsed.kind === "file") {
+			const name = opts.name ?? parsed.name;
+			if (name === null)
+				throw new Error(`[ojm] 无法从文件名推导方案名：${target}——请用 --name <name>（及 --version <version>）显式指定`);
+			const version = opts.version ?? parsed.version;
+			const bytes = new Uint8Array(fs.readFileSync(parsed.path));
+			const form = new FormData();
+			form.append("name", name);
+			if (version !== null)
+				form.append("version", version);
+			form.append("source", "file");
+			form.append("file", new Blob([bytes], { type: "application/gzip" }), path.basename(parsed.path));
+			// detached 侧车签名（P2-3，G4）：同目录 <tgz>.sig 自动探测随 multipart 第二文件上传——
+			// 缺签即被宿主 G4 拒（sig_missing 人话转述），与 Form B 同一信任模型
+			const sigPath = `${parsed.path}.sig`;
+			if (fs.existsSync(sigPath)) {
+				form.append("sig", new Blob([new Uint8Array(fs.readFileSync(sigPath))], { type: "application/json" }), path.basename(sigPath));
+				console.log(`[ojm] 已随包上传签名侧车：${path.basename(sigPath)}`);
+			}
+			else {
+				console.log(`[ojm] 未发现签名侧车（${path.basename(sigPath)}）——宿主验签硬 fail-closed，未签名包将被拒（sig_missing）；签名方法见 devkit「签名与信任」`);
+			}
+			const res = await fetchFn(`${base}/api/_platform/market/install`, {
+				method: "POST",
+				headers: { authorization: `Bearer ${token}` },
+				body: form,
+			});
+			response = await unwrapInstall(res);
+		}
+		else {
+			if (opts.name !== undefined && opts.name !== parsed.name)
+				throw new Error(`[ojm] --name「${opts.name}」与目标「${parsed.name}」不一致——请二选一`);
+			response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
+				name: parsed.name,
+				version: opts.version ?? parsed.version,
+				source: "cdn",
+			});
+		}
 	}
 
 	const record = await pollTask(fetchFn, base, token, response.task_id, { sleep: opts.sleep });

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

@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { DEFAULT_KEY_ID, isValidKeyId, keygenCommand } from "../../keygen";
 import { signCommand } from "../../sign";
 import { readPrivateKeyPem } from "../keygen";
-import { fingerprintOfPublicKey, signCanonical as signCanonicalLocal, verifyCanonical } from "../sign";
+import { CANON, fingerprintOfPublicKey, signCanonical as signCanonicalLocal, verifyCanonical } from "../sign";
 
 const tmp = path.join(os.tmpdir(), `ojm-authoring-${Date.now()}-${Math.random().toString(36).slice(2)}`);
 
@@ -66,20 +66,21 @@ describe("ojm sign 命令体（detached .sig，G4 载体）", () => {
 		fs.writeFileSync(TGZ, "demo-archive-bytes\n");
 	});
 
-	it("签名产出 .sig 五字段（alg/key_id/public_key/value/canon），且 verifyCanonical 通过", () => {
+	it("签名产出 .sig 六字段（alg/key_id/public_key/value/canon/registry_id），且 verifyCanonical 通过", () => {
 		const kp = keygenCommand({ id: "acme.market", out: path.join(tmp, "k"), yes: true, cwd: tmp });
-		const r = signCommand(TGZ, { id: "acme.market", key: kp.privateKeyPath });
+		const r = signCommand(TGZ, { id: "acme.market", key: kp.privateKeyPath, registryId: "oj-registry" });
 		const sig = JSON.parse(fs.readFileSync(r.sigPath, "utf8"));
 		expect(sig.alg).toBe("Ed25519");
 		expect(sig.key_id).toBe("acme.market");
 		expect(sig.public_key).toBe(kp.publicKeyHex);
-		expect(sig.canon).toBe("v1");
+		expect(sig.canon).toBe(CANON);
+		expect(sig.registry_id).toBe("oj-registry");
 		expect(verifyCanonical(sig.public_key, r.canonical, sig.value)).toBe(true);
 	});
 
 	it("--check 离线自检：真签名通过（checkPassed=true）；--key+--id 自定义位置", () => {
 		const kp = keygenCommand({ id: "acme.market", out: path.join(tmp, "k"), yes: true, cwd: tmp });
-		const r = signCommand(TGZ, { id: "acme.market", key: kp.privateKeyPath, check: true });
+		const r = signCommand(TGZ, { id: "acme.market", key: kp.privateKeyPath, check: true, registryId: "oj-registry" });
 		expect(r.checkPassed).toBe(true);
 	});
 

package/src/lifecycle/__tests__/fixtures/sig/demo-solution-0.2.0.tgz.bad.sig

@@ -2,6 +2,7 @@
   "alg": "Ed25519",
   "key_id": "ojm.test",
   "public_key": "6320cd295df4a2cf48b90282daae32e133fefd0459d71af92d6c376889d038ef",
-  "value": "AizOO9Xhj4iCJJj8GRORgl7G1IzvGHfEZ1tYq6NEuwxiVDdrX7Nu3sqhazxXyrfzybPa11M23RZtji4iLHq1Dw==",
-  "canon": "v1"
+  "value": "AOtQDT2VLSQrVespj5JLMBYTCdXdWVLKh7mowJJw/mrYvfrlTwnLKvpGIMLvDZYtD+XxlHoRN/lBFVHVirpAAw==",
+  "canon": "v2",
+  "registry_id": "test.registry"
 }

package/src/lifecycle/__tests__/fixtures/sig/demo-solution-0.2.0.tgz.sig

@@ -2,6 +2,7 @@
   "alg": "Ed25519",
   "key_id": "ojm.test",
   "public_key": "6320cd295df4a2cf48b90282daae32e133fefd0459d71af92d6c376889d038ef",
-  "value": "ZizOO9Xhj4iCJJj8GRORgl7G1IzvGHfEZ1tYq6NEuwxiVDdrX7Nu3sqhazxXyrfzybPa11M23RZtji4iLHq1Dw==",
-  "canon": "v1"
+  "value": "oOtQDT2VLSQrVespj5JLMBYTCdXdWVLKh7mowJJw/mrYvfrlTwnLKvpGIMLvDZYtD+XxlHoRN/lBFVHVirpAAw==",
+  "canon": "v2",
+  "registry_id": "test.registry"
 }

package/src/lifecycle/__tests__/fixtures/sig/demo-solution-0.2.0.tgz.unknown.sig

@@ -2,6 +2,7 @@
   "alg": "Ed25519",
   "key_id": "stranger.unknown",
   "public_key": "a329626d90b337a969f66b101ad8bda4dc95f8c6f000731083147c262e8bbabb",
-  "value": "A8X5XsXQJOvIY55I1Dnz7bB6Y/TY0yLJiGze9AFN+ZsHor5ZPlm09ZLgBRdaymw/cLaEgeSkLr6dnYXaKSDxDw==",
-  "canon": "v1"
+  "value": "qexZRu47FY3tGzjdutR0SxJ75v3ybCZNTZJmD/FbQQhhl+QWMaPCo9OKFsTsQHykB6vNXX3T921kqOM81mzkAA==",
+  "canon": "v2",
+  "registry_id": "test.registry"
 }

package/src/lifecycle/__tests__/fixtures/sig/gen-signed-fixtures.d.mts

@@ -2,9 +2,10 @@
 export declare const FIXTURE_NAME: string;
 export declare const FIXTURE_VERSION: string;
 export declare const CANON: string;
+export declare const FIXTURE_REGISTRY_ID: string;
 export declare const TRUSTED_KEY: { key_id: string, public_key_hex: string };
 export declare const UNKNOWN_KEY: { key_id: string, public_key_hex: string };
-export declare function canonicalString(name: string, version: string, sha256: string): string;
+export declare function canonicalString(registryId: string, slug: string, version: string, sha256: string): string;
 export declare function fingerprintOf(publicKeyHex: string): string;
 export declare function signCanonicalB64(privateKey: unknown, canonical: string): string;
 export declare function verifyCanonicalB64(publicKeyHex: string, canonical: string, valueB64: string): boolean;
@@ -14,8 +15,8 @@ export declare function generate(outDir?: string): {
 	tgzPath: string
 	paths: { tgz: string, good: string, bad: string, unknown: string }
 	sig: {
-		good: { alg: string, key_id: string, public_key: string, value: string, canon: string }
-		bad: { alg: string, key_id: string, public_key: string, value: string, canon: string }
-		unknown: { alg: string, key_id: string, public_key: string, value: string, canon: string }
+		good: { alg: string, key_id: string, public_key: string, value: string, canon: string, registry_id: string }
+		bad: { alg: string, key_id: string, public_key: string, value: string, canon: string, registry_id: string }
+		unknown: { alg: string, key_id: string, public_key: string, value: string, canon: string, registry_id: string }
 	}
 };

package/src/lifecycle/__tests__/fixtures/sig/gen-signed-fixtures.mjs

@@ -30,13 +30,15 @@ const FIXTURE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
 export const FIXTURE_NAME = "demo-solution";
 export const FIXTURE_VERSION = "0.2.0";
-/** 规范串版本标记（契约 §2.11：canon 字段恒 "v1"） */
-export const CANON = "v1";
+/** 规范串版本标记（REG-CS3 v2：canon 字段恒 "v2"） */
+export const CANON = "v2";
+/** 夹具签发方 registry 身份（REG-CS3 v2 规范串首段，跨仓重放判定真源） */
+export const FIXTURE_REGISTRY_ID = "test.registry";
 const SEED_PREFIX = "ojm-lifecycle-fixture-v1:";
 
-/** 契约 v1.3 §2.11 规范串格式（逐字，P2-1 照抄实现，禁止自造分隔符） */
-export function canonicalString(name, version, sha256) {
-	return `${name}@${version}:${sha256}`;
+/** REG-CS3 v2 规范串格式（逐字：`<registry_id>:<slug>@<version>:<sha256>`） */
+export function canonicalString(registryId, slug, version, sha256) {
+	return `${registryId}:${slug}@${version}:${sha256}`;
 }
 
 /** 指纹 = sha256Hex(publicKey) 全 64 hex（契约 §2.11，UI 分组展示用） */
@@ -155,7 +157,7 @@ function tamperFirstChar(valueB64) {
 export function generate(outDir = FIXTURE_DIR) {
 	const tgz = buildTgz(fixtureMembers());
 	const sha256 = createHash("sha256").update(tgz).digest("hex");
-	const canonical = canonicalString(FIXTURE_NAME, FIXTURE_VERSION, sha256);
+	const canonical = canonicalString(FIXTURE_REGISTRY_ID, FIXTURE_NAME, FIXTURE_VERSION, sha256);
 
 	const sigOf = (keyId, publicKeyHex, privateKey) => ({
 		alg: "Ed25519",
@@ -163,6 +165,7 @@ export function generate(outDir = FIXTURE_DIR) {
 		public_key: publicKeyHex,
 		value: signCanonicalB64(privateKey, canonical),
 		canon: CANON,
+		registry_id: FIXTURE_REGISTRY_ID,
 	});
 
 	const good = sigOf(TRUSTED_KEY.key_id, TRUSTED_KEY.public_key_hex, trusted.privateKey);

package/src/lifecycle/__tests__/helpers.ts

@@ -26,13 +26,15 @@ export function nodeVerifyEd25519(publicKeyHex: string, msg: string, sigB64: str
 	}
 }
 
-/** detached 侧车 / Form B archive.signature 的字段形状（契约 §2.11 / C2-35） */
+/** detached 侧车 / Form B archive.signature 的字段形状（契约 §2.11 / C2-35，REG-CS3 增 registry_id） */
 export interface SigFile {
 	alg: string
 	key_id: string
 	public_key: string
 	value: string
 	canon: string
+	/** 签发方 registry 身份（REG-CS3 v2 规范串首段；跨仓重放判定真源） */
+	registry_id: string
 }
 
 export interface SignedArchive {
@@ -54,15 +56,17 @@ export function defaultTestKey(): KeyPair {
 }
 
 /**
- * 对 tgz 字节签名：sha256(bytes) → 规范串 → Ed25519 → .sig 五字段。
- * `keyPair` 缺省 = defaultTestKey()；传第二个 keyPair 即「未知发布方」场景。
+ * 对 tgz 字节签名：sha256(bytes) → 规范串（REG-CS3 v2：`<registry_id>:<slug>@<version>:<sha256>`）
+ * → Ed25519 → .sig 五字段 + registry_id。
+ * `keyPair` 缺省 = defaultTestKey()；传第二个 keyPair 即「未知发布方」场景；`registryId` 缺省 = "test.registry"。
  */
-export function signedArchiveFor(tgz: Uint8Array, name: string, version: string, opts?: { keyPair?: KeyPair, keyId?: string }): SignedArchive {
+export function signedArchiveFor(tgz: Uint8Array, name: string, version: string, opts?: { keyPair?: KeyPair, keyId?: string, registryId?: string }): SignedArchive {
 	const keyPair = opts?.keyPair ?? defaultTestKey();
+	const registryId = opts?.registryId ?? "test.registry";
 	const sha256 = createHash("sha256").update(tgz).digest("hex");
-	const value = signCanonical(keyPair.privateKeyPem, canonicalString(name, version, sha256));
+	const value = signCanonical(keyPair.privateKeyPem, canonicalString(registryId, name, version, sha256));
 	return {
-		sig: { alg: SIG_ALG, key_id: opts?.keyId ?? "test.publisher", public_key: keyPair.publicKeyHex, value, canon: CANON },
+		sig: { alg: SIG_ALG, key_id: opts?.keyId ?? "test.publisher", public_key: keyPair.publicKeyHex, value, canon: CANON, registry_id: registryId },
 		keyId: opts?.keyId ?? "test.publisher",
 		publicKeyHex: keyPair.publicKeyHex,
 		fingerprint: fingerprintOfPublicKey(keyPair.publicKeyHex),

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

@@ -7,7 +7,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { setEnabledCommand } from "../../enable";
-import { installCommand, parseTarget, renderOutcome } from "../../install";
+import { installCommand, isSiteApiAtLeast, parseRegistryTarget, parseTarget, renderOutcome } from "../../install";
 import { pollTask, resolveSite } from "../../site";
 
 /** 终态记录工厂（§10.2 形状，测试只需关键字段） */
@@ -71,12 +71,12 @@ describe("resolveSite · 站点寻址（flag > 环境变量 > 缺省模板 serve
 		expect(resolveSite({ user: "u", pass: "p" })).toEqual({ base: "http://127.0.0.1:9778", user: "u", pass: "p" });
 	});
 
-	it("环境变量 OJM_URL/OJM_USER/OJM_PASS 兜底；flag 优先；尾斜杠归一", () => {
-		process.env.OJM_URL = "http://env:9/";
+	it("环境变量 OJM_SITE_URL/OJM_USER/OJM_PASS 兜底；flag 优先；尾斜杠归一", () => {
+		process.env.OJM_SITE_URL = "http://env:9/";
 		process.env.OJM_USER = "eu";
 		process.env.OJM_PASS = "ep";
 		expect(resolveSite({})).toEqual({ base: "http://env:9", user: "eu", pass: "ep" });
-		expect(resolveSite({ url: "http://flag:8/", user: "fu", pass: "fp" }).base).toBe("http://flag:8");
+		expect(resolveSite({ siteUrl: "http://flag:8/", user: "fu", pass: "fp" }).base).toBe("http://flag:8");
 	});
 
 	it("缺凭据即人话报错（凭据只走内存不落盘）", () => {
@@ -251,7 +251,7 @@ describe("schemaVersion 旧记录兼容（P2-10 升版纪律读方侧：高版
 		const exitBackup = process.exitCode;
 		process.exitCode = 0;
 		try {
-			await installCommand(tgz, { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+			await installCommand(tgz, { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 			expect(process.exitCode).toBe(1);
 		}
 		finally {
@@ -354,7 +354,7 @@ describe("installCommand · file 源端到端（stub fetch：登录 → multipar
 			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
 			"/api/_platform/market/task": () => ok(rec()),
 		});
-		await installCommand(tgz, { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+		await installCommand(tgz, { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 		// 登录体
 		const loginBody = JSON.parse(String(calls[0]?.init?.body));
 		expect(loginBody).toEqual({ username: "u", password: "p" });
@@ -388,7 +388,7 @@ describe("installCommand · file 源端到端（stub fetch：登录 → multipar
 		const exitBackup = process.exitCode;
 		process.exitCode = 0;
 		try {
-			await installCommand(tgz, { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+			await installCommand(tgz, { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 			expect(process.exitCode).toBe(1);
 		}
 		finally {
@@ -400,13 +400,13 @@ describe("installCommand · file 源端到端（stub fetch：登录 → multipar
 	it("detached 侧车自动探测（P2-3，G4）：同目录 .sig 随 multipart 第二文件上传", async () => {
 		const tgz = join(dir, "demo-solution-0.1.0.tgz");
 		writeFileSync(tgz, "fake-tgz-bytes");
-		writeFileSync(`${tgz}.sig`, JSON.stringify({ alg: "Ed25519", key_id: "test.publisher", public_key: "a".repeat(64), value: "AAAA", canon: "v1" }));
+		writeFileSync(`${tgz}.sig`, JSON.stringify({ alg: "Ed25519", key_id: "test.publisher", public_key: "a".repeat(64), value: "AAAA", canon: "v2", registry_id: "test.registry" }));
 		const { fetchFn, calls } = fetchStub({
 			"/api/auth/login": () => ok({ access_token: "tok", refresh_token: "r", expires_in: 1 }),
 			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
 			"/api/_platform/market/task": () => ok(rec()),
 		});
-		await installCommand(tgz, { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+		await installCommand(tgz, { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 		const form = calls[1]?.init?.body as FormData;
 		expect(form.get("sig")).toBeInstanceOf(File);
 		expect((form.get("sig") as File).name).toBe("demo-solution-0.1.0.tgz.sig");
@@ -421,7 +421,7 @@ describe("installCommand · file 源端到端（stub fetch：登录 → multipar
 			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
 			"/api/_platform/market/task": () => ok(rec()),
 		});
-		await installCommand(tgz, { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+		await installCommand(tgz, { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 		const form = calls[1]?.init?.body as FormData;
 		expect(form.get("sig")).toBeNull();
 		expect(logs.join("\n")).toContain("未发现签名侧车");
@@ -433,7 +433,7 @@ describe("installCommand · file 源端到端（stub fetch：登录 → multipar
 		const { fetchFn } = fetchStub({
 			"/api/auth/login": () => ({ ok: true, status: 200, text: async () => JSON.stringify({ code: 401, msg: "invalid credentials" }) }),
 		});
-		await expect(installCommand(tgz, { url: "http://x", user: "u", pass: "bad", fetchFn })).rejects.toThrow(/invalid credentials/);
+		await expect(installCommand(tgz, { siteUrl: "http://x", user: "u", pass: "bad", fetchFn })).rejects.toThrow(/invalid credentials/);
 	});
 });
 
@@ -444,7 +444,7 @@ describe("installCommand · cdn 源（JSON 体 name@version）", () => {
 			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
 			"/api/_platform/market/task": () => ok(rec()),
 		});
-		await installCommand("demo-solution", { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+		await installCommand("demo-solution", { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 		const installCall = calls[1]!;
 		expect((installCall.init?.headers as Record<string, string>)["content-type"]).toBe("application/json");
 		expect(JSON.parse(String(installCall.init?.body))).toEqual({ name: "demo-solution", version: null, source: "cdn" });
@@ -456,7 +456,7 @@ describe("installCommand · cdn 源（JSON 体 name@version）", () => {
 			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
 			"/api/_platform/market/task": () => ok(rec()),
 		});
-		await installCommand("demo-solution@0.2.0", { url: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
+		await installCommand("demo-solution@0.2.0", { siteUrl: "http://x", user: "u", pass: "p", fetchFn, sleep: async () => {} });
 		expect(JSON.parse(String(calls[1]?.init?.body)).version).toBe("0.2.0");
 	});
 });
@@ -467,7 +467,7 @@ describe("setEnabledCommand · enable/disable 瘦客户端（D8）", () => {
 			"/api/auth/login": () => ok({ access_token: "tok", refresh_token: "r", expires_in: 1 }),
 			"/api/_platform/market/enable": () => ok({ ok: true, message: "启用完成：四处同写" }),
 		});
-		await setEnabledCommand("demo-solution", true, { url: "http://x", user: "u", pass: "p", fetchFn });
+		await setEnabledCommand("demo-solution", true, { siteUrl: "http://x", user: "u", pass: "p", fetchFn });
 		const call = calls[1]!;
 		expect(call.url).toContain("/api/_platform/market/enable");
 		expect(JSON.parse(String(call.init?.body))).toEqual({ name: "demo-solution", enabled: true });
@@ -480,7 +480,7 @@ describe("setEnabledCommand · enable/disable 瘦客户端（D8）", () => {
 				"/api/auth/login": () => ok({ access_token: "tok", refresh_token: "r", expires_in: 1 }),
 				"/api/_platform/market/enable": () => ok({ ok: false, message: "禁用失败：「x」未安装" }),
 			});
-			await setEnabledCommand("x", false, { url: "http://x", user: "u", pass: "p", fetchFn: fetchFn2 });
+			await setEnabledCommand("x", false, { siteUrl: "http://x", user: "u", pass: "p", fetchFn: fetchFn2 });
 			expect(process.exitCode).toBe(1);
 		}
 		finally {
@@ -489,3 +489,60 @@ describe("setEnabledCommand · enable/disable 瘦客户端（D8）", () => {
 		expect(logs.join("\n")).toContain("禁用失败：「x」未安装");
 	});
 });
+
+describe("s5-2② REG-R9 install 源切换：registry（CLI 归一 + 旧站点拒）", () => {
+	it("parseRegistryTarget：@scope/name → slug=scope-name、version=null", () => {
+		expect(parseRegistryTarget("@acme/demo")).toEqual({ slug: "acme-demo", version: null });
+	});
+
+	it("parseRegistryTarget：@scope/name@version 拆出版本；acme/demo 等价", () => {
+		expect(parseRegistryTarget("@acme/demo@1.2.3")).toEqual({ slug: "acme-demo", version: "1.2.3" });
+		expect(parseRegistryTarget("acme/demo@1.2.3")).toEqual({ slug: "acme-demo", version: "1.2.3" });
+	});
+
+	it("parseRegistryTarget：裸 slug 原样透传（含 @version）", () => {
+		expect(parseRegistryTarget("acme-demo")).toEqual({ slug: "acme-demo", version: null });
+		expect(parseRegistryTarget("acme-demo@2.0.0")).toEqual({ slug: "acme-demo", version: "2.0.0" });
+	});
+
+	it("parseRegistryTarget：大写/空段/空串即抛 UsageError（REG-R5 字符集）", () => {
+		expect(() => parseRegistryTarget("@ACME/demo")).toThrow(/REG-R5/);
+		expect(() => parseRegistryTarget("@acme/")).toThrow();
+		expect(() => parseRegistryTarget("")).toThrow(/registry 源用法/);
+	});
+
+	it("isSiteApiAtLeast：0.1.0 < 0.2.0 → false；0.2.0/0.2.1 → true；undefined → false", () => {
+		expect(isSiteApiAtLeast("0.1.0", "0.2.0")).toBe(false);
+		expect(isSiteApiAtLeast("0.2.0", "0.2.0")).toBe(true);
+		expect(isSiteApiAtLeast("0.2.1", "0.2.0")).toBe(true);
+		expect(isSiteApiAtLeast(undefined, "0.2.0")).toBe(false);
+	});
+
+	it("installCommand registry：新站点（apiVersion 0.2.0）POST source=registry + registry=origin（slug 归一）", async () => {
+		const { fetchFn, calls } = fetchStub({
+			"/api/auth/login": () => ok({ access_token: "tok" }),
+			"/api/_platform/market/meta": () => ok({ apiVersion: "0.2.0" }),
+			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
+			"/api/_platform/market/task": () => ok(rec()),
+		});
+		const r = await installCommand("@acme/demo", { siteUrl: "http://site", user: "u", pass: "p", registry: "https://r.example.com/", fetchFn });
+		expect(r.status).toBe("done");
+		const call = calls.find(c => c.url.includes("/api/_platform/market/install"));
+		expect(call).toBeDefined();
+		const body = JSON.parse(String(call!.init!.body));
+		expect(body).toMatchObject({ name: "acme-demo", source: "registry", registry: "https://r.example.com" });
+		expect(body.version).toBeNull();
+	});
+
+	it("installCommand registry：旧站点（apiVersion 0.1.0）→ 抛「站点版本过低」且不 POST install", async () => {
+		const { fetchFn, calls } = fetchStub({
+			"/api/auth/login": () => ok({ access_token: "tok" }),
+			"/api/_platform/market/meta": () => ok({ apiVersion: "0.1.0" }),
+			"/api/_platform/market/install": () => ok({ task_id: "t1" }),
+		});
+		await expect(installCommand("@acme/demo", { siteUrl: "http://site", user: "u", pass: "p", registry: "https://r.example.com", fetchFn }))
+			.rejects
+			.toThrow(/版本过低/);
+		expect(calls.some(c => c.url.includes("/api/_platform/market/install"))).toBe(false);
+	});
+});