@hachej/boring-ui-plugin-cli 0.1.31 → 0.1.33

package/dist/chunk-DH4PSVGY.js

@@ -0,0 +1,1096 @@
+// src/server/index.ts
+import { join as join4, resolve as resolve4 } from "path";
+
+// src/server/createPlugin.ts
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { dirname, join, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+var KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function findRepoRoot(from) {
+  let current = from;
+  while (true) {
+    if (existsSync(join(current, "pnpm-workspace.yaml"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function walkDir(dir, base, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry === ".git" || entry === "dist") continue;
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkDir(fullPath, base, out);
+      continue;
+    }
+    out.push(relative(base, fullPath));
+  }
+  return out;
+}
+function replaceInFile(filePath, replacements) {
+  let content = readFileSync(filePath, "utf8");
+  for (const [from, to] of Object.entries(replacements)) {
+    content = content.replaceAll(from, to);
+  }
+  writeFileSync(filePath, content, "utf8");
+}
+function packageRoot() {
+  let current = dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const pkgPath = join(current, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.name === "@hachej/boring-ui-plugin-cli") return current;
+      } catch {
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  throw new Error("Could not locate @hachej/boring-ui-plugin-cli package root");
+}
+function createPlugin(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const name = options.name;
+  const templateDir = join(packageRoot(), "templates", "plugin");
+  if (!existsSync(templateDir)) {
+    throw new Error(
+      `Plugin template not found at ${templateDir}.
+This build may not include the plugin template.`
+    );
+  }
+  if (!KEBAB_RE.test(name)) {
+    throw new Error(
+      `invalid plugin name "${name}" \u2014 must be kebab-case (e.g. "my-plugin")`
+    );
+  }
+  const repoRoot = findRepoRoot(cwd);
+  const targetParent = options.path ? resolve(cwd, options.path) : join(repoRoot ?? cwd, "plugins");
+  const targetDir = join(targetParent, name);
+  if (existsSync(targetDir)) throw new Error(`Directory already exists: ${targetDir}`);
+  const id = name;
+  const symbolBase = id.replace(/-plugin$/, "") || id;
+  const pascalBase = symbolBase.split(/[-_]+/).map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1)).join("");
+  const camelBase = pascalBase.charAt(0).toLowerCase() + pascalBase.slice(1);
+  const upperBase = symbolBase.replace(/-/g, "_").toUpperCase();
+  const packageName = `@hachej/boring-${id}`;
+  mkdirSync(targetParent, { recursive: true });
+  cpSync(templateDir, targetDir, { recursive: true });
+  const files = walkDir(targetDir, targetDir);
+  for (const file of files) {
+    const fullPath = join(targetDir, file);
+    replaceInFile(fullPath, {
+      "@hachej/boring-plugin-template": packageName,
+      "sample-plugin": id,
+      "sample-panel": `${id}-panel`,
+      "sample.open": `${id}.open`,
+      "sample:": `${id}:`,
+      '"sample"': `"${id}"`,
+      SAMPLE: upperBase,
+      Sample: pascalBase,
+      sampleSurfaceResolver: `${camelBase}SurfaceResolver`,
+      samplePanel: `${camelBase}Panel`
+    });
+    if (file.includes("samplePlugin")) {
+      const newFile = file.replace(/samplePlugin/g, `${camelBase}Plugin`);
+      const oldPath = join(targetDir, file);
+      const newPath = join(targetDir, newFile);
+      if (oldPath !== newPath) {
+        mkdirSync(dirname(newPath), { recursive: true });
+        renameSync(oldPath, newPath);
+      }
+    }
+  }
+  return {
+    id,
+    pluginDir: targetDir,
+    packageName,
+    filesCreated: walkDir(targetDir, targetDir)
+  };
+}
+
+// src/server/scaffoldPlugin.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var KEBAB_RE2 = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function scaffoldPlugin(opts) {
+  if (!KEBAB_RE2.test(opts.name)) {
+    throw new Error(
+      `invalid plugin name "${opts.name}" \u2014 must be kebab-case (e.g. "my-plugin")`
+    );
+  }
+  const workspaceRoot = resolve2(opts.workspaceRoot);
+  const pluginDir = join2(workspaceRoot, ".pi", "extensions", opts.name);
+  mkdirSync2(join2(workspaceRoot, ".pi", "extensions"), { recursive: true });
+  try {
+    mkdirSync2(pluginDir, { recursive: false });
+  } catch (error) {
+    const code = error.code;
+    if (code === "EEXIST") {
+      throw new Error(`plugin already exists at ${pluginDir}`);
+    }
+    throw error;
+  }
+  const templatesDir = opts.templatesDir ?? resolveBundledTemplatesDir();
+  if (!templatesDir) {
+    throw new Error(
+      "could not locate bundled plugin templates \u2014 pass `templatesDir` explicitly. (this usually indicates a broken @hachej/boring-ui-plugin-cli install)"
+    );
+  }
+  const tplFront = join2(templatesDir, "front-canonical.tsx");
+  const tplPackage = join2(templatesDir, "package-canonical.json");
+  for (const tpl of [tplFront, tplPackage]) {
+    if (!existsSync2(tpl)) {
+      throw new Error(`canonical template missing: ${tpl}`);
+    }
+  }
+  const label = labelFromName(opts.name);
+  const filesCreated = [];
+  const write = (relPath, contents) => {
+    const target = join2(pluginDir, relPath);
+    mkdirSync2(join2(target, ".."), { recursive: true });
+    writeFileSync2(target, contents, "utf8");
+    filesCreated.push(target);
+  };
+  const pkgRaw = JSON.parse(readFileSync2(tplPackage, "utf8"));
+  delete pkgRaw._doc_;
+  const pkgJson = substitute(JSON.stringify(pkgRaw, null, 2), opts.name, label);
+  write("package.json", `${pkgJson}
+`);
+  const frontSource = substitute(readFileSync2(tplFront, "utf8"), opts.name, label);
+  write("front/index.tsx", frontSource);
+  write(".gitignore", "# Machine-managed sidecars written by the boring-ui plugin runtime.\n.boring-signature.json\n");
+  return { pluginDir, filesCreated };
+}
+function labelFromName(name) {
+  return name.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function substitute(source, name, label) {
+  const paneName = `${pascalCase(name)}Pane`;
+  return source.replaceAll("<kebab-name>", name).replaceAll("&lt;kebab-name&gt;", name).replaceAll("<Label>", label).replaceAll(/\bMyPane\b/g, paneName);
+}
+function pascalCase(name) {
+  return name.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function resolveBundledTemplatesDir() {
+  const here = dirname2(fileURLToPath2(import.meta.url));
+  const candidates = [
+    resolve2(here, "..", "templates"),
+    resolve2(here, "..", "..", "templates")
+  ];
+  return candidates.find((candidate) => existsSync2(candidate));
+}
+
+// src/server/verifyPlugin.ts
+import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, realpathSync, statSync as statSync2 } from "fs";
+import { builtinModules, createRequire } from "module";
+import { extname, isAbsolute, join as join3, relative as relative2, resolve as resolve3 } from "path";
+
+// src/manifest.ts
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+var PLUGIN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+function isValidBoringPluginId(id) {
+  return typeof id === "string" && id.length > 0 && PLUGIN_ID_RE.test(id);
+}
+function isSafePluginRelativePath(value) {
+  return typeof value === "string" && value.length > 0 && value !== "." && !value.includes("\0") && !value.includes("\\") && !value.startsWith("/") && !value.startsWith("//") && !/^[A-Za-z]:[\\/]/.test(value) && !value.split("/").includes("..");
+}
+function issue(code, field, message) {
+  return { code, field, message };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateStringArray(issues, value, field, pathLike) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(issue("INVALID_FIELD", field, `${field} must be an array`));
+    return;
+  }
+  value.forEach((entry, index) => {
+    const itemField = `${field}[${index}]`;
+    if (typeof entry !== "string" || entry.length === 0) {
+      issues.push(issue("INVALID_FIELD", itemField, `${itemField} must be a non-empty string`));
+      return;
+    }
+    if (pathLike && !isSafePluginRelativePath(entry)) {
+      issues.push(issue("INVALID_PATH", itemField, `${itemField} must be a safe relative path`));
+    }
+  });
+}
+var REMOVED_BORING_UI_FIELDS = ["outputs", "panels", "commands", "leftTabs", "surfaceResolvers", "providers", "bindings", "catalogs"];
+function validateBoringField(issues, boring) {
+  if (boring === void 0) return void 0;
+  if (!isRecord(boring)) {
+    issues.push(issue("INVALID_FIELD", "boring", "boring must be an object when provided"));
+    return void 0;
+  }
+  for (const field of REMOVED_BORING_UI_FIELDS) {
+    if (boring[field] !== void 0) {
+      issues.push(issue(
+        "INVALID_FIELD",
+        `boring.${field}`,
+        `boring.${field} is not supported; declare front contributions in boring.front via definePlugin({ ... })`
+      ));
+    }
+  }
+  if (boring.id !== void 0 && (typeof boring.id !== "string" || !isValidBoringPluginId(boring.id))) {
+    issues.push(issue("INVALID_ID", "boring.id", "boring.id must start with a letter or number and use only letters, numbers, dot, underscore, colon, or dash"));
+  }
+  const front = boring.front;
+  if (front !== void 0 && (typeof front !== "string" || !isSafePluginRelativePath(front))) {
+    issues.push(issue("INVALID_PATH", "boring.front", "boring.front must be a safe relative path"));
+  }
+  const server = boring.server;
+  if (server !== void 0 && server !== false && (typeof server !== "string" || !isSafePluginRelativePath(server))) {
+    issues.push(issue("INVALID_PATH", "boring.server", "boring.server must be a safe relative path or false"));
+  }
+  if (boring.label !== void 0 && typeof boring.label !== "string") {
+    issues.push(issue("INVALID_FIELD", "boring.label", "boring.label must be a string when provided"));
+  }
+  return {
+    ...typeof boring.id === "string" ? { id: boring.id } : {},
+    ...typeof boring.front === "string" ? { front: boring.front } : {},
+    ...typeof boring.server === "string" || boring.server === false ? { server: boring.server } : {},
+    ...typeof boring.label === "string" ? { label: boring.label } : {}
+  };
+}
+var REMOTE_PI_PACKAGE_PREFIXES = ["npm:", "git:", "github:", "http:", "https:", "ssh:"];
+function isRemotePiPackageSource(value) {
+  return REMOTE_PI_PACKAGE_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+function isSafePiPackageSource(value) {
+  if (value.length === 0) return false;
+  if (isRemotePiPackageSource(value)) return true;
+  const path = value.startsWith("file:") ? value.slice("file:".length) : value;
+  if (path === "." || path === "./") return true;
+  const normalized = path.startsWith("./") ? path.slice(2) : path;
+  return isSafePluginRelativePath(normalized);
+}
+function validatePiPackages(issues, value) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(issue("INVALID_FIELD", "pi.packages", "pi.packages must be an array when provided"));
+    return;
+  }
+  value.forEach((entry, index) => {
+    const field = `pi.packages[${index}]`;
+    if (typeof entry === "string") {
+      if (!isSafePiPackageSource(entry)) {
+        issues.push(issue("INVALID_PATH", field, `${field} must be a safe package source`));
+      }
+      return;
+    }
+    if (!isRecord(entry)) {
+      issues.push(issue("INVALID_FIELD", field, `${field} must be a string or package source object`));
+      return;
+    }
+    if (typeof entry.source !== "string" || entry.source.length === 0) {
+      issues.push(issue("INVALID_FIELD", `${field}.source`, `${field}.source must be a non-empty string`));
+    } else if (!isSafePiPackageSource(entry.source)) {
+      issues.push(issue("INVALID_PATH", `${field}.source`, `${field}.source must be a safe package source`));
+    }
+  });
+}
+function validatePiField(issues, pi) {
+  if (pi === void 0) return void 0;
+  if (!isRecord(pi)) {
+    issues.push(issue("INVALID_FIELD", "pi", "pi must be an object when provided"));
+    return void 0;
+  }
+  validateStringArray(issues, pi.extensions, "pi.extensions", true);
+  validateStringArray(issues, pi.skills, "pi.skills", true);
+  validatePiPackages(issues, pi.packages);
+  if (pi.systemPrompt !== void 0 && typeof pi.systemPrompt !== "string") {
+    issues.push(issue("INVALID_FIELD", "pi.systemPrompt", "pi.systemPrompt must be a string when provided"));
+  }
+  return pi;
+}
+function validateBoringPluginManifest(raw) {
+  const issues = [];
+  if (!isRecord(raw)) {
+    return {
+      valid: false,
+      issues: [issue("INVALID_FIELD", "<root>", "package.json manifest must be an object")]
+    };
+  }
+  if (raw.name !== void 0 && typeof raw.name !== "string") {
+    issues.push(issue("INVALID_FIELD", "name", "name must be a string when provided"));
+  }
+  if (raw.version !== void 0 && typeof raw.version !== "string") {
+    issues.push(issue("INVALID_VERSION", "version", "version must be a string when provided"));
+  } else if (typeof raw.version === "string" && raw.version.length > 0 && !SEMVER_RE.test(raw.version)) {
+    issues.push(issue("INVALID_VERSION", "version", "version must be a valid semver string"));
+  }
+  const boring = validateBoringField(issues, raw.boring);
+  const pi = validatePiField(issues, raw.pi);
+  if (!boring && !pi) {
+    issues.push(issue("MISSING_REQUIRED_FIELD", "boring|pi", "package.json must include boring and/or pi plugin metadata"));
+  }
+  if (issues.length > 0) return { valid: false, issues };
+  return {
+    valid: true,
+    packageJson: {
+      ...typeof raw.name === "string" ? { name: raw.name } : {},
+      ...typeof raw.version === "string" ? { version: raw.version } : {},
+      ...boring ? { boring } : {},
+      ...pi ? { pi } : {}
+    }
+  };
+}
+
+// src/server/verifyPlugin.ts
+function pluginFileSignature(path) {
+  if (!path || !existsSync3(path)) return "missing";
+  const stat = statSync2(path);
+  return `${stat.mtimeMs}:${stat.size}`;
+}
+function readPluginSignatureCache(pluginRootDir) {
+  const path = join3(pluginRootDir, ".boring-signature.json");
+  if (!existsSync3(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync3(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  if (obj.version !== 1) return null;
+  const sig = obj.serverSignature;
+  if (sig !== null && typeof sig !== "string") return null;
+  const loadedAt = typeof obj.loadedAt === "number" ? obj.loadedAt : 0;
+  return { version: 1, serverSignature: sig, loadedAt };
+}
+var HOST_PROVIDED_IMPORTS = /* @__PURE__ */ new Set([
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "@hachej/boring-workspace",
+  "@hachej/boring-workspace/plugin",
+  "@hachej/boring-workspace/events",
+  "@hachej/boring-ui-kit"
+]);
+var HOST_PROVIDED_DEPENDENCIES = /* @__PURE__ */ new Set([
+  "react",
+  "react-dom",
+  "@hachej/boring-workspace",
+  "@hachej/boring-ui-kit"
+]);
+var FRONT_SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".css"]);
+var NODE_BUILTIN_IMPORTS = new Set(builtinModules.flatMap((name) => [name, `node:${name}`]));
+function verifyPlugin(opts) {
+  const workspaceRoot = resolve3(opts.workspaceRoot);
+  const extensionsDir = join3(workspaceRoot, ".pi", "extensions");
+  if (!existsSync3(extensionsDir)) {
+    return {
+      outcomes: [],
+      ok: true,
+      extensionsDir,
+      extensionsDirMissing: true
+    };
+  }
+  const targets = [];
+  if (opts.name) {
+    const dir = join3(extensionsDir, opts.name);
+    if (!existsSync3(dir)) {
+      return {
+        outcomes: [
+          { id: opts.name, dir, ok: false, errors: [`plugin directory not found: ${dir}`], warnings: [] }
+        ],
+        ok: false,
+        extensionsDir,
+        extensionsDirMissing: false
+      };
+    }
+    targets.push(dir);
+  } else {
+    for (const entry of readdirSync2(extensionsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".") || entry.name.startsWith("preflight-")) continue;
+      targets.push(join3(extensionsDir, entry.name));
+    }
+  }
+  const outcomes = targets.map((dir) => verifySinglePlugin(dir));
+  return {
+    outcomes,
+    ok: outcomes.every((o) => o.ok),
+    extensionsDir,
+    extensionsDirMissing: false
+  };
+}
+function isInsideRoot(rootReal, targetReal) {
+  const rel = relative2(rootReal, targetReal);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function resolveExistingContainedPath(pluginDir, value, field) {
+  if (!isSafePluginRelativePath(value)) {
+    return { path: null, error: `${field} must be a safe relative path inside the plugin root: ${JSON.stringify(value)}` };
+  }
+  const abs = resolve3(pluginDir, value);
+  if (!existsSync3(abs)) return { path: null, error: `${field} points at "${value}" but that file does not exist (looked at ${abs})` };
+  const rootReal = realpathSync(pluginDir);
+  const targetReal = realpathSync(abs);
+  if (!isInsideRoot(rootReal, targetReal)) {
+    return { path: null, error: `${field} points at "${value}" but resolves outside the plugin root (looked at ${abs})` };
+  }
+  return { path: targetReal };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function packageNameFromSpecifier(specifier) {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+function dependencyDir(pluginDir, packageName) {
+  return packageName.startsWith("@") ? join3(pluginDir, "node_modules", ...packageName.split("/")) : join3(pluginDir, "node_modules", packageName);
+}
+function readDependencySection(pkg, section) {
+  const value = pkg[section];
+  if (!isObject(value)) return [];
+  return Object.keys(value);
+}
+function validateDependencyManifest(pluginDir, pkg, errors) {
+  for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    for (const dep of readDependencySection(pkg, section)) {
+      if (HOST_PROVIDED_DEPENDENCIES.has(dep)) {
+        errors.push(`${section}.${dep}: do not list host-provided package "${dep}" as a plugin dependency; import it from the host runtime instead.`);
+      }
+    }
+  }
+  for (const dep of readDependencySection(pkg, "dependencies")) {
+    if (HOST_PROVIDED_DEPENDENCIES.has(dep)) continue;
+    if (!existsSync3(dependencyDir(pluginDir, dep))) {
+      errors.push(`dependency "${dep}" is declared but not installed. Run: cd ${pluginDir} && npm install`);
+    }
+  }
+}
+function isBareImport(specifier) {
+  return !specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.startsWith("file://");
+}
+function isUnsafeFrontSpecifier(specifier) {
+  return specifier.startsWith("/@fs/") || specifier.startsWith("//") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(specifier) || isAbsolute(specifier);
+}
+function stripCommentsForImportScan(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+function collectImportSpecifiers(source, path) {
+  const specs = [];
+  const extension = extname(path).toLowerCase();
+  if (extension === ".css") {
+    const cssImportPattern = /^\s*@import\s+(?:url\(\s*(?:["']([^"']+)["']|([^\s)"']+))\s*\)|["']([^"']+)["'])/gm;
+    const cssUrlPattern = /\burl\(\s*(?:["']([^"']+)["']|([^\s)"']+))\s*\)/gm;
+    let match;
+    while ((match = cssImportPattern.exec(source)) !== null) specs.push(match[1] ?? match[2] ?? match[3] ?? "");
+    while ((match = cssUrlPattern.exec(source)) !== null) specs.push(match[1] ?? match[2] ?? "");
+    return specs.filter(Boolean);
+  }
+  const code = stripCommentsForImportScan(source);
+  const patterns = [
+    /\bimport\s+(?:[^"']*?\s+from\s+)?["']([^"']+)["']/g,
+    /\bexport\s+[^"']*?\s+from\s+["']([^"']+)["']/g,
+    /\bimport\(\s*["']([^"']+)["']\s*\)/g
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(code)) !== null) specs.push(match[1]);
+  }
+  return specs;
+}
+function visitSourceFiles(root, check) {
+  if (!existsSync3(root)) return;
+  for (const entry of readdirSync2(root, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+    const path = join3(root, entry.name);
+    if (entry.isDirectory()) {
+      visitSourceFiles(path, check);
+    } else if (entry.isFile() && FRONT_SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      check(path);
+    }
+  }
+}
+function validateFrontImports(pluginDir, errors) {
+  const req = createRequire(join3(pluginDir, "package.json"));
+  const nodeModulesReal = existsSync3(join3(pluginDir, "node_modules")) ? realpathSync(join3(pluginDir, "node_modules")) : null;
+  const check = (path) => {
+    const source = readFileSync3(path, "utf8");
+    for (const specifier of collectImportSpecifiers(source, path)) {
+      if (specifier.startsWith("node:") || NODE_BUILTIN_IMPORTS.has(specifier)) {
+        errors.push(`${path}: front import "${specifier}" is not browser-safe; Node built-ins are not available in runtime plugin fronts.`);
+        continue;
+      }
+      if (isUnsafeFrontSpecifier(specifier)) {
+        errors.push(`${path}: front import "${specifier}" bypasses the host runtime URL space.`);
+        continue;
+      }
+      if (!isBareImport(specifier)) continue;
+      const packageName = packageNameFromSpecifier(specifier);
+      if (HOST_PROVIDED_IMPORTS.has(specifier)) continue;
+      if (HOST_PROVIDED_DEPENDENCIES.has(packageName)) {
+        errors.push(`${path}: front import "${specifier}" targets an unsupported host-provided package subpath; use documented front imports only.`);
+        continue;
+      }
+      try {
+        const resolved = req.resolve(specifier);
+        if (!nodeModulesReal || !isInsideRoot(nodeModulesReal, realpathSync(resolved))) {
+          errors.push(`${path}: front import "${specifier}" must resolve from this plugin's node_modules. Run: cd ${pluginDir} && npm install ${packageName}`);
+        }
+      } catch {
+        errors.push(`${path}: missing dependency for front import "${specifier}". Run: cd ${pluginDir} && npm install ${packageName}`);
+      }
+    }
+  };
+  visitSourceFiles(join3(pluginDir, "front"), check);
+  visitSourceFiles(join3(pluginDir, "shared"), check);
+}
+function verifySinglePlugin(pluginDir) {
+  const id = pluginDir.split(/[\\/]/).pop() ?? "<unknown>";
+  const errors = [];
+  const warnings = [];
+  const pkgPath = join3(pluginDir, "package.json");
+  if (!existsSync3(pkgPath)) {
+    return { id, dir: pluginDir, ok: false, errors: ["package.json missing"], warnings };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync3(pkgPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { id, dir: pluginDir, ok: false, errors: [`package.json is not valid JSON: ${message}`], warnings };
+  }
+  if (isObject(parsed)) validateDependencyManifest(pluginDir, parsed, errors);
+  const result = validateBoringPluginManifest(parsed);
+  if (!result.valid) {
+    for (const issue2 of result.issues) errors.push(formatIssue(issue2));
+    return { id, dir: pluginDir, ok: false, errors, warnings };
+  }
+  const manifest = result.packageJson;
+  const boring = manifest.boring;
+  if (boring?.front) {
+    const resolved = resolveExistingContainedPath(pluginDir, boring.front, "boring.front");
+    if (resolved.error) errors.push(resolved.error);
+  }
+  let serverPathAbs = null;
+  if (typeof boring?.server === "string") {
+    const resolved = resolveExistingContainedPath(pluginDir, boring.server, "boring.server");
+    if (resolved.error) {
+      errors.push(resolved.error);
+    } else {
+      serverPathAbs = resolved.path;
+      warnings.push(
+        "boring.server file is valid, but workspace server entries are boot-time/static composition only. /reload does not import or register .pi/extensions server routes/agentTools; restart the workspace with this package passed via defaultPluginPackages or explicit plugins to activate server code."
+      );
+    }
+  }
+  const cache = readPluginSignatureCache(pluginDir);
+  if (cache) {
+    const currentServerSig = serverPathAbs ? pluginFileSignature(serverPathAbs) : null;
+    const cachedSig = cache.serverSignature;
+    if (cachedSig !== currentServerSig) {
+      warnings.push(
+        "server file changed since the workspace last loaded this plugin \u2014 /reload will hot-swap the front, but routes and agent tools stay on the previously loaded code. Stop and restart the workspace process (Ctrl-C, then re-run your dev command) to pick up the new code."
+      );
+    }
+  }
+  const piExt = manifest.pi?.extensions;
+  if (Array.isArray(piExt)) {
+    for (const ext of piExt) {
+      if (typeof ext !== "string") continue;
+      const resolved = resolveExistingContainedPath(pluginDir, ext, "pi.extensions entry");
+      if (resolved.error) errors.push(resolved.error);
+    }
+  }
+  validateFrontImports(pluginDir, errors);
+  const piSkills = manifest.pi?.skills;
+  if (Array.isArray(piSkills)) {
+    for (const skill of piSkills) {
+      if (typeof skill !== "string") continue;
+      const resolved = resolveExistingContainedPath(pluginDir, skill, "pi.skills entry");
+      if (resolved.error) errors.push(resolved.error);
+    }
+  }
+  return { id, dir: pluginDir, ok: errors.length === 0, errors, warnings };
+}
+function formatIssue(issue2) {
+  return `${issue2.code}: ${issue2.field}: ${issue2.message}`;
+}
+function formatVerifyResult(result) {
+  if (result.extensionsDirMissing) {
+    return [
+      `WARNING \u2014 no plugins to verify. Scanned: ${result.extensionsDir} (directory does not exist).`,
+      "",
+      "If you just wrote a plugin: check that you put it under THIS workspace's `.pi/extensions/` and not a different cwd. The scanned path above is `<cwd>/.pi/extensions/`."
+    ].join("\n");
+  }
+  if (result.outcomes.length === 0) {
+    return [
+      `WARNING \u2014 scanned ${result.extensionsDir} but found NO plugin directories.`,
+      "",
+      "If you just wrote a plugin: it is NOT in this dir. Either you wrote to a different `.pi/extensions/` (check your cwd), or the dir name starts with `.` / `preflight-` (skipped)."
+    ].join("\n");
+  }
+  const lines = [];
+  const failures = result.outcomes.filter((o) => !o.ok);
+  const withWarnings = result.outcomes.filter((o) => o.warnings.length > 0);
+  if (failures.length === 0) {
+    lines.push(`OK \u2014 ${result.outcomes.length} plugin(s) have valid manifests + present files. (scanned ${result.extensionsDir})`);
+    for (const outcome of result.outcomes) {
+      const tag = outcome.warnings.length > 0 ? "\u26A0" : "\u2713";
+      lines.push(`  ${tag} ${outcome.id}`);
+      for (const w of outcome.warnings) {
+        lines.push(`      WARN: ${w}`);
+      }
+    }
+    lines.push("");
+    if (withWarnings.length > 0) {
+      const n = withWarnings.length;
+      lines.push(`Manifests are valid, but ${n} plugin${n === 1 ? "" : "s"} need a workspace restart (NOT just /reload) to pick up server-side changes \u2014 see WARN lines above.`);
+      lines.push("");
+    }
+    lines.push("Note: this validator does NOT execute plugin code. Front/Pi syntax / type / runtime errors surface on /reload; boring.server files require static composition plus a process restart.");
+  } else {
+    lines.push(`FAILED \u2014 ${failures.length} of ${result.outcomes.length} plugin(s) have errors.  (scanned ${result.extensionsDir})`);
+    lines.push("");
+    for (const outcome of result.outcomes) {
+      if (outcome.ok) {
+        const tag = outcome.warnings.length > 0 ? "\u26A0" : "\u2713";
+        lines.push(`  ${tag} ${outcome.id}`);
+        for (const w of outcome.warnings) {
+          lines.push(`      WARN: ${w}`);
+        }
+      } else {
+        lines.push(`  \u2717 ${outcome.id}  (${outcome.dir})`);
+        for (const err of outcome.errors) {
+          lines.push(`      ${err}`);
+        }
+        for (const w of outcome.warnings) {
+          lines.push(`      WARN: ${w}`);
+        }
+      }
+    }
+    lines.push("");
+    lines.push("Fix the errors above and run `boring-ui-plugin verify` again. Once it reports OK, ask the user to run /reload for front/Pi assets; boring.server changes require static composition plus restart.");
+  }
+  return lines.join("\n");
+}
+var COMMON_MISTAKE_HINTS = [
+  {
+    pattern: /boring\.server must be a safe relative path or false/i,
+    hint: 'Set `boring.server` to a string path like "server/index.ts", or to `false` (or omit the field). It is NOT a boolean true. For hot-reloadable agent behavior in .pi/extensions, prefer pi.extensions instead.'
+  },
+  {
+    pattern: /package\.json manifest must be an object/i,
+    hint: "package.json must parse as a JSON object \u2014 check for trailing commas or unquoted keys."
+  }
+];
+function findHintForError(message) {
+  for (const m of COMMON_MISTAKE_HINTS) {
+    if (m.pattern.test(message)) return m.hint;
+  }
+  return void 0;
+}
+
+// src/server/index.ts
+function defaultWorkspaceRoot() {
+  return process.env.BORING_AGENT_WORKSPACE_ROOT ?? process.cwd();
+}
+function workspaceLocalPluginRootsEnabled() {
+  const raw = process.env.BORING_AGENT_WORKSPACE_LOCAL_PLUGIN_ROOTS;
+  if (raw == null || raw.trim() === "") return true;
+  return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
+}
+function buildPluginStatus(workspaceRoot = defaultWorkspaceRoot()) {
+  const resolvedRoot = resolve4(workspaceRoot);
+  const enabled = workspaceLocalPluginRootsEnabled();
+  return {
+    workspaceLocalPluginRoots: enabled,
+    workspaceRoot: resolvedRoot,
+    extensionsDir: join4(resolvedRoot, ".pi", "extensions"),
+    reloadSupported: enabled,
+    ...enabled ? {} : {
+      reason: "This runtime writes to a remote sandbox; host-side plugin discovery cannot load .pi/extensions from there."
+    }
+  };
+}
+function parseVerifyArgs(positionals, workspaceRoot = defaultWorkspaceRoot()) {
+  const maybeName = positionals[0];
+  const maybeWorkspace = positionals[1];
+  const looksLikePath = maybeName && (maybeName.includes("/") || maybeName.startsWith("."));
+  const name = looksLikePath ? void 0 : maybeName;
+  return {
+    ...name ? { name } : {},
+    workspaceRoot: resolve4(maybeWorkspace ?? (looksLikePath ? maybeName : workspaceRoot))
+  };
+}
+function parseScaffoldArgs(positionals, workspaceRoot = defaultWorkspaceRoot()) {
+  const name = positionals[0];
+  if (!name) throw new Error("usage: boring-ui-plugin scaffold <name> [workspace]");
+  return { name, workspaceRoot: resolve4(positionals[1] ?? workspaceRoot) };
+}
+function parseCreateArgs(positionals) {
+  const name = positionals[0];
+  if (!name) throw new Error("usage: boring-ui-plugin create <name> [--path <dir>]");
+  return { name };
+}
+
+// src/server/testPlugin.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var POLL_MS = 500;
+function inferSelfTestUrl(explicitUrl, env = process.env) {
+  const envUrl = env.BORING_UI_SELF_TEST_URL ?? env.BORING_UI_URL ?? env.BORING_WORKSPACE_URL;
+  const portUrl = env.PORT ? `http://127.0.0.1:${env.PORT}` : void 0;
+  return explicitUrl?.trim() || envUrl?.trim() || portUrl || "http://127.0.0.1:5200";
+}
+function inferSelfTestWorkspaceId(explicitWorkspaceId, env = process.env) {
+  return explicitWorkspaceId?.trim() || env.BORING_UI_WORKSPACE_ID?.trim() || env.BORING_WORKSPACE_ID?.trim() || env.BORING_AGENT_WORKSPACE_ID?.trim() || void 0;
+}
+function buildPanelId(pluginId, panelId) {
+  return panelId?.trim() || `${pluginId}.panel`;
+}
+function buildPanelInstanceId(pluginId, panelId) {
+  return `self-test:${pluginId}:${panelId}`;
+}
+function normalizeBaseUrl(rawUrl) {
+  const url = new URL(rawUrl);
+  url.hash = "";
+  return url.toString().replace(/\/+$/, "");
+}
+function apiUrl(baseUrl, path) {
+  return `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function workspaceHeaders(workspaceId) {
+  return workspaceId ? { "x-boring-workspace-id": workspaceId } : {};
+}
+function truncateMessage(message) {
+  return message.replace(/\s+/g, " ").trim().slice(0, 1e3);
+}
+function event(code, message) {
+  return { code, message: truncateMessage(message) };
+}
+async function readJson(response) {
+  const text = await response.text();
+  if (!text.trim()) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function fetchJson(url, init) {
+  const response = await fetch(url, init);
+  return { status: response.status, body: await readJson(response) };
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null;
+}
+function collectReloadDiagnostics(pluginId, body) {
+  if (!isObject2(body) || !Array.isArray(body.diagnostics)) return [];
+  const events = [];
+  for (const diagnostic of body.diagnostics) {
+    if (!isObject2(diagnostic)) continue;
+    const diagnosticPlugin = typeof diagnostic.pluginId === "string" ? diagnostic.pluginId : void 0;
+    if (diagnosticPlugin && diagnosticPlugin !== pluginId) continue;
+    const message = typeof diagnostic.message === "string" ? diagnostic.message : "reload diagnostic";
+    events.push(event("RELOAD_DIAGNOSTIC", message));
+  }
+  return events;
+}
+function collectRuntimeDiagnostics(pluginId, body) {
+  const events = [];
+  let revision;
+  if (!isObject2(body) || !Array.isArray(body.plugins)) return { events };
+  const plugin = body.plugins.find((entry) => isObject2(entry) && entry.id === pluginId);
+  if (!plugin) return { events };
+  if (typeof plugin.serverLoadedRevision === "number") revision = plugin.serverLoadedRevision;
+  if (typeof plugin.serverError === "string") events.push(event("PLUGIN_SERVER_ERROR", plugin.serverError));
+  if (isObject2(plugin.host)) {
+    if (typeof plugin.host.revision === "number") revision = plugin.host.revision;
+    const code = typeof plugin.host.lastErrorCode === "string" ? plugin.host.lastErrorCode : "PLUGIN_RUNTIME_HOST_ERROR";
+    const message = typeof plugin.host.lastErrorMessage === "string" ? plugin.host.lastErrorMessage : typeof plugin.host.lastErrorStage === "string" ? plugin.host.lastErrorStage : void 0;
+    if (message) events.push(event(code, message));
+  }
+  return { events, revision };
+}
+async function inferWorkspaceIdFromMeta(baseUrl) {
+  try {
+    const meta = await fetchJson(apiUrl(baseUrl, "/api/v1/workspace/meta"));
+    if (meta.status < 200 || meta.status >= 300 || !isObject2(meta.body)) return void 0;
+    return typeof meta.body.workspaceId === "string" ? meta.body.workspaceId : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function maybeReadPluginError(baseUrl, pluginId, headers) {
+  try {
+    const response = await fetch(apiUrl(baseUrl, `/api/v1/agent-plugins/${encodeURIComponent(pluginId)}/error`), { headers });
+    if (response.status === 404) return [];
+    if (!response.ok) return [];
+    const text = await response.text();
+    return text.trim() ? [event("PLUGIN_LOAD_ERROR", text)] : [];
+  } catch {
+    return [];
+  }
+}
+async function pollPaneStatus(args) {
+  const url = new URL(apiUrl(args.baseUrl, "/api/v1/ui/panels/status"));
+  url.searchParams.set("panelInstanceId", args.panelInstanceId);
+  url.searchParams.set("pluginId", args.pluginId);
+  url.searchParams.set("panelId", args.panelId);
+  if (args.workspaceId) url.searchParams.set("workspaceId", args.workspaceId);
+  const result = await fetchJson(url.toString(), { headers: args.headers });
+  if (result.status < 200 || result.status >= 300) return { state: "missing" };
+  const body = isObject2(result.body) ? result.body : {};
+  const status = isObject2(body.status) ? body.status : void 0;
+  const reportedAt = typeof status?.reportedAt === "string" ? Date.parse(status.reportedAt) : void 0;
+  if (reportedAt !== void 0 && Number.isFinite(reportedAt) && reportedAt < args.minReportedAtMs) {
+    return { state: "missing" };
+  }
+  const state = typeof body.state === "string" ? body.state : "missing";
+  return { state, status };
+}
+async function openPanel(args) {
+  try {
+    const result = await fetchJson(apiUrl(args.baseUrl, "/api/v1/ui/commands"), {
+      method: "POST",
+      headers: { "content-type": "application/json", ...args.headers },
+      body: JSON.stringify({
+        kind: "openPanel",
+        params: {
+          id: args.panelInstanceId,
+          component: args.panelId,
+          title: `Self-test: ${args.pluginId}`
+        }
+      })
+    });
+    if (result.status < 200 || result.status >= 300) {
+      return [event("OPEN_PANEL_HTTP_ERROR", `/api/v1/ui/commands returned ${result.status}`)];
+    }
+  } catch (error) {
+    return [event("OPEN_PANEL_FAILED", error instanceof Error ? error.message : String(error))];
+  }
+  return [];
+}
+async function runPluginSelfTest(options) {
+  const pluginId = options.pluginId.trim();
+  if (!pluginId) throw new Error("plugin id is required");
+  const baseUrl = normalizeBaseUrl(inferSelfTestUrl(options.url));
+  const workspaceId = inferSelfTestWorkspaceId(options.workspaceId) ?? await inferWorkspaceIdFromMeta(baseUrl);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const panelId = buildPanelId(pluginId, options.panelId);
+  const panelInstanceId = buildPanelInstanceId(pluginId, panelId);
+  const headers = workspaceHeaders(workspaceId);
+  const reloadErrors = [];
+  let revision;
+  try {
+    const reload = await fetchJson(apiUrl(baseUrl, "/api/v1/agent/reload"), {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify({ ...workspaceId ? { sessionId: workspaceId } : {} })
+    });
+    if (reload.status < 200 || reload.status >= 300) reloadErrors.push(event("RELOAD_HTTP_ERROR", `/api/v1/agent/reload returned ${reload.status}`));
+    reloadErrors.push(...collectReloadDiagnostics(pluginId, reload.body));
+  } catch (error) {
+    reloadErrors.push(event("RELOAD_FAILED", error instanceof Error ? error.message : String(error)));
+  }
+  try {
+    const diagnostics = await fetchJson(apiUrl(baseUrl, "/api/v1/runtime-plugin-diagnostics"), { headers });
+    if (diagnostics.status >= 200 && diagnostics.status < 300) {
+      const normalized = collectRuntimeDiagnostics(pluginId, diagnostics.body);
+      reloadErrors.push(...normalized.events);
+      revision = normalized.revision;
+    } else if (diagnostics.status !== 404) {
+      reloadErrors.push(event("DIAGNOSTICS_HTTP_ERROR", `/api/v1/runtime-plugin-diagnostics returned ${diagnostics.status}`));
+    }
+  } catch {
+  }
+  reloadErrors.push(...await maybeReadPluginError(baseUrl, pluginId, headers));
+  const start = Date.now();
+  let lastOpenAt = 0;
+  let lastState = "missing";
+  let lastStatus;
+  let openErrors = [];
+  while (Date.now() - start <= timeoutMs) {
+    const status = await pollPaneStatus({ baseUrl, headers, workspaceId, pluginId, panelId, panelInstanceId, minReportedAtMs: start });
+    lastState = status.state;
+    lastStatus = status.status;
+    if (status.state === "no-browser-connected") {
+      return buildResult({ pluginId, workspaceId, revision, reloadErrors, panelId, panelInstanceId, state: "no-browser-connected", status: lastStatus });
+    }
+    if (status.state === "ready" || status.state === "error") break;
+    if (Date.now() - lastOpenAt >= POLL_MS) {
+      openErrors = await openPanel({ baseUrl, headers, pluginId, panelId, panelInstanceId });
+      lastOpenAt = Date.now();
+    }
+    await new Promise((resolve5) => setTimeout(resolve5, POLL_MS));
+  }
+  if (openErrors.length > 0) reloadErrors.push(...openErrors);
+  const finalState = lastState === "ready" || lastState === "error" ? lastState : "timeout";
+  return buildResult({ pluginId, workspaceId, revision, reloadErrors, panelId, panelInstanceId, state: finalState, status: lastStatus });
+}
+function buildResult(args) {
+  const error = isObject2(args.status?.error) ? event(typeof args.status.error.code === "string" ? args.status.error.code : "PANE_ERROR", typeof args.status.error.message === "string" ? args.status.error.message : "pane error") : void 0;
+  const lastReportedAt = typeof args.status?.reportedAt === "string" ? args.status.reportedAt : void 0;
+  const revision = typeof args.status?.revision === "number" ? args.status.revision : args.revision;
+  return {
+    ok: args.reloadErrors.length === 0 && args.state === "ready",
+    ...args.workspaceId ? { workspaceId: args.workspaceId } : {},
+    pluginId: args.pluginId,
+    ...revision !== void 0 ? { revision } : {},
+    reloadErrors: args.reloadErrors,
+    pane: {
+      found: args.state === "ready" || args.state === "error",
+      state: args.state,
+      panelId: args.panelId,
+      panelInstanceId: args.panelInstanceId,
+      ...error ? { error } : {},
+      ...lastReportedAt ? { lastReportedAt } : {}
+    }
+  };
+}
+function formatSelfTestResult(result) {
+  const lines = [
+    result.ok ? `OK ${result.pluginId}` : `FAIL ${result.pluginId}`,
+    `  pane     ${result.pane.state}${result.pane.found ? "" : " (not found)"}`
+  ];
+  if (result.revision !== void 0) lines.push(`  revision ${result.revision}`);
+  for (const item of result.reloadErrors) lines.push(`  reload   ${item.code}: ${item.message}`);
+  if (result.pane.error) lines.push(`  pane     ${result.pane.error.code}: ${result.pane.error.message}`);
+  if (result.pane.state === "no-browser-connected") {
+    lines.push(`  hint     open the workspace UI, then rerun boring-ui-plugin test ${result.pluginId}`);
+  }
+  return lines.join("\n");
+}
+
+// src/index.ts
+function pluginCommandUsage() {
+  return [
+    "usage: boring-ui-plugin <command>",
+    "",
+    "Commands:",
+    "  boring-ui-plugin status [--json]",
+    "  boring-ui-plugin create <name> [--path <dir>]",
+    "  boring-ui-plugin scaffold <name> [workspace]",
+    "  boring-ui-plugin verify [name] [workspace]",
+    "  boring-ui-plugin test <name> [--url <url>] [--workspace <id>] [--panel-id <id>] [--timeout-ms <ms>] [--json]"
+  ].join("\n");
+}
+function handleStatus(json) {
+  const status = buildPluginStatus();
+  if (json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+  console.log(status.workspaceLocalPluginRoots ? `workspace-local plugin roots enabled: ${status.extensionsDir}` : `workspace-local plugin roots disabled: ${status.reason}`);
+}
+function handleCreate(argv, positionals) {
+  const args = parseCreateArgs(positionals);
+  const result = createPlugin({
+    name: args.name,
+    ...readOption(argv, "--path") ? { path: readOption(argv, "--path") } : {}
+  });
+  console.log(`created ${result.id}`);
+  console.log(`  dir   ${result.pluginDir}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  1. cd ${result.pluginDir}`);
+  console.log("  2. pnpm install");
+  console.log(`  3. pnpm --filter ${result.packageName} typecheck`);
+  console.log(`  4. pnpm --filter ${result.packageName} test`);
+}
+function handleScaffold(positionals) {
+  const args = parseScaffoldArgs(positionals);
+  const status = buildPluginStatus(args.workspaceRoot);
+  if (!workspaceLocalPluginRootsEnabled()) {
+    throw new Error(`${status.reason} Do not scaffold into .pi/extensions in this runtime.`);
+  }
+  const result = scaffoldPlugin(args);
+  console.log(`scaffolded ${args.name}`);
+  console.log(`  dir   ${result.pluginDir}`);
+  for (const file of result.filesCreated) console.log(`  +     ${file}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log("  1. edit front/index.tsx for UI panels/commands/resolvers");
+  console.log("  2. add pi.extensions / skills for hot-reloadable agent behavior");
+  console.log("  3. bash `boring-ui-plugin verify` \u2014 confirms manifests + files are valid");
+  console.log("  4. if the UI is open, bash `boring-ui-plugin test <name>` \u2014 catches panel render failures");
+  console.log("  5. ask the user: /reload");
+}
+function handleVerify(positionals) {
+  const result = verifyPlugin(parseVerifyArgs(positionals));
+  console.log(formatVerifyResult(result));
+  if (result.ok) return;
+  const hints = [];
+  for (const outcome of result.outcomes) {
+    for (const err of outcome.errors) {
+      const hint = findHintForError(err);
+      if (hint) hints.push(`  hint (${outcome.id}): ${hint}`);
+    }
+  }
+  if (hints.length > 0) {
+    console.log("");
+    console.log("Suggestions:");
+    for (const hint of hints) console.log(hint);
+  }
+  process.exit(1);
+}
+function readOption(argv, name) {
+  const index = argv.indexOf(name);
+  if (index === -1) return void 0;
+  return argv[index + 1];
+}
+async function handleTest(argv, positionals, json) {
+  const name = positionals[0];
+  if (!name) throw new Error("usage: boring-ui-plugin test <name> [--url <local-server-url>] [--workspace <id>] [--panel-id <id>] [--timeout-ms <ms>] [--json]");
+  const timeoutRaw = readOption(argv, "--timeout-ms");
+  const timeoutMs = timeoutRaw ? Number(timeoutRaw) : void 0;
+  if (timeoutRaw && (timeoutMs == null || !Number.isFinite(timeoutMs) || timeoutMs <= 0)) throw new Error("--timeout-ms must be a positive number");
+  const result = await runPluginSelfTest({
+    pluginId: name,
+    ...readOption(argv, "--url") ? { url: readOption(argv, "--url") } : {},
+    ...readOption(argv, "--workspace") ? { workspaceId: readOption(argv, "--workspace") } : {},
+    ...readOption(argv, "--panel-id") ? { panelId: readOption(argv, "--panel-id") } : {},
+    ...timeoutMs == null ? {} : { timeoutMs }
+  });
+  console.log(json ? JSON.stringify(result, null, 2) : formatSelfTestResult(result));
+  if (!result.ok) process.exit(1);
+}
+async function runBoringUiPluginCli(argv = process.argv.slice(2)) {
+  const positionals = argv.filter((arg) => !arg.startsWith("-"));
+  const json = argv.includes("--json");
+  const command = positionals[0];
+  const rest = positionals.slice(1);
+  if (command === "status") return handleStatus(json);
+  if (command === "create") return handleCreate(argv, rest);
+  if (command === "scaffold") return handleScaffold(rest);
+  if (command === "verify") return handleVerify(rest);
+  if (command === "test") return await handleTest(argv, rest, json);
+  console.log(pluginCommandUsage());
+}
+
+export {
+  createPlugin,
+  scaffoldPlugin,
+  verifyPlugin,
+  formatVerifyResult,
+  findHintForError,
+  runPluginSelfTest,
+  formatSelfTestResult,
+  pluginCommandUsage,
+  runBoringUiPluginCli
+};