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

package/dist/cli.js

@@ -0,0 +1,961 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { basename, join as join5, resolve as resolve2 } from "path";
+
+// src/check.mjs
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { assertPluginUiSingleReact } from "@international-iot-association/plugin-vite-config";
+
+// src/manifest-schema.mjs
+var 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-]+)*))?$/;
+var PLUGIN_ID_RE = /^[a-z][a-z0-9]*(\.[a-z0-9][a-z0-9-]*)+$/;
+var PERMISSION_RE = /^[a-z][a-z0-9]*([.:][a-z0-9][a-z0-9-]*)*$/;
+var DEP_RANGE_RE = /^[0-9a-zA-Z.^~*<>=| -]+$/;
+var WINDOWS_RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`)
+]);
+var KNOWN_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "name",
+  "version",
+  "description",
+  "kind",
+  "stationTypes",
+  "models",
+  "agentApi",
+  "uiEntry",
+  "runtimeEntry",
+  "permissions",
+  "autoStart",
+  "dependencies",
+  "resultSchema",
+  "steps",
+  "checksum",
+  "storage",
+  "readinessTimeoutMs"
+]);
+function isStrictSemver(value) {
+  return typeof value === "string" && SEMVER_RE.test(value);
+}
+function isValidPluginId(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 128) return false;
+  if (!PLUGIN_ID_RE.test(value)) return false;
+  const firstSegment = value.split(".", 1)[0];
+  if (WINDOWS_RESERVED_NAMES.has(firstSegment.toLowerCase())) return false;
+  return true;
+}
+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");
+}
+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 \u5FC5\u987B\u662F JSON object"] };
+  }
+  const m = (
+    /** @type {Record<string, unknown>} */
+    manifest
+  );
+  for (const key of Object.keys(m)) {
+    if (!KNOWN_FIELDS.has(key))
+      push(
+        `\u672A\u77E5\u5B57\u6BB5 "${key}"\uFF08fail-closed\uFF1A\u65B0\u5B57\u6BB5\u9700\u540C\u6B65\u66F4\u65B0 manifest-schema \u4E0E plugin-contracts\uFF09`
+      );
+  }
+  if (!isValidPluginId(m.id))
+    push(`id \u975E\u6CD5\uFF1A"${m.id}"\uFF08\u8981\u6C42\u5168\u5C0F\u5199\u3001\u81F3\u5C11\u4E24\u6BB5\u3001\u65E0\u4FDD\u7559\u540D\uFF0C\u5982 rti.demo.example\uFF09`);
+  if (typeof m.name !== "string" || m.name.trim() === "") push("name \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  if (!isStrictSemver(m.version)) push(`version \u5FC5\u987B\u662F strict SemVer\uFF1A"${m.version}"`);
+  if (!isStrictSemver(m.agentApi)) push(`agentApi \u5FC5\u987B\u662F strict SemVer\uFF1A"${m.agentApi}"`);
+  const kind = m.kind ?? "station";
+  if (kind !== "station" && kind !== "global") push(`kind \u53EA\u80FD\u662F station/global\uFF1A"${m.kind}"`);
+  if (!isStringArray(m.stationTypes)) push("stationTypes \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u53EF\u4E3A\u7A7A\u6570\u7EC4\uFF09");
+  if (m.models !== void 0 && !isStringArray(m.models))
+    push("models \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u53EF\u7701\u7565\uFF1B\u7701\u7565\u7B49\u4EF7\u4E8E\u7A7A\u6570\u7EC4\uFF09");
+  if (!isSafeRelativeEntry(m.runtimeEntry)) push(`runtimeEntry \u975E\u6CD5\uFF1A"${m.runtimeEntry}"`);
+  if (kind === "station") {
+    if (!isSafeRelativeEntry(m.uiEntry)) push(`station \u63D2\u4EF6\u5FC5\u987B\u63D0\u4F9B\u5408\u6CD5 uiEntry\uFF1A"${m.uiEntry}"`);
+  } else if (m.uiEntry !== void 0 && !isSafeRelativeEntry(m.uiEntry)) {
+    push(`uiEntry \u975E\u6CD5\uFF1A"${m.uiEntry}"`);
+  }
+  if (!isStringArray(m.permissions)) {
+    push("permissions \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u53EF\u4E3A\u7A7A\u6570\u7EC4\uFF09");
+  } else {
+    for (const perm of m.permissions) {
+      if (!PERMISSION_RE.test(perm)) push(`permission \u975E\u6CD5\uFF1A"${perm}"`);
+    }
+  }
+  if (m.autoStart !== void 0 && typeof m.autoStart !== "boolean")
+    push("autoStart \u5FC5\u987B\u662F boolean");
+  if (m.description !== void 0 && typeof m.description !== "string")
+    push("description \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+  if (m.checksum !== void 0 && typeof m.checksum !== "string") push("checksum \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+  if (m.storage !== void 0) {
+    if (m.storage === null || typeof m.storage !== "object" || Array.isArray(m.storage)) {
+      push("storage \u5FC5\u987B\u662F { scope?: 'version' | 'shared', migrateLegacy?: boolean } \u5BF9\u8C61");
+    } else {
+      for (const key of Object.keys(m.storage)) {
+        if (key !== "scope" && key !== "migrateLegacy") {
+          push(`storage \u672A\u77E5\u5B57\u6BB5 "${key}"\uFF08\u53EA\u5141\u8BB8 scope/migrateLegacy\uFF09`);
+        }
+      }
+      const scope = m.storage.scope;
+      if (scope !== void 0 && scope !== "version" && scope !== "shared") {
+        push(`storage.scope \u53EA\u80FD\u662F version/shared\uFF1A"${scope}"`);
+      }
+      if (m.storage.migrateLegacy !== void 0 && typeof m.storage.migrateLegacy !== "boolean") {
+        push(`storage.migrateLegacy \u5FC5\u987B\u662F boolean\uFF1A"${m.storage.migrateLegacy}"`);
+      }
+    }
+  }
+  if (m.readinessTimeoutMs !== void 0) {
+    if (typeof m.readinessTimeoutMs !== "number" || !Number.isInteger(m.readinessTimeoutMs) || m.readinessTimeoutMs <= 0) {
+      push(`readinessTimeoutMs \u5FC5\u987B\u662F\u6B63\u6574\u6570\u6BEB\u79D2\u6570\uFF1A"${m.readinessTimeoutMs}"`);
+    }
+  }
+  if (m.resultSchema !== void 0 && !isSafeRelativeEntry(m.resultSchema)) {
+    push(`resultSchema \u975E\u6CD5\uFF1A"${m.resultSchema}"`);
+  }
+  if (m.dependencies !== void 0) {
+    if (m.dependencies === null || typeof m.dependencies !== "object" || Array.isArray(m.dependencies)) {
+      push("dependencies \u5FC5\u987B\u662F { pluginId: versionRange } \u5BF9\u8C61");
+    } else {
+      for (const [depId, range] of Object.entries(m.dependencies)) {
+        if (!isValidPluginId(depId)) push(`dependencies \u952E\u975E\u6CD5\uFF1A"${depId}"`);
+        if (typeof range !== "string" || range.trim() === "" || !DEP_RANGE_RE.test(range)) {
+          push(`dependencies["${depId}"] \u7248\u672C\u8303\u56F4\u975E\u6CD5\uFF1A"${range}"`);
+        }
+      }
+    }
+  }
+  if (m.steps !== void 0) {
+    if (!Array.isArray(m.steps)) {
+      push("steps \u5FC5\u987B\u662F\u6570\u7EC4");
+    } else {
+      m.steps.forEach((step, i) => {
+        if (step === null || typeof step !== "object" || Array.isArray(step)) {
+          push(`steps[${i}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+          return;
+        }
+        if (typeof step.key !== "string" || step.key.trim() === "")
+          push(`steps[${i}].key \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+        if (typeof step.label !== "string" || step.label.trim() === "")
+          push(`steps[${i}].label \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+        if (step.description !== void 0 && typeof step.description !== "string") {
+          push(`steps[${i}].description \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
+        }
+      });
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// src/check.mjs
+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);
+}
+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 \u7F3A\u5931\u6216\u662F\u7A7A\u58F3");
+    }
+  }
+  const testDir = join(pluginDir, "test");
+  const hasTestFile = existsSync(testDir) && readdirSync(testDir).some((f) => f.endsWith(".test.mjs"));
+  if (!hasTestFile) errors.push("\u7F3A\u5C11 test/*.test.mjs\uFF08\u81F3\u5C11 1 \u4E2A\uFF09");
+  if (!existsSync(join(pluginDir, "smoke.mjs"))) {
+    errors.push("\u7F3A\u5C11 smoke.mjs");
+  }
+  const reactGate = assertPluginUiSingleReact(pluginDir);
+  if (!reactGate.ok) errors.push(reactGate.error);
+  return { ok: errors.length === 0, errors };
+}
+
+// src/new.ts
+import { execFileSync } from "child_process";
+import {
+  cpSync,
+  existsSync as existsSync2,
+  mkdtempSync,
+  readFileSync as readFileSync2,
+  readdirSync as readdirSync2,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { tmpdir } from "os";
+import { dirname, join as join2, resolve } from "path";
+import { fileURLToPath } from "url";
+var DEFAULT_TEMPLATE_PACKAGE = "@international-iot-association/plugin-template";
+var SKIP_ENTRIES = /* @__PURE__ */ new Set(["node_modules", "ui-dist", "runtime-dist", ".turbo"]);
+var TEXT_FILE_RE = /\.(ts|tsx|json|css|html|mjs|md)$/;
+var DIR_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+function lastPathSegment(path) {
+  const parts = path.split(/[\\/]/);
+  return parts[parts.length - 1] ?? "";
+}
+function shouldSkipCopy(src) {
+  return SKIP_ENTRIES.has(lastPathSegment(src));
+}
+function assertSafeDirName(dirName) {
+  if (!DIR_NAME_RE.test(dirName)) {
+    throw new Error(
+      `\u76EE\u5F55\u540D\u975E\u6CD5\uFF1A"${dirName}"\uFF08\u53EA\u5141\u8BB8\u5C0F\u5199\u5B57\u6BCD/\u6570\u5B57/._-\uFF0C\u4E14\u4E0D\u80FD\u4EE5 . \u6216 - \u5F00\u5934\uFF09`
+    );
+  }
+}
+function extractTarball(tgzPath) {
+  const extractDir = mkdtempSync(join2(tmpdir(), "plugin-cli-tpl-extract-"));
+  execFileSync("tar", ["-xzf", tgzPath, "-C", extractDir], { stdio: "pipe" });
+  const packageDir = join2(extractDir, "package");
+  if (!existsSync2(packageDir)) {
+    throw new Error(`\u6A21\u677F\u538B\u7F29\u5305\u89E3\u538B\u540E\u672A\u627E\u5230 package/ \u76EE\u5F55\uFF08${tgzPath}\uFF09\uFF1A\u4E0D\u662F\u5408\u6CD5\u7684 npm \u5305\u4EA7\u7269`);
+  }
+  return packageDir;
+}
+function readOwnVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync2(join2(here, "..", "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "";
+  } catch {
+    return "";
+  }
+}
+function resolveDefaultTemplateSpec(cliVersion, override) {
+  if (override && override.trim()) return override.trim();
+  return cliVersion.includes("-") ? "next" : "latest";
+}
+function fetchDefaultTemplate(templateVersion) {
+  const spec = resolveDefaultTemplateSpec(readOwnVersion(), templateVersion);
+  const packDestDir = mkdtempSync(join2(tmpdir(), "plugin-cli-tpl-pack-"));
+  let stdout;
+  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(
+      `\u62C9\u53D6\u9ED8\u8BA4\u6A21\u677F\u5305 ${DEFAULT_TEMPLATE_PACKAGE}@${spec} \u5931\u8D25\uFF1A\u53EF\u80FD\u662F\u7F51\u7EDC / registry \u4E0D\u53EF\u8FBE\uFF0C\u6216\u8BE5\u7248\u672C / dist-tag \u4E0B\u6CA1\u6709\u53D1\u5E03\u8FC7\u6A21\u677F\u5305\u3002\u53EF\u7528 --template-version <\u7248\u672C\u6216 dist-tag> \u6307\u5B9A\uFF0C\u6216\u6539\u7528 --template <\u672C\u5730\u6A21\u677F\u76EE\u5F55\u6216 .tgz>\uFF08\u4ED3\u5185\u4E3A --template templates/plugin\uFF09\u3002
+\u539F\u59CB\u9519\u8BEF\uFF1A${err.message}`
+    );
+  }
+  const lastLine = stdout.trim().split("\n").pop() ?? "";
+  const tgzPath = join2(packDestDir, lastLine.trim());
+  if (!lastLine || !existsSync2(tgzPath)) {
+    throw new Error(`npm pack ${DEFAULT_TEMPLATE_PACKAGE} \u672A\u4EA7\u51FA\u53EF\u8BC6\u522B\u7684 .tgz \u6587\u4EF6`);
+  }
+  return extractTarball(tgzPath);
+}
+function resolveTemplateDir(template, templateVersion) {
+  if (!template) return fetchDefaultTemplate(templateVersion);
+  const resolved = resolve(template);
+  if (resolved.endsWith(".tgz")) {
+    if (!existsSync2(resolved)) throw new Error(`\u6A21\u677F\u538B\u7F29\u5305\u4E0D\u5B58\u5728\uFF1A${resolved}`);
+    return extractTarball(resolved);
+  }
+  if (!existsSync2(resolved) || !statSync(resolved).isDirectory()) {
+    throw new Error(`--template \u6307\u5411\u7684\u76EE\u5F55\u4E0D\u5B58\u5728\u6216\u4E0D\u662F\u76EE\u5F55\uFF1A${resolved}`);
+  }
+  return resolved;
+}
+function replacePlaceholders(dest, id, displayName) {
+  const walk = (d) => {
+    for (const e of readdirSync2(d, { withFileTypes: true })) {
+      const p = join2(d, e.name);
+      if (e.isDirectory()) {
+        walk(p);
+      } else if (TEXT_FILE_RE.test(e.name)) {
+        const s = readFileSync2(p, "utf8");
+        const next = s.split("__PLUGIN_ID__").join(id).split("__PLUGIN_NAME__").join(displayName);
+        if (next !== s) writeFileSync(p, next);
+      }
+    }
+  };
+  walk(dest);
+}
+function scaffoldPlugin(opts) {
+  assertSafeDirName(opts.dirName);
+  if (!isValidPluginId(opts.id)) {
+    throw new Error(
+      `\u63D2\u4EF6 id \u975E\u6CD5\uFF1A"${opts.id}"\uFF08\u8981\u6C42\u5168\u5C0F\u5199\u3001\u81F3\u5C11\u4E24\u6BB5\u3001\u65E0 Windows \u4FDD\u7559\u540D\uFF0C\u5982 rti.demo.water-sensor\uFF09`
+    );
+  }
+  const dest = join2(resolve(opts.outParentDir), opts.dirName);
+  if (existsSync2(dest)) {
+    throw new Error(`\u76EE\u6807\u5DF2\u5B58\u5728\uFF0C\u62D2\u7EDD\u8986\u76D6\uFF1A${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 = join2(dest, "package.json");
+  if (existsSync2(pkgPath)) {
+    const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
+    pkg.name = opts.id;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`);
+  }
+  const manifestPath = join2(dest, "manifest.json");
+  if (!existsSync2(manifestPath)) {
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error(`\u6A21\u677F\u7F3A\u5C11 manifest.json\uFF08\u6A21\u677F\u76EE\u5F55\uFF1A${templateDir}\uFF09`);
+  }
+  const generatedManifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
+  const { ok, errors } = validatePluginManifest(generatedManifest);
+  if (!ok) {
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error(`\u751F\u6210\u7684 manifest \u672A\u901A\u8FC7\u6821\u9A8C\uFF08\u6A21\u677F\u4E0E schema \u4E0D\u540C\u6B65\uFF09\uFF1A
+  - ${errors.join("\n  - ")}`);
+  }
+  return dest;
+}
+
+// src/registry.ts
+function buildRegistryEntry(manifest, fileName, sha256, sizeBytes) {
+  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
+  };
+}
+
+// src/smoke.mjs
+import assert from "assert/strict";
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
+import { pathToFileURL } from "url";
+import { createAPIClient } from "@international-iot-association/api-bridge";
+var 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;
+}
+function assertSmokeMinimums(manifest, counters, activated) {
+  assert.ok(activated, `${manifest.id} smoke \u672A\u8C03\u7528 toolkit.activate()`);
+  assert.ok(
+    counters.roundtrips >= 1 || isRetiredGlobalLoggerCompatibilityShell(manifest),
+    `${manifest.id} smoke \u672A\u5B8C\u6210\u4EFB\u4F55 API \u5F80\u8FD4`
+  );
+  const kind = manifest.kind ?? "station";
+  if (kind === "station") {
+    assert.ok(counters.reports >= 1, `${manifest.id} smoke \u672A\u4EA7\u751F\u4EFB\u4F55 ctx.report.result`);
+  }
+}
+function hasChannelPermission(permissions, logicalName) {
+  return permissions.includes(logicalName) || permissions.includes(`${logicalName}.writeRead`) || permissions.includes(`channel.${logicalName}.writeRead`);
+}
+function hasChannelControlPermission(permissions, logicalName) {
+  return permissions.includes(`${logicalName}.control`) || permissions.includes(`channel.${logicalName}.control`);
+}
+function hasSerialDiscoveryPermission(permissions) {
+  return permissions.some(
+    (perm) => perm === "serial" || perm === "serial.discovery" || perm === "channel.serial.discovery" || perm === "channel.serial.discovery.read"
+  );
+}
+function makeMemoryStorage() {
+  const files = /* @__PURE__ */ 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
+  };
+}
+function makeBusRouter() {
+  const nodes = /* @__PURE__ */ 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);
+        }
+      };
+    }
+  };
+}
+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 !== void 0 && (counters.roundtrips += 1);
+      clientMessageHandler(envelope);
+    } else if (envelope.type === "event") {
+      serverEventHandler(envelope);
+    }
+  });
+  return client;
+}
+function makeGatedHarness(manifest, opts = {}, counters = { roundtrips: 0 }) {
+  const permissions = manifest.permissions ?? [];
+  const events = [];
+  const results = [];
+  const subscriptions = /* @__PURE__ */ 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);
+        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() {
+        return { canceled: true, files: [] };
+      }
+    };
+  }
+  if (permissions.includes("platform:object-upload")) {
+    ctx.platform = {
+      ...ctx.platform ?? {},
+      upload: opts.upload ?? {
+        async submit() {
+          return {
+            ok: false,
+            code: "internal",
+            faultCode: "UP-SMOKE-STUB",
+            retryable: false,
+            detail: "smoke \u7F3A\u7701\u4E0A\u4F20\u6869\uFF1A\u672A\u6CE8\u5165 opts.upload",
+            attempts: 1,
+            uploadedBeforeFailure: 0
+          };
+        }
+      }
+    };
+  }
+  if (permissions.includes("devtools:virtual-serial")) {
+    const denyVirtualSerial = async () => {
+      throw new Error(
+        "\u865A\u62DF\u4E32\u53E3\u80FD\u529B\u672A\u542F\u7528\uFF1Asmoke \u7F3A\u7701\u6869\u4E0D\u94F8\u9020 PTY\uFF08\u8981\u6D4B\u6210\u529F\u8DEF\u5F84\u8BF7\u6CE8\u5165 opts.virtualSerial\uFF09"
+      );
+    };
+    ctx.platform = {
+      ...ctx.platform ?? {},
+      virtualSerial: opts.virtualSerial ?? {
+        create: denyVirtualSerial,
+        release: denyVirtualSerial,
+        list: denyVirtualSerial
+      }
+    };
+  }
+  const { client, clientMessageHandler, serverEventHandler } = createAPIClient({
+    requestServerFunc: async (req) => {
+      runtimeOnMessage?.(req);
+    }
+  });
+  const emitChannelEvent = (logicalName, event) => {
+    for (const handler of subscriptions.get(logicalName) ?? []) handler(event);
+  };
+  return { ctx, client, events, results, subscriptions, emitChannelEvent, storage: ctx.storage };
+}
+async function runPluginSmoke(pluginDir) {
+  const manifestRaw = readFileSync3(join3(pluginDir, "manifest.json"), "utf8");
+  const manifest = JSON.parse(manifestRaw);
+  const { ok, errors } = validatePluginManifest(manifest);
+  if (!ok) throw new Error(`manifest \u6821\u9A8C\u5931\u8D25\uFF08${pluginDir}\uFF09\uFF1A${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 === void 0) {
+        const entry = pathToFileURL(join3(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 \u672A\u63D0\u4F9B\u53EF\u8C03\u7528\u7684 activate()\uFF08${manifest.id}\uFF09`);
+      }
+      const handle = await runtimeActivate(ctx);
+      activated = true;
+      return handle;
+    }
+  };
+  const smokeUrl = pathToFileURL(join3(pluginDir, "smoke.mjs")).href;
+  const smokeMod = await import(smokeUrl);
+  if (typeof smokeMod.default !== "function") {
+    throw new Error(`smoke.mjs \u5FC5\u987B\u9ED8\u8BA4\u5BFC\u51FA async \u51FD\u6570\uFF08${manifest.id}\uFF09`);
+  }
+  await smokeMod.default(toolkit);
+  assertSmokeMinimums(manifest, counters, activated);
+  return { pluginId: manifest.id, roundtrips: counters.roundtrips, reports: counters.reports };
+}
+
+// src/stage.ts
+import { cpSync as cpSync2, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync4, rmSync as rmSync2 } from "fs";
+import { join as join4 } from "path";
+import { assertPluginUiSingleReact as assertPluginUiSingleReact2 } from "@international-iot-association/plugin-vite-config";
+function assertExists(path, label) {
+  if (!existsSync3(path)) throw new Error(`${label} not found: ${path}`);
+}
+function readPluginManifest(pluginDir) {
+  const manifestPath = join4(pluginDir, "manifest.json");
+  if (!existsSync3(manifestPath)) {
+    throw new Error(`missing manifest.json in ${pluginDir}`);
+  }
+  const manifest = JSON.parse(readFileSync4(manifestPath, "utf8"));
+  const { ok, errors } = validatePluginManifest(manifest);
+  if (!ok) {
+    throw new Error(`manifest \u6821\u9A8C\u5931\u8D25\uFF08${manifestPath}\uFF09\uFF1A
+  - ${errors.join("\n  - ")}`);
+  }
+  return manifest;
+}
+function stagePlugin(pluginDir, stagingDir) {
+  const manifest = readPluginManifest(pluginDir);
+  rmSync2(stagingDir, { recursive: true, force: true });
+  mkdirSync(stagingDir, { recursive: true });
+  cpSync2(join4(pluginDir, "manifest.json"), join4(stagingDir, "manifest.json"));
+  const schemas = join4(pluginDir, "schemas");
+  if (existsSync3(schemas)) cpSync2(schemas, join4(stagingDir, "schemas"), { recursive: true });
+  if (manifest.uiEntry) {
+    const uiDist = join4(pluginDir, "ui-dist");
+    assertExists(uiDist, `ui build output (run "pnpm --filter ${manifest.id} build")`);
+    const reactGate = assertPluginUiSingleReact2(pluginDir);
+    if (!reactGate.ok) {
+      throw new Error(reactGate.error);
+    }
+    cpSync2(uiDist, join4(stagingDir, "ui"), { recursive: true });
+  }
+  const runtimeDist = join4(pluginDir, "runtime-dist");
+  assertExists(runtimeDist, `runtime build output (run "pnpm --filter ${manifest.id} build")`);
+  cpSync2(runtimeDist, join4(stagingDir, "runtime"), { recursive: true });
+  if (manifest.uiEntry) assertExists(join4(stagingDir, manifest.uiEntry), `uiEntry "${manifest.uiEntry}"`);
+  assertExists(join4(stagingDir, manifest.runtimeEntry), `runtimeEntry "${manifest.runtimeEntry}"`);
+  return manifest;
+}
+
+// src/test-runner.mjs
+import { spawnSync } from "child_process";
+function parseTapTestCount(output) {
+  const matches = [...output.matchAll(/^# tests (\d+)$/gm)];
+  const last = matches.at(-1);
+  return last ? Number(last[1]) : null;
+}
+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);
+}
+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: `\u65E0\u6CD5\u542F\u52A8\u6D4B\u8BD5\u8FDB\u7A0B\uFF1A${result.error.message}`
+    };
+  }
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const testCount = parseTapTestCount(output);
+  if (testCount === null) {
+    return {
+      ok: false,
+      testCount: null,
+      output,
+      error: "\u6D4B\u8BD5\u8F93\u51FA\u4E2D\u6CA1\u6709 node --test TAP \u6C47\u603B\uFF08\u811A\u672C\u6CA1\u6709\u771F\u6B63\u8DD1\u6D4B\u8BD5\uFF0C\u6216\u672A\u4F7F\u7528 node --test\uFF09"
+    };
+  }
+  if (testCount === 0) {
+    return { ok: false, testCount, output, error: "0 \u4E2A\u6D4B\u8BD5\u7528\u4F8B" };
+  }
+  const failCount = parseTapFailureCount(output);
+  if (failCount !== null && failCount > 0) {
+    return { ok: false, testCount, output, error: `TAP \u6C47\u603B\u6709 ${failCount} \u4E2A\u5931\u8D25/\u53D6\u6D88\u7528\u4F8B` };
+  }
+  if (result.status !== 0) {
+    return { ok: false, testCount, output, error: `\u6D4B\u8BD5\u8FDB\u7A0B\u9000\u51FA\u7801 ${result.status}` };
+  }
+  return { ok: true, testCount, output };
+}
+
+// src/zip.ts
+import { createHash } from "crypto";
+import { readFileSync as readFileSync5, statSync as statSync2 } from "fs";
+import AdmZip from "adm-zip";
+function zipStaging(stagingDir, outZip) {
+  const zip = new AdmZip();
+  zip.addLocalFolder(stagingDir, "", (entryName) => !entryName.includes(".DS_Store"));
+  zip.writeZip(outZip);
+  const bytes = readFileSync5(outZip);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const sizeBytes = statSync2(outZip).size;
+  return { zipPath: outZip, sha256, sizeBytes };
+}
+
+// src/cli.ts
+var USAGE_LINES = [
+  "\u7528\u6CD5\uFF1Aplugin-cli check <\u63D2\u4EF6\u76EE\u5F55>",
+  "     plugin-cli pack <\u63D2\u4EF6\u76EE\u5F55> --out <\u8F93\u51FA\u76EE\u5F55>",
+  '     plugin-cli new <\u76EE\u5F55\u540D> "<\u663E\u793A\u540D>" <\u63D2\u4EF6id> [--template <\u76EE\u5F55\u6216.tgz>] [--template-version <\u7248\u672C\u6216dist-tag>] [--out <\u7236\u76EE\u5F55>]',
+  "     plugin-cli smoke <\u63D2\u4EF6\u76EE\u5F55>",
+  "     plugin-cli --help"
+];
+function printUsage(stream) {
+  const write = stream === "stdout" ? console.log : console.error;
+  for (const line of USAGE_LINES) write(line);
+}
+function help() {
+  printUsage("stdout");
+  process.exit(0);
+}
+function usage() {
+  printUsage("stderr");
+  process.exit(1);
+}
+function parseArgs(argv) {
+  const positional = [];
+  let out;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--out") {
+      out = argv[i + 1];
+      i += 1;
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  const pluginDir = positional[0];
+  if (!pluginDir) usage();
+  return { pluginDir: resolve2(pluginDir), out };
+}
+function runCheck(argv) {
+  const { pluginDir } = parseArgs(argv);
+  const result = checkPlugin(pluginDir);
+  for (const e of result.errors) console.error(`- ${e}`);
+  const testResult = runPluginTestSuite(pluginDir);
+  if (!testResult.ok) console.error(`- \u63D2\u4EF6\u81EA\u8EAB\u6D4B\u8BD5\u672A\u901A\u8FC7\uFF1A${testResult.error}`);
+  const ok = result.ok && testResult.ok;
+  console.log(ok ? `check ok: ${pluginDir}` : `check failed: ${pluginDir}`);
+  console.log(
+    "\u6CE8\u610F\uFF1A\u672C\u547D\u4EE4\u4E0D\u542B\u8DE8\u63D2\u4EF6 id \u5BF9\u8D26\u3001registry \u5BF9\u8D26\u3001\u5168\u4ED3 secret-scan\uFF08\u8FD9\u4E9B\u53EA\u5728\u4ED3\u5185 ./dev verify \u505A\uFF09\u3002"
+  );
+  if (!ok) process.exitCode = 1;
+}
+function runPack(argv) {
+  const { pluginDir, out } = parseArgs(argv);
+  if (!out) usage();
+  const outDir = resolve2(out);
+  mkdirSync2(outDir, { recursive: true });
+  const stagingDir = join5(outDir, ".staging", basename(pluginDir));
+  const manifest = stagePlugin(pluginDir, stagingDir);
+  const fileName = `${manifest.id}-${manifest.version}.zip`;
+  const zipPath = join5(outDir, fileName);
+  const { sha256, sizeBytes } = zipStaging(stagingDir, zipPath);
+  const entry = buildRegistryEntry(manifest, fileName, sha256, sizeBytes);
+  const registry = { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), plugins: [entry] };
+  const registryPath = join5(outDir, `${manifest.id}-registry.json`);
+  writeFileSync2(registryPath, JSON.stringify(registry, null, 2));
+  console.log(`packed ${fileName}  sha256=${sha256.slice(0, 16)}\u2026  ${sizeBytes}B  (unsigned)`);
+  console.log(`wrote ${registryPath}`);
+}
+function parseNewArgs(argv) {
+  const positional = [];
+  let template;
+  let templateVersion;
+  let out;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--template") {
+      template = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === "--template-version") {
+      templateVersion = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === "--out") {
+      out = argv[i + 1];
+      i += 1;
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  const [dirName, displayName, id] = positional;
+  if (!dirName || !displayName || !id) usage();
+  return { dirName, displayName, id, template, templateVersion, out };
+}
+function runNew(argv) {
+  const { dirName, displayName, id, template, templateVersion, out } = parseNewArgs(argv);
+  const outParentDir = out ? resolve2(out) : join5(process.cwd(), "plugins");
+  try {
+    const dest = scaffoldPlugin({ dirName, displayName, id, template, templateVersion, outParentDir });
+    console.log(`\u2713 \u5DF2\u751F\u6210 ${dest}  (id=${id}, name=${displayName})`);
+    console.log("\u4E0B\u4E00\u6B65\uFF1A");
+    console.log(`  cd ${dest}`);
+    console.log("  pnpm install");
+    console.log("  pnpm run build && pnpm run pack   # \u4ED3\u5185 monorepo \u5219\u6539\u7528 pnpm --filter <id> build");
+    console.log(dest);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+async function runSmoke(argv) {
+  const { pluginDir } = parseArgs(argv);
+  let smokeResult;
+  try {
+    smokeResult = await runPluginSmoke(pluginDir);
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  const testResult = runPluginTestSuite(pluginDir);
+  if (!testResult.ok) {
+    console.error(`- \u63D2\u4EF6\u81EA\u8EAB\u6D4B\u8BD5\u672A\u901A\u8FC7\uFF1A${testResult.error}`);
+    console.log(`smoke failed: ${pluginDir}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(
+    `smoke ok: ${pluginDir}  roundtrips=${smokeResult.roundtrips} reports=${smokeResult.reports} tests=${testResult.testCount}`
+  );
+}
+async function main() {
+  const [sub, ...rest] = process.argv.slice(2);
+  switch (sub) {
+    case "check":
+      runCheck(rest);
+      break;
+    case "pack":
+      runPack(rest);
+      break;
+    case "new":
+      runNew(rest);
+      break;
+    case "smoke":
+      await runSmoke(rest);
+      break;
+    case "--help":
+    case "-h":
+    case "help":
+      help();
+    // eslint-disable-next-line no-fallthrough -- help() 的返回类型是 never，不会落到下一分支
+    default:
+      usage();
+  }
+}
+main();