@hachej/boring-ui-cli 0.1.40 → 0.1.42

package/README.md

@@ -7,237 +7,133 @@
 
 </div>
 
-**Turn an agent into an app — in one command.** Start a full IDE-style workbench pointed at your current directory: chat, file tree, editor, command palette. No clone. No database. No config.
+**Turn an agent into an app — in one command.** Start a full IDE-style workbench pointed at a folder: chat, file tree, editor, command palette, plugins. No clone, no database, no config.
 
 ```bash
 npx @hachej/boring-ui-cli
 ```
 
----
-
-## TL;DR
-
-**The Problem**: You want a coding agent in a browser IDE — but you don't want to clone a repo, set up Postgres, configure auth, or deploy anything. You just want to talk to an AI about your code.
-
-**The Solution**: `npx @hachej/boring-ui-cli` starts a full workbench locally, using your current directory as the workspace. It opens a browser tab with chat, file explorer, and panels. Zero setup, zero config, zero deploy.
-
-### Why Use @hachej/boring-ui-cli?
-
-| Feature | What It Does |
-|---------|--------------|
-| **Zero-config startup** | `npx @hachej/boring-ui-cli` — that's it. Opens your browser to a full agent workbench. |
-| **Simple auth** | Set `ANTHROPIC_API_KEY` in your environment. The agent runs with direct filesystem access to your cwd. |
-| **Full workspace** | Chat, file tree, editor panels, command palette — all running against your real directory. |
-| **No database** | Runs in-memory. State persists for the session. No external dependencies. |
-| **Customizable port + root** | `PORT=8080` and `BORING_AGENT_WORKSPACE_ROOT=/path` env vars for power users. |
+The binary is `boring-ui`.
 
 ---
 
-## Quick Example
+## Quick start
 
 ```bash
-# Navigate to any project
-cd /path/to/my-project
-
-# Start the CLI — opens browser at localhost:5200
+# Open the current folder as a workspace (browser opens at localhost:5200)
 npx @hachej/boring-ui-cli
 
-# With a custom port
-PORT=8080 npx @hachej/boring-ui-cli
-
-# Point at a specific directory
-BORING_AGENT_WORKSPACE_ROOT=/path/to/project npx @hachej/boring-ui-cli
+# Open a specific folder
+npx @hachej/boring-ui-cli ~/projects/foo
 
-# With API key
-ANTHROPIC_API_KEY=sk-ant-... npx @hachej/boring-ui-cli
+# Custom port / host
+npx @hachej/boring-ui-cli --port 8080 --host 127.0.0.1
 ```
 
-Once the browser opens, you can:
-```
-# In the chat box:
-"read my README and suggest improvements"
-"find all TypeScript files that import 'react'"
-"rewrite the test file to use vitest"
-```
+The CLI does not take an API key flag. On first run, if no LLM provider is
+configured it prints a guide: in another terminal run `pi` (or
+`npx @earendil-works/pi-coding-agent`) and use `/login` to add an API key or
+sign in to a subscription (Claude Pro/Max, ChatGPT Plus, Copilot). Credentials
+are saved at `~/.pi/agent/auth.json`; refresh the browser afterward.
 
 ---
 
-## Installation
-
-No installation needed — use `npx`:
+## Commands
 
-```bash
-npx @hachej/boring-ui-cli
 ```
-
-Or install globally for repeated use:
-
-```bash
-# npm
-npm install -g @hachej/boring-ui-cli
-
-# pnpm
-pnpm add -g @hachej/boring-ui-cli
-
-# Then just run:
-boring-ui
+boring-ui [folder] [options]            Open a single folder as a workspace (folder mode)
+boring-ui workspaces                    Start the multi-workspace hub (workspaces mode)
+boring-ui workspaces add <folder>       Register a folder as a saved workspace
+boring-ui workspaces list               List saved workspaces
+boring-ui workspaces remove <id>        Remove a saved workspace
+boring-ui workspaces rename <id> <name> Rename a saved workspace
+boring-ui plugin <subcommand> …         Plugin authoring (delegates to boring-ui-plugin)
 ```
 
-### From Source
+`boring-ui plugin …` forwards to `@hachej/boring-ui-plugin-cli`; run
+`boring-ui plugin` with no subcommand for its usage.
 
