@hachej/boring-ui-plugin-cli 0.1.40 → 0.1.42

package/README.md

@@ -0,0 +1,79 @@
+# @hachej/boring-ui-plugin-cli
+
+Plugin authoring CLI for the boring-ui workspace runtime. The binary is
+`boring-ui-plugin`; it is also bundled into `@hachej/boring-ui-cli` and reached
+as `boring-ui plugin <subcommand>`.
+
+It scaffolds, verifies, tests, and manages boring-ui plugins, and exports the
+plugin-source resolution helpers the CLI uses to discover plugins.
+
+## Two kinds of plugin
+
+| | `create` | `scaffold` |
+|--|----------|------------|
+| Output | npm-package plugin under `plugins/<name>/` (copied from `templates/plugin/`) | workspace runtime plugin under `<workspace>/.pi/extensions/<name>/` |
+| Build | has a build step (`tsup`), `workspace:*` deps | no build step, hot-reloadable via `/reload` |
+| Use for | app/internal publishable plugins | per-workspace plugins authored from inside the running UI |
+
+## 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]
+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>
+```
+
+- **status** — reports whether workspace-local plugin roots are enabled (driven
+  by `BORING_AGENT_WORKSPACE_LOCAL_PLUGIN_ROOTS`) and the resolved
+  `.pi/extensions` dir.
+- **verify** — validates plugin manifests on disk *without* a running server
+  (manifest validity + `boring.front` / `boring.server` / `pi.extensions` file
+  existence). It does not execute plugin code, so syntax errors only surface on
+  a real `/reload`. Prints hints for known errors and exits non-zero on failure.
+- **test** — drives a self-test against a running workspace server (default URL
+  inferred, override with `--url`) to catch panel render / front-import
+  failures that don't appear in the `/reload` banner.
+- **install / list / remove** — manage plugin *sources* in two scopes: `local`
+  (`<workspace>/.pi`, default) and `global` (`~/.pi/agent`). Sources can be a
+  local path, a git URL, or an npm spec. Dependencies are **not** installed for
+  you — run your package manager in the plugin folder, then `/reload` in the UI.
+
+Run `boring-ui-plugin` with no command for usage.
+
+## Plugin manifest
+
+Plugins are declared in `package.json` via two fields (`src/manifest.ts`):
+
+- `boring` — workspace/UI discovery: `front` (browser entry default-exporting a
+  `BoringFrontFactory`), `server` (backend entry), labels.
+- `pi` — agent/Pi runtime contributions: `extensions`, `skills`, prompt
+  fragments, Pi packages, and slash commands.
+
+## Programmatic API
+
+The package exports its building blocks for embedding hosts (e.g. the CLI):
+`runBoringUiPluginCli`, `createPlugin`, `scaffoldPlugin`, `verifyPlugin`,
+`runPluginSelfTest`, `installPluginSource` / `listPluginSources` /
+`removePluginSource`, and source-scope helpers
+(`resolvePluginSourceScopePaths`, `readPluginSourceRecords`) via the
+`./plugin-sources` subpath. See `src/index.ts` for the full surface.
+
+## Templates
+
+`templates/plugin/` is the canonical npm-package plugin shape copied by
+`create`; its [README](./templates/plugin/README.md) documents the front /
+server / shared layout and invariants. `templates/*-canonical.*` are the
+single-file canonical sources used by `scaffold`.
+
+## Docs
+
+- [`docs/README.md`](./docs/README.md) — architecture and internals.
+
+## License
+
+MIT

package/dist/bin.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   runBoringUiPluginCli
-} from "./chunk-PYNOFBR6.js";
-import "./chunk-3WN35EV3.js";
+} from "./chunk-4ZXW5O2M.js";
+import "./chunk-KTILPA2U.js";
 
 // src/bin.ts
 runBoringUiPluginCli().catch((error) => {

package/dist/{chunk-PYNOFBR6.js → chunk-4ZXW5O2M.js}

@@ -5,7 +5,7 @@ import {
   listPluginSources,
   removePluginSource,
   validateBoringPluginManifest
-} from "./chunk-3WN35EV3.js";
+} from "./chunk-KTILPA2U.js";
 
 // src/server/index.ts
 import { join as join4, resolve as resolve4 } from "path";
@@ -679,6 +679,11 @@ function collectRuntimeDiagnostics(pluginId, body) {
   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.frontError)) {
+    if (typeof plugin.frontError.revision === "number") revision = plugin.frontError.revision;
+    const message = typeof plugin.frontError.message === "string" ? plugin.frontError.message : "front module failed to load";
+    events.push(event("PLUGIN_FRONT_ERROR", message));
+  }
   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";
@@ -896,7 +901,8 @@ function handleScaffold(positionals) {
   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");
-  console.log("  6. after /reload, call the plugin_diagnostics tool to confirm no load errors \u2014 /reload reports plugin/skill errors there");
+  console.log("  6. after /reload, ALWAYS call the plugin_diagnostics tool AND re-run `boring-ui-plugin test <name>` \u2014 front import failures only show up there (source plugin-front / PLUGIN_FRONT_ERROR), not in the /reload banner");
+  console.log("  7. iterate (fix -> /reload -> plugin_diagnostics + test) until both are clean before reporting success");
 }
 function handleVerify(positionals) {
   const result = verifyPlugin(parseVerifyArgs(positionals));

package/dist/{chunk-3WN35EV3.js → chunk-KTILPA2U.js}

@@ -503,6 +503,14 @@ function readPluginSourceRecordsForRoots(opts) {
   const global = resolvePluginSourceScopePaths("global", opts);
   return [...readPluginSourceRecords(global), ...readPluginSourceRecords(local)];
 }
+function resolveRegisteredPluginSourceDirs(paths) {
+  return packageEntries(readPiSettings(paths.settingsPath)).flatMap((entry) => {
+    const source = packageEntrySource(entry);
+    if (!source) return [];
+    const rootDir = resolvePackageSourcePath(paths.baseDir, source);
+    return rootDir ? [{ source, rootDir }] : [];
+  });
+}
 function upsertPackageSource(paths, record) {
   const settings = readPiSettings(paths.settingsPath);
   const entries = packageEntries(settings);
@@ -621,6 +629,7 @@ export {
   resolvePluginSourceScopePaths,
   readPluginSourceRecords,
   readPluginSourceRecordsForRoots,
+  resolveRegisteredPluginSourceDirs,
   installPluginSource,
   listPluginSources,
   removePluginSource,

package/dist/index.d.ts

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

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   runPluginSelfTest,
   scaffoldPlugin,
   verifyPlugin
-} from "./chunk-PYNOFBR6.js";
+} from "./chunk-4ZXW5O2M.js";
 import {
   formatPluginSourceList,
   installPluginSource,
@@ -16,8 +16,9 @@ import {
   readPluginSourceRecords,
   readPluginSourceRecordsForRoots,
   removePluginSource,
-  resolvePluginSourceScopePaths
-} from "./chunk-3WN35EV3.js";
+  resolvePluginSourceScopePaths,
+  resolveRegisteredPluginSourceDirs
+} from "./chunk-KTILPA2U.js";
 export {
   createPlugin,
   findHintForError,
@@ -31,6 +32,7 @@ export {
   readPluginSourceRecordsForRoots,
   removePluginSource,
   resolvePluginSourceScopePaths,
+  resolveRegisteredPluginSourceDirs,
   runBoringUiPluginCli,
   runPluginSelfTest,
   scaffoldPlugin,

package/dist/plugin-sources.d.ts

@@ -63,9 +63,28 @@ declare function readPluginSourceRecordsForRoots(opts: {
     workspaceRoot: string;
     globalRoot?: string;
 }): PluginSourceRecord[];
+interface RegisteredPluginSourceDir {
+    /** Raw package source string as written in settings.json. */
+    source: string;
+    /** Absolute directory the source resolves to (may not exist). */
+    rootDir: string;
+}
+/**
+ * Resolve every local-path `packages` entry in the scope's settings.json
+ * to its directory WITHOUT validating the plugin root. Remote specs
+ * (npm:, git:, URLs) are skipped — their installed copies live under the
+ * scope's npm/git dirs, which hosts already scan directly.
+ *
+ * Unlike `readPluginSourceRecords`, broken entries are returned rather
+ * than dropped: hosts pass these dirs to the Boring plugin scanner with
+ * `registered: true`, so a deleted dir or stripped package.json surfaces
+ * as a preflight error in the plugin UI instead of the plugin silently
+ * vanishing.
+ */
+declare function resolveRegisteredPluginSourceDirs(paths: PluginSourceScopePaths): RegisteredPluginSourceDir[];
 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 };
