@oj-module/cli 0.2.29 → 0.2.42

package/devkit/manual.md

@@ -1605,7 +1605,7 @@ export default async (path: string, html: string) => {
 
 | 类别 | 命令 | 谁实现 | 一句话 |
 |---|---|---|---|
-| **ojm 原生** | `init` / `dev` / `build` / `preview` / `api` / `info` / `vendor` / `merge` / `install` / `enable` / `disable` / `uninstall` / `trust` / `keygen` / `sign` / `publish` | `ojm` 自己 | 前后端一体工程的脚手架、开发、构建、契约生成、版本/清单、oj 分发、清单合并；方案包安装面与签名信任（install/enable/disable/uninstall 见 §11，trust/keygen/sign 见 §12，publish 见 §11.2） |
+| **ojm 原生** | `init` / `dev` / `build` / `preview` / `api` / `info` / `vendor` / `merge` / `install` / `list` / `enable` / `disable` / `uninstall` / `trust` / `view` / `keygen` / `sign` / `publish` / `registry` | `ojm` 自己 | 前后端一体工程的脚手架、开发、构建、契约生成、版本/清单、oj 分发、清单合并；方案包安装面与签名信任（install/list/enable/disable/uninstall 见 §11，trust/keygen/sign 见 §12，publish 见 §11.2）；`registry` 是索引/吊销清单/离线包的外置签名与流转；整条 registry 链路（发版 / 安装 / 运维 / 查询）的图文流程见 [`prd/20261026-registry-cli-commands-design.md`](../prd/20261026-registry-cli-commands-design.md) |
 | **oj 透传** | `test` / `exec` / `openapi` / `migrate` / `schema` | `oj`（ojm 仅转发） | 这 5 个**就是 oj 的同名子命令**，ojm 只负责定位 `bin/oj` 并补上 `-c config.yaml` |
 
 > **为什么只有这 5 个走透传？** oj 还有 `serve` / `build` / `secret`（`keygen`/`seal` 等）
@@ -1781,7 +1781,7 @@ module-root 下数据源是「扫描 + `web.config.ts` 登记」并集（未登
 
 | 子命令 | 一句话 |
 |---|---|
-| `ojm market setup [--url <站点>] [--user <u> --pass <p>] [--new-pass <p>]` | **外部真 CDN 场景才需要**：把 `framework.market_cdn_url` 改写为绝对地址；账号须 **superadmin**（该设置安全组仅 superadmin 可写，admin 角色会被 403）；首跑若账号处于首次改密期会先自动改密再写入 |
+| `ojm market setup [--site-url <站点>] [--user <u> --pass <p>] [--new-pass <p>]` | **外部真 CDN 场景才需要**：把 `framework.market_cdn_url` 改写为绝对地址；账号须 **superadmin**（该设置安全组仅 superadmin 可写，admin 角色会被 403）；首跑若账号处于首次改密期会先自动改密再写入 |
 | `ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]` | 把方案包落进 `cdn/` 并做包级 detached 签名；**不碰索引**（索引由 `build-index` 重建，避免多人发布互相覆盖） |
 | `ojm market build-index [--id <key>] [--key <pem>] [--check]` | 扫描 `cdn/*.tgz`、提取包内 manifest，全量重建 `bundles.yaml` + `manifests.yaml` 并签名；结果只取决于目录内容，连续执行字节一致 |
 | `ojm market verify [--file <tgz>] [--rebuild-index]` | 离线验包（不起站点、不装、不要凭据）：sha256 完整性 / 包级 Ed25519 验签 / 索引验签 / manifest 结构分列输出；`--rebuild-index` 额外比对重建索引与盘上索引的漂移 |
@@ -1908,9 +1908,9 @@ flowchart TD
 `install` / `enable` / `disable` / `uninstall` / `trust` 都是**瘦客户端**——它们把请求发到目标站点
 （需 superadmin），本地只做「登录 → 提交 → 轮询任务至终态」并打印结果。三处寻址约定完全一致：
 
-- `--url <站点地址>`：缺省 `http://127.0.0.1:9778`；
+- `--site-url <站点地址>`：缺省 `http://127.0.0.1:9778`；
 - `--user <账号>` / `--pass <密码>`：站点凭据；
-- 等价环境变量 `OJM_URL` / `OJM_USER` / `OJM_PASS`（命令行缺省时回退读取，**凭据只走内存不落盘**）；
+- 等价环境变量 `OJM_SITE_URL` / `OJM_USER` / `OJM_PASS`（命令行缺省时回退读取，**凭据只走内存不落盘**）；
 - `--locale <zh-CN|en-US>`：`install` 专用，切换失败文案双语（默认按站点 locale）。
 
 | 命令 | 作用 | 注意 |
@@ -1963,7 +1963,7 @@ ojm keygen --id <publisher>.<key-name>
 ojm sign dist/<name>-<version>.tgz --id <publisher>.<key-name> --check
 
 # ③ 安装/分发：.sig 自动探测随包上传
-ojm install dist/<name>-<version>.tgz --url <站点> --user superadmin --pass …
+ojm install dist/<name>-<version>.tgz --site-url <站点> --user superadmin --pass …
 ```
 
 宿主验签六码（失败文案双语，`--locale` 切换）：`sig_missing`（缺签）/ `sig_alg`（算法

package/devkit/module-dev-and-cdn-playground.md

@@ -165,7 +165,7 @@ node "$CLI_PKG/bin/ojm.mjs" market verify --rebuild-index
 node "$CLI_PKG/bin/ojm.mjs" build                 # 生成 api/dist + web/dist（含 api/dist/versions.json）
 # config：platform.root 改成 api/dist（安装目标恒为 release 部署，root 必须与 --api-path 同源）
 (bin/oj serve -c config.yaml -b /api --api-path api/dist --console-log &)
-node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user superadmin --pass 123456 --new-pass <新口令>
+node "$CLI_PKG/bin/ojm.mjs" market setup --site-url http://127.0.0.1:9778 --user superadmin --pass 123456 --new-pass <新口令>
 # 市场页点安装 → 首次停在「待信任」→ 核对指纹 → ojm trust confirm --task <id> → 重试 → done
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.29",
+  "version": "0.2.42",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.29",
+    "@oj-module/runtime": "0.2.42",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",

package/shell-dist/assets/{index-CnJsHOe-.js → index-FYt9CjFd.js}

@@ -235,9 +235,54 @@ async function hydrateUser() {
 useAuthStore.subscribe((state, prev) => {
 	if (state.token !== prev.token) hydrateUser().then(() => {
 		useAccessStore.getState().setAccessStore(getRoutes());
+		repatchShellRoutes();
 	});
 });
 /**
+* 宿主路由根 id：patchRoutes 重登记的 parentId（与 runtime 的 ROOT_ROUTE_ID
+* 同名无碍——各自作用于各自 router 实例）。
+*/
+var SHELL_ROOT_ID = "shell-root";
+/** Boot 建表后持有的宿主 router 实例；token 变化时按新角色快照重登记其路由表。 */
+var shellRouter = null;
+/**
+* 宿主路由表 children：index 重定向 + 模块路由（getHostRoutes 同源重写）+
+* catch-all 兜底。Boot 建表与登录后重登记共用同一构建口，保证两处同源。
+*/
+function buildShellChildren() {
+	const hostRoutes = getHostRoutes();
+	return [
+		{
+			index: true,
+			element: /* @__PURE__ */ jsx(Navigate, {
+				to: hostRoutes[0]?.path ?? "/",
+				replace: true
+			})
+		},
+		...hostRoutes,
+		{
+			path: "*",
+			element: /* @__PURE__ */ jsx(CatchAll, {})
+		}
+	];
+}
+/**
+* 按当前角色快照重登记宿主路由表（B16 回归，2026-10-24）。
+*
+* setAccessStore 内部的 router.patchRoutes 打的是 runtime 单例 router，而宿主
+* 渲染的是本文件 Boot 里自建的 router——仅调 setAccessStore 只会更新菜单
+* （access store），路由表保持 Boot 期快照。后果：Boot 期 user-info 失败
+* （后端闪断/过期 token 刷新失败）→ 角色空 → requiredRoles 门禁模块被过滤出
+* 路由表；随后 SPA 登录（不刷新页面）菜单回来了，但 /system/* 仍不在路由表里，
+* 直达恒落 catch-all 404「返回首页」，须硬刷新才恢复。
+*/
+function repatchShellRoutes() {
+	if (!shellRouter) return;
+	shellRouter.patchRoutes(SHELL_ROOT_ID, buildShellChildren());
+	const { pathname, search } = shellRouter.state.location;
+	shellRouter.navigate(`${pathname}${search}`, { replace: true }).catch(() => {});
+}
+/**
 * 直链兜底页（catch-all 路由元素）。无匹配路由时渲染框架 `PageError`，
 * 把 title 设为框架 404 文案（`exception.notFoundTitle` = "404"），
 * 观感与无权限面板同构，替代 React Router 默认的「Unexpected Application Error!」。
@@ -299,27 +344,14 @@ function Boot() {
 				await hydrateUser();
 				await loadAll(manifest);
 				if (cancelled) return;
-				const hostRoutes = getHostRoutes();
-				setRouter(createBrowserRouter([{
+				shellRouter = createBrowserRouter([{
 					path: "/",
+					id: SHELL_ROOT_ID,
 					element: /* @__PURE__ */ jsxs(ErrorBoundary, {
 						FallbackComponent: PageError,
 						children: [/* @__PURE__ */ jsx(LayoutEffects, {}), /* @__PURE__ */ jsx(Outlet, {})]
 					}),
-					children: [
-						{
-							index: true,
-							element: /* @__PURE__ */ jsx(Navigate, {
-								to: hostRoutes[0]?.path ?? "/",
-								replace: true
-							})
-						},
-						...hostRoutes,
-						{
-							path: "*",
-							element: /* @__PURE__ */ jsx(CatchAll, {})
-						}
-					]
+					children: buildShellChildren()
 				}], { 
 				/**
 				* 子路径部署（oj `mounts: [{ prefix: /oj, web: dist, spa: true }]`）：
@@ -330,7 +362,8 @@ function Boot() {
 				*
 				* 浏览器 URL 不受影响：react-router 只是在匹配/生成时剥/补前缀。
 				*/
-basename: base }));
+basename: base });
+				setRouter(shellRouter);
 			} catch (e) {
 				if (!cancelled) setError(e instanceof Error ? e.message : String(e));
 			}

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.29",
+			"version": "0.2.42",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-24 20:31:54"
+		"lastBuildTime": "2026-10-26 10:15:05"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-5zLHUGQHePNQzqOPB7RBQA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-2Xr8lEfbU8h45hDFonkWmg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="5zLHUGQHePNQzqOPB7RBQA==">{
+		<script type="importmap" nonce="2Xr8lEfbU8h45hDFonkWmg==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",
@@ -133,7 +133,7 @@
     "dayjs/locale/zh-cn": "/assets/ojm-dayjs-locale-zh-cn.js"
   }
 }</script>
-		<script type="module" crossorigin src="/assets/index-CnJsHOe-.js"></script>
+		<script type="module" crossorigin src="/assets/index-FYt9CjFd.js"></script>
 	</head>
 	<body>
 		<div id="root"></div>

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.29",
-  "@oj-module/runtime/contract": "0.2.29",
-  "@oj-module/runtime/contract/errors": "0.2.29",
+  "@oj-module/runtime": "0.2.42",
+  "@oj-module/runtime/contract": "0.2.42",
+  "@oj-module/runtime/contract/errors": "0.2.42",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/cli.test.ts

@@ -23,6 +23,9 @@ const buildBundleMock = vi.hoisted(() => vi.fn(async () => [{ file: "x.tgz" }]))
 vi.mock("../bundle", () => ({ buildBundle: buildBundleMock }));
 const vendorCommandMock = vi.hoisted(() => vi.fn(async () => {}));
 vi.mock("../vendor", () => ({ vendorCommand: vendorCommandMock }));
+// REG-CS3 v2：sign 的 --registry-id 曾只被 signCommand 要求、却没在 CLI 上接线，命令成死路
+const signCommandMock = vi.hoisted(() => vi.fn(() => ({})));
+vi.mock("../sign", () => ({ signCommand: signCommandMock }));
 
 beforeEach(() => {
 	logs.length = 0;
@@ -35,6 +38,7 @@ afterEach(() => {
 	vi.restoreAllMocks();
 	buildBundleMock.mockClear();
 	vendorCommandMock.mockClear();
+	signCommandMock.mockClear();
 });
 
 interface RunResult { out: string, unknown: string[], exitCode: number | undefined }
@@ -116,22 +120,22 @@ describe("反常识行为修正（20261023-0937）", () => {
 		expect(isKnownCommand("nope")).toBe(false);
 	});
 
-	it("unknownCommandResult：help 形态报未知命令（双语），code 1", async () => {
+	it("unknownCommandResult：help 形态报未知命令（双语），code 2（用法错误）", async () => {
 		const { unknownCommandResult } = await import("../cli");
 		const zh = unknownCommandResult("nope", "zh-CN", true);
 		expect(zh.text).toContain("[ojm] 未知命令：nope");
-		expect(zh.code).toBe(1);
+		expect(zh.code).toBe(2);
 		const en = unknownCommandResult("nope", "en-US", true);
 		expect(en.text).toContain("[ojm] Unknown command: nope");
-		expect(en.code).toBe(1);
+		expect(en.code).toBe(2);
 	});
 
-	it("unknownCommandResult：非 help 形态给顶层帮助，code 1", async () => {
+	it("unknownCommandResult：非 help 形态给顶层帮助，code 2（用法错误）", async () => {
 		const { unknownCommandResult } = await import("../cli");
 		const { usageText } = await import("../usage");
 		const r = unknownCommandResult("nope", "zh-CN", false);
 		expect(r.text).toBe(usageText("zh-CN"));
-		expect(r.code).toBe(1);
+		expect(r.code).toBe(2);
 	});
 
 	it("localizeCacError：未知选项本地化（双语）+ 指引", async () => {
@@ -152,28 +156,28 @@ describe("反常识行为修正（20261023-0937）", () => {
 });
 
 describe("校验搬入 action 后行为保持", () => {
-	it("new 多余位置参数显式拒绝（F8）", async () => {
+	it("new 多余位置参数显式拒绝（F8），exit 2", async () => {
 		const r = await run(["new", "crm", "erp"], "zh-CN", tmp);
 		expect(r.out).toContain("只接受一个方案名");
-		expect(r.exitCode).toBe(1);
+		expect(r.exitCode).toBe(2);
 	});
 
-	it("new --layout 非 container|none 报错", async () => {
+	it("new --layout 非 container|none 报错，exit 2", async () => {
 		const r = await run(["new", "demo", "--layout", "bogus"], "zh-CN", tmp);
 		expect(r.out).toContain("--layout 只接受 container | none");
-		expect(r.exitCode).toBe(1);
+		expect(r.exitCode).toBe(2);
 	});
 
-	it("new 缺 name 打印用法并 exit 1", async () => {
+	it("new 缺 name 打印用法并 exit 2", async () => {
 		const r = await run(["new"], "zh-CN", tmp);
 		expect(r.out).toContain("ojm new <name>");
-		expect(r.exitCode).toBe(1);
+		expect(r.exitCode).toBe(2);
 	});
 
-	it("vendor 非法 tag 报错", async () => {
+	it("vendor 非法 tag 报错（exit 2：改命令行即可）", async () => {
 		const r = await run(["vendor", "notatag"], "zh-CN", tmp);
 		expect(r.out).toContain("非法版本号");
-		expect(r.exitCode).toBe(1);
+		expect(r.exitCode).toBe(2);
 	});
 
 	it("vendor 0.1.12 规范化补 v 前缀后传入 vendorCommand", async () => {
@@ -188,7 +192,7 @@ describe("校验搬入 action 后行为保持", () => {
 });
 
 describe("参数映射", () => {
-	it("merge <out> <inputs...> variadic 映射（缺文件报错提及输入名）", async () => {
+	it("merge <out> <inputs...> variadic 映射（缺文件报错提及输入名，exit 1：业务失败）", async () => {
 		const r = await run(["merge", "out.json", "in1.json", "in2.json"], "zh-CN", tmp);
 		expect(r.out).toContain("in1.json");
 		expect(r.exitCode).toBe(1);
@@ -204,6 +208,11 @@ describe("参数映射", () => {
 		await run(["build", "--bundle"], "zh-CN", tmp, () => buildBundleMock.mock.calls.length > 0);
 		expect(buildBundleMock).toHaveBeenCalledWith(tmp, { out: undefined, name: undefined });
 	});
+
+	it("sign --registry-id 映射到 signCommand.registryId（REG-CS3 v2 规范串首段）", async () => {
+		await run(["sign", "demo-0.1.0.tgz", "--id", "acme.market", "--registry-id", "oj-registry"], "zh-CN", tmp, () => signCommandMock.mock.calls.length > 0);
+		expect(signCommandMock).toHaveBeenCalledWith("demo-0.1.0.tgz", { id: "acme.market", key: undefined, check: undefined, registryId: "oj-registry" });
+	});
 });
 
 describe("help 词形", () => {

package/src/__tests__/list.test.ts

@@ -0,0 +1,176 @@
+// BDD：`ojm list`（站点已装方案的可查面）。
+//
+// 到 0.3.2 为止 CLI 没有任何命令能回答「这个站点上装了什么」——装完只有一条终态文案。
+// 用例盯四件事：
+//   ① 缺省只列**已装**（installed != null），`--all` 才连未装行一起列；
+//   ② 三个派生结论不许算错：upgradable / enabled / trust_state 都原样取自站点索引行；
+//   ③ 空清算是成功（exit 0），并在人话里给出下一步（`ojm list --all`）；
+//   ④ `--json` 下 stdout 只有一行信封，命令名 `list`，数据在 data.solutions。
+import type { SolutionRow } from "../list";
+import process from "node:process";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildCli, localizeCacError, reportCliError } from "../cli";
+import { listCommand } from "../list";
+
+/** fetch stub：按 URL 前缀分发，记录全部调用（uninstall.test.ts 同范式） */
+function fetchStub(handlers: Record<string, (url: string) => unknown>): { fetchFn: typeof fetch, calls: string[] } {
+	const calls: string[] = [];
+	const fetchFn = (async (url: string | URL) => {
+		const u = String(url);
+		calls.push(u);
+		for (const [prefix, handler] of Object.entries(handlers)) {
+			if (u.includes(prefix))
+				return handler(u);
+		}
+		throw new Error(`fetchStub 未覆盖：${u}`);
+	}) as typeof fetch;
+	return { fetchFn, calls };
+}
+
+const ok = (data: unknown) => ({ ok: true, status: 200, text: async () => JSON.stringify({ code: 0, data }) });
+const LOGIN = () => ok({ access_token: "tok", refresh_token: "r", expires_in: 1 });
+
+const ROWS = [
+	{ name: "demo-solution", latest: "0.1.2", installed: "0.1.0", enabled: true, upgradable: true, available: ["0.1.0", "0.1.2"], trust_state: "trusted" },
+	{ name: "acme-demo", latest: "2.0.0", installed: "2.0.0", enabled: false, upgradable: false, available: ["2.0.0"], trust_state: "untrusted" },
+	{ name: "not-installed-one", latest: "1.0.0", installed: null, enabled: null, upgradable: false, available: ["1.0.0"], trust_state: null },
+];
+
+let logs: string[];
+
+beforeEach(() => {
+	logs = [];
+	vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+		logs.push(args.map(String).join(" "));
+	});
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe("listCommand：已装清单", () => {
+	it("scenario: 缺省只列已装，按名字排序，upgradable / trust_state 原样透出", async () => {
+		const { fetchFn, calls } = fetchStub({
+			"/api/auth/login": LOGIN,
+			"/api/_platform/market/index": () => ok(ROWS),
+		});
+		const rows = await listCommand({ siteUrl: "http://x", user: "u", pass: "p", fetchFn });
+
+		expect(rows.map(r => r.name)).toEqual(["acme-demo", "demo-solution"]); // 未装的不出现
+		expect(rows.find(r => r.name === "demo-solution")).toEqual({
+			name: "demo-solution",
+			installed: "0.1.0",
+			enabled: true,
+			latest: "0.1.2",
+			upgradable: true,
+			trustState: "trusted",
+		});
+		// 登录用的是站点寻址（Bearer 由 callApi 注入，这里只断言两次调用与顺序）
+		expect(calls).toEqual(["http://x/api/auth/login", "http://x/api/_platform/market/index"]);
+
+		const text = logs.join("\n");
+		expect(text).toContain("已装 2 个方案");
+		expect(text).toContain("NAME");
+		expect(text).toContain("可升级：demo-solution");
+		expect(text).toContain("签名不受信：acme-demo");
+		expect(text).toContain("no"); // 禁用态
+	});
+
+	it("scenario: --all 连未装行一起列（installed 显示 -），人话里给两个计数", async () => {
+		const { fetchFn } = fetchStub({
+			"/api/auth/login": LOGIN,
+			"/api/_platform/market/index": () => ok(ROWS),
+		});
+		const rows = await listCommand({ siteUrl: "http://x", user: "u", pass: "p", fetchFn, all: true });
+
+		expect(rows.map(r => r.name)).toEqual(["acme-demo", "demo-solution", "not-installed-one"]);
+		expect(rows.find(r => r.name === "not-installed-one")).toMatchObject({ installed: null, upgradable: false, enabled: null });
+		const text = logs.join("\n");
+		expect(text).toContain("3 个方案（已装 2 个）");
+		expect(text).toMatch(/not-installed-one\s+-/); // 未装的行 installed 列是 `-`
+	});
+
+	it("scenario: 站点上一个方案都没装 → 成功（exit 0 语义），人话指路 --all", async () => {
+		const { fetchFn } = fetchStub({
+			"/api/auth/login": LOGIN,
+			"/api/_platform/market/index": () => ok([ROWS[2]]),
+		});
+		const rows = await listCommand({ siteUrl: "http://x", user: "u", pass: "p", fetchFn });
+		expect(rows).toEqual([]);
+		expect(logs.join("\n")).toContain("还没有已装方案");
+		expect(logs.join("\n")).toContain("ojm list --all");
+	});
+
+	it("scenario: 缺凭据 → 用法错误（2），不去联网", async () => {
+		const { fetchFn, calls } = fetchStub({});
+		await expect(listCommand({ siteUrl: "http://x", fetchFn })).rejects.toThrowError(/缺少站点凭据/);
+		expect(calls).toEqual([]);
+	});
+});
+
+/* ────────────────────────────── CLI 接线与信封 ────────────────────────────── */
+
+interface RunResult { out: string[], err: string[], exitCode: number | undefined }
+
+async function run(argv: string[], fetchFn: typeof fetch): Promise<RunResult> {
+	vi.stubGlobal("fetch", fetchFn);
+	const out: string[] = [];
+	const err: string[] = [];
+	vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+		out.push(args.map(String).join(" "));
+	});
+	vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+		err.push(args.map(String).join(" "));
+	});
+	const exitSpy = vi.fn();
+	const exit = exitSpy as unknown as (code: number) => never;
+	const cli = buildCli(process.cwd(), "zh-CN", { exit, argv });
+	try {
+		cli.parse(["node", "ojm", ...argv], { run: true });
+	}
+	catch (error) {
+		reportCliError(localizeCacError(error, "zh-CN"), exit, argv);
+	}
+	await vi.waitUntil(() => out.length > 0 || err.length > 0 || exitSpy.mock.calls.length > 0, { timeout: 3000, interval: 10 });
+	return { out, err, exitCode: exitSpy.mock.calls[0]?.[0] as number | undefined };
+}
+
+describe("list：CLI 接线与信封", () => {
+	it("scenario: --json → stdout 只有一行信封，data.solutions 是过滤后的已装行", async () => {
+		const { fetchFn } = fetchStub({
+			"/api/auth/login": LOGIN,
+			"/api/_platform/market/index": () => ok(ROWS),
+		});
+		const r = await run(["list", "--site-url", "http://x", "--user", "u", "--pass", "p", "--json"], fetchFn);
+
+		expect(r.exitCode).toBeUndefined();
+		expect(r.out).toHaveLength(1);
+		const envelope = JSON.parse(r.out[0]!) as { ok: boolean, command: string, code: string, data: { site: string, all: boolean, solutions: SolutionRow[] } };
+		expect(envelope).toMatchObject({ ok: true, command: "list", code: "ok" });
+		expect(envelope.data.site).toBe("http://x");
+		expect(envelope.data.all).toBe(false);
+		expect(envelope.data.solutions.map(s => s.name)).toEqual(["acme-demo", "demo-solution"]);
+	});
+
+	it("scenario: --all 也进信封（all = true 且包含未装行）", async () => {
+		const { fetchFn } = fetchStub({
+			"/api/auth/login": LOGIN,
+			"/api/_platform/market/index": () => ok(ROWS),
+		});
+		const r = await run(["list", "--site-url", "http://x", "--user", "u", "--pass", "p", "--all", "--json"], fetchFn);
+		const envelope = JSON.parse(r.out[0]!) as { data: { all: boolean, solutions: SolutionRow[] } };
+		expect(envelope.data.all).toBe(true);
+		expect(envelope.data.solutions).toHaveLength(3);
+	});
+
+	it("scenario: 站点报错（索引 503）→ 业务失败（1），错误话说清楚", async () => {
+		const { fetchFn } = fetchStub({
+			"/api/auth/login": LOGIN,
+			"/api/_platform/market/index": () => ({ ok: false, status: 503, text: async () => JSON.stringify({ code: 503, msg: "未配置市场地址" }) }),
+		});
+		const r = await run(["list", "--site-url", "http://x", "--user", "u", "--pass", "p"], fetchFn);
+		expect(r.exitCode).toBe(1);
+		expect(r.err.join("\n")).toContain("未配置市场地址");
+	});
+});