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

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+/** 插件 manifest.json 的形状，与仓内 tools/pack.ts 的 Manifest 接口一致。 */
+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;
+}
+/** 读取并严格校验单个插件目录的 manifest.json（fail-closed，校验失败即抛错）。 */
+declare function readPluginManifest(pluginDir: string): PluginManifest;
+/**
+ * 把单个插件目录的构建产物组装进 stagingDir：
+ *   manifest.json -> 根；schemas/ -> schemas/；ui-dist/ -> ui/；runtime-dist/ -> runtime/。
+ * 同时做入口存在性断言（uiEntry/runtimeEntry 在 staging 内必须能解析到）与产物单 React 断言。
+ * 只清理并写入调用方传入的 stagingDir，不触碰任何全仓目录。
+ */
+declare function stagePlugin(pluginDir: string, stagingDir: string): PluginManifest;
+
+interface ZipResult {
+    zipPath: string;
+    sha256: string;
+    sizeBytes: number;
+}
+/**
+ * 把 stagingDir 的内容打到 zip 根目录（过滤 .DS_Store），写到 outZip，
+ * 返回 zip 路径、sha256、字节数。
+ *
+ * 注意：AdmZip.addLocalFolder 的条目带 mtime，且调用方通常会在 registry 片段里
+ * 写入 generatedAt，所以同一份插件连打两次 sha256 必不同——这是预期行为，
+ * 不是本函数的 bug（等价性验收走「解包后逐文件 sha256」，不是「同 sha256」）。
+ */
+declare function zipStaging(stagingDir: string, outZip: string): ZipResult;
+
+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）。 */
+declare function buildRegistryEntry(manifest: PluginManifest, fileName: string, sha256: string, sizeBytes: number): RegistryEntry;
+
+// check.mjs 的类型声明（供 tools/verify.mjs、tools/pack.ts 等 TS/JS 消费者取类型）。
+interface CheckResult {
+  ok: boolean;
+  errors: string[];
+}
+
+declare function isEmptyTestScript(script: unknown): boolean;
+declare function checkPlugin(pluginDir: string): CheckResult;
+
+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 明确要求修复）。
+ */
+declare function lastPathSegment(path: string): string;
+/** cpSync filter：跳过构建产物与依赖目录，需兼容 Windows 反斜杠路径。 */
+declare function shouldSkipCopy(src: string): boolean;
+/**
+ * 决定默认模板包的版本 spec：显式给了就用显式的；否则 CLI 自身是预发布版
+ * 取 dist-tag "next"（发布手册约定 rc 一律打 next），正式版取 "latest"。
+ */
+declare function resolveDefaultTemplateSpec(cliVersion: string, override?: string): string;
+/**
+ * 生成一个新插件目录。
+ * 校验顺序：dirName 安全字符 -> id 合法 -> 目标未占用 -> 拷贝模板 -> 占位符替换 ->
+ * package.json.name 写回 -> 生成产物的 manifest.json 严格自检（不通过则回滚删除
+ * 已生成目录，避免留下半成品）。成功时返回生成目录的绝对路径。
+ */
+declare function scaffoldPlugin(opts: ScaffoldOptions): string;
+
+// test-runner.mjs 的类型声明。
+interface TestRunResult {
+  ok: boolean;
+  testCount: number | null;
+  output: string;
+  error?: string;
+}
+
+declare function parseTapTestCount(output: string): number | null;
+declare function runPluginTestSuite(pluginDir: string): TestRunResult;
+
+export { type CheckResult, type PluginManifest, type RegistryEntry, type ScaffoldOptions, type TestRunResult, type ZipResult, buildRegistryEntry, checkPlugin, isEmptyTestScript, lastPathSegment, parseTapTestCount, readPluginManifest, resolveDefaultTemplateSpec, runPluginTestSuite, scaffoldPlugin, shouldSkipCopy, stagePlugin, zipStaging };

package/dist/index.js

