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

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@international-iot-association/plugin-cli",
+  "version": "1.0.0-rc.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/International-IoT-Association/MES.git",
+    "directory": "electron-station-plugins/packages/plugin-cli"
+  },
+  "type": "module",
+  "description": "单插件目录的打包（pack）与预检（check）纯函数与 CLI。签名逻辑（sign.mjs）不在此包，留在仓内 electron-station-plugins/tools/。",
+  "bin": {
+    "plugin-cli": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest-schema": {
+      "types": "./src/manifest-schema.d.mts",
+      "default": "./src/manifest-schema.mjs"
+    },
+    "./smoke": {
+      "types": "./src/smoke.d.mts",
+      "default": "./src/smoke.mjs"
+    },
+    "./new": {
+      "types": "./src/new.ts",
+      "default": "./src/new.ts"
+    },
+    "./check": {
+      "types": "./src/check.d.mts",
+      "default": "./src/check.mjs"
+    },
+    "./test-runner": {
+      "types": "./src/test-runner.d.mts",
+      "default": "./src/test-runner.mjs"
+    },
+    "./stage": {
+      "types": "./src/stage.ts",
+      "default": "./src/stage.ts"
+    },
+    "./zip": {
+      "types": "./src/zip.ts",
+      "default": "./src/zip.ts"
+    },
+    "./registry": {
+      "types": "./src/registry.ts",
+      "default": "./src/registry.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/manifest-schema.mjs",
+    "src/manifest-schema.d.mts",
+    "src/smoke.mjs",
+    "src/smoke.d.mts",
+    "src/new.ts",
+    "src/check.mjs",
+    "src/check.d.mts",
+    "src/test-runner.mjs",
+    "src/test-runner.d.mts",
+    "src/stage.ts",
+    "src/zip.ts",
+    "src/registry.ts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.mjs",
+    "clean": "rimraf dist .turbo"
+  },
+  "dependencies": {
+    "@international-iot-association/api-bridge": "3.0.0-rc.1",
+    "@international-iot-association/plugin-vite-config": "1.0.0-rc.1",
+    "adm-zip": "^0.5.16"
+  },
+  "devDependencies": {
+    "@international-iot-association/tsconfig": "1.0.0-rc.1",
+    "@types/adm-zip": "^0.5.7",
+    "@types/node": "^22.19.1",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3"
+  },
+  "x-internal-version": "1.0.0",
+  "x-source-revision": "410a2f3b85ef03b678f04f22ea0a47718f5ddae1",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/check.d.mts

@@ -0,0 +1,8 @@
+// check.mjs 的类型声明（供 tools/verify.mjs、tools/pack.ts 等 TS/JS 消费者取类型）。
+export interface CheckResult {
+  ok: boolean;
+  errors: string[];
+}
+
+export declare function isEmptyTestScript(script: unknown): boolean;
+export declare function checkPlugin(pluginDir: string): CheckResult;

package/src/check.mjs

