@international-iot-association/plugin-cli 1.0.0-rc.1

package/src/smoke.d.mts

@@ -0,0 +1,49 @@
+// packages/plugin-cli/src/smoke.mjs 的类型声明（供 cli.ts 等 TS 消费者引入）。
+// 与 manifest-schema.d.mts 同一约定：声明文件与源文件逐字同目录放置。
+export declare const sleep: (ms: number) => Promise<void>;
+
+export interface SmokeCounters {
+  roundtrips: number;
+  reports: number;
+  permissionDenials: number;
+}
+
+export declare function assertSmokeMinimums(
+  manifest: Record<string, unknown>,
+  counters: SmokeCounters,
+  activated: boolean,
+): void;
+
+export declare function hasChannelPermission(permissions: unknown, logicalName: string): boolean;
+
+export declare function hasChannelControlPermission(
+  permissions: unknown,
+  logicalName: string,
+): boolean;
+
+export declare function hasSerialDiscoveryPermission(permissions: unknown): boolean;
+
+export declare function makeMemoryStorage(): unknown;
+
+export declare function makeBusRouter(): unknown;
+
+export declare function makeBusConsumer(
+  router: unknown,
+  consumerId: string,
+  providerId: string,
+  counters: SmokeCounters,
+): unknown;
+
+export declare function makeGatedHarness(
+  manifest: Record<string, unknown>,
+  opts?: Record<string, unknown>,
+  counters?: SmokeCounters,
+): unknown;
+
+export interface SmokeResult {
+  pluginId: string;
+  roundtrips: number;
+  reports: number;
+}
+
+export declare function runPluginSmoke(pluginDir: string): Promise<SmokeResult>;

package/src/smoke.mjs