@@ -0,0 +1,507 @@
+// src/stage.ts
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync } 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/stage.ts
+function assertExists(path, label) {
+  if (!existsSync(path)) throw new Error(`${label} not found: ${path}`);
+}
+function readPluginManifest(pluginDir) {
+  const manifestPath = join(pluginDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`missing manifest.json in ${pluginDir}`);
+  }
+  const manifest = JSON.parse(readFileSync(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);
+  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")`);
+    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 });
+  if (manifest.uiEntry) assertExists(join(stagingDir, manifest.uiEntry), `uiEntry "${manifest.uiEntry}"`);
+  assertExists(join(stagingDir, manifest.runtimeEntry), `runtimeEntry "${manifest.runtimeEntry}"`);
+  return manifest;
+}
+
+// src/zip.ts
+import { createHash } from "crypto";
+import { readFileSync as readFileSync2, statSync } 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 = readFileSync2(outZip);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const sizeBytes = statSync(outZip).size;
+  return { zipPath: outZip, sha256, sizeBytes };
+}
+
+// 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/check.mjs
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync } from "fs";
+import { join as join2 } from "path";
+import { assertPluginUiSingleReact as assertPluginUiSingleReact2 } from "@international-iot-association/plugin-vite-config";
+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 = join2(pluginDir, "manifest.json");
+  if (!existsSync2(manifestPath)) {
+    return { ok: false, errors: [`missing manifest.json in ${pluginDir}`] };
+  }
+  const manifest = JSON.parse(readFileSync3(manifestPath, "utf8"));
+  const { ok: manifestOk, errors: manifestErrors } = validatePluginManifest(manifest);
+  if (!manifestOk) {
+    for (const e of manifestErrors) errors.push(`manifest: ${e}`);
+  }
+  const pkgPath = join2(pluginDir, "package.json");
+  if (!existsSync2(pkgPath)) {
+    errors.push("missing package.json");
+  } else {
+    const pkg = JSON.parse(readFileSync3(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 = join2(pluginDir, "test");
+  const hasTestFile = existsSync2(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 (!existsSync2(join2(pluginDir, "smoke.mjs"))) {
+    errors.push("\u7F3A\u5C11 smoke.mjs");
+  }
+  const reactGate = assertPluginUiSingleReact2(pluginDir);
+  if (!reactGate.ok) errors.push(reactGate.error);
+  return { ok: errors.length === 0, errors };
+}
+
+// src/new.ts
+import { execFileSync } from "child_process";
+import {
+  cpSync as cpSync2,
+  existsSync as existsSync3,
+  mkdtempSync,
+  readFileSync as readFileSync4,
+  readdirSync as readdirSync2,
+  rmSync as rmSync2,
+  statSync as statSync2,
+  writeFileSync
+} from "fs";
+import { tmpdir } from "os";
+import { dirname, join as join3, 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(join3(tmpdir(), "plugin-cli-tpl-extract-"));
+  execFileSync("tar", ["-xzf", tgzPath, "-C", extractDir], { stdio: "pipe" });
+  const packageDir = join3(extractDir, "package");
+  if (!existsSync3(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(readFileSync4(join3(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(join3(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 = join3(packDestDir, lastLine.trim());
+  if (!lastLine || !existsSync3(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 (!existsSync3(resolved)) throw new Error(`\u6A21\u677F\u538B\u7F29\u5305\u4E0D\u5B58\u5728\uFF1A${resolved}`);
+    return extractTarball(resolved);
+  }
+  if (!existsSync3(resolved) || !statSync2(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 = join3(d, e.name);
+      if (e.isDirectory()) {
+        walk(p);
+      } else if (TEXT_FILE_RE.test(e.name)) {
+        const s = readFileSync4(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 = join3(resolve(opts.outParentDir), opts.dirName);
+  if (existsSync3(dest)) {
+    throw new Error(`\u76EE\u6807\u5DF2\u5B58\u5728\uFF0C\u62D2\u7EDD\u8986\u76D6\uFF1A${dest}`);
+  }
+  const templateDir = resolveTemplateDir(opts.template, opts.templateVersion);
+  cpSync2(templateDir, dest, {
+    recursive: true,
+    filter: (src) => !shouldSkipCopy(src)
+  });
+  replacePlaceholders(dest, opts.id, opts.displayName);
+  const pkgPath = join3(dest, "package.json");
+  if (existsSync3(pkgPath)) {
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+    pkg.name = opts.id;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`);
+  }
+  const manifestPath = join3(dest, "manifest.json");
+  if (!existsSync3(manifestPath)) {
+    rmSync2(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(readFileSync4(manifestPath, "utf8"));
+  const { ok, errors } = validatePluginManifest(generatedManifest);
+  if (!ok) {
+    rmSync2(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/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 };
+}
+export {
+  buildRegistryEntry,
+  checkPlugin,
+  isEmptyTestScript,
+  lastPathSegment,
+  parseTapTestCount,
+  readPluginManifest,
+  resolveDefaultTemplateSpec,
+  runPluginTestSuite,
+  scaffoldPlugin,
+  shouldSkipCopy,
+  stagePlugin,
+  zipStaging
+};