@@ -0,0 +1,71 @@
+// check 子命令的核心逻辑：单插件档案，不做跨插件对账。
+// 覆盖范围（§3.5-N2）：manifest 严格校验、package.json.name === manifest.id、
+// test 脚本非空壳、>=1 个 test/*.test.mjs、有 smoke.mjs、产物单 React。
+// 明确不覆盖：跨插件 id 对账、registry 对账、全仓 secret-scan——这些只在仓内
+// electron-station-plugins/tools/verify.mjs 的五方对账里做（见 CLI 输出的显式声明）。
+//
+// 本文件是纯 JS（非 .ts）：@international-iot-association/plugin-vite-config 的 "." 导出直接指向源码
+// src/index.mjs（免构建），本文件也需要能被 tools/verify.mjs 用 `node`（非 tsx）
+// 直接静态导入而不依赖 Node 版本的 TS type-stripping 能力，与仓内既有的
+// manifest-schema.mjs / smoke.mjs 两个免构建子路径约定保持一致（WP-3c 评审修复：
+// 原 check.ts 只能经由 dist/index.js 消费，fresh clone + pnpm install 后未先
+// `turbo build` 会在 verify.mjs 顶层 import 处 ERR_MODULE_NOT_FOUND）。
+// 类型声明见同目录 check.d.mts。
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { assertPluginUiSingleReact } from "@international-iot-association/plugin-vite-config";
+import { validatePluginManifest } from "./manifest-schema.mjs";
+
+/**
+ * 判断一个 test 脚本字符串是否是「空壳」（未配置/仅 echo、true、exit 0、: 之类占位）。
+ * 与仓内权威定义 electron-station-plugins/tools/verify.mjs 的判据保持一致，
+ * 避免 check 子命令比五方对账更宽松、放行假绿脚本。
+ */
+export function isEmptyTestScript(script) {
+  if (typeof script !== "string") return true;
+  const trimmed = script.trim();
+  if (trimmed.length === 0) return true;
+  return /^(echo\b|true$|exit\s+0$|:$)/.test(trimmed);
+}
+
+/** 对单个插件目录做打包前预检，返回是否通过与错误列表。 */
+export function checkPlugin(pluginDir) {
+  const errors = [];
+
+  const manifestPath = join(pluginDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    return { ok: false, errors: [`missing manifest.json in ${pluginDir}`] };
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const { ok: manifestOk, errors: manifestErrors } = validatePluginManifest(manifest);
+  if (!manifestOk) {
+    for (const e of manifestErrors) errors.push(`manifest: ${e}`);
+  }
+
+  const pkgPath = join(pluginDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    errors.push("missing package.json");
+  } else {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (manifestOk && pkg.name !== manifest.id) {
+      errors.push(`package.json.name (${pkg.name}) !== manifest.id (${manifest.id})`);
+    }
+    if (isEmptyTestScript(pkg.scripts?.test)) {
+      errors.push("package.json.scripts.test 缺失或是空壳");
+    }
+  }
+
+  const testDir = join(pluginDir, "test");
+  const hasTestFile =
+    existsSync(testDir) && readdirSync(testDir).some((f) => f.endsWith(".test.mjs"));
+  if (!hasTestFile) errors.push("缺少 test/*.test.mjs（至少 1 个）");
+
+  if (!existsSync(join(pluginDir, "smoke.mjs"))) {
+    errors.push("缺少 smoke.mjs");
+  }
+
+  const reactGate = assertPluginUiSingleReact(pluginDir);
+  if (!reactGate.ok) errors.push(reactGate.error);
+
+  return { ok: errors.length === 0, errors };
+}

package/src/manifest-schema.d.mts

@@ -0,0 +1,9 @@
+// tools/manifest-schema.mjs 的类型声明（供 pack.ts / new-plugin.ts 等 TS 工具消费）。
+export declare const WINDOWS_RESERVED_NAMES: Set<string>;
+export declare function isStrictSemver(value: unknown): boolean;
+export declare function isValidPluginId(value: unknown): boolean;
+export declare function isSafeRelativeEntry(value: unknown): boolean;
+export declare function validatePluginManifest(manifest: unknown): {
+  ok: boolean;
+  errors: string[];
+};

package/src/manifest-schema.mjs

@@ -0,0 +1,224 @@
+// tools/manifest-schema.mjs —— 插件 manifest 的严格校验器（零依赖）。
+//
+// 依据 docs/mes-redesign-proposal/15-electron-plugin-platform-adjustment-plan.md
+// P0-01 第 3 条：插件 ID 使用严格命名规则；version 必须是 strict SemVer；
+// 显式拒绝 `.`/`..`、路径分隔符、Windows 保留名、尾随点/空格和 drive/UNC 变体。
+//
+// 使用方：tools/pack.ts（打包前校验）、tools/verify.mjs（五方对账）、
+// 脚手架 new-plugin（生成后校验）。外壳安装器有等价的运行期校验。
+//
+// 设计：fail-closed —— 未知顶层字段一律报错，新增契约字段时必须同步更新这里
+// 与 packages/plugin-contracts 的 PluginManifest 类型。
+
+/** semver.org 官方 strict SemVer 正则。 */
+const SEMVER_RE =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/** 插件 ID：全小写、至少两段、段内允许数字/连字符（首段不允许连字符开头）。 */
+const PLUGIN_ID_RE = /^[a-z][a-z0-9]*(\.[a-z0-9][a-z0-9-]*)+$/;
+
+/** 权限名：`serial.dut` / `serial.fixture.control` / `ui:camera` / `storage`。 */
+const PERMISSION_RE = /^[a-z][a-z0-9]*([.:][a-z0-9][a-z0-9-]*)*$/;
+
+/** 依赖版本范围（宽松：只限制字符集，完整 range 解析由包管理器负责）。 */
+const DEP_RANGE_RE = /^[0-9a-zA-Z.^~*<>=| -]+$/;
+
+/** Windows 保留设备名（不区分大小写；作为文件名主干时非法）。 */
+export const WINDOWS_RESERVED_NAMES = new Set([
+  'con',
+  'prn',
+  'aux',
+  'nul',
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+
+const KNOWN_FIELDS = new Set([
+  'id',
+  'name',
+  'version',
+  'description',
+  'kind',
+  'stationTypes',
+  'models',
+  'agentApi',
+  'uiEntry',
+  'runtimeEntry',
+  'permissions',
+  'autoStart',
+  'dependencies',
+  'resultSchema',
+  'steps',
+  'checksum',
+  'storage',
+  'readinessTimeoutMs',
+]);
+
+export function isStrictSemver(value) {
+  return typeof value === 'string' && SEMVER_RE.test(value);
+}
+
+export function isValidPluginId(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 128) return false;
+  if (!PLUGIN_ID_RE.test(value)) return false;
+  // 完整 id 会成为安装目录名：首段不得是 Windows 保留名（CON.x.y 亦被视为设备）
+  const firstSegment = value.split('.', 1)[0];
+  if (WINDOWS_RESERVED_NAMES.has(firstSegment.toLowerCase())) return false;
+  return true;
+}
+
+/**
+ * 包内相对路径是否安全：仅正斜杠、无 `.`/`..` 段、无盘符/UNC/绝对路径、
+ * 每段无尾随点/空格、段主干不是 Windows 保留名。
+ */
+export function isSafeRelativeEntry(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 512) return false;
+  if (value.includes('\\') || value.includes('\0')) return false;
+  if (value.startsWith('/') || /^[a-zA-Z]:/.test(value) || value.startsWith('//')) return false;
+  const segments = value.split('/');
+  for (const segment of segments) {
+    if (segment === '' || segment === '.' || segment === '..') return false;
+    if (segment !== segment.trim() || segment.endsWith('.')) return false;
+    const stem = segment.split('.', 1)[0];
+    if (WINDOWS_RESERVED_NAMES.has(stem.toLowerCase())) return false;
+  }
+  return true;
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+/**
+ * 校验插件 manifest 对象。
+ * @param {unknown} manifest 已 JSON.parse 的 manifest
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validatePluginManifest(manifest) {
+  const errors = [];
+  const push = (msg) => errors.push(msg);
+
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { ok: false, errors: ['manifest 必须是 JSON object'] };
+  }
+  const m = /** @type {Record<string, unknown>} */ (manifest);
+
+  for (const key of Object.keys(m)) {
+    if (!KNOWN_FIELDS.has(key))
+      push(
+        `未知字段 "${key}"（fail-closed：新字段需同步更新 manifest-schema 与 plugin-contracts）`
+      );
+  }
+
+  if (!isValidPluginId(m.id))
+    push(`id 非法："${m.id}"（要求全小写、至少两段、无保留名，如 rti.demo.example）`);
+  if (typeof m.name !== 'string' || m.name.trim() === '') push('name 必须是非空字符串');
+  if (!isStrictSemver(m.version)) push(`version 必须是 strict SemVer："${m.version}"`);
+  if (!isStrictSemver(m.agentApi)) push(`agentApi 必须是 strict SemVer："${m.agentApi}"`);
+
+  const kind = m.kind ?? 'station';
+  if (kind !== 'station' && kind !== 'global') push(`kind 只能是 station/global："${m.kind}"`);
+
+  if (!isStringArray(m.stationTypes)) push('stationTypes 必须是字符串数组（可为空数组）');
+  // models 只是给人看的元数据：外壳仅在插件详情/介绍页把它渲染成「适用机型」，
+  // 没有任何分发、准入或匹配逻辑读它（真正决定「本工位装哪些包」的是 MES 侧
+  // workOrder + stationType + skuId 解析出的 packages 清单）。因此降级为可选：
+  // 声明了就必须是字符串数组，省略等价于空数组。
+  if (m.models !== undefined && !isStringArray(m.models))
+    push('models 必须是字符串数组（可省略；省略等价于空数组）');
+
+  if (!isSafeRelativeEntry(m.runtimeEntry)) push(`runtimeEntry 非法："${m.runtimeEntry}"`);
+  if (kind === 'station') {
+    if (!isSafeRelativeEntry(m.uiEntry)) push(`station 插件必须提供合法 uiEntry："${m.uiEntry}"`);
+  } else if (m.uiEntry !== undefined && !isSafeRelativeEntry(m.uiEntry)) {
+    push(`uiEntry 非法："${m.uiEntry}"`);
+  }
+
+  if (!isStringArray(m.permissions)) {
+    push('permissions 必须是字符串数组（可为空数组）');
+  } else {
+    for (const perm of m.permissions) {
+      if (!PERMISSION_RE.test(perm)) push(`permission 非法："${perm}"`);
+    }
+  }
+
+  if (m.autoStart !== undefined && typeof m.autoStart !== 'boolean')
+    push('autoStart 必须是 boolean');
+  if (m.description !== undefined && typeof m.description !== 'string')
+    push('description 必须是字符串');
+  if (m.checksum !== undefined && typeof m.checksum !== 'string') push('checksum 必须是字符串');
+
+  // W3-6（P0-06）：storage 作用域声明。缺省 version scope；shared 必须显式声明。
+  if (m.storage !== undefined) {
+    if (m.storage === null || typeof m.storage !== 'object' || Array.isArray(m.storage)) {
+      push("storage 必须是 { scope?: 'version' | 'shared', migrateLegacy?: boolean } 对象");
+    } else {
+      for (const key of Object.keys(m.storage)) {
+        if (key !== 'scope' && key !== 'migrateLegacy') {
+          push(`storage 未知字段 "${key}"（只允许 scope/migrateLegacy）`);
+        }
+      }
+      const scope = m.storage.scope;
+      if (scope !== undefined && scope !== 'version' && scope !== 'shared') {
+        push(`storage.scope 只能是 version/shared："${scope}"`);
+      }
+      if (m.storage.migrateLegacy !== undefined && typeof m.storage.migrateLegacy !== 'boolean') {
+        push(`storage.migrateLegacy 必须是 boolean："${m.storage.migrateLegacy}"`);
+      }
+    }
+  }
+
+  // W3-4（P0-06）：readiness（activate）超时毫秒数，必须是正整数。
+  if (m.readinessTimeoutMs !== undefined) {
+    if (
+      typeof m.readinessTimeoutMs !== 'number' ||
+      !Number.isInteger(m.readinessTimeoutMs) ||
+      m.readinessTimeoutMs <= 0
+    ) {
+      push(`readinessTimeoutMs 必须是正整数毫秒数："${m.readinessTimeoutMs}"`);
+    }
+  }
+
+  if (m.resultSchema !== undefined && !isSafeRelativeEntry(m.resultSchema)) {
+    push(`resultSchema 非法："${m.resultSchema}"`);
+  }
+
+  if (m.dependencies !== undefined) {
+    if (
+      m.dependencies === null ||
+      typeof m.dependencies !== 'object' ||
+      Array.isArray(m.dependencies)
+    ) {
+      push('dependencies 必须是 { pluginId: versionRange } 对象');
+    } else {
+      for (const [depId, range] of Object.entries(m.dependencies)) {
+        if (!isValidPluginId(depId)) push(`dependencies 键非法："${depId}"`);
+        if (typeof range !== 'string' || range.trim() === '' || !DEP_RANGE_RE.test(range)) {
+          push(`dependencies["${depId}"] 版本范围非法："${range}"`);
+        }
+      }
+    }
+  }
+
+  if (m.steps !== undefined) {
+    if (!Array.isArray(m.steps)) {
+      push('steps 必须是数组');
+    } else {
+      m.steps.forEach((step, i) => {
+        if (step === null || typeof step !== 'object' || Array.isArray(step)) {
+          push(`steps[${i}] 必须是对象`);
+          return;
+        }
+        if (typeof step.key !== 'string' || step.key.trim() === '')
+          push(`steps[${i}].key 必须是非空字符串`);
+        if (typeof step.label !== 'string' || step.label.trim() === '')
+          push(`steps[${i}].label 必须是非空字符串`);
+        if (step.description !== undefined && typeof step.description !== 'string') {
+          push(`steps[${i}].description 必须是字符串`);
+        }
+      });
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/new.ts

@@ -0,0 +1,220 @@
+// packages/plugin-cli/src/new.ts —— 插件脚手架：从模板生成新插件目录。
+// 逻辑迁移自仓内 electron-station-plugins/tools/new-plugin.ts（ADR-0032 §3.3/§3.5，
+// WP-3b）。默认模板源改为 npm 包 @international-iot-association/plugin-template
+// （尚未发布，见 fetchDefaultTemplate 的报错文案）；--template 指向目录时直接
+// 从该目录实例化，不再内置模板拷贝。tools/new-plugin.ts 现为薄包装，硬编码
+// template=templates/plugin 调用本模块的 scaffoldPlugin。
+import { execFileSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isValidPluginId, validatePluginManifest } from "./manifest-schema.mjs";
+
+const DEFAULT_TEMPLATE_PACKAGE = "@international-iot-association/plugin-template";
+const SKIP_ENTRIES = new Set(["node_modules", "ui-dist", "runtime-dist", ".turbo"]);
+const TEXT_FILE_RE = /\.(ts|tsx|json|css|html|mjs|md)$/;
+const DIR_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+export interface ScaffoldOptions {
+  /** plugins/ 下的目标目录名（安全字符集）。 */
+  dirName: string;
+  /** 插件显示名，用于替换 __PLUGIN_NAME__。 */
+  displayName: string;
+  /** 插件 id，用于替换 __PLUGIN_ID__ 与 package.json.name。 */
+  id: string;
+  /** 模板来源：目录路径 / .tgz 路径；缺省时从 npm 拉取默认模板包。 */
+  template?: string;
+  /**
+   * 默认模板包的版本或 dist-tag（仅在未给 template 时生效）。缺省按本 CLI 自身
+   * 版本推：预发布版（含 "-"）取 "next"，正式版取 "latest"——npm 的 "*" 永远不
+   * 匹配预发布版本，rc 阶段不显式给 spec 会 ETARGET（3.0.0-rc.1 实测）。
+   */
+  templateVersion?: string;
+  /** 目标父目录（生成到 <outParentDir>/<dirName>）；缺省为 cwd 下 plugins/。 */
+  outParentDir: string;
+}
+
+/**
+ * 取路径最后一段——必须同时兼容 POSIX 与 Windows 分隔符。
+ * 原实现用 `src.split("/").pop()`，在 Windows 上传入反斜杠路径时不会真正
+ * 按分隔符切开，导致 SKIP 目录名恒不命中、node_modules 等构建产物被一并
+ * 拷进生成的插件目录（Windows 路径 bug，WP-3b 明确要求修复）。
+ */
+export function lastPathSegment(path: string): string {
+  const parts = path.split(/[\\/]/);
+  return parts[parts.length - 1] ?? "";
+}
+
+/** cpSync filter：跳过构建产物与依赖目录，需兼容 Windows 反斜杠路径。 */
+export function shouldSkipCopy(src: string): boolean {
+  return SKIP_ENTRIES.has(lastPathSegment(src));
+}
+
+function assertSafeDirName(dirName: string): void {
+  if (!DIR_NAME_RE.test(dirName)) {
+    throw new Error(
+      `目录名非法："${dirName}"（只允许小写字母/数字/._-，且不能以 . 或 - 开头）`,
+    );
+  }
+}
+
+/** 把一份 npm pack 产出的 .tgz 解到临时目录，返回其中 package/ 子目录的绝对路径。 */
+function extractTarball(tgzPath: string): string {
+  const extractDir = mkdtempSync(join(tmpdir(), "plugin-cli-tpl-extract-"));
+  execFileSync("tar", ["-xzf", tgzPath, "-C", extractDir], { stdio: "pipe" });
+  const packageDir = join(extractDir, "package");
+  if (!existsSync(packageDir)) {
+    throw new Error(`模板压缩包解压后未找到 package/ 目录（${tgzPath}）：不是合法的 npm 包产物`);
+  }
+  return packageDir;
+}
+
+/** 读取本 CLI 自身（发布形态下）的版本号；读不到时返回空串，走 latest。 */
+function readOwnVersion(): string {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // 构建后本文件在 dist/ 下，源码态在 src/ 下，两者的 package.json 都在上一级。
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")) as { version?: string };
+    return typeof pkg.version === "string" ? pkg.version : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * 决定默认模板包的版本 spec：显式给了就用显式的；否则 CLI 自身是预发布版
+ * 取 dist-tag "next"（发布手册约定 rc 一律打 next），正式版取 "latest"。
+ */
+export function resolveDefaultTemplateSpec(cliVersion: string, override?: string): string {
+  if (override && override.trim()) return override.trim();
+  return cliVersion.includes("-") ? "next" : "latest";
+}
+
+/**
+ * 从默认模板包 @international-iot-association/plugin-template 拉取模板。
+ * 必须带版本 spec：npm 对不带 spec 的包名按 "*" 解析，永远不命中预发布版本。
+ */
+function fetchDefaultTemplate(templateVersion?: string): string {
+  const spec = resolveDefaultTemplateSpec(readOwnVersion(), templateVersion);
+  const packDestDir = mkdtempSync(join(tmpdir(), "plugin-cli-tpl-pack-"));
+  let stdout: string;
+  try {
+    stdout = execFileSync(
+      "npm",
+      ["pack", `${DEFAULT_TEMPLATE_PACKAGE}@${spec}`, "--pack-destination", packDestDir],
+      {
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8",
+        // Windows 上 npm 实际是 npm.cmd，不带 shell 直接 spawn 会 EINVAL/ENOENT
+        // （Node ≥18.20.2/20.12.2 的 CVE-2024-27980 修复后行为）；
+        // 与 test-runner.mjs 里 pnpm 的处理保持一致。
+        shell: process.platform === "win32",
+      },
+    );
+  } catch (err) {
+    throw new Error(
+      `拉取默认模板包 ${DEFAULT_TEMPLATE_PACKAGE}@${spec} 失败：可能是网络 / registry 不可达，` +
+        `或该版本 / dist-tag 下没有发布过模板包。可用 --template-version <版本或 dist-tag> 指定，` +
+        `或改用 --template <本地模板目录或 .tgz>（仓内为 --template templates/plugin）。\n` +
+        `原始错误：${(err as Error).message}`,
+    );
+  }
+  const lastLine = stdout.trim().split("\n").pop() ?? "";
+  const tgzPath = join(packDestDir, lastLine.trim());
+  if (!lastLine || !existsSync(tgzPath)) {
+    throw new Error(`npm pack ${DEFAULT_TEMPLATE_PACKAGE} 未产出可识别的 .tgz 文件`);
+  }
+  return extractTarball(tgzPath);
+}
+
+/** 解析 --template 参数：目录原样使用；.tgz 解压后取 package/ 子目录；缺省走默认模板包。 */
+function resolveTemplateDir(template?: string, templateVersion?: string): string {
+  if (!template) return fetchDefaultTemplate(templateVersion);
+  const resolved = resolve(template);
+  if (resolved.endsWith(".tgz")) {
+    if (!existsSync(resolved)) throw new Error(`模板压缩包不存在：${resolved}`);
+    return extractTarball(resolved);
+  }
+  if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+    throw new Error(`--template 指向的目录不存在或不是目录：${resolved}`);
+  }
+  return resolved;
+}
+
+/** 在文本文件中替换占位符 __PLUGIN_ID__ / __PLUGIN_NAME__（与原 new-plugin.ts 逐字一致）。 */
+function replacePlaceholders(dest: string, id: string, displayName: string): void {
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) {
+        walk(p);
+      } else if (TEXT_FILE_RE.test(e.name)) {
+        const s = readFileSync(p, "utf8");
+        const next = s.split("__PLUGIN_ID__").join(id).split("__PLUGIN_NAME__").join(displayName);
+        if (next !== s) writeFileSync(p, next);
+      }
+    }
+  };
+  walk(dest);
+}
+
+/**
+ * 生成一个新插件目录。
+ * 校验顺序：dirName 安全字符 -> id 合法 -> 目标未占用 -> 拷贝模板 -> 占位符替换 ->
+ * package.json.name 写回 -> 生成产物的 manifest.json 严格自检（不通过则回滚删除
+ * 已生成目录，避免留下半成品）。成功时返回生成目录的绝对路径。
+ */
+export function scaffoldPlugin(opts: ScaffoldOptions): string {
+  assertSafeDirName(opts.dirName);
+  if (!isValidPluginId(opts.id)) {
+    throw new Error(
+      `插件 id 非法："${opts.id}"（要求全小写、至少两段、无 Windows 保留名，如 rti.demo.water-sensor）`,
+    );
+  }
+
+  const dest = join(resolve(opts.outParentDir), opts.dirName);
+  if (existsSync(dest)) {
+    throw new Error(`目标已存在，拒绝覆盖：${dest}`);
+  }
+
+  const templateDir = resolveTemplateDir(opts.template, opts.templateVersion);
+
+  cpSync(templateDir, dest, {
+    recursive: true,
+    filter: (src) => !shouldSkipCopy(src),
+  });
+
+  replacePlaceholders(dest, opts.id, opts.displayName);
+
+  const pkgPath = join(dest, "package.json");
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>;
+    pkg.name = opts.id;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+
+  // 生成后自检：脚手架产物的 manifest 必须直接通过严格校验（原 new-plugin.ts:85-91 逻辑）。
+  const manifestPath = join(dest, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error(`模板缺少 manifest.json（模板目录：${templateDir}）`);
+  }
+  const generatedManifest = JSON.parse(readFileSync(manifestPath, "utf8")) as unknown;
+  const { ok, errors } = validatePluginManifest(generatedManifest);
+  if (!ok) {
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error(`生成的 manifest 未通过校验（模板与 schema 不同步）：\n  - ${errors.join("\n  - ")}`);
+  }
+
+  return dest;
+}

package/src/registry.ts

@@ -0,0 +1,46 @@
+// 单插件 registry 片段。字段形状与仓内 tools/pack.ts 产出的 registry.json 条目
+// 完全一致，只去掉 signature 相关字段（签名留在仓内包，见 ADR-0032 D7）。
+// 与仓外 MES 后台的字段对齐留给 WP-9（WP-0 的接口调研未做，这里先保持形状对齐）。
+import type { PluginManifest } from "./stage.js";
+
+export interface RegistryEntry {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  kind?: "station" | "global";
+  stationTypes: string[];
+  models: string[];
+  agentApi: string;
+  permissions: string[];
+  autoStart?: boolean;
+  dependencies?: Record<string, string>;
+  fileName: string;
+  sha256: string;
+  sizeBytes: number;
+}
+
+/** 由 manifest + zip 结果组装单插件 registry 片段（不含 signature，不含顶层 generatedAt）。 */
+export function buildRegistryEntry(
+  manifest: PluginManifest,
+  fileName: string,
+  sha256: string,
+  sizeBytes: number,
+): RegistryEntry {
+  return {
+    id: manifest.id,
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
+    kind: manifest.kind,
+    stationTypes: manifest.stationTypes,
+    models: manifest.models ?? [],
+    agentApi: manifest.agentApi,
+    permissions: manifest.permissions,
+    autoStart: manifest.autoStart,
+    dependencies: manifest.dependencies,
+    fileName,
+    sha256,
+    sizeBytes,
+  };
+}