-```bash
-git clone https://github.com/hachej/boring-ui.git
-cd boring-ui && pnpm install
-pnpm --filter @hachej/boring-ui-cli build
-npx ./packages/cli/dist/index.js
-```
+### Options
 
-### Plugins
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p, --port <port>` | `5200` (or `$PORT`) | HTTP port |
+| `--host <host>` | `0.0.0.0` (or `$HOST`) | Listen host |
+| `-m, --mode <mode>` | `local` | `local` (no sandbox, full network) or `local-sandbox` (bwrap-isolated, no network, Linux only) |
+| `-h, --help` | | Show help |
 
-Plugin authoring operations live in the dedicated plugin CLI:
+### Environment variables
 
-```bash
-boring-ui-plugin create my-package-plugin --path plugins
-boring-ui-plugin scaffold my-runtime-plugin "$BORING_AGENT_WORKSPACE_ROOT"
-boring-ui-plugin verify my-runtime-plugin "$BORING_AGENT_WORKSPACE_ROOT"
-boring-ui-plugin test my-runtime-plugin
-```
+| Variable | Description |
+|----------|-------------|
+| `PORT`, `HOST` | Fallbacks for `--port` / `--host` |
+| `BORING_MODE` | Fallback for `--mode` |
+| `BORING_AGENT_WORKSPACE_ROOT` | Overrides the folder argument in folder mode |
+| `BORING_UI_WORKSPACES_PATH` | Path to the workspaces registry (default `~/.boring-ui/workspaces.yaml`) |
+| `BORING_USE_LOCAL_PACKAGES` | `1` to resolve the bundled plugin-cli runtime from the local monorepo checkout |
 
 ---
 
-## Authentication
+## Installation
 
-The CLI talks to Anthropic Claude via the agent runtime. You need a valid API key:
+No install needed — `npx @hachej/boring-ui-cli`. Or install globally:
 
 ```bash
-ANTHROPIC_API_KEY=sk-ant-... npx @hachej/boring-ui-cli
+npm install -g @hachej/boring-ui-cli   # or: pnpm add -g @hachej/boring-ui-cli
+boring-ui
 ```
 
-Only Anthropic Claude is wired in v1. The agent harness supports other providers via the `AgentHarness` interface, but only Anthropic is implemented.
-
----
-
-## Options
-
-| Environment Variable | Default | Description |
-|---------------------|---------|-------------|
-| `ANTHROPIC_API_KEY` | Yes | Anthropic API key. The agent requires a valid key to function. |
-| `PORT` | `5200` | Port to run the server on |
-| `BORING_AGENT_WORKSPACE_ROOT` | `.` (cwd) | Root directory for the workspace. The agent sees this as its filesystem. |
-| `BORING_AGENT_MODE` | `direct` | `direct` (no sandbox) or `local` (bwrap sandbox, Linux only) |
-| `BORING_AGENT_DEFAULT_MODEL_ID` | `claude-sonnet-4-6` | Default model to use |
-
----
-
-## Architecture
+### From source
 
+```bash
+git clone https://github.com/hachej/boring-ui.git
+cd boring-ui && pnpm install
+pnpm --filter @hachej/boring-ui-cli build:full   # builds front bundle + server
+node packages/cli/dist/index.js
 ```
-npx @hachej/boring-ui-cli
-  ├── Boot Fastify server (direct mode, in-memory)
-  ├── Serve frontend SPA (Vite-built bundle)
-  ├── Open browser → http://localhost:5200
-  └── Workspace = your current directory (or $BORING_AGENT_WORKSPACE_ROOT)
-```
-
-The CLI is the zero-config entry point to the full boring-ui stack. Under the hood it wires together:
-
-- `@hachej/boring-agent` — agent runtime, tools, chat UI
-- `@hachej/boring-workspace` — file tree, panels, command palette, plugins
-- `@hachej/boring-ui-kit` — shared UI primitives
-
-All running locally against your real filesystem with no database.
-
----
 