+export { type InstallPluginSourceOptions, type ListPluginSourcesOptions, type PluginInstallResult, type PluginInstallScope, type PluginListResult, type PluginRemoveResult, type PluginSourceKind, type PluginSourceRecord, type PluginSourceScopePaths, type RegisteredPluginSourceDir, type RemovePluginSourceOptions, formatPluginSourceList, installPluginSource, listPluginSources, readPluginSourceRecords, readPluginSourceRecordsForRoots, removePluginSource, resolvePluginSourceScopePaths, resolveRegisteredPluginSourceDirs };

package/dist/plugin-sources.js

@@ -5,8 +5,9 @@ import {
   readPluginSourceRecords,
   readPluginSourceRecordsForRoots,
   removePluginSource,
-  resolvePluginSourceScopePaths
-} from "./chunk-3WN35EV3.js";
+  resolvePluginSourceScopePaths,
+  resolveRegisteredPluginSourceDirs
+} from "./chunk-KTILPA2U.js";
 export {
   formatPluginSourceList,
   installPluginSource,
@@ -14,5 +15,6 @@ export {
   readPluginSourceRecords,
   readPluginSourceRecordsForRoots,
   removePluginSource,
-  resolvePluginSourceScopePaths
+  resolvePluginSourceScopePaths,
+  resolveRegisteredPluginSourceDirs
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-plugin-cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Slim boring-ui plugin authoring CLI for workspace runtimes.",
   "license": "MIT",
   "type": "module",