@oj-module/cli 0.2.2 → 0.2.6

package/src/init.ts

@@ -1,8 +1,8 @@
 /**
  * `ojm init` —— 前后端一体化工程脚手架（设计 §3，D1/D3/D6/D10）。
  *
- * 产物：api/（oj 后端 + 现场签发证书 + seed）、web/src/（前端模块）、
- * bin/（从 everpan/only-js 最新 release 联网下载：oj + plugins + devkit）、
+ * 产物：api/（oj 后端 + seed）、config/（config.yaml + 现场签发证书，与 api/、web/ 同级）、
+ * web/src/（前端模块）、bin/（从 everpan/only-js 最新 release 联网下载：oj + plugins + devkit）、
  * 工程配置文件。
  *
  * 幂等补缺：对既有工程重跑只补缺失文件（bin/oj 已在则跳过下载），config.yaml 与
@@ -15,6 +15,8 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import yaml from "yaml";
+import { resolveCertDir, resolveConfigPath } from "./layout";
 import { mintDevCert } from "./oj-cert";
 import { resolveOjBin, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
@@ -56,13 +58,15 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	const templatesDir = path.join(cliRoot, "templates");
 	const jwtSecret = crypto.randomBytes(32).toString("hex");
 	const projectName = path.basename(destDir);
+	const include = readInitInclude(templatesDir);
 	copyTemplates(templatesDir, destDir, {
 		__JWT_SECRET__: jwtSecret,
 		__PROJECT_NAME__: projectName,
-	}, report);
+	}, report, include, templatesDir);
+	pruneUnincludedApiPaths(destDir, include, report);
 
-	// 2) 证书三件套（现场签发，D6）
-	const certDir = path.join(destDir, "api/config");
+	// 2) 证书三件套（现场签发，D6）——落点即 resolveCertDir()（config.yaml 同级的 config/）
+	const certDir = resolveCertDir(destDir);
 	if (fs.existsSync(path.join(certDir, "cert.jws"))) {
 		report.skipped.push("api/config/cert.jws");
 	}
@@ -142,6 +146,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	// 的「已存在即跳过」会把审批挡在门外（0.1.0 发布实测）——必须合并
 	ensureAllowBuilds(destDir, report);
 
+	// 5c) .gitignore：模板自带一份（模板兼作可运行 demo 用），但 npm/pnpm pack
+	//     会剥离 `.gitignore` 点文件（npm-packlist always-exclude，`files` 字段
+	//     绕不过），收录进 init.include.yaml 只会让安装包缺文件、readInitInclude
+	//     fail-fast 把整个 init 打挂（0.2.5 发布实测：目标目录只剩空壳）——
+	//     与 pnpm-workspace.yaml 同型，改由 init 现场生成
+	ensureGitignore(destDir, report);
+
 	console.log(`[ojm] init 完成：${destDir}`);
 	console.log(`[ojm]   新增 ${report.created.length} 项，跳过（已存在）${report.skipped.length} 项`);
 	for (const item of report.skipped)
@@ -154,7 +165,7 @@ const defaultSealer: Sealer = async (destDir, plainSecret) => {
 	const ojBin = resolveOjBin(destDir);
 	if (!fs.existsSync(ojBin))
 		return null;
-	const keysDir = path.join(destDir, "api/config");
+	const keysDir = resolveCertDir(destDir);
 	const publicKey = path.join(keysDir, "secrets-public.pem");
 	try {
 		fs.mkdirSync(keysDir, { recursive: true });
@@ -178,7 +189,7 @@ const defaultSealer: Sealer = async (destDir, plainSecret) => {
  * 并补 `secrets:` 段指向私钥。失败一律降级为明文 + 告警——init 不因加密失败而失败。
  */
 async function sealJwtSecret(destDir: string, report: InitReport, seal: Sealer = defaultSealer): Promise<void> {
-	const configPath = path.join(destDir, "api/config.yaml");
+	const configPath = resolveConfigPath(destDir);
 	if (!fs.existsSync(configPath))
 		return;
 	const text = fs.readFileSync(configPath, "utf-8");
@@ -192,43 +203,68 @@ async function sealJwtSecret(destDir: string, report: InitReport, seal: Sealer =
 		return;
 	}
 	const next = text.replace(match[0], `${match.groups.indent}jwt_secret: "${sealed}"`);
-	// secrets 段：私钥只放部署机，路径相对 config 目录
+	// secrets 段：私钥只放部署机，路径相对 config 目录（config.yaml 同级）
 	const withSecrets = `${next.trimEnd()}\nsecrets:\n  private_key_path: ./config/secrets-private.pem\n  public_key_path: ./config/secrets-public.pem\n`;
 	fs.writeFileSync(configPath, withSecrets);
 	report.created.push("api/config/{secrets-private.pem,secrets-public.pem} + auth.jwt_secret 已密封（ENC[...]）");
 }
 