-## How @hachej/boring-ui-cli Compares
-
-| Feature | @hachej/boring-ui-cli | Claude Code | Codex CLI | Cursor |
-|---------|------------------------|-------------|-----------|--------|
-| Browser UI | ✅ Full IDE with panels | ❌ Terminal only | ❌ Terminal only | ✅ Desktop app |
-| File tree | ✅ Side panel | ❌ | ❌ | ✅ |
-| Zero setup | ✅ `npx` anywhere | ⚠️ Install + login | ⚠️ Install + login | ❌ Desktop app download |
-| Panel system | ✅ Dockview splittable panels | ❌ | ❌ | ❌ |
-| Plugin extensibility | ✅ Panels, commands, catalogs | ❌ | ❌ | ⚠️ Extensions |
-| Local filesystem | ✅ Direct access | ✅ | ✅ | ✅ |
-| Database required | ❌ None | ❌ | ❌ | ❌ |
-
-**When to use @hachej/boring-ui-cli:**
-- You want a browser-based coding agent with file tree and panels
-- You don't want to install anything — just `npx`
-- You want plugin extensibility (custom panels, data catalogs, etc.)
-
-**When it might not fit:**
-- You prefer terminal-only agent workflows (use Claude Code or Codex CLI)
-- You need multi-user auth, workspaces, or a database (use `@hachej/boring-core`)
-- You want a full desktop IDE with LSP, debugging, and git (use Cursor or VS Code)
-
----
-
-## Troubleshooting
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ANTHROPIC_API_KEY not set` | No API key | `export ANTHROPIC_API_KEY=sk-ant-...` before running |
-| `port already in use` | Port 5200 occupied | `PORT=5201 npx @hachej/boring-ui-cli` |
-| Browser doesn't open | `BROWSER=none` or no display | Manually navigate to `http://localhost:5200` |
-| Agent returns errors | Invalid API key | Verify your Anthropic API key is valid and has quota |
-| `workspace root not found` | `BORING_AGENT_WORKSPACE_ROOT` points to non-existent dir | Create the directory or unset the variable to use cwd |
+`build:full` is required from source: the server refuses to start without a
+built frontend under `public/`.
 
 ---
 
-## Limitations
+## Two modes
 
-- **In-memory only**: No database, no persistent workspaces. State is lost when the CLI exits.
-- **Single workspace**: Points at one directory. No multi-workspace switching.
-- **No auth management**: No user accounts, invites, or role-based access.
-- **Direct mode only**: No bwrap sandbox by default (use `BORING_AGENT_MODE=local` on Linux with bubblewrap installed).
-- **Not for production**: This is a developer tool, not a deployment target. Use `@hachej/boring-core` for multi-user apps.
-- **Only Anthropic Claude**: No OpenAI, Google, or other model providers wired in v1.
+- **Folder mode** (`boring-ui [folder]`) — one folder, one workspace. The fast
+  editor-launcher path, like `code .`.
+- **Workspaces mode** (`boring-ui workspaces`) — a persistent local hub serving
+  multiple folder-backed workspaces, with a workspace switcher in the UI. The
+  registry is a user-local YAML file, not a database.
 
----
+Both run a Fastify server that serves the prebuilt React/Vite SPA plus the agent
+and workspace API routes against your real filesystem. There is no database.
 
-## FAQ
+## Plugins
 
-**Q: Do I need to install anything first?**  
-A: No. `npx` downloads and runs the package on first use. Subsequent runs use the cached version.
+The CLI discovers plugins from Pi-shaped roots — `~/.pi/agent/extensions/*`
+(global) and `<workspace>/.pi/extensions/*` (workspace-local) — plus
+CLI-bundled defaults (e.g. `@hachej/boring-ask-user`). Authoring is handled by
+the bundled `boring-ui-plugin` CLI:
 
-**Q: What happens when I close the browser?**  
-A: The server keeps running. Stop it with `Ctrl+C` in the terminal.
-
-**Q: Can I use this with OpenAI models?**  
-A: Only Anthropic Claude is wired in v1. Additional providers may be supported in future versions.
-
-**Q: Is my code sent to the cloud?**  
-A: Yes — the agent sends file contents and chat messages to the LLM provider (e.g. Anthropic). The filesystem operations run locally on your machine.
-
-**Q: How is this different from `npx @hachej/boring-agent`?**  
-A: `@hachej/boring-ui-cli` ships the full workbench (file tree, editor, command palette, plugins). `@hachej/boring-agent` is just the agent + chat. The CLI is the batteries-included zero-config entry point.
+```bash
+boring-ui-plugin create <name> --path plugins   # npm-package plugin (build step)
+boring-ui-plugin scaffold <name>                 # workspace runtime plugin (.pi/extensions, hot-reload)
+boring-ui-plugin verify [name]
+boring-ui-plugin test <name>
+```
 
