@oj-module/cli 0.2.2 → 0.2.5

package/src/usage.ts

@@ -15,8 +15,11 @@ export function usageText(): string {
         开发模式快捷键（仅 TTY 终端，类 Vite）:
           r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开
           q  退出（后端 oj 一并终止）
-  ojm build
+  ojm build [--bundle] [--out <dir>]
         构建后端（oj build）与模块产物（含全站合并）
+        --bundle   方案包构建：manifest.yaml 契约校验（C2，fail-fast）→ 确定性 tgz
+                   → dist/<name>-<version>.tgz + sha256（市场安装器的上游产物）
+        --out <dir>  --bundle 输出目录（缺省 dist/）
   ojm preview [port] [--oj-static]
         生产形态预览（migrate → oj serve + 静态兜底）
   ojm api [dir] [--check] [--docs] [--exempt <path>]
@@ -30,6 +33,37 @@ export function usageText(): string {
         下载/重装 oj vendor（经 npm 包 @oj-bin/oj；tag 缺省取最新，形如 v0.1.13）
   ojm merge <out.json> <in1.json> [in2.json ...]
         合并多团队清单（R12）
+  ojm install <file.tgz | name[@version]> [--url <u>] [--user <u>] [--pass <p>]
+              [--name <n>] [--version <v>] [--locale <zh-CN|en-US>]
+        安装方案包到目标站点（P1-13）：本地 tgz 走 file 上传（<name>-<version>.tgz 文件名推导
+        身份，可 --name/--version 覆盖）；name[@version] 走 CDN 市场源。登录 → 提交 → 轮询任务
+        至终态并打印结果（失败附原因 + 指引，--locale 切双语）
+  ojm enable|disable <name> [--url <u>] [--user <u>] [--pass <p>]
+        启用/禁用已装方案（D12 四处同写：锁 / sidecar / sys_solution_route / modules.json）
+  ojm uninstall <name> [--url <u>] [--user <u>] [--pass <p>]
+        卸载已装方案（P1-15a：四处同删 + 权限级联清理 + 版本目录移除；站点至少保留一个已锁模块）
+  ojm trust ls|add|revoke|confirm [--url <u>] [--user <u>] [--pass <p>]
+        发布方信任库管理（P2-2/3，站点 .solutions/trusted-keys.yaml）：
+        ls <key_id 前缀?>        列出已信任 key（含 sha256 指纹分组展示）
+        add <key_id> <pub>       新增信任（64 hex 公钥；首次绑定不可改）
+        revoke <key_id>          吊销（阻断新装/升级，不动已装方案）
+        confirm --task <id>      TOFU 确认：把 needs_trust 终态待确认 key 入库
+        站点寻址：--url/--user/--pass，或环境变量 OJM_URL / OJM_USER / OJM_PASS
+  ojm keygen --id <publisher.id> [--out <dir>] [--yes]
+        生成 Ed25519 签名密钥对（P2-1）：私钥默认 ~/.ojm/keys/<id>/ 永不出目录（--out 指到
+        工程树内须 --yes 显式确认——私钥入仓即泄露）；打印公钥 hex 供 ojm trust add / 模板回填
+  ojm sign <file.tgz> [--id <publisher.id>] [--key <pem>] [--check]
+        detached 侧车签名（P2-4）：产出 <tgz>.sig（ojm install 自动探测随包上传）；
+        私钥缺省取 ~/.ojm/keys/<id>/private.pem（--key 指定 pem 时须同时 --id）；
+        --check 离线自检签名（不必靠宿主装失败发现签错）
+        站点寻址：--url/--user/--pass，或环境变量 OJM_URL / OJM_USER / OJM_PASS
+        （缺省 http://127.0.0.1:9778；凭据只走内存不落盘）
+  ojm publish <dir> [--id <publisher.id>] [--key <pem>] [--check]
+        索引发布（P3-5/6/7）：重算 <dir>/bundles.yaml + manifests.yaml（确定性
+        stringify，消弭格式漂移）→ 对两份索引各产出 detached 侧车签名 <kind>.yaml.sig
+        （与 archive .sig 同构，公钥取 ~/.ojm/keys/<id>/private.pem，缺省 --id 推导）→ 写回
+        <dir>。CDN 侧 resolveCdn/index 拉取索引时校验签名（篡改/不符即拒，G4 fail-closed）。
+        --check 离线自检两份索引签名
   ojm test|exec|openapi|migrate|schema [args...]
         透传给 oj 同名子命令（自动补 -c <project>/api/config.yaml；其余参数原样转发）
         例：ojm test --anonymous / ojm migrate --db report / ojm openapi --check

package/templates/README.md

@@ -84,4 +84,4 @@ web/dist/  构建产物（完整站点）
   pnpm dlx @oj-module/cli@<明确版本> init <工程名> --yes   # 显式指定版本最稳
   ```
 
-  养成显式带版本号（如 `@oj-module/cli@0.2.2`）的习惯，可避免 `@latest` 缓存歧义。
+  养成显式带版本号（如 `@oj-module/cli@0.2.4`）的习惯，可避免 `@latest` 缓存歧义。

package/templates/api/config.yaml

@@ -1,6 +1,26 @@
 # oj 服务配置（字段语义见 oj 后端开发手册 oj-api-dev / 或 oj --help）。
 # 本文件由 ojm init 生成；config 内相对路径相对本文件所在目录。
 # 更多能力见手册 §10：vars / broker / tasks / oidc / ws / html_meta / secrets。
+#
+# ---- 证书与密钥的唯一落点：`./config/`（= api/config/，本文件同级的子目录）----
+# 三件套由 `ojm init` 现场签发（dev 缺证时 `ojm dev` 也会补签），逐把的作用与后果：
+#
+#   ① private.pem —— 证书签发私钥（RSA 2048）。只用来给 ③ 签名，**oj 不读它**，
+#      也绝不出部署机、不入仓。丢了不需要恢复：重新签发一套即可（旧的 ③ 作废）。
+#   ② public.pem  —— 与 ① 成对的公钥，oj 启动时拿它验 ③ 的 RS256 签名。
+#      配错路径或与 ③ 不是同一对 → oj 验签失败、启动即拒（读作「证书无效」）。
+#      由 server.public_key_path 引用。
+#   ③ cert.jws    —— JWS 证书（RS256 紧凑三段，payload 仅 nbf/exp），**oj 的启动闸门**：
+#      缺失、过期、签名对不上 → fail-fast 拒启，devkit 手册明确**无任何 config/CLI 绕过开关**。
+#      默认有效期 3650 天（短有效期等于定时炸弹）；过期只能重新签发一套 ①②③。
+#      由 server.certificate_path 引用。
+#
+# 另有一对与上面无关的密钥（jwt_secret 密封用，init 密封成功后追加到本文件末尾）：
+#   secrets.private_key_path  ./config/secrets-private.pem  解 jwt_secret 密文的私钥，只放部署机
+#   secrets.public_key_path   ./config/secrets-public.pem   加密用的公钥，可随代码分发
+#   （密文形如 ENC 后跟方括号包裹的字串；未密封时 config 里是 32 字节十六进制明文）
+#
+# ojm 侧的解析入口是 `resolveCertDir()`，由本文件位置派生；改落点只需动那一处 + 本段注释。
 
 # 站点挂载（oj v0.1.58 起顶层扁平表：一行=一个 URL 前缀+一个目录，api/web 恰好其一）。
 # 被删除的 server.api_prefix / app_spa_fallback 已由 mounts 取代；
@@ -33,6 +53,9 @@ server:
   route_timeouts: []
   # ---- 统一响应头（v0.1.30）----
   response_headers: {}
+  # ---- 热更端点（ojm install 的 reloading 段消费；显式关闭 = 安装器 reloading 段可读失败）----
+  # ojm:reload
+  reload_api: true
   # ---- 直传路由 PUT {base}/blob/{key} 的体积上限（v0.1.30，默认 1GiB）----
   # 与 max_upload_bytes（multipart，默认 10MB）是两套闸，别混。
   blob_upload_max_bytes: 1073741824
@@ -43,6 +66,30 @@ server:
 db:
   default: 'sqlite://db.sqlite' # 相对 config 目录；缺文件自动建空库
 
+# ---- 安装序号（ojm install 每次安装自增一次，作为 reload 热更触发变更——unchanged 判定基于
+# config 文档 sha，无落盘变更则热更恒失败。勿删行/勿手工回写旧值。）----
+vars:
+  ojm_install_seq: 0
+
+# ---- 平台 exec 白名单（ojm install 的解压/迁移两处消费；模板逐字对齐 lifecycle steps 命令构造，
+# 不得增删——多一个 token 都会 NotCapable）----
+platform:
+  # ---- U6 信任库加固（P3-1；P2-2 红线 spike 结论）----
+  # 威胁：devkit 0.1.75 语义下 fs: 段对全部模块生效（jail = fs.root），且 trusted_paths 只增不减——
+  # 信任库落在第三方方案模块可写的 fs.root 内即可被其伪造信任锚。加固须两端配合：
+  # ① 本模板已将信任库默认路径移出 modules/ 安装子树（见 _lifecycle 默认 `.solutions/trusted-keys.yaml`，
+  #    落在 fs.root 之外的部署根，第三方方案模块 jail 之外）；
+  # ② **部署侧**须按 oj 语义补 `platform.trusted_paths`（指向运行时信任库目录，该目录须先存在——
+  #    oj 对不存在的 trusted_paths 装配 fail-fast，故不可在模板里硬编码尚未创建的目录）显式授权给
+  #    _platform 特权模块写信任库，并收窄第三方方案模块的 fs.root 至其安装子树，方可彻底隔离。
+  # 本仓负责①（代码路径）；②属部署/上游配置，留作部署清单项（P3-1 备案，不硬编码以免 oj serve 装配失败）。
+  exec:
+    _platform:
+      allow:
+        - 'tar -tvzf ${path:archive}'
+        - 'tar -xzf ${path:archive} -C ${path:dest}'
+        - 'oj migrate --format json -d ${path:dir} ${raw:module}'
+
 # ---- LDAP 连接段（D1/PRD §4.5 两段式之连接段；oj 插件严格解析本段，未知键启动 fail-fast——只写下列键）----
 # 取消注释并填值即接通目录服务；应用映射段在 DB/设置页（ldap.enabled、ldap_base_dn、
 # ldap_uid_attr、ldap_email_attr，group=ldap，即时生效）。本段改动属 restart_pending，需重启。

package/templates/api/seed.mysql.sql

@@ -1,5 +1,5 @@
 -- 系统设置默认值（PRD §4.3；注释内禁英文分号）
 INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'React Antd Admin', 'React Antd Admin', 'system:setting.site_title', 0, 0);
-INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('market.cdn_url', 'market', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0);
+INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('framework.market_cdn_url', 'framework', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0);
 INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('ldap.enabled', 'ldap', 'login', 'bool', '0', '0', 'system:setting.ldap_enabled', 0, 0);
 INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('sso.enabled', 'sso', 'login', 'bool', '0', '0', 'system:setting.sso_enabled', 0, 0);

package/templates/api/seed.pg.sql

@@ -1,5 +1,5 @@
 -- 系统设置默认值（PRD §4.3；注释内禁英文分号）
 INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'React Antd Admin', 'React Antd Admin', 'system:setting.site_title', 0, 0) ON CONFLICT DO NOTHING;
-INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('market.cdn_url', 'market', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0) ON CONFLICT DO NOTHING;
+INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.market_cdn_url', 'framework', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0) ON CONFLICT DO NOTHING;
 INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap.enabled', 'ldap', 'login', 'bool', '0', '0', 'system:setting.ldap_enabled', 0, 0) ON CONFLICT DO NOTHING;
 INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('sso.enabled', 'sso', 'login', 'bool', '0', '0', 'system:setting.sso_enabled', 0, 0) ON CONFLICT DO NOTHING;

package/templates/api/src/_platform/_lifecycle/atomic.ts

@@ -0,0 +1,98 @@
+// 状态文件原子写底座（D13）：state.yaml / manifests.yaml / modules.json / 任务文件
+// 一切状态落盘统一走这里——同目录 tmp + rename 原子替换，读者永远见不到半截文件
+// （rename 同目录即同文件系统，POSIX 语义下原子替换 inode）。
+// fs 依赖从 globalThis.fs 取（平台 isolate 注入 FsApi 面；测试注入 node:fs/promises 适配），
+// 签名不携带 fs 参数（DIP：依赖结构化最小面 FsFace，两实现天然兼容）。
+// 写失败（writeFile/rename 抛错）时尽力清理 tmp 后原样上抛，目标旧文件不受影响。
+
+export interface FsFace {
+	writeFile: (path: string, data: Uint8Array) => Promise<void>
+	readFile: (path: string) => Promise<Uint8Array>
+	mkdir: (path: string, opts?: { recursive?: boolean }) => Promise<void>
+	remove: (path: string, opts?: { recursive?: boolean }) => Promise<void>
+	rename: (oldPath: string, newPath: string) => Promise<void>
+	/** 复制文件（R14 迁移前置备份：sqlite 库 copy 为 <db>.bak-<ts>）；两路径须同文件系统无需递归 */
+	copyFile: (src: string, dest: string) => Promise<void>
+	/** 列目录成员名（不含路径；不含 . / ..） */
+	readdir: (path: string) => Promise<string[]>
+}
+
+/**
+ * 随机 id：oj isolate 的 crypto 增补面（api-manual §crypto）只有 randomHex，无 Web 的 randomUUID
+ * ——有 randomUUID 用之（Node 测试侧），否则 randomHex(16) 兜底（真机冒烟 P1-13 实测，附录 B-9 同源缺面）。
+ */
+export function randomId(): string {
+	const c = (globalThis as { crypto?: { randomUUID?: () => string, randomHex?: (n?: number) => string } }).crypto;
+	if (c?.randomUUID !== undefined)
+		return c.randomUUID();
+	if (c?.randomHex !== undefined)
+		return c.randomHex(16);
+	throw new Error("atomic: 随机数面不可用（globalThis.crypto 缺 randomUUID/randomHex）");
+}
+
+/**
+ * 「路径不存在」判别（isolate 双端，B-11 真机实测补面）：Node/测试侧 = NotFound 且 .code
+ * 为 ENOENT；oj 真机（0.1.78 实测）= TypeError "invalid_argument"（deno ext 对缺失目标的
+ * readFile/remove 报错形态，无 .code）。前置：调用方 fs 调用形状合法（路径为字符串）——
+ * 此时 invalid_argument 只能来自缺失目标，语义等价 ENOENT。
+ */
+export function isMissingPath(e: unknown): boolean {
+	if ((e as { code?: string } | null)?.code === "ENOENT") {
+		return true;
+	}
+	return e instanceof TypeError && e.message === "invalid_argument";
+}
+
+export function fsFace(): FsFace {
+	const f = (globalThis as { fs?: Partial<FsFace> & { readDir?: (path: string) => Promise<AsyncIterable<{ name: string }>> } }).fs;
+	if (f === undefined) {
+		throw new Error("atomic: 平台 fs 面不可用（globalThis.fs 未注入），无法落盘");
+	}
+	if (f.copyFile !== undefined && f.readdir !== undefined) {
+		return f as FsFace;
+	}
+	// oj fs 全局面缺 copyFile、目录列举叫 readDir 且形状是 AsyncIterable<DirEntry>（api-manual §fs）
+	// ——在此单点适配到生命周期代码消费的 FsFace（P1-13 真机冒烟实测缺面，契约附录 B-9）。
+	return {
+		writeFile: (path, data) => f.writeFile!(path, data),
+		readFile: path => f.readFile!(path),
+		mkdir: (path, opts) => f.mkdir!(path, opts),
+		remove: (path, opts) => f.remove!(path, opts),
+		rename: (oldPath, newPath) => f.rename!(oldPath, newPath),
+		// ponytail: copyFile 经字节中转（V8 常驻峰值 = 文件大小）；sqlite 备份上 GB 时须上游补原生 copy
+		copyFile: f.copyFile ?? (async (src, dest) => f.writeFile!(dest, await f.readFile!(src))),
+		readdir: f.readdir ?? (async (path) => {
+			const names: string[] = [];
+			for await (const e of await f.readDir!(path))
+				names.push(e.name);
+			return names;
+		}),
+	};
+}
+
+const encoder = new TextEncoder();
+
+export async function atomicWriteText(path: string, content: string): Promise<void> {
+	const f = fsFace();
+	// tmp 与目标同目录：保证 rename 不跨文件系统；随机后缀防并发写者互踩同一 tmp
+	const slash = path.lastIndexOf("/");
+	const dir = slash === -1 ? "" : path.slice(0, slash);
+	const base = slash === -1 ? path : path.slice(slash + 1);
+	const tmp = `${dir === "" ? "" : `${dir}/`}${base}.${randomId()}.tmp`;
+	if (dir !== "") {
+		await f.mkdir(dir, { recursive: true });
+	}
+	try {
+		await f.writeFile(tmp, encoder.encode(content));
+		await f.rename(tmp, path);
+	}
+	catch (e) {
+		try {
+			await f.remove(tmp, { recursive: true });
+		}
+		catch {
+			// 清理失败不掩盖原始错误
+		}
+		throw e;
+	}
+}

package/templates/api/src/_platform/_lifecycle/history.ts

@@ -0,0 +1,31 @@
+// market_history 留痕（P1-15a 缺口 A，P4 上收 _platform）：install / enable / disable / uninstall
+// 四类动作共用的平台级留痕出口（前端 HistoryDrawer 消费面）。表由 _platform 自带迁移创建
+// （0012__market_history），归平台核心所有；守卫式 insert 仍兜底表缺失/写失败，静默跳过，
+// 不阻断主流程（历史是观测面，不是业务正确性依赖；与终态审计附录 B-5 同语义）。
+// 参数化 insert，与 audit.ts 同纪律（值不拼字符串）。
+
+// db 为 oj isolate 注入全局（同模板 service 层惯例，installer.ts 同款；测试由夹具装 globalThis.db）
+declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown> };
+
+export interface HistoryRow {
+	solution: string
+	version: string
+	action: "install" | "enable" | "disable" | "uninstall"
+	status: string
+	/** 操作人（用户名；编排层可得则传，缺省 null） */
+	operator: string | null
+	message: string
+}
+
+/** 守卫式 insert：表不存在/写失败一律静默（留痕失败不影响主流程） */
+export async function recordHistory(row: HistoryRow): Promise<void> {
+	try {
+		await db.exec(
+			"insert into market_history (solution, version, action, status, operator, message, created_at) values (?, ?, ?, ?, ?, ?, ?)",
+			[row.solution, row.version, row.action, row.status, row.operator, row.message, Math.floor(Date.now() / 1000)],
+		);
+	}
+	catch {
+		// 表不存在（市场方案未装）或写失败：静默跳过，不阻断主流程
+	}
+}