-/** 递归拷贝模板；文本文件做占位符替换；已存在的目标文件一律跳过 */
+/**
+ * 递归拷贝模板；文本文件做占位符替换；已存在的目标文件一律跳过。
+ *
+ * 白名单语义（init.include.yaml）：清单内路径整棵拷贝；清单外一律不拷、不计入
+ * created/skipped（demo 模块/模板自运行产物/元数据的大头在清单外）。清单外的
+ * 目录仅在「有收录子孙」时才穿行（如 `api/`、`web/src/`、`web/src/demo/`——
+ * 只收录了后者底下的 entry/locales/pages），穿行时未收录的子项继续被挡下。
+ */
 function copyTemplates(
 	srcDir: string,
 	destDir: string,
 	placeholders: Record<string, string>,
 	report: InitReport,
+	include: Set<string>,
+	rootDir: string,
+	underIncluded = false,
 ): void {
 	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
 		const src = path.join(srcDir, entry.name);
 		const dest = path.join(destDir, entry.name);
+		const srcRel = path.relative(rootDir, src);
+		const listed = include.has(srcRel);
+		if (!underIncluded && !listed && !hasIncludedDescendant(include, srcRel))
+			continue;
 		if (entry.isDirectory()) {
 			// 空目录不进工程：git 不跟踪空目录，模板里残留的空目录（如误建的
 			// api/src/_shared）会被 oj build 当作缺 manifest.yaml 的模块 fail-fast
 			if (!dirHasFiles(src))
 				continue;
 			fs.mkdirSync(dest, { recursive: true });
-			copyTemplates(src, dest, placeholders, report);
+			copyTemplates(src, dest, placeholders, report, include, rootDir, underIncluded || listed);
 			continue;
 		}
-		const rel = path.relative(destDir, dest);
+		const destRel = path.relative(destDir, dest);
 		if (fs.existsSync(dest)) {
-			report.skipped.push(rel);
+			report.skipped.push(destRel);
 			continue;
 		}
 		let content = fs.readFileSync(src, "utf-8");
 		for (const [token, value] of Object.entries(placeholders))
 			content = content.replaceAll(token, value);
+		content = stripRegion(content, "demo-only");
 		fs.mkdirSync(path.dirname(dest), { recursive: true });
 		fs.writeFileSync(dest, content);
-		report.created.push(rel);
+		report.created.push(destRel);
+	}
+}
+
+/** srcRel 是否为白名单里某条收录路径的祖先目录——决定清单外目录要不要穿行 */
+function hasIncludedDescendant(include: Set<string>, srcRel: string): boolean {
+	const prefix = `${srcRel}/`;
+	for (const p of include) {
+		if (p.startsWith(prefix))
+			return true;
 	}
+	return false;
 }
 
 /** 目录（递归）是否含至少一个文件——空目录判定供 copyTemplates 跳过用 */
@@ -242,6 +278,85 @@ function dirHasFiles(dir: string): boolean {
 	return false;
 }
 
