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

package/dist/bin.js

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

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

@@ -119,6 +119,28 @@ function validatePiPackages(issues, value) {
     }
   });
 }
+function validatePiSlashCommands(issues, value) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(issue("INVALID_FIELD", "pi.slashCommands", "pi.slashCommands must be an array when provided"));
+    return;
+  }
+  value.forEach((entry, index) => {
+    const field = `pi.slashCommands[${index}]`;
+    if (!isRecord(entry)) {
+      issues.push(issue("INVALID_FIELD", field, `${field} must be an object with name and description`));
+      return;
+    }
+    if (typeof entry.name !== "string" || entry.name.length === 0) {
+      issues.push(issue("INVALID_FIELD", `${field}.name`, `${field}.name must be a non-empty string (no leading slash)`));
+    } else if (entry.name.startsWith("/")) {
+      issues.push(issue("INVALID_FIELD", `${field}.name`, `${field}.name must not start with "/" \u2014 omit the slash`));
+    }
+    if (typeof entry.description !== "string" || entry.description.length === 0) {
+      issues.push(issue("INVALID_FIELD", `${field}.description`, `${field}.description must be a non-empty string`));
+    }
+  });
+}
 function validatePiField(issues, pi) {
   if (pi === void 0) return void 0;
   if (!isRecord(pi)) {
@@ -131,6 +153,7 @@ function validatePiField(issues, pi) {
   if (pi.systemPrompt !== void 0 && typeof pi.systemPrompt !== "string") {
     issues.push(issue("INVALID_FIELD", "pi.systemPrompt", "pi.systemPrompt must be a string when provided"));
   }
+  validatePiSlashCommands(issues, pi.slashCommands);
   return pi;
 }
 function validateBoringPluginManifest(raw) {

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

@@ -5,7 +5,7 @@ import {
   listPluginSources,
   removePluginSource,
   validateBoringPluginManifest
-} from "./chunk-6FD653KO.js";
+} from "./chunk-3WN35EV3.js";
 
 // src/server/index.ts
 import { join as join4, resolve as resolve4 } from "path";
@@ -161,6 +161,7 @@ function scaffoldPlugin(opts) {
   }
   const tplFront = join2(templatesDir, "front-canonical.tsx");
   const tplPackage = join2(templatesDir, "package-canonical.json");
+  const tplAgent = join2(templatesDir, "agent-canonical.ts");
   for (const tpl of [tplFront, tplPackage]) {
     if (!existsSync2(tpl)) {
       throw new Error(`canonical template missing: ${tpl}`);
@@ -181,6 +182,10 @@ function scaffoldPlugin(opts) {
 `);
   const frontSource = substitute(readFileSync2(tplFront, "utf8"), opts.name, label);
   write("front/index.tsx", frontSource);
+  if (existsSync2(tplAgent)) {
+    const agentSource = substitute(readFileSync2(tplAgent, "utf8"), opts.name, label);
+    write("agent/index.ts", agentSource);
+  }
   write(".gitignore", "# Machine-managed sidecars written by the boring-ui plugin runtime.\n.boring-signature.json\n");
   return { pluginDir, filesCreated };
 }
@@ -606,6 +611,7 @@ function parseCreateArgs(positionals) {
 // src/server/testPlugin.ts
 var DEFAULT_TIMEOUT_MS = 1e4;
 var POLL_MS = 500;
+var NO_BROWSER_GRACE_MS = 1500;
 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;
@@ -779,22 +785,25 @@ async function runPluginSelfTest(options) {
   let lastState = "missing";
   let lastStatus;
   let openErrors = [];
+  let openedAtLeastOnce = false;
   while (Date.now() - start <= timeoutMs) {
+    const now = Date.now();
+    if (!openedAtLeastOnce || now - lastOpenAt >= POLL_MS) {
+      openErrors = await openPanel({ baseUrl, headers, pluginId, panelId, panelInstanceId });
+      lastOpenAt = Date.now();
+      openedAtLeastOnce = openErrors.length === 0 || openedAtLeastOnce;
+    }
     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();
+    if (status.state === "no-browser-connected" && openedAtLeastOnce && Date.now() - lastOpenAt >= NO_BROWSER_GRACE_MS) {
+      return buildResult({ pluginId, workspaceId, revision, reloadErrors, panelId, panelInstanceId, state: "no-browser-connected", status: lastStatus });
     }
     await new Promise((resolve5) => setTimeout(resolve5, POLL_MS));
   }
   if (openErrors.length > 0) reloadErrors.push(...openErrors);
-  const finalState = lastState === "ready" || lastState === "error" ? lastState : "timeout";
+  const finalState = lastState === "ready" || lastState === "error" ? lastState : lastState === "no-browser-connected" && openedAtLeastOnce ? "no-browser-connected" : "timeout";
   return buildResult({ pluginId, workspaceId, revision, reloadErrors, panelId, panelInstanceId, state: finalState, status: lastStatus });
 }
 function buildResult(args) {

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   runPluginSelfTest,
   scaffoldPlugin,
   verifyPlugin
-} from "./chunk-HY4ZELTX.js";
+} from "./chunk-LWVRDO4C.js";
 import {
   formatPluginSourceList,
   installPluginSource,
@@ -17,7 +17,7 @@ import {
   readPluginSourceRecordsForRoots,
   removePluginSource,
   resolvePluginSourceScopePaths
-} from "./chunk-6FD653KO.js";
+} from "./chunk-3WN35EV3.js";
 export {
   createPlugin,
   findHintForError,

package/dist/plugin-sources.js

@@ -6,7 +6,7 @@ import {
   readPluginSourceRecordsForRoots,
   removePluginSource,
   resolvePluginSourceScopePaths
-} from "./chunk-6FD653KO.js";
+} from "./chunk-3WN35EV3.js";
 export {
   formatPluginSourceList,
   installPluginSource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-plugin-cli",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Slim boring-ui plugin authoring CLI for workspace runtimes.",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
     "@types/node": "^22.15.3",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.3"
+    "vitest": "^3.2.6"
   },
   "repository": {
     "type": "git",

package/templates/agent-canonical.ts

@@ -0,0 +1,45 @@
+// CANONICAL agent/index.ts for a boring-ui runtime plugin.
+// Registers a hot-reloadable Pi slash command for deterministic plugin activation.
+//
+// The command opens its panel through the in-process workspace UI bridge via
+// `openPanel` from "@hachej/boring-workspace/plugin" — the SAME path the agent's
+// own `exec_ui` tool uses. No BORING_UI_URL, no env vars, no HTTP self-call:
+// the bridge is already connected to the browser.
+
+import { NoWorkspaceUiBridgeError, notify, openPanel } from "@hachej/boring-workspace/plugin"
+
+const PLUGIN_ID = "<kebab-name>"
+const PANEL_ID = "<kebab-name>.panel"
+const PANEL_TITLE = "<Label>"
+const OPEN_COMMAND = "open-<kebab-name>"
+
+export default function (pi: any) {
+  // User-facing deterministic slash command. Add pi.registerTool(...) below
+  // when this plugin also needs an LLM-callable tool.
+  pi.registerCommand(OPEN_COMMAND, {
+    description: `Open the ${PANEL_TITLE} panel`,
+    handler: async () => {
+      try {
+        await openPanel({
+          id: `${PLUGIN_ID}.slash-open`,
+          component: PANEL_ID,
+          params: { source: `/${OPEN_COMMAND}` },
+        })
+        // Surfaces as a workspace toast (unlike Pi's ctx.ui.notify, which is a
+        // terminal notification that is swallowed in server/headless mode).
+        await notify(`Opened ${PANEL_TITLE}.`, "info")
+      } catch (error) {
+        if (error instanceof NoWorkspaceUiBridgeError) {
+          // Running outside a workspace agent (e.g. a bare Pi CLI). Nothing to
+          // open; rethrow so the caller logs a clear reason.
+          throw error
+        }
+        await notify(
+          `Could not open ${PANEL_TITLE}: ${error instanceof Error ? error.message : String(error)}`,
+          "error",
+        ).catch(() => {})
+        throw error
+      }
+    },
+  })
+}

package/templates/front-file-visualizer.tsx

@@ -0,0 +1,113 @@
+// CANONICAL file visualizer front/index.tsx for a boring-ui runtime plugin.
+// Recipe contract: the imports, surfaceResolvers shape, file fetch route, and
+// workspace-id header below are supported public API. Do not grep workspace
+// internals for these names unless `boring-ui-plugin test` fails. Change
+// FILE_EXT and parser/rendering for your file type.
+
+import React, { useEffect, useMemo, useState } from "react"
+import { definePlugin, WORKSPACE_OPEN_PATH_SURFACE_KIND, type PaneProps } from "@hachej/boring-workspace/plugin"
+import { useApiBaseUrl, useWorkspaceRequestId } from "@hachej/boring-workspace"
+
+const MAIN_PANEL_ID = "<kebab-name>.panel"
+const FILE_EXT = ".csv"
+
+interface FilePaneParams {
+  path?: string
+}
+
+function parseCsv(text: string): string[][] {
+  return text
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((row) => row.split(",").map((cell) => cell.trim()))
+}
+
+function FilePane({ params }: PaneProps<FilePaneParams>) {
+  const path = params?.path ?? ""
+  const apiBaseUrl = useApiBaseUrl()
+  const workspaceId = useWorkspaceRequestId()
+  const [text, setText] = useState("")
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!path) return
+    let cancelled = false
+    const url = `${apiBaseUrl}/api/v1/files/raw?path=${encodeURIComponent(path)}`
+    fetch(url, {
+      credentials: "include",
+      headers: workspaceId ? { "x-boring-workspace-id": workspaceId } : {},
+    })
+      .then((response) => {
+        if (!response.ok) throw new Error(`Failed to load ${path}: ${response.status}`)
+        return response.text()
+      })
+      .then((body) => { if (!cancelled) setText(body) })
+      .catch((err) => { if (!cancelled) setError(err instanceof Error ? err.message : String(err)) })
+    return () => { cancelled = true }
+  }, [apiBaseUrl, path, workspaceId])
+
+  const rows = useMemo(() => parseCsv(text), [text])
+  const headers = rows[0] ?? []
+  const dataRows = rows.slice(1)
+  const numericValues = dataRows
+    .map((row) => Number(row[1] ?? row[0]))
+    .filter((value) => Number.isFinite(value))
+  const max = Math.max(1, ...numericValues)
+
+  return (
+    <div className="flex h-full min-h-0 min-w-0 flex-col bg-background text-foreground">
+      <div className="border-b border-border px-4 py-3">
+        <div className="text-sm font-semibold"><Label></div>
+        <div className="text-xs text-muted-foreground">{path || `Open a ${FILE_EXT} file`}</div>
+      </div>
+      <div className="min-h-0 flex-1 overflow-auto p-4">
+        {error ? <div className="text-sm text-destructive">{error}</div> : null}
+        <table className="w-full border-collapse text-sm">
+          <thead>
+            <tr>{headers.map((header, index) => <th key={index} className="border border-border px-2 py-1 text-left">{header}</th>)}</tr>
+          </thead>
+          <tbody>
+            {dataRows.map((row, rowIndex) => (
+              <tr key={rowIndex}>{row.map((cell, cellIndex) => <td key={cellIndex} className="border border-border px-2 py-1">{cell}</td>)}</tr>
+            ))}
+          </tbody>
+        </table>
+        <svg className="mt-4 h-32 w-full overflow-visible" viewBox="0 0 320 120" role="img" aria-label="CSV value chart">
+          {numericValues.map((value, index) => {
+            const width = 280 / Math.max(1, numericValues.length)
+            const height = (value / max) * 100
+            return <rect key={index} x={10 + index * width} y={110 - height} width={Math.max(2, width - 2)} height={height} fill="currentColor" opacity="0.7" />
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+export default definePlugin({
+  id: "<kebab-name>",
+  label: "<Label>",
+  panels: [
+    { id: MAIN_PANEL_ID, label: "<Label>", component: FilePane },
+  ],
+  commands: [
+    { id: "<kebab-name>.open", title: "Open <Label>", panelId: MAIN_PANEL_ID },
+  ],
+  surfaceResolvers: [
+    {
+      id: "<kebab-name>.open-file",
+      kind: WORKSPACE_OPEN_PATH_SURFACE_KIND,
+      resolve: (request) => {
+        if (request.kind !== WORKSPACE_OPEN_PATH_SURFACE_KIND) return null
+        if (!request.target.endsWith(FILE_EXT)) return null
+        return {
+          id: `<kebab-name>:${request.target}`,
+          component: MAIN_PANEL_ID,
+          title: request.target.split("/").pop() ?? "<Label>",
+          params: { path: request.target },
+        }
+      },
+    },
+  ],
+})

package/templates/package-canonical.json

@@ -14,6 +14,10 @@
     "front": "front/index.tsx"
   },
   "pi": {
-    "systemPrompt": "<Label> plugin — describe what it does so the agent knows when to use it."
+    "systemPrompt": "<Label> plugin — describe what it does so the agent knows when to use it.",
+    "extensions": ["agent/index.ts"],
+    "slashCommands": [
+      { "name": "open-<kebab-name>", "description": "Open the <Label> panel" }
+    ]
   }
 }