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

package/dist/bin.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   runBoringUiPluginCli
-} from "./chunk-DH4PSVGY.js";
+} from "./chunk-HY4ZELTX.js";
+import "./chunk-6FD653KO.js";
 
 // src/bin.ts
 runBoringUiPluginCli().catch((error) => {

package/dist/chunk-6FD653KO.js

@@ -0,0 +1,605 @@
+// src/server/pluginSources.ts
+import { spawnSync } from "child_process";
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { basename, dirname, isAbsolute, join, relative, resolve } 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/pluginSources.ts
+function defaultWorkspaceRoot() {
+  return process.env.BORING_AGENT_WORKSPACE_ROOT ?? process.cwd();
+}
+function defaultGlobalRoot() {
+  return process.env.BORING_UI_PLUGIN_GLOBAL_ROOT ?? join(homedir(), ".pi", "agent");
+}
+function resolvePluginSourceScopePaths(scope, opts = {}) {
+  if (scope === "global") {
+    const baseDir2 = resolve(opts.globalRoot ?? defaultGlobalRoot());
+    return {
+      scope,
+      baseDir: baseDir2,
+      extensionsDir: join(baseDir2, "extensions"),
+      gitDir: join(baseDir2, "git"),
+      npmDir: join(baseDir2, "npm"),
+      settingsPath: join(baseDir2, "settings.json")
+    };
+  }
+  const workspaceRoot = resolve(opts.workspaceRoot ?? defaultWorkspaceRoot());
+  const baseDir = join(workspaceRoot, ".pi");
+  return {
+    scope,
+    workspaceRoot,
+    baseDir,
+    extensionsDir: join(baseDir, "extensions"),
+    gitDir: join(baseDir, "git"),
+    npmDir: join(baseDir, "npm"),
+    settingsPath: join(baseDir, "settings.json")
+  };
+}
+function ensureScopeDirs(paths) {
+  mkdirSync(paths.baseDir, { recursive: true });
+  mkdirSync(paths.extensionsDir, { recursive: true });
+  mkdirSync(paths.gitDir, { recursive: true });
+  mkdirSync(paths.npmDir, { recursive: true });
+}
+function readPiSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`invalid Pi settings file ${settingsPath}: ${message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`invalid Pi settings file ${settingsPath}: expected object`);
+  }
+  return parsed;
+}
+function writePiSettings(settingsPath, settings) {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
+`, "utf8");
+}
+function packageEntries(settings) {
+  if (!Array.isArray(settings.packages)) return [];
+  return settings.packages.flatMap((entry) => {
+    if (typeof entry === "string") return [entry];
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) return [entry];
+    return [];
+  });
+}
+function packageEntrySource(entry) {
+  return typeof entry === "string" ? entry : typeof entry.source === "string" ? entry.source : void 0;
+}
+function resolveMaybePath(value) {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return resolve(join(homedir(), value.slice(2)));
+  if (isAbsolute(value) || value.startsWith(".")) return resolve(value);
+  return value;
+}
+function resolvePackageSourcePath(settingsDir, source) {
+  const path = source.startsWith("file:") ? source.slice("file:".length) : source;
+  if (path.startsWith("npm:") || path.startsWith("git:") || path.startsWith("github:") || /^(https?|ssh):\/\//.test(path)) return void 0;
+  if (path === "~" || path.startsWith("~/")) return resolveMaybePath(path);
+  return isAbsolute(path) ? resolve(path) : resolve(settingsDir, path);
+}
+function pathInside(parent, child) {
+  const rel = relative(parent, child);
+  return rel === "" || !!rel && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function sourceForLocalPackage(paths, rootDir) {
+  if (paths.workspaceRoot && pathInside(paths.workspaceRoot, rootDir)) {
+    const rel2 = relative(paths.baseDir, rootDir).split("\\").join("/");
+    if (!rel2 || rel2 === ".") return ".";
+    return rel2.startsWith(".") ? rel2 : rel2.startsWith("..") ? rel2 : `./${rel2}`;
+  }
+  const rel = relative(paths.baseDir, rootDir).split("\\").join("/");
+  if (!rel || rel === ".") return ".";
+  if (!rel.startsWith("..") && !isAbsolute(rel)) return rel.startsWith(".") ? rel : `./${rel}`;
+  return rootDir;
+}
+function inferKind(paths, rootDir, source) {
+  if (source.startsWith("npm:") || pathInside(paths.npmDir, rootDir)) return "npm";
+  if (source.startsWith("git:") || source.startsWith("github:") || /^(https?|ssh):\/\//.test(source) || pathInside(paths.gitDir, rootDir)) return "git";
+  return "local";
+}
+function run(command, args, opts = {}) {
+  const result = spawnSync(command, args, {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.status === 0) return;
+  const stderr = result.stderr?.trim();
+  const stdout = result.stdout?.trim();
+  const details = stderr || stdout ? `: ${stderr || stdout}` : "";
+  throw new Error(`${command} ${args.join(" ")} failed${details}`);
+}
+function runWithStdout(command, args, opts = {}) {
+  const result = spawnSync(command, args, {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim();
+    const stdout = result.stdout?.trim();
+    const details = stderr || stdout ? `: ${stderr || stdout}` : "";
+    throw new Error(`${command} ${args.join(" ")} failed${details}`);
+  }
+  return result.stdout;
+}
+function readPackageJson(pluginRoot) {
+  const pkgPath = join(pluginRoot, "package.json");
+  if (!existsSync(pkgPath)) throw new Error(`package.json missing in plugin source: ${pluginRoot}`);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`package.json is not valid JSON in ${pluginRoot}: ${message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`package.json must be an object in ${pluginRoot}`);
+  }
+  return parsed;
+}
+function pluginIdFromPackageJson(pkg, rootDir) {
+  const boring = pkg.boring && typeof pkg.boring === "object" && !Array.isArray(pkg.boring) ? pkg.boring : void 0;
+  const pi = pkg.pi && typeof pkg.pi === "object" && !Array.isArray(pkg.pi) ? pkg.pi : void 0;
+  const explicitId = typeof boring?.id === "string" && boring.id.trim() ? boring.id.trim() : typeof pi?.id === "string" && pi.id.trim() ? pi.id.trim() : void 0;
+  if (explicitId) return explicitId;
+  const name = typeof pkg.name === "string" && pkg.name.trim() ? pkg.name.trim() : void 0;
+  return ((name ?? basename(rootDir)) || "plugin").replace(/^@/, "").replaceAll("/", "-");
+}
+function validateInstallablePluginRoot(pluginRoot) {
+  const resolvedRoot = resolve(pluginRoot);
+  const pkg = readPackageJson(resolvedRoot);
+  const validation = validateBoringPluginManifest(pkg);
+  if (!validation.valid) {
+    const issues = validation.issues.map((issue2) => `${issue2.field}: ${issue2.message}`).join("; ");
+    throw new Error(`invalid Boring plugin manifest in ${resolvedRoot}: ${issues}`);
+  }
+  const id = pluginIdFromPackageJson(validation.packageJson, resolvedRoot);
+  return {
+    id,
+    ...typeof validation.packageJson.name === "string" ? { packageName: validation.packageJson.name } : {},
+    ...typeof validation.packageJson.version === "string" ? { version: validation.packageJson.version } : {},
+    dependencyHints: dependencyHints(resolvedRoot, pkg)
+  };
+}
+var HOST_PROVIDED_DEPENDENCIES = /* @__PURE__ */ new Set(["react", "react-dom", "@hachej/boring-workspace", "@hachej/boring-ui-kit"]);
+function dependencyHints(pluginRoot, pkg) {
+  const dependencies = pkg.dependencies;
+  if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) return [];
+  const hints = [];
+  for (const dep of Object.keys(dependencies)) {
+    if (HOST_PROVIDED_DEPENDENCIES.has(dep)) continue;
+    const depDir = dep.startsWith("@") ? join(pluginRoot, "node_modules", ...dep.split("/")) : join(pluginRoot, "node_modules", dep);
+    if (!existsSync(depDir)) hints.push(`Missing dependency: ${dep}
+Run: cd ${pluginRoot} && npm install`);
+  }
+  return hints;
+}
+function classifySource(source) {
+  if (source.startsWith("npm:")) return { kind: "npm", spec: source.slice("npm:".length), original: source };
+  if (source.startsWith("git:")) return { ...normalizeGitSource(source.slice("git:".length)), original: source };
+  if (source.startsWith("github:")) return { ...normalizeGitSource(source), original: source };
+  if (/^(https?|ssh):\/\//.test(source)) return { kind: "git", spec: source, original: source };
+  const maybePath = resolveMaybePath(source);
+  if (existsSync(maybePath)) return { kind: "local", spec: maybePath, original: source };
+  throw new Error(`unsupported plugin source ${JSON.stringify(source)}. Use a local path, npm:<package>, git:<repo>, github:<owner>/<repo>, or an http(s) git URL.`);
+}
+function normalizeGitSource(raw) {
+  let spec = raw;
+  let ref;
+  const hashIndex = spec.lastIndexOf("#");
+  if (hashIndex > 0) {
+    ref = spec.slice(hashIndex + 1);
+    spec = spec.slice(0, hashIndex);
+  } else {
+    const slashIndex = spec.lastIndexOf("/");
+    const atIndex = spec.lastIndexOf("@");
+    if (atIndex > slashIndex && !spec.slice(0, atIndex).includes(":")) {
+      ref = spec.slice(atIndex + 1);
+      spec = spec.slice(0, atIndex);
+    }
+  }
+  if (spec.startsWith("github:")) spec = `https://github.com/${spec.slice("github:".length)}`;
+  if (spec.startsWith("github.com/")) spec = `https://${spec}`;
+  return { kind: "git", spec, ...ref ? { ref } : {} };
+}
+function safeInstallDir(parent, id) {
+  const cleaned = id.replace(/[^A-Za-z0-9._:-]+/g, "-");
+  if (!cleaned || cleaned === "." || cleaned === "..") throw new Error(`invalid plugin id ${JSON.stringify(id)}`);
+  return join(parent, cleaned);
+}
+function moveFreshDir(from, to) {
+  if (existsSync(to)) throw new Error(`plugin install target already exists: ${to}. Remove it first with boring-ui-plugin remove ${basename(to)}`);
+  mkdirSync(dirname(to), { recursive: true });
+  renameSync(from, to);
+}
+function installLocalSource(source, paths) {
+  const rootDir = realpathSync(resolveMaybePath(source));
+  return { rootDir, packageSource: sourceForLocalPackage(paths, rootDir) };
+}
+function installPluginDependencies(pluginRoot) {
+  const pkg = readPackageJson(pluginRoot);
+  const declared = pkg.dependencies;
+  if (!declared || typeof declared !== "object" || Array.isArray(declared)) return;
+  const installable = Object.fromEntries(
+    Object.entries(declared).filter(([name]) => !HOST_PROVIDED_DEPENDENCIES.has(name))
+  );
+  if (Object.keys(installable).length === 0) return;
+  if (Object.keys(installable).length !== Object.keys(declared).length) {
+    writeFileSync(
+      join(pluginRoot, "package.json"),
+      `${JSON.stringify({ ...pkg, dependencies: installable }, null, 2)}
+`,
+      "utf8"
+    );
+  }
+  try {
+    run("npm", ["install", "--omit=dev", "--no-audit", "--no-fund", "--legacy-peer-deps"], { cwd: pluginRoot });
+  } catch (err) {
+    rmSync(pluginRoot, { recursive: true, force: true });
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`failed to install dependencies for plugin at ${pluginRoot}; install rolled back. ${detail}`);
+  }
+}
+function withStagingDir(parent, fn) {
+  mkdirSync(parent, { recursive: true });
+  const staging = mkdtempSync(join(parent, ".staging-"));
+  try {
+    return fn(staging);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+function installGitSource(spec, paths, ref) {
+  return withStagingDir(paths.gitDir, (staging) => {
+    const cloneDir = join(staging, "repo");
+    run("git", ["clone", "--quiet", spec, cloneDir]);
+    if (ref) run("git", ["checkout", "--quiet", ref], { cwd: cloneDir });
+    const meta = validateInstallablePluginRoot(cloneDir);
+    const target = safeInstallDir(paths.gitDir, meta.id);
+    moveFreshDir(cloneDir, target);
+    installPluginDependencies(target);
+    return { rootDir: target, packageSource: sourceForLocalPackage(paths, target), ...ref ? { ref } : {} };
+  });
+}
+function installNpmSource(spec, paths) {
+  return withStagingDir(paths.npmDir, (staging) => {
+    const packDir = join(staging, "pack");
+    const extractDir = join(staging, "extract");
+    mkdirSync(packDir, { recursive: true });
+    mkdirSync(extractDir, { recursive: true });
+    const stdout = runWithStdout("npm", ["pack", "--silent", spec, "--pack-destination", packDir], { cwd: staging });
+    const tarballName = stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    if (!tarballName) throw new Error(`npm pack did not produce a tarball for ${spec}`);
+    const tarball = isAbsolute(tarballName) ? tarballName : join(packDir, tarballName);
+    run("tar", ["-xzf", tarball, "-C", extractDir, "--strip-components", "1"]);
+    const meta = validateInstallablePluginRoot(extractDir);
+    const target = safeInstallDir(paths.npmDir, meta.id);
+    moveFreshDir(extractDir, target);
+    installPluginDependencies(target);
+    return { rootDir: target, packageSource: sourceForLocalPackage(paths, target) };
+  });
+}
+function recordFromPackageSource(paths, entry) {
+  const packageSource = packageEntrySource(entry);
+  if (!packageSource) return null;
+  const rootDir = resolvePackageSourcePath(paths.baseDir, packageSource);
+  if (!rootDir || !existsSync(join(rootDir, "package.json"))) return null;
+  const meta = validateInstallablePluginRoot(rootDir);
+  return {
+    id: meta.id,
+    kind: inferKind(paths, rootDir, packageSource),
+    scope: paths.scope,
+    packageSource,
+    source: rootDir,
+    rootDir,
+    ...meta.packageName ? { packageName: meta.packageName } : {},
+    ...meta.version ? { version: meta.version } : {}
+  };
+}
+function readPluginSourceRecords(paths) {
+  return packageEntries(readPiSettings(paths.settingsPath)).flatMap((entry) => {
+    try {
+      const record = recordFromPackageSource(paths, entry);
+      return record ? [record] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+function readPluginSourceRecordsForRoots(opts) {
+  const local = resolvePluginSourceScopePaths("local", opts);
+  const global = resolvePluginSourceScopePaths("global", opts);
+  return [...readPluginSourceRecords(global), ...readPluginSourceRecords(local)];
+}
+function upsertPackageSource(paths, record) {
+  const settings = readPiSettings(paths.settingsPath);
+  const entries = packageEntries(settings);
+  let replaced = false;
+  const nextEntries = [];
+  for (const entry of entries) {
+    const existing = recordFromPackageSource(paths, entry);
+    const existingSource = packageEntrySource(entry);
+    if (existing?.id === record.id || existing?.rootDir === record.rootDir || existingSource === record.packageSource) {
+      replaced = true;
+      continue;
+    }
+    nextEntries.push(entry);
+  }
+  nextEntries.push(record.packageSource);
+  settings.packages = nextEntries;
+  writePiSettings(paths.settingsPath, settings);
+  return replaced;
+}
+function removePackageSource(paths, target) {
+  const settings = readPiSettings(paths.settingsPath);
+  const entries = packageEntries(settings);
+  const resolvedTarget = resolveMaybePath(target);
+  let removed = null;
+  const nextEntries = [];
+  for (const entry of entries) {
+    const packageSource = packageEntrySource(entry);
+    let record = null;
+    try {
+      record = recordFromPackageSource(paths, entry);
+    } catch {
+      record = null;
+    }
+    const rootDir = packageSource ? resolvePackageSourcePath(paths.baseDir, packageSource) : void 0;
+    const matches = record ? record.id === target || record.packageSource === target || record.source === target || record.rootDir === target || record.source === resolvedTarget || record.rootDir === resolvedTarget : packageSource === target || rootDir === target || rootDir === resolvedTarget;
+    if (matches && !removed) {
+      removed = record ?? (packageSource ? {
+        id: target,
+        kind: rootDir ? inferKind(paths, rootDir, packageSource) : "local",
+        scope: paths.scope,
+        packageSource,
+        source: rootDir ?? packageSource,
+        rootDir: rootDir ?? packageSource
+      } : null);
+      continue;
+    }
+    if (matches) {
+      continue;
+    }
+    nextEntries.push(entry);
+  }
+  if (!removed) return null;
+  settings.packages = nextEntries;
+  writePiSettings(paths.settingsPath, settings);
+  return removed;
+}
+function installPluginSource(opts) {
+  const scope = opts.scope ?? "local";
+  const paths = resolvePluginSourceScopePaths(scope, opts);
+  ensureScopeDirs(paths);
+  const classified = classifySource(opts.source);
+  const installed = classified.kind === "local" ? installLocalSource(classified.spec, paths) : classified.kind === "git" ? installGitSource(classified.spec, paths, classified.ref) : installNpmSource(classified.spec, paths);
+  const meta = validateInstallablePluginRoot(installed.rootDir);
+  const record = {
+    id: meta.id,
+    kind: classified.kind,
+    scope,
+    packageSource: installed.packageSource,
+    source: installed.rootDir,
+    rootDir: installed.rootDir,
+    ...meta.packageName ? { packageName: meta.packageName } : {},
+    ...meta.version ? { version: meta.version } : {},
+    ...installed.ref ? { ref: installed.ref } : {}
+  };
+  const replaced = upsertPackageSource(paths, record);
+  return { record, scopePaths: paths, dependencyHints: meta.dependencyHints, replaced };
+}
+function listPluginSources(opts = {}) {
+  const scopes = opts.scope === "all" ? [resolvePluginSourceScopePaths("global", opts), resolvePluginSourceScopePaths("local", opts)] : [resolvePluginSourceScopePaths(opts.scope ?? "local", opts)];
+  return {
+    scopes,
+    records: scopes.flatMap((paths) => readPluginSourceRecords(paths))
+  };
+}
+function removePluginSource(opts) {
+  const scope = opts.scope ?? "local";
+  const paths = resolvePluginSourceScopePaths(scope, opts);
+  const record = removePackageSource(paths, opts.target);
+  if (!record) throw new Error(`plugin source not found in ${scope} scope: ${opts.target}`);
+  let removedSourceDir = false;
+  if (record.kind === "git" || record.kind === "npm") {
+    const expectedRoot = record.kind === "git" ? paths.gitDir : paths.npmDir;
+    const resolvedRoot = resolve(record.rootDir);
+    if (pathInside(expectedRoot, resolvedRoot)) {
+      rmSync(resolvedRoot, { recursive: true, force: true });
+      removedSourceDir = true;
+    }
+  }
+  return { record, scopePaths: paths, removedSourceDir };
+}
+function formatPluginSourceList(result) {
+  if (result.records.length === 0) {
+    const scopes = result.scopes.map((scope) => scope.scope).join("+");
+    return `No plugins installed in ${scopes} scope.`;
+  }
+  return result.records.sort((a, b) => a.scope.localeCompare(b.scope) || a.id.localeCompare(b.id)).map((record) => `${record.id}
+  scope  ${record.scope}
+  kind   ${record.kind}
+  source ${record.packageSource}
+  dir    ${record.rootDir}`).join("\n");
+}
+
+export {
+  isSafePluginRelativePath,
+  validateBoringPluginManifest,
+  resolvePluginSourceScopePaths,
+  readPluginSourceRecords,
+  readPluginSourceRecordsForRoots,
+  installPluginSource,
+  listPluginSources,
+  removePluginSource,
+  formatPluginSourceList
+};

package/dist/{chunk-DH4PSVGY.js → chunk-HY4ZELTX.js}

@@ -1,3 +1,12 @@
+import {
+  formatPluginSourceList,
+  installPluginSource,
+  isSafePluginRelativePath,
+  listPluginSources,
+  removePluginSource,
+  validateBoringPluginManifest
+} from "./chunk-6FD653KO.js";
+
 // src/server/index.ts
 import { join as join4, resolve as resolve4 } from "path";
 
@@ -198,161 +207,6 @@ function resolveBundledTemplatesDir() {
 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);
@@ -577,7 +431,7 @@ function verifySinglePlugin(pluginDir) {
   if (isObject(parsed)) validateDependencyManifest(pluginDir, parsed, errors);
   const result = validateBoringPluginManifest(parsed);
   if (!result.valid) {
-    for (const issue2 of result.issues) errors.push(formatIssue(issue2));
+    for (const issue of result.issues) errors.push(formatIssue(issue));
     return { id, dir: pluginDir, ok: false, errors, warnings };
   }
   const manifest = result.packageJson;
@@ -627,8 +481,8 @@ function verifySinglePlugin(pluginDir) {
   }
   return { id, dir: pluginDir, ok: errors.length === 0, errors, warnings };
 }
-function formatIssue(issue2) {
-  return `${issue2.code}: ${issue2.field}: ${issue2.message}`;
+function formatIssue(issue) {
+  return `${issue.code}: ${issue.field}: ${issue.message}`;
 }
 function formatVerifyResult(result) {
   if (result.extensionsDirMissing) {
@@ -987,7 +841,10 @@ function pluginCommandUsage() {
     "  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]"
+    "  boring-ui-plugin test <name> [--url <url>] [--workspace <id>] [--panel-id <id>] [--timeout-ms <ms>] [--json]",
+    "  boring-ui-plugin install [-l|--local|--global] [--workspace <dir>] <source>",
+    "  boring-ui-plugin list [--local|--global|--all] [--workspace <dir>] [--json]",
+    "  boring-ui-plugin remove [-l|--local|--global] [--workspace <dir>] <id-or-source>"
   ].join("\n");
 }
 function handleStatus(json) {
@@ -1054,6 +911,77 @@ function readOption(argv, name) {
   if (index === -1) return void 0;
   return argv[index + 1];
 }
+function pluginSourceScope(argv) {
+  if (argv.includes("--global")) return "global";
+  return "local";
+}
+function pluginSourceWorkspaceRoot(argv) {
+  return readOption(argv, "--workspace");
+}
+function commandPositionals(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--workspace") {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+function handleInstall(argv, json) {
+  const source = commandPositionals(argv)[1];
+  if (!source) throw new Error("usage: boring-ui-plugin install [--local|--global] [--workspace <dir>] <source>");
+  const result = installPluginSource({
+    source,
+    scope: pluginSourceScope(argv),
+    ...pluginSourceWorkspaceRoot(argv) ? { workspaceRoot: pluginSourceWorkspaceRoot(argv) } : {}
+  });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.record.kind === "git" || result.record.kind === "npm") {
+    console.warn("Security: Boring plugins run as trusted local code in CLI mode. Review third-party source before installing.");
+  }
+  console.log(`${result.replaced ? "updated" : "installed"} ${result.record.id}`);
+  console.log(`  scope ${result.record.scope}`);
+  console.log(`  kind  ${result.record.kind}`);
+  console.log(`  dir   ${result.record.rootDir}`);
+  if (result.dependencyHints.length > 0) {
+    console.log("");
+    console.log("Dependencies are not installed by boring-ui-plugin install. Run package-manager commands in the plugin folder:");
+    for (const hint of result.dependencyHints) console.log(hint);
+  }
+  console.log("");
+  console.log("Next step: ask the user to run /reload in the workspace UI.");
+}
+function handleList(argv, json) {
+  const scope = argv.includes("--all") ? "all" : pluginSourceScope(argv);
+  const result = listPluginSources({
+    scope,
+    ...pluginSourceWorkspaceRoot(argv) ? { workspaceRoot: pluginSourceWorkspaceRoot(argv) } : {}
+  });
+  console.log(json ? JSON.stringify(result, null, 2) : formatPluginSourceList(result));
+}
+function handleRemove(argv, json) {
+  const target = commandPositionals(argv)[1];
+  if (!target) throw new Error("usage: boring-ui-plugin remove [--local|--global] [--workspace <dir>] <id-or-source>");
+  const result = removePluginSource({
+    target,
+    scope: pluginSourceScope(argv),
+    ...pluginSourceWorkspaceRoot(argv) ? { workspaceRoot: pluginSourceWorkspaceRoot(argv) } : {}
+  });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`removed ${result.record.id}`);
+  console.log(`  scope ${result.record.scope}`);
+  if (result.removedSourceDir) console.log(`  deleted ${result.record.rootDir}`);
+}
 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]");
@@ -1080,6 +1008,9 @@ async function runBoringUiPluginCli(argv = process.argv.slice(2)) {
   if (command === "scaffold") return handleScaffold(rest);
   if (command === "verify") return handleVerify(rest);
   if (command === "test") return await handleTest(argv, rest, json);
+  if (command === "install") return handleInstall(argv, json);
+  if (command === "list") return handleList(argv, json);
+  if (command === "remove") return handleRemove(argv, json);
   console.log(pluginCommandUsage());
 }
 

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { InstallPluginSourceOptions, ListPluginSourcesOptions, PluginInstallResult, PluginInstallScope, PluginListResult, PluginRemoveResult, PluginSourceKind, PluginSourceRecord, PluginSourceScopePaths, RemovePluginSourceOptions, formatPluginSourceList, installPluginSource, listPluginSources, readPluginSourceRecords, readPluginSourceRecordsForRoots, removePluginSource, resolvePluginSourceScopePaths } from './plugin-sources.js';
+
 interface CreatePluginOptions {
     name: string;
     path?: string;

package/dist/index.js

@@ -8,13 +8,29 @@ import {
   runPluginSelfTest,
   scaffoldPlugin,
   verifyPlugin
-} from "./chunk-DH4PSVGY.js";
+} from "./chunk-HY4ZELTX.js";
+import {
+  formatPluginSourceList,
+  installPluginSource,
+  listPluginSources,
+  readPluginSourceRecords,
+  readPluginSourceRecordsForRoots,
+  removePluginSource,
+  resolvePluginSourceScopePaths
+} from "./chunk-6FD653KO.js";
 export {
   createPlugin,
   findHintForError,
+  formatPluginSourceList,
   formatSelfTestResult,
   formatVerifyResult,
+  installPluginSource,
+  listPluginSources,
   pluginCommandUsage,
+  readPluginSourceRecords,
+  readPluginSourceRecordsForRoots,
+  removePluginSource,
+  resolvePluginSourceScopePaths,
   runBoringUiPluginCli,
   runPluginSelfTest,
   scaffoldPlugin,

package/dist/plugin-sources.d.ts

@@ -0,0 +1,71 @@
+type PluginInstallScope = "local" | "global";
+type PluginSourceKind = "local" | "git" | "npm";
+interface PluginSourceRecord {
+    id: string;
+    kind: PluginSourceKind;
+    scope: PluginInstallScope;
+    /** Pi package source entry as stored in settings.json. */
+    packageSource: string;
+    /** Resolved package root when the source is locally inspectable. */
+    source: string;
+    rootDir: string;
+    packageName?: string;
+    version?: string;
+    ref?: string;
+}
+interface PluginSourceScopePaths {
+    scope: PluginInstallScope;
+    workspaceRoot?: string;
+    baseDir: string;
+    extensionsDir: string;
+    gitDir: string;
+    npmDir: string;
+    settingsPath: string;
+}
+interface InstallPluginSourceOptions {
+    source: string;
+    scope?: PluginInstallScope;
+    workspaceRoot?: string;
+    globalRoot?: string;
+}
+interface RemovePluginSourceOptions {
+    target: string;
+    scope?: PluginInstallScope;
+    workspaceRoot?: string;
+    globalRoot?: string;
+}
+interface ListPluginSourcesOptions {
+    scope?: PluginInstallScope | "all";
+    workspaceRoot?: string;
+    globalRoot?: string;
+}
+interface PluginInstallResult {
+    record: PluginSourceRecord;
+    scopePaths: PluginSourceScopePaths;
+    dependencyHints: string[];
+    replaced: boolean;
+}
+interface PluginRemoveResult {
+    record: PluginSourceRecord;
+    scopePaths: PluginSourceScopePaths;
+    removedSourceDir: boolean;
+}
+interface PluginListResult {
+    records: PluginSourceRecord[];
+    scopes: PluginSourceScopePaths[];
+}
+declare function resolvePluginSourceScopePaths(scope: PluginInstallScope, opts?: {
+    workspaceRoot?: string;
+    globalRoot?: string;
+}): PluginSourceScopePaths;
+declare function readPluginSourceRecords(paths: PluginSourceScopePaths): PluginSourceRecord[];
+declare function readPluginSourceRecordsForRoots(opts: {
+    workspaceRoot: string;
+    globalRoot?: string;
+}): PluginSourceRecord[];
+declare function installPluginSource(opts: InstallPluginSourceOptions): PluginInstallResult;
+declare function listPluginSources(opts?: ListPluginSourcesOptions): PluginListResult;
+declare function removePluginSource(opts: RemovePluginSourceOptions): PluginRemoveResult;
+declare function formatPluginSourceList(result: PluginListResult): string;
+
+export { type InstallPluginSourceOptions, type ListPluginSourcesOptions, type PluginInstallResult, type PluginInstallScope, type PluginListResult, type PluginRemoveResult, type PluginSourceKind, type PluginSourceRecord, type PluginSourceScopePaths, type RemovePluginSourceOptions, formatPluginSourceList, installPluginSource, listPluginSources, readPluginSourceRecords, readPluginSourceRecordsForRoots, removePluginSource, resolvePluginSourceScopePaths };

package/dist/plugin-sources.js

@@ -0,0 +1,18 @@
+import {
+  formatPluginSourceList,
+  installPluginSource,
+  listPluginSources,
+  readPluginSourceRecords,
+  readPluginSourceRecordsForRoots,
+  removePluginSource,
+  resolvePluginSourceScopePaths
+} from "./chunk-6FD653KO.js";
+export {
+  formatPluginSourceList,
+  installPluginSource,
+  listPluginSources,
+  readPluginSourceRecords,
+  readPluginSourceRecordsForRoots,
+  removePluginSource,
+  resolvePluginSourceScopePaths
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-plugin-cli",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "Slim boring-ui plugin authoring CLI for workspace runtimes.",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,10 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./plugin-sources": {
+      "import": "./dist/plugin-sources.js",
+      "types": "./dist/plugin-sources.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "devDependencies": {