+/**
+ * 读取模板根 `init.include.yaml` 的 `include` 白名单，归一为相对模板根的路径集合。
+ * 清单随模板一起发布，缺失即安装包损坏——直接 fail-fast，不留「静默少拷」的
+ * 退化路径。条目指向不存在的路径同样 fail-fast：拼错一个目录名不会当场报错，
+ * 只会在用户工程里留下难以追溯的缺文件（旧 exclude 清单没有这类校验面）。
+ */
+function readInitInclude(templatesDir: string): Set<string> {
+	const yamlPath = path.join(templatesDir, "init.include.yaml");
+	if (!fs.existsSync(yamlPath))
+		throw new Error(`模板缺少 init.include.yaml：${yamlPath}（安装包损坏？）`);
+	const doc = yaml.parse(fs.readFileSync(yamlPath, "utf-8")) as { include?: string[] } | null;
+	const out = new Set<string>();
+	for (const raw of doc?.include ?? []) {
+		const p = path.normalize(raw).replace(/^(\.\/)+/, "");
+		out.add(p);
+		if (!fs.existsSync(path.join(templatesDir, p)))
+			throw new Error(`init.include.yaml 收录了不存在的路径：${p}（拼写错误或模板缺文件？）`);
+	}
+	return out;
+}
+
+/**
+ * 从脚手架产出的 openapi.json 里删掉未进白名单的 api 模块端点。
+ *
+ * 模板的 openapi.json 是「全量演示工程」的产物，含 demo-only 模块（demo/home）
+ * 的端点；这些模块的文件不拷进新工程，契约里留着它们会让 `ojm api --check`
+ * 一上手就报「openapi 多」（有契约无 handler）。故只保留白名单内 api 模块
+ * 名下的 `/api/<mod>/` 路径，其余裁掉——契约与脚手架实际模块严格一致。
+ */
+function pruneUnincludedApiPaths(destDir: string, include: Set<string>, report: InitReport): void {
+	// 只裁本次新建的 openapi.json：init 是幂等补缺，不改动既有工程文件
+	if (!report.created.includes("openapi.json"))
+		return;
+	const mods = new Set([...include]
+		.map(p => (p.startsWith("api/src/") ? p.slice("api/src/".length) : null))
+		.filter((m): m is string => !!m && !m.includes("/")));
+	if (mods.size === 0)
+		return;
+	const openapiPath = path.join(destDir, "openapi.json");
+	const doc = JSON.parse(fs.readFileSync(openapiPath, "utf-8")) as { paths?: Record<string, unknown> };
+	const paths = doc.paths ?? {};
+	const dropped = Object.keys(paths).filter((p) => {
+		const mod = /^\/api\/([^/]+)\//.exec(p)?.[1];
+		return !!mod && !mods.has(mod);
+	});
+	if (dropped.length === 0)
+		return;
+	for (const p of dropped)
+		delete paths[p];
+	fs.writeFileSync(openapiPath, `${JSON.stringify(doc, null, "\t")}\n`);
+	report.created.push(`openapi.json 裁掉未收录 api 模块端点 ${dropped.length} 条`);
+}
+
+/**
+ * 删除文本里的 `#region <name>` … `#endregion` 区间（含标记行本身）。
+ * 用于把模板内置的 demo-only 模块条目从脚手架产出的配置里剥离，避免留下
+ * 指向未拷贝文件的死条目。标记写不成对时原样返回，不做猜测。
+ */
+function stripRegion(text: string, name: string): string {
+	const lines = text.split("\n");
+	const start = new RegExp(`^\\s*//\\s*#region\\s+${name}\\b`);
+	const end = /^\s*\/\/\s*#endregion\b/;
+	const kept: string[] = [];
+	let inRegion = false;
+	for (const line of lines) {
+		if (inRegion) {
+			if (end.test(line))
+				inRegion = false;
+			continue;
+		}
+		if (start.test(line)) {
+			inRegion = true;
+			continue;
+		}
+		kept.push(line);
+	}
+	return inRegion ? text : kept.join("\n");
+}
+
 function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	if (fs.existsSync(dest)) {
 		report.skipped.push(path.basename(dest));
@@ -253,14 +368,74 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 }
 
 /**
- * 确保 pnpm-workspace.yaml 的 allowBuilds 含 `esbuild: true`。
+ * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
+ *
+ * 内容与 templates/.gitignore 对齐（模板兼作可运行 demo，ignore 的是同一套
+ * 现场产物）：dev 下载的 bin/oj、sqlite/日志/现场签发的私钥与证书、构建产物。
+ * 它不能随模板拷贝——npm/pnpm pack 剥离 `.gitignore`，详见 initProject 5c。
+ */
+const SCAFFOLD_GITIGNORE = `# 由 ojm init 生成。
+node_modules/
+bin/
+.ojm-tmp-*
+# 本地 sqlite 与运行日志
+api/db.sqlite
+api/db.sqlite-shm
+api/db.sqlite-wal
+api/logs/
+# 现场签发的开发证书与凭据私钥（ojm dev 缺证时自动签发，见 oj-cert.ts）；私钥绝不入仓
+api/config/*.pem
+api/config/cert.jws
+# 构建产物
+api/dist/
+web/dist/
+modules/dist/
+`;
+
+function ensureGitignore(destDir: string, report: InitReport): void {
+	const gitignorePath = path.join(destDir, ".gitignore");
+	if (fs.existsSync(gitignorePath)) {
+		report.skipped.push(".gitignore");
+		return;
+	}
+	fs.writeFileSync(gitignorePath, SCAFFOLD_GITIGNORE);
+	report.created.push(".gitignore");
+}
+
+/**
+ * 确保工程根 pnpm-workspace.yaml 的 allowBuilds 含 `esbuild: true`。
+ *  - 文件不存在（本函数即唯一来源，见下）→ 按 SCAFFOLD_WORKSPACE_YAML 生成
  *  - pnpm v11 自动生成的占位行（"set this to true or false"）→ 填 true
  *  - 有 allowBuilds 段无 esbuild 行 → 段内追加
  *  - 无 allowBuilds 段 → 文末追加整段
  *  - 显式 `esbuild: false` → 用户的选择，尊重不动
+ *
+ * 本文件由 init 生成而非模板拷贝：模板目录本身是根 workspace 的成员，若带一份
+ * pnpm-workspace.yaml，pnpm 会就近把它当 workspace 根，`cd templates && pnpm i`
+ * 就找不到父级 catalog（ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC）。
  */