-**Q: Can I extend the CLI with plugins?**  
-A: Not directly in v1. The CLI uses the default agent + workspace configuration. For plugin extensibility, build a custom app using `@hachej/boring-workspace` + `@hachej/boring-core`.
+See `@hachej/boring-ui-plugin-cli` for the full plugin authoring workflow.
 
 ---
 
-## Building Something Bigger?
-
-`@hachej/boring-ui-cli` is the zero-config entry point. For a full app with:
-- Multi-user authentication
-- Persistent workspaces with Postgres
-- Email invites and password resets
-- Custom domain plugins
-
-See the [boring-ui monorepo](https://github.com/hachej/boring-ui) and its packages:
+## Documentation
 
-| Package | Purpose |
-|---------|---------|
-| `@hachej/boring-core` | Auth, DB, app factory, multi-user |
-| `@hachej/boring-workspace` | Plugin system, panels, layouts |
-| `@hachej/boring-agent` | Agent runtime, tools, chat UI |
-| `@hachej/boring-ui-kit` | Shared React UI primitives |
+- [`docs/README.md`](./docs/README.md) — architecture and key abstractions
+- [`docs/plans/archive/`](./docs/plans/archive/) — historical design plans (not current docs)
 
 ---
 
-*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
+*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings.
 
 ---
 

package/dist/server/modeApps.js

@@ -108,6 +108,7 @@ const RUNTIME_PLUGIN_TRUST_LABEL = "Trusted local runtime plugins";
 const RUNTIME_PLUGIN_TRUST_DESCRIPTION = "Loads plugin UI code from trusted local Pi extension roots through the CLI-owned runtime module host.";
 function createRuntimePluginDiagnosticsStore() {
   const byWorkspace = /* @__PURE__ */ new Map();
+  const frontErrorsByWorkspace = /* @__PURE__ */ new Map();
   function upsert(workspaceId, pluginId) {
     const workspace = byWorkspace.get(workspaceId) ?? /* @__PURE__ */ new Map();
     byWorkspace.set(workspaceId, workspace);
@@ -137,6 +138,10 @@ function createRuntimePluginDiagnosticsStore() {
         entry.lastErrorCode = void 0;
         entry.lastErrorMessage = void 0;
         entry.lastErrorStage = void 0;
+        const storedFrontError = frontErrorsByWorkspace.get(diagnostic.workspaceId)?.get(diagnostic.pluginId);
+        if (storedFrontError && diagnostic.revision !== void 0 && storedFrontError.revision < diagnostic.revision) {
+          frontErrorsByWorkspace.get(diagnostic.workspaceId)?.delete(diagnostic.pluginId);
+        }
       }
       if (diagnostic.stage === "cache") entry.lastRequestAt = now;
       if (diagnostic.stage === "transform" && diagnostic.outcome === "served") {
@@ -163,8 +168,22 @@ function createRuntimePluginDiagnosticsStore() {
     snapshot(workspaceId) {
       return [...byWorkspace.get(workspaceId)?.values() ?? []].map((entry) => ({ ...entry, recent: [...entry.recent] })).sort((a, b) => a.pluginId.localeCompare(b.pluginId));
     },
+    recordFrontError(workspaceId, error) {
+      const forWorkspace = frontErrorsByWorkspace.get(workspaceId) ?? /* @__PURE__ */ new Map();
+      frontErrorsByWorkspace.set(workspaceId, forWorkspace);
+      const existing = forWorkspace.get(error.pluginId);
+      if (existing && existing.revision > error.revision) return;
+      forWorkspace.set(error.pluginId, error);
+    },
+    clearFrontError(workspaceId, pluginId) {
+      frontErrorsByWorkspace.get(workspaceId)?.delete(pluginId);
+    },
+    frontErrors(workspaceId) {
+      return [...frontErrorsByWorkspace.get(workspaceId)?.values() ?? []].sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+    },
     disposeWorkspace(workspaceId) {
       byWorkspace.delete(workspaceId);
+      frontErrorsByWorkspace.delete(workspaceId);
     }
   };
 }
@@ -204,11 +223,33 @@ function buildRuntimePluginDiagnosticsResponse(args) {
       host: hostEntry
     });
   }
+  for (const frontError of args.frontErrors ?? []) {
+    const current = byPlugin.get(frontError.pluginId) ?? { id: frontError.pluginId };
+    byPlugin.set(frontError.pluginId, {
+      ...current,
+      frontError
+    });
+  }
   return {
     workspaceId: args.workspaceId,
     plugins: [...byPlugin.values()].sort((a, b) => a.id.localeCompare(b.id))
   };
 }