@@ -0,0 +1,413 @@
+// packages/plugin-cli/src/smoke.mjs —— 插件无头 smoke 的共享工具箱。
+// 迁移自仓内 electron-station-plugins/tools/smoke-harness.mjs（ADR-0032 §3.5-N2，
+// WP-3b）。逻辑与原文件逐字保持一致，唯一变化：api-bridge 从仓内相对路径
+// import 改为包依赖 @international-iot-association/api-bridge（发布时按 scope 改写）。
+// tools/smoke-harness.mjs 现为薄包装：export * from "@international-iot-association/plugin-cli/smoke"。
+//
+// 与外壳等价的行为：
+// - ctx 形状对齐 electron-station-shell/src/main/plugin-host/runner.ts；
+// - 通道权限门对齐 electron-station-shell/src/main/plugin/pluginManager.ts：
+//     writeRead/subscribe: <name> | <name>.writeRead | channel.<name>.writeRead
+//     control(configure/open/close/status): <name>.control | channel.<name>.control
+//     listPorts/detectDevices: serial | serial.discovery | channel.serial.discovery(.read)
+//     storage: 仅声明 "storage" 权限时注入
+//     dialog: 仅声明 "ui:file-dialog" 权限时注入
+//     platform.upload: 仅声明 "platform:object-upload" 权限时注入
+//     platform.virtualSerial: 仅声明 "devtools:virtual-serial" 权限时注入
+//       （权限决定方法在不在，外壳设置开关决定调用成不成——与关系）
+//     writeReadMock: 不需要权限（进程内合成）
+// - 权限不足时抛出与外壳同语义的错误 —— smoke 场景不能用 ctx 桩绕过权限门。
+//
+// 每个插件在其根目录提供 smoke.mjs：
+//   export default async function smoke(toolkit) { ... }
+// 由 tools/verify.mjs 发现并执行。toolkit 的 runSmoke 完成后强制断言：
+//   activate 成功 + 至少一次 API 往返 +（station 插件）至少一条 ctx.report.result。
+// 已退役的 rti.global.logger 兼容壳不提供 API，仅在 manifest 仍满足退役不变量时豁免往返。
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createAPIClient } from "@international-iot-association/api-bridge";
+import { validatePluginManifest } from "./manifest-schema.mjs";
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function isRetiredGlobalLoggerCompatibilityShell(manifest) {
+  return (
+    manifest.id === "rti.global.logger" &&
+    manifest.kind === "global" &&
+    manifest.autoStart === false &&
+    Array.isArray(manifest.permissions) &&
+    manifest.permissions.length === 0
+  );
+}
+
+export function assertSmokeMinimums(manifest, counters, activated) {
+  assert.ok(activated, `${manifest.id} smoke 未调用 toolkit.activate()`);
+  assert.ok(
+    counters.roundtrips >= 1 || isRetiredGlobalLoggerCompatibilityShell(manifest),
+    `${manifest.id} smoke 未完成任何 API 往返`,
+  );
+  const kind = manifest.kind ?? "station";
+  if (kind === "station") {
+    assert.ok(counters.reports >= 1, `${manifest.id} smoke 未产生任何 ctx.report.result`);
+  }
+}
+
+// ---- 权限判定（与 pluginManager.ts 保持逐字等价的规则）----------------------
+
+export function hasChannelPermission(permissions, logicalName) {
+  return (
+    permissions.includes(logicalName) ||
+    permissions.includes(`${logicalName}.writeRead`) ||
+    permissions.includes(`channel.${logicalName}.writeRead`)
+  );
+}
+
+export function hasChannelControlPermission(permissions, logicalName) {
+  return (
+    permissions.includes(`${logicalName}.control`) ||
+    permissions.includes(`channel.${logicalName}.control`)
+  );
+}
+
+export function hasSerialDiscoveryPermission(permissions) {
+  return permissions.some(
+    (perm) =>
+      perm === "serial" ||
+      perm === "serial.discovery" ||
+      perm === "channel.serial.discovery" ||
+      perm === "channel.serial.discovery.read",
+  );
+}
+
+// ---- 进程内桩（与 verify-bridge.mjs 同源语义）-------------------------------
+
+/** 内存版 ctx.storage：与外壳 runner 的语义一致（read 缺省 null、list 仅文件名）。 */
+export function makeMemoryStorage() {
+  const files = new Map();
+  const normalize = (p) => p.replace(/^\.\//, "");
+  return {
+    dir: "/mem",
+    async read(p) {
+      const key = normalize(p);
+      return files.has(key) ? files.get(key) : null;
+    },
+    async write(p, c) {
+      files.set(normalize(p), c);
+    },
+    async append(p, c) {
+      const key = normalize(p);
+      files.set(key, (files.get(key) ?? "") + c);
+    },
+    async list(dir = ".") {
+      const prefix = dir === "." ? "" : `${dir.replace(/\/+$/, "")}/`;
+      const names = [];
+      for (const key of files.keys()) {
+        if (!key.startsWith(prefix)) continue;
+        const rest = key.slice(prefix.length);
+        if (rest && !rest.includes("/")) names.push(rest);
+      }
+      return names;
+    },
+    async remove(p) {
+      files.delete(normalize(p));
+    },
+    _files: files,
+  };
+}
+
+/** 进程内服务总线路由：模拟外壳的 from/to 转发（目标未注册则丢弃）。 */
+export function makeBusRouter() {
+  const nodes = new Map();
+  return {
+    register(pluginId) {
+      const handlers = [];
+      nodes.set(pluginId, handlers);
+      return {
+        postMessage(to, envelope) {
+          const target = nodes.get(to);
+          if (!target) return;
+          queueMicrotask(() => {
+            for (const h of target) h(pluginId, envelope);
+          });
+        },
+        onMessage(handler) {
+          handlers.push(handler);
+        },
+      };
+    },
+  };
+}
+
+/** 以「消费者插件」身份接到总线上，返回原始 api-bridge 客户端（轴 D）。 */
+export function makeBusConsumer(router, consumerId, providerId, counters) {
+  const endpoint = router.register(consumerId);
+  const { client, clientMessageHandler, serverEventHandler } = createAPIClient({
+    requestServerFunc: async (req) => {
+      endpoint.postMessage(providerId, req);
+    },
+  });
+  endpoint.onMessage((_from, envelope) => {
+    if (envelope.type === "response") {
+      counters?.roundtrips !== undefined && (counters.roundtrips += 1);
+      clientMessageHandler(envelope);
+    } else if (envelope.type === "event") {
+      serverEventHandler(envelope);
+    }
+  });
+  return client;
+}
+
+// ---- 权限门 ctx + 轴 A 客户端 ------------------------------------------------
+
+/**
+ * 构造一个带权限门的无头 ctx 与轴 A 客户端。
+ * @param manifest 已校验的插件 manifest（权限门数据源）
+ * @param opts.writeRead 设备往返桩（缺省 fail-closed："no device configured"）
+ * @param opts.controlOverride 覆盖 control 行为（缺省 mock provider 状态机应答）
+ * @param opts.bus 轴 D 端点（缺省断线总线）
+ * @param opts.storage 内存 storage（仅当 manifest 声明 storage 权限时注入）
+ * @param opts.dialog dialog 桩（仅当 manifest 声明 ui:file-dialog 时注入）
+ * @param opts.upload 机台上传桩（仅当 manifest 声明 platform:object-upload 时注入）
+ * @param opts.virtualSerial 虚拟串口桩（仅当 manifest 声明 devtools:virtual-serial 时注入；
+ *   缺省桩三个方法全部抛错，对齐外壳「开关默认关闭」的语义）
+ * @param counters 由 runSmoke 传入的计数器
+ */
+export function makeGatedHarness(manifest, opts = {}, counters = { roundtrips: 0 }) {
+  const permissions = manifest.permissions ?? [];
+  const events = [];
+  const results = [];
+  const subscriptions = new Map();
+  let runtimeOnMessage = null;
+
+  const deny = (message) => {
+    const err = new Error(message);
+    counters.permissionDenials = (counters.permissionDenials ?? 0) + 1;
+    throw err;
+  };
+
+  const defaultControl = async (request) => {
+    if (request.action === "configure") {
+      return {
+        logicalName: request.config.logicalName,
+        provider: request.config.provider,
+        state: "closed",
+        metrics: {},
+      };
+    }
+    if (request.action === "open") {
+      return { logicalName: request.logicalName, provider: "mock", state: "open", metrics: {} };
+    }
+    if (request.action === "close") {
+      return { logicalName: request.logicalName, provider: "mock", state: "closed", metrics: {} };
+    }
+    if (request.action === "status") {
+      return { logicalName: request.logicalName, provider: "mock", state: "open", metrics: {} };
+    }
+    if (request.action === "listPorts" || request.action === "detectDevices") return [];
+    throw new Error(`unexpected control action: ${request.action}`);
+  };
+
+  const ctx = {
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    channels: {
+      async writeReadMock(logicalName, payload) {
+        return {
+          logicalName,
+          request: payload,
+          response: `MOCK<${logicalName}>:${payload}:OK`,
+          latencyMs: 1,
+        };
+      },
+      async writeRead(logicalName, payload, options) {
+        if (!hasChannelPermission(permissions, logicalName)) {
+          deny(
+            `permission denied: plugin "${manifest.id}" has no permission for channel "${logicalName}"`,
+          );
+        }
+        if (!opts.writeRead) throw new Error("no device configured");
+        return opts.writeRead(logicalName, payload, options);
+      },
+      async control(request) {
+        if (request.action === "listPorts" || request.action === "detectDevices") {
+          if (!hasSerialDiscoveryPermission(permissions)) {
+            deny(`plugin "${manifest.id}" has no serial discovery permission for ${request.action}`);
+          }
+        } else {
+          const logicalName =
+            request.action === "configure" ? request.config.logicalName : request.logicalName;
+          if (!hasChannelControlPermission(permissions, logicalName)) {
+            deny(`plugin ${manifest.id} does not have permission for channel ${logicalName}`);
+          }
+        }
+        return (opts.controlOverride ?? defaultControl)(request);
+      },
+      subscribe(logicalName, handler) {
+        if (!hasChannelPermission(permissions, logicalName)) {
+          deny(
+            `permission denied: plugin "${manifest.id}" has no permission for channel "${logicalName}"`,
+          );
+        }
+        const list = subscriptions.get(logicalName) ?? [];
+        list.push(handler);
+        subscriptions.set(logicalName, list);
+        // 与契约一致：返回反注册函数（移除本次 handler，幂等）。
+        return () => {
+          const current = subscriptions.get(logicalName);
+          if (!current) return;
+          const idx = current.indexOf(handler);
+          if (idx >= 0) current.splice(idx, 1);
+        };
+      },
+    },
+    report: {
+      stepEvent: (e) => events.push(e),
+      result: (r) => {
+        counters.reports = (counters.reports ?? 0) + 1;
+        results.push(r);
+      },
+    },
+    ui: {
+      postMessage: (env) => {
+        if (env.type === "response") {
+          counters.roundtrips += 1;
+          clientMessageHandler(env);
+        } else if (env.type === "event") {
+          serverEventHandler(env);
+        }
+      },
+      onMessage: (h) => {
+        runtimeOnMessage = h;
+      },
+    },
+    bus: opts.bus ?? { postMessage() {}, onMessage() {} },
+  };
+
+  if (permissions.includes("storage")) {
+    ctx.storage = opts.storage ?? makeMemoryStorage();
+  }
+  if (permissions.includes("ui:file-dialog")) {
+    ctx.dialog = opts.dialog ?? {
+      async openFile() {
+        // W1-7 契约：files 为一次性 handle 列表（不再回传绝对路径 filePaths）。
+        return { canceled: true, files: [] };
+      },
+    };
+  }
+  if (permissions.includes("platform:object-upload")) {
+    // 机台上传对象。缺省桩**恒失败且不可重试**：smoke 里"什么都不接就默默成功"
+    // 会让一个根本没接线的上传路径看起来是绿的。要测成功路径就自己传 opts.upload。
+    ctx.platform = {
+      ...(ctx.platform ?? {}),
+      upload: opts.upload ?? {
+        async submit() {
+          return {
+            ok: false,
+            code: "internal",
+            faultCode: "UP-SMOKE-STUB",
+            retryable: false,
+            detail: "smoke 缺省上传桩：未注入 opts.upload",
+            attempts: 1,
+            uploadedBeforeFailure: 0,
+          };
+        },
+      },
+    };
+  }
+
+  if (permissions.includes("devtools:virtual-serial")) {
+    // 虚拟串口（ADR-0031 D2/D3）。与外壳同款「与关系」：**权限决定方法在不在，
+    // 开关决定调用成不成**——外壳里开关默认关闭，create 会抛「未启用」。
+    // 所以缺省桩也恒失败：smoke 里默默铸出一对假 PTY 会让「没开开关也能跑」
+    // 这个错误结论看起来是绿的。要测成功路径就自己传 opts.virtualSerial。
+    //
+    // 注意这里**没有**、也不许有任何把 PTY 绑进通道的方法（ADR-0031 D6）：
+    // clientPath 只作只读文本交出去，由人工填进工位配置。
+    const denyVirtualSerial = async () => {
+      throw new Error(
+        "虚拟串口能力未启用：smoke 缺省桩不铸造 PTY（要测成功路径请注入 opts.virtualSerial）",
+      );
+    };
+    ctx.platform = {
+      ...(ctx.platform ?? {}),
+      virtualSerial: opts.virtualSerial ?? {
+        create: denyVirtualSerial,
+        release: denyVirtualSerial,
+        list: denyVirtualSerial,
+      },
+    };
+  }
+
+  const { client, clientMessageHandler, serverEventHandler } = createAPIClient({
+    requestServerFunc: async (req) => {
+      runtimeOnMessage?.(req);
+    },
+  });
+
+  /** 向订阅了 logicalName 的 runtime 处理器注入一条设备事件。 */
+  const emitChannelEvent = (logicalName, event) => {
+    for (const handler of subscriptions.get(logicalName) ?? []) handler(event);
+  };
+
+  return { ctx, client, events, results, subscriptions, emitChannelEvent, storage: ctx.storage };
+}
+
+// ---- smoke 执行入口 -----------------------------------------------------------
+
+/**
+ * 运行一个插件的 smoke.mjs。
+ * @param pluginDir 插件绝对路径（plugins/<dir>）
+ * @returns {Promise<{ pluginId: string, roundtrips: number, reports: number }>}
+ */
+export async function runPluginSmoke(pluginDir) {
+  const manifestRaw = readFileSync(join(pluginDir, "manifest.json"), "utf8");
+  const manifest = JSON.parse(manifestRaw);
+  const { ok, errors } = validatePluginManifest(manifest);
+  if (!ok) throw new Error(`manifest 校验失败（${pluginDir}）：${errors.join("; ")}`);
+
+  const counters = { roundtrips: 0, reports: 0, permissionDenials: 0 };
+  let activated = false;
+
+  const toolkit = {
+    assert,
+    sleep,
+    manifest,
+    pluginDir,
+    counters,
+    makeBusRouter,
+    makeMemoryStorage,
+    makeBusConsumer: (router, consumerId, providerId) =>
+      makeBusConsumer(router, consumerId, providerId, counters),
+    createHarness: (opts = {}) => makeGatedHarness(manifest, opts, counters),
+    /**
+     * 激活已构建 runtime 并登记 smoke 最小契约。
+     * override 只供需要测试专用 assembly 的 smoke 使用；默认仍加载插件导出的生产 activate。
+     */
+    async activate(ctx, override) {
+      let runtimeActivate = override;
+      if (runtimeActivate === undefined) {
+        const entry = pathToFileURL(join(pluginDir, "runtime-dist", "main.mjs")).href;
+        const mod = await import(entry);
+        runtimeActivate = mod.activate;
+      }
+      if (typeof runtimeActivate !== "function") {
+        throw new Error(`runtime-dist/main.mjs 未提供可调用的 activate()（${manifest.id}）`);
+      }
+      const handle = await runtimeActivate(ctx);
+      activated = true;
+      return handle;
+    },
+  };
+
+  const smokeUrl = pathToFileURL(join(pluginDir, "smoke.mjs")).href;
+  const smokeMod = await import(smokeUrl);
+  if (typeof smokeMod.default !== "function") {
+    throw new Error(`smoke.mjs 必须默认导出 async 函数（${manifest.id}）`);
+  }
+  await smokeMod.default(toolkit);
+
+  assertSmokeMinimums(manifest, counters, activated);
+  return { pluginId: manifest.id, roundtrips: counters.roundtrips, reports: counters.reports };
+}

package/src/stage.ts

@@ -0,0 +1,86 @@
+// 单插件目录的 staging 纯函数：从 electron-station-plugins/tools/pack.ts:131-165 抽出。
+//
+// 与仓内原实现的关键差异（WP-3a 决定）：
+//   - 只接受调用方传入的 pluginDir / stagingDir，不做全仓插件遍历；
+//   - 不 rmSync 任何全仓目录（原实现 :211 会清空 repoRoot/dist，这里绝不触碰）；
+//   - 签名相关逻辑（sign.mjs）一个符号都不 import，留在仓内 tools/pack.ts。
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { assertPluginUiSingleReact } from "@international-iot-association/plugin-vite-config";
+import { validatePluginManifest } from "./manifest-schema.mjs";
+
+/** 插件 manifest.json 的形状，与仓内 tools/pack.ts 的 Manifest 接口一致。 */
+export interface PluginManifest {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  kind?: "station" | "global";
+  stationTypes: string[];
+  /** 可选展示元数据；写进 registry 片段时归一化为 []。 */
+  models?: string[];
+  agentApi: string;
+  permissions: string[];
+  autoStart?: boolean;
+  dependencies?: Record<string, string>;
+  /** kind=global 时可省略（无界面后台插件，不打包 ui/）。 */
+  uiEntry?: string;
+  runtimeEntry: string;
+}
+
+function assertExists(path: string, label: string): void {
+  if (!existsSync(path)) throw new Error(`${label} not found: ${path}`);
+}
+
+/** 读取并严格校验单个插件目录的 manifest.json（fail-closed，校验失败即抛错）。 */
+export function readPluginManifest(pluginDir: string): PluginManifest {
+  const manifestPath = join(pluginDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`missing manifest.json in ${pluginDir}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as PluginManifest;
+  const { ok, errors } = validatePluginManifest(manifest);
+  if (!ok) {
+    throw new Error(`manifest 校验失败（${manifestPath}）：\n  - ${errors.join("\n  - ")}`);
+  }
+  return manifest;
+}
+
+/**
+ * 把单个插件目录的构建产物组装进 stagingDir：
+ *   manifest.json -> 根；schemas/ -> schemas/；ui-dist/ -> ui/；runtime-dist/ -> runtime/。
+ * 同时做入口存在性断言（uiEntry/runtimeEntry 在 staging 内必须能解析到）与产物单 React 断言。
+ * 只清理并写入调用方传入的 stagingDir，不触碰任何全仓目录。
+ */
+export function stagePlugin(pluginDir: string, stagingDir: string): PluginManifest {
+  const manifest = readPluginManifest(pluginDir);
+
+  rmSync(stagingDir, { recursive: true, force: true });
+  mkdirSync(stagingDir, { recursive: true });
+
+  cpSync(join(pluginDir, "manifest.json"), join(stagingDir, "manifest.json"));
+
+  const schemas = join(pluginDir, "schemas");
+  if (existsSync(schemas)) cpSync(schemas, join(stagingDir, "schemas"), { recursive: true });
+
+  if (manifest.uiEntry) {
+    const uiDist = join(pluginDir, "ui-dist");
+    assertExists(uiDist, `ui build output (run "pnpm --filter ${manifest.id} build")`);
+    // 拒收双 React 单文件产物（useRef null / 空白页）
+    const reactGate = assertPluginUiSingleReact(pluginDir);
+    if (!reactGate.ok) {
+      throw new Error(reactGate.error);
+    }
+    cpSync(uiDist, join(stagingDir, "ui"), { recursive: true });
+  }
+
+  const runtimeDist = join(pluginDir, "runtime-dist");
+  assertExists(runtimeDist, `runtime build output (run "pnpm --filter ${manifest.id} build")`);
+  cpSync(runtimeDist, join(stagingDir, "runtime"), { recursive: true });
+
+  // 快速失败：installer 之后要校验的入口必须能在 staging 内解析到。
+  if (manifest.uiEntry) assertExists(join(stagingDir, manifest.uiEntry), `uiEntry "${manifest.uiEntry}"`);
+  assertExists(join(stagingDir, manifest.runtimeEntry), `runtimeEntry "${manifest.runtimeEntry}"`);
+
+  return manifest;
+}

package/src/test-runner.d.mts

@@ -0,0 +1,11 @@
+// test-runner.mjs 的类型声明。
+export interface TestRunResult {
+  ok: boolean;
+  testCount: number | null;
+  output: string;
+  error?: string;
+}
+
+export declare function parseTapTestCount(output: string): number | null;
+export declare function parseTapFailureCount(output: string): number | null;
+export declare function runPluginTestSuite(pluginDir: string): TestRunResult;

package/src/test-runner.mjs

@@ -0,0 +1,82 @@
+// 单插件测试执行 + TAP 汇总解析（ADR-0032 §3.5-N2）。
+// 与仓内 tools/verify.mjs 的 parseNodeTestSummary 同一套判据：显式强制
+// --test-reporter=tap，解析不到 "# tests N" 一律判失败——Node 22+ 默认 spec
+// reporter，不钉死会把没有真正跑测试的插件误判成通过（假绿）。
+// 同样必须解析 "# fail N" / "# cancelled N"：仅看 "# tests N" + 进程退出码会漏判
+// 「测试脚本吞掉了非零退出码，但 TAP 里确有失败/取消用例」这一假绿场景
+// （WP-3c 评审修复，避免 verify.mjs 第 5 步比旧 parseNodeTestSummary 更松）。
+//
+// 本文件是纯 JS（非 .ts）：需要能被 tools/verify.mjs 用 `node`（非 tsx）直接静态
+// 导入，不依赖 Node 版本的 TS type-stripping 能力，与 check.mjs 同一整改（WP-3c
+// 评审修复）。类型声明见同目录 test-runner.d.mts。
+import { spawnSync } from "node:child_process";
+
+/** 解析 `node --test` 的 TAP 汇总；找不到返回 null（与 verify.mjs 判据一致）。 */
+export function parseTapTestCount(output) {
+  const matches = [...output.matchAll(/^# tests (\d+)$/gm)];
+  const last = matches.at(-1);
+  return last ? Number(last[1]) : null;
+}
+
+/**
+ * 解析 TAP 汇总里的失败数（`# fail N` + `# cancelled N` 之和，取最后一份汇总）。
+ * 找不到 `# fail` 行返回 null——与 verify.mjs 的 parseNodeTestSummary 同一判据：
+ * 没有 fail 行时视为汇总不完整，交给调用方按「没有真正跑测试」处理。
+ */
+export function parseTapFailureCount(output) {
+  const fail = [...output.matchAll(/^# fail (\d+)$/gm)].at(-1);
+  if (!fail) return null;
+  const cancelled = [...output.matchAll(/^# cancelled (\d+)$/gm)].at(-1);
+  return Number(fail[1]) + (cancelled ? Number(cancelled[1]) : 0);
+}
+
+/**
+ * 在插件目录跑 `pnpm test`，通过 NODE_OPTIONS 强制 TAP reporter；
+ * 解析不到汇总、汇总为 0、有失败/取消用例、或进程非零退出，一律判失败。
+ * 供 CLI `check` / `smoke` 子命令复用，避免两处各写一份判据。
+ */
+export function runPluginTestSuite(pluginDir) {
+  const result = spawnSync("pnpm", ["test"], {
+    cwd: pluginDir,
+    encoding: "utf8",
+    // Windows 上 pnpm 是 pnpm.cmd，不带 shell 直接 spawn 会 ENOENT；
+    // 与仓内 tools/verify.mjs 的既定写法（run()/runCaptured()）保持一致。
+    shell: process.platform === "win32",
+    env: {
+      ...process.env,
+      NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ""} --test-reporter=tap`.trim(),
+    },
+  });
+  if (result.error) {
+    return {
+      ok: false,
+      testCount: null,
+      output: `${result.stdout ?? ""}${result.stderr ?? ""}`,
+      error: `无法启动测试进程：${result.error.message}`,
+    };
+  }
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const testCount = parseTapTestCount(output);
+  if (testCount === null) {
+    return {
+      ok: false,
+      testCount: null,
+      output,
+      error: "测试输出中没有 node --test TAP 汇总（脚本没有真正跑测试，或未使用 node --test）",
+    };
+  }
+  if (testCount === 0) {
+    return { ok: false, testCount, output, error: "0 个测试用例" };
+  }
+  // 必须先查 fail/cancelled 再查进程退出码：测试脚本可能吞掉非零退出码
+  // （例如 `node --test ...; echo done`），此时 result.status 会是 0，
+  // 只有 TAP 汇总里的 "# fail N" / "# cancelled N" 能揭穿假绿。
+  const failCount = parseTapFailureCount(output);
+  if (failCount !== null && failCount > 0) {
+    return { ok: false, testCount, output, error: `TAP 汇总有 ${failCount} 个失败/取消用例` };
+  }
+  if (result.status !== 0) {
+    return { ok: false, testCount, output, error: `测试进程退出码 ${result.status}` };
+  }
+  return { ok: true, testCount, output };
+}

package/src/zip.ts

@@ -0,0 +1,30 @@
+// 把 staging 目录打成 zip 并计算 sha256。与 pack.ts:223-229 逻辑等价，
+// 但只对调用方给定的 stagingDir / outZip 生效，不做任何全仓路径假设。
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import AdmZip from "adm-zip";
+
+export interface ZipResult {
+  zipPath: string;
+  sha256: string;
+  sizeBytes: number;
+}
+
+/**
+ * 把 stagingDir 的内容打到 zip 根目录（过滤 .DS_Store），写到 outZip，
+ * 返回 zip 路径、sha256、字节数。
+ *
+ * 注意：AdmZip.addLocalFolder 的条目带 mtime，且调用方通常会在 registry 片段里
+ * 写入 generatedAt，所以同一份插件连打两次 sha256 必不同——这是预期行为，
+ * 不是本函数的 bug（等价性验收走「解包后逐文件 sha256」，不是「同 sha256」）。
+ */
+export function zipStaging(stagingDir: string, outZip: string): ZipResult {
+  const zip = new AdmZip();
+  zip.addLocalFolder(stagingDir, "", (entryName) => !entryName.includes(".DS_Store"));
+  zip.writeZip(outZip);
+
+  const bytes = readFileSync(outZip);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const sizeBytes = statSync(outZip).size;
+  return { zipPath: outZip, sha256, sizeBytes };
+}