+const SCAFFOLD_WORKSPACE_YAML = `# 由 ojm init 生成。
+# pnpm v11 起构建审批只读 pnpm-workspace.yaml（package.json 的 pnpm 字段
+# 已废弃）。缺了 allowBuilds，esbuild 的 postinstall 会被默认拦截，之后所有
+# pnpm 命令报 ERR_PNPM_IGNORED_BUILDS。
+allowBuilds:
+  esbuild: true
+
+# @oj-module/cli 经 catalog: 拉 @redocly/cli，而 catalog 只作用于 workspace
+# 自有 package.json 的依赖，对 cli（外部包）的 catalog: 传递依赖无效；不钉的话
+# 会漂到 latest，撞本机 minimumReleaseAge 供应链策略被拒
+# （ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION）。钉到 cli 实测通过的 2.51.0。
+overrides:
+  '@redocly/cli': 2.51.0
+`;
+
 function ensureAllowBuilds(destDir: string, report: InitReport): void {
 	const yamlPath = path.join(destDir, "pnpm-workspace.yaml");
+	if (!fs.existsSync(yamlPath)) {
+		fs.writeFileSync(yamlPath, SCAFFOLD_WORKSPACE_YAML);
+		report.created.push("pnpm-workspace.yaml（构建审批 + redocly 钉版）");
+		return;
+	}
 	let content = fs.readFileSync(yamlPath, "utf-8");
 	if (/^\s+esbuild:\s*(?:true|false)\s*$/m.test(content)) {
 		if (/^\s+esbuild:\s*true\s*$/m.test(content))

package/src/install.ts

@@ -0,0 +1,268 @@
+import type { TaskRecord } from "./site";
+// ojm install（P1-13，D6）：方案包安装瘦客户端。目标两种形态：
+//   · 本地 tgz 路径（<name>-<version>.tgz 文件名推导身份，--name/--version 可覆盖）→ file 源 multipart 上传；
+//   · name[@version] → cdn 源（站点侧 Form B 索引解析，安装器不拼 URL——市场侧职责，api.ts 同纪律）。
+// 流程：登录 → POST /api/_platform/market/install → 轮询 task?id= 至终态 → 渲染。
+// 终态渲染（契约附录 A 同表取用，R28/DRY）：失败/partial 打 error.reason + retryable 标注 +
+// hintKey 对应双语指引（--locale zh-CN|en-US，缺省 zh-CN；文案真源为契约附录 A 表）。
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { callApi, isFutureSchema, login, pollTask, resolveSite, TASK_SCHEMA_VERSION_KNOWN, unwrapEnvelope } from "./site";
+
+export type Locale = "zh-CN" | "en-US";
+
+/** 契约附录 A 十阶段指引（zh/en 双语列；文案单一来源 = 契约附录 A 表，此处为渲染镜像） */
+const STAGE_HINTS: Record<string, { zh: string, en: string }> = {
+	preflight: { zh: "请修正方案清单或释放占用的名称与前缀后重新安装", en: "Fix the manifest or release the occupied name and prefix, then install again" },
+	downloading: { zh: "请检查网络与市场地址（框架设置 → 市场源），稍后重试", en: "Check the network and market URL (Framework settings → Market source), then retry" },
+	verifying: { zh: "分发包可能损坏，请重试下载；持续失败请联系发布方", en: "The archive may be corrupted; retry the download, or contact the publisher if it persists" },
+	extracting: { zh: "安装已终止且零落盘；若反复出现，请勿使用该分发包并联系发布方", en: "Installation aborted with nothing written; if it repeats, do not use this archive and contact the publisher" },
+	migrating: { zh: "数据已保留原状，请修复后重试；必要时回退到上一版本", en: "Data is left intact; fix the issue and retry, or roll back to the previous version if needed" },
+	lock_commit: { zh: "存在并发构建或安装，请稍后重试", en: "A concurrent build or install is in progress; retry later" },
+	registering: { zh: "请重试；多次失败请检查站点数据库状态", en: "Retry; if it keeps failing, check the site database state" },
+	deploying_web: { zh: "请重试；方案已部分生效，若持续失败请禁用该方案", en: "Retry; the solution is partially live — disable it if the failure persists" },
+	reloading: { zh: "站点仍在使用旧配置服务，请稍后重试或联系运维", en: "The site still serves the old config; retry later or contact ops" },
+	smoke: { zh: "方案已部分生效，请按详情排查；可先禁用该方案恢复原状", en: "The solution is partially live; inspect the details, or disable it to restore the previous state" },
+};
+
+/** retryable 全局两值（契约附录 A：全 stage 共用） */
+const RETRYABLE_LABELS: Record<Locale, { yes: string, no: string }> = {
+	"zh-CN": { yes: "本次失败可重试", no: "本次失败不可自动重试" },
+	"en-US": { yes: "This failure is retryable", no: "This failure is not retryable" },
+};
+
+/**
+ * verifying 段签名失败六码双语文案（契约附录 A.2；文案真源 = 契约附录 A.2 表，此处为渲染镜像，
+ * 缺失即测试红，同 C2-25 纪律）。`error.reason` 走 key（六码），渲染层按 locale 取本表；
+ * 非六码失败（其它 stage）reason 仍是服务端可读串，渲染原样回退（不丢信息）。
+ */
+const VERIFY_CODE_COPY: Record<string, { reason: { zh: string, en: string }, hint: { zh: string, en: string } }> = {
+	sig_missing: {
+		reason: {
+			zh: "缺少签名：未找到 detached 签名侧车（.sig）且市场清单无 signature 字段——宿主已启用强制验签，未签名包一律拒装",
+			en: "Missing signature: no detached .sig sidecar and the manifest has no signature field — the host enforces signing, so unsigned packages are rejected",
+		},
+		hint: {
+			zh: "请用 ojm sign 对包签名后重传，或确认市场源已发布带签名的版本",
+			en: "Sign the package with `ojm sign` and re-upload, or confirm the market source published a signed version",
+		},
+	},
+	sig_alg: {
+		reason: {
+			zh: "签名算法不被接受：仅支持 Ed25519（alg 必须逐字为 \"Ed25519\"，大小写敏感）",
+			en: "Unsupported signature algorithm: only Ed25519 is accepted (alg must be exactly \"Ed25519\", case-sensitive)",
+		},
+		hint: { zh: "请让发布方改用 Ed25519 签名", en: "Ask the publisher to sign with Ed25519" },
+	},
+	sig_key: {
+		reason: {
+			zh: "公钥标识（key_id）不合法，或与信任库绑定不一致（首次绑定不可覆盖）",
+			en: "Key identifier (key_id) is invalid, or does not match the trusted-key binding (first binding cannot be overwritten)",
+		},
+		hint: {
+			zh: "请核对 key_id 命名空间（<publisher>.<id>），或联系运维将正确公钥加入信任库",
+			en: "Check the key_id namespace (<publisher>.<id>), or ask ops to add the correct public key to the trust store",
+		},
+	},
+	tampered: {
+		reason: {
+			zh: "验签失败：包体、公钥或签名任一被篡改（Ed25519 验签返回 false）",
+			en: "Signature verification failed: the archive, public key, or signature was tampered with (Ed25519 verify returned false)",
+		},
+		hint: {
+			zh: "重新下载安装包并核对发布方指纹；若持续失败请勿使用该包",
+			en: "Re-download the package and verify the publisher's fingerprint; if it persists, do not use this package",
+		},
+	},
+	unknown_key: {
+		reason: {
+			zh: "未知发布方（key_id 不在信任库）：需经 TOFU 确认后方可安装",
+			en: "Unknown publisher (key_id not in the trust store): requires TOFU confirmation before install",
+		},
+		hint: {
+			zh: "请与发布方核对指纹后执行 ojm trust confirm --task <id>",
+			en: "Verify the fingerprint with the publisher, then run `ojm trust confirm --task <id>`",
+		},
+	},
+	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",
+		},
+		hint: {
+			zh: "请让发布方使用标准签名工具（ojm sign）重新签名",
+			en: "Ask the publisher to re-sign with the standard tooling (ojm sign)",
+		},
+	},
+};
+
+function normalizeLocale(locale?: string): Locale {
+	return locale === "en-US" || locale === "en" ? "en-US" : "zh-CN";
+}
+
+/**
+ * 终态渲染（纯函数，人话多行文本）：done 单行；failed/partial = 标题 + 原因 + 指引 + 重试标注
+ * （hintKey 随标注行附上，便于对照契约附录 A）。
+ */
+export function renderOutcome(record: TaskRecord, locale?: string): string {
+	const lang = normalizeLocale(locale);
+	// P2-10 升版纪律（读方）：不认识的高版本 → 人话降级提示 + 不误渲染成功——
+	// 语义可能已漂移（status 字段含义不再可信），只出降级提示，连 done 也不报「安装完成」
+	if (isFutureSchema(record)) {
+		return lang === "en-US"
+			? `[ojm] Task record schema version ${record.schemaVersion} is newer than this CLI supports (${TASK_SCHEMA_VERSION_KNOWN}) — fields may be missing or semantics drifted. Upgrade ojm and retry.`
+			: `[ojm] 任务记录 schema 版本 ${record.schemaVersion} 高于本 CLI 支持的版本（${TASK_SCHEMA_VERSION_KNOWN}）——字段可能缺失或语义漂移，请升级 ojm 后重试。`;
+	}
+	if (record.status === "done") {
+		return lang === "en-US"
+			? `[ojm] Install complete: ${record.name} ${record.version}`
+			: `[ojm] 安装完成：${record.name} ${record.version}`;
+	}
+	if (record.status === "needs_trust") {
+		// 第五终态（P2-3，G3）：未知发布方待 TOFU 确认——**非成功态、非失败崩溃**；
+		// 指纹分组展示 + 确认命令 + 重试指引（契约附录 A.2 unknown_key）
+		const t = record.trust;
+		const fp = t?.fingerprint ? (t.fingerprint.match(/.{1,8}/g) ?? []).join(" ") : "（未知）";
+		return lang === "en-US"
+			? [
+				`[ojm] Trust confirmation required (publisher: ${t?.key_id ?? "unknown"})`,
+				`Fingerprint (sha256 of public key): ${fp}`,
+				`Verify it with the publisher, then run: ojm trust confirm --task ${record.id}`,
+				"After confirming, retry the install command.",
+			].join("\n")
+			: [
+				`[ojm] 待信任确认（发布方：${t?.key_id ?? "未知"}）——安装未完成`,
+				`指纹（公钥 sha256，请与发布方公布值逐字核对）：${fp}`,
+				`确认命令：ojm trust confirm --task ${record.id}`,
+				"确认入库后重试安装命令即可继续。",
+			].join("\n");
+	}
+	const retryable = RETRYABLE_LABELS[lang][record.error?.retryable ? "yes" : "no"];
+	const stage = record.error?.hintKey?.replace(/^lifecycle\.stage\./, "").replace(/\.hint$/, "") ?? record.stage ?? "";
+	const en = lang === "en-US";
+	// 六码走 key：hintKey 形如 lifecycle.stage.verifying.<code>，按 locale 取本表（fail-fast 测试据此断言实际渲染）
+	const code = /^lifecycle\.stage\.verifying\.(sig_missing|sig_alg|sig_key|tampered|unknown_key|sig_format)$/
+		.exec(record.error?.hintKey ?? "")?.[1];
+	const reason = code
+		? (VERIFY_CODE_COPY[code]?.reason[en ? "en" : "zh"] ?? record.error?.reason ?? record.message)
+		: (record.error?.reason ?? record.message);
+	const hint = code
+		? (VERIFY_CODE_COPY[code]?.hint[en ? "en" : "zh"] ?? STAGE_HINTS[stage]?.[en ? "en" : "zh"] ?? "")
+		: (STAGE_HINTS[stage]?.[en ? "en" : "zh"] ?? (en ? "Inspect the task details on the site for more information" : "请到站点任务详情页查看更多信息"));
+	const head = record.status === "partial"
+		? (lang === "en-US"
+			? `[ojm] Install partially applied (stage: ${stage}) — the solution is partly live, see hint below`
+			: `[ojm] 安装部分生效（stage：${stage}）——方案已部分上线，详见下方指引`)
+		: (lang === "en-US"
+			? `[ojm] Install failed (stage: ${stage})`
+			: `[ojm] 安装失败（stage：${stage}）`);
+	return [
+		head,
+		lang === "en-US" ? `Reason: ${reason}` : `原因：${reason}`,
+		lang === "en-US" ? `Hint: ${hint}` : `指引：${hint}`,
+		`${retryable}（${record.error?.hintKey ?? `lifecycle.stage.${stage}.hint`}）`,
+	].join("\n");
+}
+
+export type InstallTarget = { kind: "file", path: string, name: string | null, version: string | null } | { kind: "cdn", name: string, version: string | null };
+
+/** 目标解析：.tgz 路径 → file 源（<name>-<version>.tgz 文件名推导身份）；否则 name[@version] → cdn 源 */
+export function parseTarget(target: string): InstallTarget {
+	if (target.endsWith(".tgz")) {
+		const stem = path.basename(target).replace(/\.tgz$/i, "");
+		// 文件名推导：<name>-<version>（版本 = 尾段点分数字开头，可带 -prerelease 段；ojm build --bundle 产物命名，Finding C）
+		const m = /^(.+)-(\d[\w.]+(?:-[\w.]+)?)$/.exec(stem);
+		return { kind: "file", path: target, name: m?.[1] ?? null, version: m?.[2] ?? null };
+	}
+	const at = target.indexOf("@");
+	const name = at === -1 ? target : target.slice(0, at);
+	const version = at === -1 ? null : target.slice(at + 1);
+	if (name.trim() === "")
+		throw new Error(`[ojm] 非法安装目标：「${target}」（用法：ojm install <file.tgz | name[@version]>）`);
+	return { kind: "cdn", name: name.trim(), version };
+}
+
+export interface InstallOptions {
+	url?: string
+	user?: string
+	pass?: string
+	/** file 源身份覆盖（文件名不可解析时的显式出口）；cdn 源同名冲突时报错提示二选一 */
+	name?: string
+	/** 显式版本（覆盖文件名/目标推导） */
+	version?: string
+	/** 终态文案语言（缺省 zh-CN） */
+	locale?: string
+	/** 测试注入；缺省 globalThis.fetch */
+	fetchFn?: typeof fetch
+	/** 测试注入；缺省真睡 */
+	sleep?: (ms: number) => Promise<void>
+}
+
+/**
+ * 安装命令体：解析目标 → 登录 → POST install（file=multipart / cdn=JSON）→ 轮询至终态 →
+ * 渲染人话。失败/partial 打印全文后置 process.exitCode = 1（不抛——多行渲染已输出，栈是噪音），
+ * 返回终态记录供调用方（真机冒烟）断言。
+ */
+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,
+		});
+		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 });
+	console.log(renderOutcome(record, opts.locale));
+	// P2-10：未来 schema 版本即使 status=done 也按非成功态处理（语义可能漂移，不误报成功）
+	if (record.status !== "done" || isFutureSchema(record))
+		process.exitCode = 1;
+	return record;
+}
+
+/** file 源响应解包：复用站点信封语义，额外校验 task_id 在场（防编排面版本错配静默空转） */
+async function unwrapInstall(res: { ok: boolean, status: number, text: () => Promise<string> }): Promise<{ task_id: string }> {
+	const data = await unwrapEnvelope(res) as { task_id?: string };
+	const taskId = String(data?.task_id ?? "");
+	if (taskId === "")
+		throw new Error("[ojm] install 响应缺 task_id——核对站点平台编排面版本（peerPlatform 预检）");
+	return { task_id: taskId };
+}