+function parseFrontErrorReport(pluginId, body) {
+  if (typeof body !== "object" || body === null) return null;
+  const record = body;
+  const message = typeof record.message === "string" ? record.message : "";
+  if (!pluginId || !message) return null;
+  const revisionRaw = record.revision;
+  const revision = typeof revisionRaw === "number" && Number.isFinite(revisionRaw) ? revisionRaw : 0;
+  return {
+    pluginId,
+    revision,
+    message,
+    ...typeof record.url === "string" ? { url: record.url } : {},
+    reportedAt: Date.now()
+  };
+}
 async function createFolderModeApp(opts) {
   const workspaceRoot = resolve(opts.workspaceRoot);
   const projectName = opts.projectName ?? (basename(workspaceRoot) || "workspace");
@@ -234,6 +275,10 @@ async function createFolderModeApp(opts) {
     logger: false,
     provisionWorkspace: false,
     runtimeProvisioning,
+    // The standalone CLI runs on the user's own machine, so ambient skill
+    // discovery (workspace + user-global ~/.pi skills) is on. The library
+    // default is off (withPiHarnessDefaults) to keep hosted agents isolated.
+    pi: { noSkills: false },
     // CLI-bundled internal plugins, resolved to absolute package dirs. This
     // drives the server-side install array (boot-time routes/agentTools);
     // additionalBoringPluginDirs only feeds the asset-manager scan.
@@ -257,9 +302,17 @@ async function createFolderModeApp(opts) {
       workspaceId: FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID,
       loaded: manager?.inspectLoaded() ?? [],
       errors: manager?.getErrors() ?? [],
-      host: diagnosticsStore.snapshot(FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID)
+      host: diagnosticsStore.snapshot(FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID),
+      frontErrors: diagnosticsStore.frontErrors(FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID)
     });
   });
+  app.post("/api/v1/agent-plugins/:id/front-error", async (request, reply) => {
+    const { id } = request.params;
+    const report = parseFrontErrorReport(id, request.body);
+    if (!report) return reply.code(400).send({ error: "invalid_front_error_report" });
+    diagnosticsStore.recordFrontError(FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID, report);
+    return reply.code(204).send();
+  });
   app.get("/api/v1/workspace/meta", async () => ({
     workspaceId: "default",
     workspaceRoot,
@@ -497,6 +550,14 @@ async function createWorkspacesModeApp(opts) {
           source: "plugin-preflight",
           message: `${error.code}: ${error.message} (${error.pluginDir})`,
           ...error.pluginId ? { pluginId: error.pluginId } : {}
+        })),
+        // Browser-reported front import failures: the server scan/transform is
+        // green, so without these a plugin that never renders looks healthy to
+        // the agent. The plugin_diagnostics tool consumes this array.
+        ...diagnosticsStore.frontErrors(workspace.id).map((error) => ({
+          source: "plugin-front",
+          message: error.message,
+          pluginId: error.pluginId
         }))
       ];
     },
@@ -504,6 +565,9 @@ async function createWorkspacesModeApp(opts) {
       const workspace = await requireWorkspace(workspaceId);
       await getLoadedPluginRuntime(workspace);
       return {
+        // Same policy as folder mode: the local hub runs on the user's own
+        // machine, so ambient skill discovery is on (library default is off).
+        noSkills: false,
         additionalSkillPaths: [join(workspaceRoot, ".agents", "skills")],
         packages: [],
         extensionPaths: [],
@@ -527,9 +591,18 @@ async function createWorkspacesModeApp(opts) {
       workspaceId: workspace.id,
       loaded: runtime.manager.inspectLoaded(),
       errors: runtime.manager.getErrors(),
-      host: diagnosticsStore.snapshot(workspace.id)
+      host: diagnosticsStore.snapshot(workspace.id),
+      frontErrors: diagnosticsStore.frontErrors(workspace.id)
     });
   });