package/src/keygen.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// ojm keygen（P2-4，作者工具链）：生成 Ed25519 签名密钥对并落盘。
+// 落点缺省 `~/.ojm/keys/<id>/`（private.pem 0600 + public.hex）；`--out` 指到**工程树内**
+// （cwd 之下）即警告并要求 `--yes` 显式确认——私钥入仓 = 泄露（P2-12 全仓 grep 零命中的
+// 前提是私钥只活在 ~/.ojm/keys 或用户显式指定的受管位置）。
+// 纯函数面（generateKeyPair/导出/签名）在 lifecycle/sign.ts 与 lifecycle/keygen.ts；
+// 本文件只做命令编排（SRP）：解析 → 校验 key_id 命名空间（C2-37）→ 生成 → 落盘 → 打印。
+import process from "node:process";
+import { generateKeyPair } from "./lifecycle/keygen";
+import { fingerprintOfPublicKey } from "./lifecycle/sign";
+
+export interface KeygenOptions {
+	/** 发布方 key_id（C2-37：<publisher>.<id> 全小写，禁裸通用名） */
+	id?: string
+	/** 输出目录（缺省 ~/.ojm/keys/<id>） */
+	out?: string
+	/** 工程树内落盘的显式确认（缺省拒绝） */
+	yes?: boolean
+	/** 测试注入；缺省 process.cwd() */
+	cwd?: string
+}
+
+export const DEFAULT_KEY_ID = "local.dev";
+
+/** `ojm keygen [--id <publisher.id>] [--out <dir>] [--yes]` 参数解析（值式 flag 逐项消费，P6 同款纪律） */
+export function parseKeygenArgs(argv: string[]): { id?: string, out?: string, yes?: boolean } {
+	const values: Record<string, string> = {};
+	let yes = false;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]!;
+		if (a === "--yes") {
+			yes = true;
+			continue;
+		}
+		if (a === "--id" || a === "--out") {
+			values[a] = argv[i + 1] ?? "";
+			i++;
+			continue;
+		}
+	}
+	return { id: values["--id"], out: values["--out"], yes };
+}
+
+/** C2-37 key_id 命名空间（与 isolate 侧 trust.ts isValidKeyId 同规则；禁裸通用名单段） */
+export function isValidKeyId(keyId: string): boolean {
+	return /^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)+$/.test(keyId);
+}
+
+export interface KeygenResult {
+	keyId: string
+	publicKeyHex: string
+	fingerprint: string
+	dir: string
+	privateKeyPath: string
+	publicKeyPath: string
+}
+
+/**
+ * keygen 命令体。返回产物路径（测试/调用方断言用）；stdout 打印人话摘要。
+ * 工程树内落盘无 --yes → 抛错（私钥不得意外入仓——仓内出现即 P2-12 grep 红灯）。
+ */
+export function keygenCommand(opts: KeygenOptions = {}): KeygenResult {
+	const keyId = opts.id ?? DEFAULT_KEY_ID;
+	if (!isValidKeyId(keyId))
+		throw new Error(`[ojm] key_id 命名空间非法（C2-37：<publisher>.<id> 全小写、禁裸通用名单段）：「${keyId}」——示例：acme.market`);
+	const cwd = opts.cwd ?? process.cwd();
+	const home = path.join(os.homedir(), ".ojm", "keys", keyId);
+	const dir = opts.out === undefined ? home : path.resolve(cwd, opts.out);
+	if (path.resolve(cwd) !== path.parse(cwd).root && dir.startsWith(`${path.resolve(cwd)}/`) && opts.yes !== true) {
+		throw new Error(`[ojm] 输出目录在工程树内（${path.relative(cwd, dir) || "."}）——私钥入仓即泄露。请使用缺省位置 ~/.ojm/keys/<id>，或确认已知风险后加 --yes 重试（建议把该目录加进 .gitignore）`);
+	}
+	const kp = generateKeyPair();
+	const fingerprint = fingerprintOfPublicKey(kp.publicKeyHex);
+	const privateKeyPath = path.join(dir, "private.pem");
+	const publicKeyPath = path.join(dir, "public.hex");
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(privateKeyPath, kp.privateKeyPem, { mode: 0o600 });
+	fs.writeFileSync(publicKeyPath, `${kp.publicKeyHex}\n`);
+	console.log(`[ojm] 已生成 Ed25519 密钥对：${dir}`);
+	console.log(`[ojm] key_id：${keyId}（发布方标识，签名与信任库按它绑定；轮换 = 新 key_id，禁覆写）`);
+	console.log(`[ojm] public_key：${kp.publicKeyHex}`);
+	console.log(`[ojm] 指纹（sha256(publicKey)，公布给宿主核对）：${fingerprint}`);
+	console.log(`[ojm] 私钥文件：${privateKeyPath}（0600；永不入仓、永不入日志——P2-5 redact 钉面）`);
+	console.log(`[ojm] 下一步：ojm sign <pkg>.tgz --id ${keyId}（或 --key ${privateKeyPath} --id ${keyId}）`);
+	return { keyId, publicKeyHex: kp.publicKeyHex, fingerprint, dir, privateKeyPath, publicKeyPath };
+}