+  app.post("/api/v1/agent-plugins/:id/front-error", async (request, reply) => {
+    const workspace = await workspaceFromRequest(request);
+    const { id } = request.params;
+    const report = parseFrontErrorReport(id, request.body);
+    if (!report) return reply.code(400).send({ error: "invalid_front_error_report" });
+    diagnosticsStore.recordFrontError(workspace.id, report);
+    return reply.code(204).send();
+  });
   app.get("/api/v1/agent-plugins", async (request) => {
     const workspace = await workspaceFromRequest(request);
     const runtime = await getLoadedPluginRuntime(workspace);

package/dist/server/pluginDiscovery.js

@@ -10,8 +10,8 @@ import {
   resolveDefaultWorkspacePluginPackagePaths
 } from "@hachej/boring-workspace/app/server";
 import {
-  readPluginSourceRecords,
-  resolvePluginSourceScopePaths
+  resolvePluginSourceScopePaths,
+  resolveRegisteredPluginSourceDirs
 } from "@hachej/boring-ui-plugin-cli";
 function resolveBoringUiCliPackageRoot() {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -41,8 +41,8 @@ function resolveCliBoringPluginDirs(workspaceRoot, options = {}) {
   const globalScope = resolvePluginSourceScopePaths("global", { globalRoot: globalAgentRoot });
   const localScope = resolvePluginSourceScopePaths("local", { workspaceRoot: resolvedWorkspaceRoot });
   const packageSources = [
-    ...readPluginSourceRecords(globalScope),
-    ...readPluginSourceRecords(localScope)
+    ...resolveRegisteredPluginSourceDirs(globalScope).map((dir) => ({ ...dir, scope: "global" })),
+    ...resolveRegisteredPluginSourceDirs(localScope).map((dir) => ({ ...dir, scope: "local" }))
   ];
   const includeDefaultPackages = options.includeDefaultPackages ?? true;
   const roots = [
@@ -56,6 +56,7 @@ function resolveCliBoringPluginDirs(workspaceRoot, options = {}) {
     ...packageSources.map((record) => ({
       rootDir: record.rootDir,
       kind: "external",
+      registered: true,
       ...record.scope === "local" ? { workspaceId: resolvedWorkspaceRoot } : {}
     }))
   ];

package/dist/server/pluginFrontRuntime.js

@@ -8,6 +8,7 @@ import react from "@vitejs/plugin-react";
 import { ErrorCode } from "@hachej/boring-agent/shared";
 import ts from "typescript";
 import { createServer } from "vite";
+import { init as initCjsLexer, parse as parseCjsExports } from "cjs-module-lexer";
 const PLUGIN_FRONT_RUNTIME_BASE_PATH = "/api/v1/agent-plugins/runtime";
 const HOST_VIRTUAL_SINGLETON_MODULES = [
   "react",
@@ -817,6 +818,86 @@ function runtimeAssetContentType(path) {
       return "application/octet-stream";
   }
 }
+const CJS_REQUIRE_PLACEHOLDER = "__boringCjsRequire";
+let cjsLexerReady;
+function ensureCjsLexer() {
+  if (!cjsLexerReady) cjsLexerReady = initCjsLexer();
+  return cjsLexerReady;
+}
+function hasEsmSyntax(sourceText) {
+  const sourceFile = ts.createSourceFile("cjs-probe.js", sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  let esm = false;
+  const visit = (node) => {
+    if (esm) return;
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isExportAssignment(node) || ts.isFunctionDeclaration(node) && node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) || (ts.isVariableStatement(node) || ts.isClassDeclaration(node)) && node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+      esm = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return esm;
+}
+function looksLikeCommonJs(sourceText) {
+  if (hasEsmSyntax(sourceText)) return false;
+  return /\b(?:module\.exports|exports\.|exports\[)/.test(sourceText) || /\brequire\s*\(/.test(sourceText);
+}
+function collectRequireSpecifiers(sourceFile) {
+  const specifiers = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require" && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])) {
+      specifiers.add(node.arguments[0].text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return [...specifiers];
+}
+async function cjsDependencyToEsm(sourceText, modulePath) {
+  await ensureCjsLexer();
+  const sourceFile = ts.createSourceFile(modulePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  const requireSpecifiers = collectRequireSpecifiers(sourceFile);
+  const importLines = [];
+  const requireMapEntries = [];
+  requireSpecifiers.forEach((specifier, index) => {
+    const binding = `${CJS_REQUIRE_PLACEHOLDER}_${index}`;
+    importLines.push(`import * as ${binding} from ${JSON.stringify(specifier)};`);
+    requireMapEntries.push(`  [${JSON.stringify(specifier)}]: ${binding},`);
+  });
+  let exportNames = [];
+  try {
+    const parsed = parseCjsExports(sourceText, modulePath);
+    exportNames = [...parsed.exports];
+  } catch {
+    exportNames = [];
+  }
+  const safeExportNames = exportNames.filter(
+    (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) && name !== "default" && name !== "__esModule"
+  );
+  const namedExportLines = safeExportNames.map(
+    (name) => `export const ${name} = ${JSON.stringify(name)} in __boringCjsExports ? __boringCjsExports[${JSON.stringify(name)}] : undefined;`
+  );
+  return [
+    ...importLines,
+    `const ${CJS_REQUIRE_PLACEHOLDER}_modules = {`,
+    ...requireMapEntries,
+    "};",
+    `function ${CJS_REQUIRE_PLACEHOLDER}(id) {`,
+    `  const ns = ${CJS_REQUIRE_PLACEHOLDER}_modules[id];`,
+    `  if (!ns) throw new Error("runtime plugin CommonJS require could not be resolved: " + id);`,
+    "  const def = ns.default;",
+    "  if (def !== undefined && (ns.__esModule || typeof def !== 'object' || Object.keys(ns).length === 1)) return def;",
+    "  return ns.default !== undefined ? ns.default : ns;",
+    "}",
+    "const __boringCjsModule = { exports: {} };",
+    `(function (module, exports, require) {`,
+    sourceText,
+    `})(__boringCjsModule, __boringCjsModule.exports, ${CJS_REQUIRE_PLACEHOLDER});`,
+    "const __boringCjsExports = __boringCjsModule.exports;",
+    "export default __boringCjsExports;",
+    ...namedExportLines
+  ].join("\n");
+}
 function runtimeAssetModuleCode(path, bytes) {
   const dataUrl = `data:${runtimeAssetContentType(path)};base64,${Buffer.from(bytes).toString("base64")}`;
   return `export default ${JSON.stringify(dataUrl)};`;
@@ -1093,6 +1174,13 @@ async function createPluginFrontRuntimeHost(options = {}) {
               return runtimeAssetModuleCode(resolvedPath2, await readFile(resolvedPath2));
             }
             const sourceText2 = await readFile(resolvedPath2, "utf8");
+            const extension = extname(resolvedPath2).toLowerCase();
+            const isCommonJs = extension === ".cjs" || extension !== ".mjs" && looksLikeCommonJs(sourceText2);
+            if (isCommonJs) {
+              const interop = await cjsDependencyToEsm(sourceText2, resolvedPath2);
+              validateSourceImports(interop, resolvedPath2, basePath);
+              return interop;
+            }
             validateSourceImports(sourceText2, resolvedPath2, basePath);
             return sourceText2;
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Turn an agent into an app",
   "license": "MIT",
   "type": "module",
@@ -15,15 +15,16 @@
     "@fastify/compress": "^8.3.1",
     "@fastify/static": "^9.1.1",
     "@vitejs/plugin-react": "^4.0.0",
+    "cjs-module-lexer": "^2.0.0",
     "fastify": "^5.4.0",
     "lucide-react": "^1.8.0",
     "typescript": "^5.8.3",
     "vite": "^6.0.0",
-    "@hachej/boring-agent": "0.1.40",
-    "@hachej/boring-ui-kit": "0.1.40",
-    "@hachej/boring-ask-user": "0.1.40",
-    "@hachej/boring-ui-plugin-cli": "0.1.40",
-    "@hachej/boring-workspace": "0.1.40"
+    "@hachej/boring-agent": "0.1.42",
+    "@hachej/boring-ask-user": "0.1.42",
+    "@hachej/boring-workspace": "0.1.42",
+    "@hachej/boring-ui-kit": "0.1.42",
+    "@hachej/boring-ui-plugin-cli": "0.1.42"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.0",