@hachej/boring-ui-cli 0.1.16 → 0.1.18

package/README.md

@@ -92,6 +92,14 @@ pnpm --filter @hachej/boring-ui-cli build
 npx ./packages/cli/dist/index.js
 ```
 
+### Scaffold a Plugin
+
+```bash
+boring-ui plugin create my-plugin --path plugins
+```
+
+This copies the bundled plugin template from `templates/plugin/`, renames the sample identifiers, and creates `plugins/my-plugin`.
+
 ---
 
 ## Authentication

package/dist/server/cli.js

@@ -1,16 +1,37 @@
 #!/usr/bin/env node
 import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { basename, isAbsolute, join, resolve } from "node:path";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 import { createLocalWorkspaceRegistry } from "./localWorkspaces.js";
+import { scaffoldPlugin } from "./scaffoldPlugin.js";
+import { findHintForError, formatVerifyResult, verifyPlugin } from "./verifyPlugin.js";
 const MODE_MAP = {
   "local": "direct",
   // no sandbox, full network access
   "local-sandbox": "local"
   // bwrap isolated, no network (Linux only)
 };
+const require2 = createRequire(import.meta.url);
+const CLI_VERSION = (() => {
+  try {
+    const pkg = require2("../../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
 function httpError(message, statusCode) {
   const error = new Error(message);
   error.statusCode = statusCode;
@@ -87,7 +108,8 @@ const AUTH_GUIDE = [
   "  Credentials are saved at ~/.pi/agent/auth.json. Then refresh the browser.",
   ""
 ].join("\n");
-function checkAuth() {
+async function checkAuth() {
+  const { AuthStorage, ModelRegistry } = await import("@mariozechner/pi-coding-agent");
   const authStorage = AuthStorage.create();
   const registry = ModelRegistry.create(authStorage);
   return registry.getAvailable().length;
@@ -95,7 +117,7 @@ function checkAuth() {
 async function startFolderMode(opts) {
   const workspaceRoot = process.env.BORING_AGENT_WORKSPACE_ROOT ?? resolve(opts.folderArg ?? process.cwd());
   const projectName = basename(resolve(workspaceRoot)) || "workspace";
-  const modelCount = checkAuth();
+  const modelCount = await checkAuth();
   console.log(`
 ${projectName}`);
   console.log(`  workspace  ${workspaceRoot}`);
@@ -111,7 +133,8 @@ ${projectName}`);
   });
   app.get("/api/v1/workspace/meta", async () => ({
     workspaceRoot,
-    projectName
+    projectName,
+    version: CLI_VERSION
   }));
   await registerStatic(app, opts.publicDir);
   await app.listen({ port: opts.port, host: opts.host });
@@ -186,7 +209,7 @@ async function startWorkspacesMode(opts) {
     getWorkspaceId: async (request) => (await workspaceFromRequest(request)).id,
     getWorkspaceRoot: async (workspaceId) => (await requireWorkspace(workspaceId)).path,
     getSessionNamespace: async ({ workspaceId }) => `local-workspace-${workspaceId}`,
-    getResourceLoaderOptions: async ({ workspaceRoot }) => ({
+    getPi: async ({ workspaceRoot }) => ({
       additionalSkillPaths: [join(workspaceRoot, ".agents", "skills")]
     }),
     getExtraTools: async ({ workspaceId, workspaceRoot, workspaceFsCapability }) => [
@@ -200,7 +223,8 @@ async function startWorkspacesMode(opts) {
   });
   app.get("/api/v1/workspace/meta", async () => ({
     projectName: "Boring UI",
-    workspacesMode: true
+    workspacesMode: true,
+    version: CLI_VERSION
   }));
   await registerStatic(app, opts.publicDir);
   await app.listen({ port: opts.port, host: opts.host });
@@ -215,9 +239,112 @@ Boring UI`);
   console.log(`
   ${initialUrl}
 `);
-  if (checkAuth() === 0) console.log(AUTH_GUIDE);
+  if (await checkAuth() === 0) console.log(AUTH_GUIDE);
   openBrowser(initialUrl);
 }
+function findRepoRoot(from) {
+  let current = from;
+  while (true) {
+    if (existsSync(join(current, "pnpm-workspace.yaml"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function walkDir(dir, base, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry === ".git" || entry === "dist") continue;
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkDir(fullPath, base, out);
+      continue;
+    }
+    out.push(relative(base, fullPath));
+  }
+  return out;
+}
+function replaceInFile(filePath, replacements) {
+  let content = readFileSync(filePath, "utf8");
+  for (const [from, to] of Object.entries(replacements)) {
+    content = content.replaceAll(from, to);
+  }
+  writeFileSync(filePath, content, "utf8");
+}
+async function handlePluginCommand(opts) {
+  const subcommand = opts.positionals[1];
+  if (subcommand !== "create") {
+    console.log("Usage: boring-ui plugin create <name> [--path <dir>]");
+    console.log("");
+    console.log("Scaffold a new plugin from the template.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>        Plugin name (e.g. my-plugin)");
+    console.log("  --path        Parent directory for the new plugin (default: plugins/)");
+    return;
+  }
+  const name = opts.positionals[2];
+  if (!name) throw new Error("usage: boring-ui plugin create <name>");
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = resolve(__dirname, "..", "..");
+  const templateDir = join(packageRoot, "templates", "plugin");
+  if (!existsSync(templateDir)) {
+    throw new Error(
+      `Plugin template not found at ${templateDir}.
+This build may not include the plugin template.`
+    );
+  }
+  const repoRoot = findRepoRoot(process.cwd());
+  const customPath = opts.args.path;
+  const targetParent = customPath ? resolve(customPath) : join(repoRoot ?? process.cwd(), "plugins");
+  const targetDir = join(targetParent, name);
+  if (existsSync(targetDir)) {
+    throw new Error(`Directory already exists: ${targetDir}`);
+  }
+  const id = name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "");
+  if (!id) throw new Error(`invalid plugin name: ${name}`);
+  const symbolBase = id.replace(/-plugin$/, "") || id;
+  const pascalBase = symbolBase.split(/[-_]+/).map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1)).join("");
+  const camelBase = pascalBase.charAt(0).toLowerCase() + pascalBase.slice(1);
+  const upperBase = symbolBase.replace(/-/g, "_").toUpperCase();
+  console.log(`Scaffolding plugin "${id}" at ${targetDir}`);
+  mkdirSync(targetParent, { recursive: true });
+  cpSync(templateDir, targetDir, { recursive: true });
+  const files = walkDir(targetDir, targetDir);
+  const pkgName = `@hachej/boring-${id}`;
+  for (const file of files) {
+    const fullPath = join(targetDir, file);
+    replaceInFile(fullPath, {
+      "@hachej/boring-plugin-template": pkgName,
+      "sample-plugin": id,
+      "sample-panel": `${id}-panel`,
+      "sample.open": `${id}.open`,
+      "sample:": `${id}:`,
+      '"sample"': `"${id}"`,
+      "SAMPLE": upperBase,
+      "Sample": pascalBase,
+      "sampleSurfaceResolver": `${camelBase}SurfaceResolver`,
+      "samplePanel": `${camelBase}Panel`
+    });
+    if (file.includes("samplePlugin")) {
+      const newFile = file.replace(/samplePlugin/g, `${camelBase}Plugin`);
+      const oldPath = join(targetDir, file);
+      const newPath = join(targetDir, newFile);
+      if (oldPath !== newPath) {
+        mkdirSync(dirname(newPath), { recursive: true });
+        renameSync(oldPath, newPath);
+      }
+    }
+  }
+  console.log("");
+  console.log(`\u2713 Created plugin \`${id}\` at ${relative(process.cwd(), targetDir)}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${relative(process.cwd(), targetDir)}`);
+  console.log("  pnpm install");
+  console.log(`  pnpm --filter ${pkgName} typecheck`);
+  console.log(`  pnpm --filter ${pkgName} test`);
+}
 async function handleWorkspacesCommand(opts) {
   const registry = createLocalWorkspaceRegistry();
   const subcommand = opts.positionals[1];
@@ -266,7 +393,8 @@ async function runCli(options) {
       port: { type: "string", short: "p" },
       host: { type: "string" },
       mode: { type: "string", short: "m" },
-      name: { type: "string", short: "n" }
+      name: { type: "string", short: "n" },
+      path: { type: "string" }
     },
     allowPositionals: true,
     strict: false
@@ -286,6 +414,13 @@ async function runCli(options) {
     cliMode,
     mode
   };
+  if (positionals[0] === "plugin") {
+    await handlePluginCommand({
+      positionals,
+      args: { path: args.path }
+    });
+    return;
+  }
   if (positionals[0] === "workspaces") {
     await handleWorkspacesCommand({
       ...base,
@@ -294,11 +429,69 @@ async function runCli(options) {
     });
     return;
   }
+  if (positionals[0] === "scaffold-plugin") {
+    handleScaffoldPluginCommand({ positionals });
+    return;
+  }
+  if (positionals[0] === "verify-plugin") {
+    handleVerifyPluginCommand({ positionals });
+    return;
+  }
   await startFolderMode({
     ...base,
     folderArg: positionals[0]
   });
 }
+function defaultWorkspaceRoot() {
+  return process.env.BORING_AGENT_WORKSPACE_ROOT ?? process.cwd();
+}
+function handleVerifyPluginCommand(opts) {
+  const maybeName = opts.positionals[1];
+  const maybeWorkspace = opts.positionals[2];
+  const looksLikePath = maybeName && (maybeName.includes("/") || maybeName.startsWith("."));
+  const name = looksLikePath ? void 0 : maybeName;
+  const workspaceRoot = resolve(maybeWorkspace ?? (looksLikePath ? maybeName : defaultWorkspaceRoot()));
+  const result = verifyPlugin({ workspaceRoot, ...name ? { name } : {} });
+  console.log(formatVerifyResult(result));
+  if (!result.ok) {
+    const hints = [];
+    for (const outcome of result.outcomes) {
+      for (const err of outcome.errors) {
+        const hint = findHintForError(err);
+        if (hint) hints.push(`  hint (${outcome.id}): ${hint}`);
+      }
+    }
+    if (hints.length > 0) {
+      console.log("");
+      console.log("Suggestions:");
+      for (const hint of hints) console.log(hint);
+    }
+    process.exit(1);
+  }
+}
+function handleScaffoldPluginCommand(opts) {
+  const name = opts.positionals[1];
+  if (!name) {
+    throw new Error("usage: boring-ui scaffold-plugin <name> [workspace]");
+  }
+  const workspaceRoot = resolve(opts.positionals[2] ?? defaultWorkspaceRoot());
+  const result = scaffoldPlugin({ name, workspaceRoot });
+  console.log(`scaffolded ${name}`);
+  console.log(`  dir   ${result.pluginDir}`);
+  for (const file of result.filesCreated) {
+    console.log(`  +     ${file}`);
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  1. edit front/index.tsx for UI panels/commands/resolvers`);
+  console.log(`  2. add pi.extensions / skills for hot-reloadable agent behavior`);
+  console.log(`  3. bash \`boring-ui verify-plugin\` \u2014 confirms manifests + files are valid`);
+  console.log(`  4. ask the user: /reload`);
+  console.log("");
+  console.log("Advanced server integration:");
+  console.log("  boring.server is boot-time/static composition only. It is NOT hot-registered");
+  console.log("  by /reload for .pi/extensions user plugins; use Pi extensions for agent tools.");
+}
 export {
   registerStatic,
   runCli

package/dist/server/scaffoldPlugin.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function scaffoldPlugin(opts) {
+  if (!KEBAB_RE.test(opts.name)) {
+    throw new Error(
+      `invalid plugin name "${opts.name}" \u2014 must be kebab-case (e.g. "my-plugin")`
+    );
+  }
+  const workspaceRoot = resolve(opts.workspaceRoot);
+  const pluginDir = join(workspaceRoot, ".pi", "extensions", opts.name);
+  mkdirSync(join(workspaceRoot, ".pi", "extensions"), { recursive: true });
+  try {
+    mkdirSync(pluginDir, { recursive: false });
+  } catch (error) {
+    const code = error.code;
+    if (code === "EEXIST") {
+      throw new Error(`plugin already exists at ${pluginDir}`);
+    }
+    throw error;
+  }
+  const templatesDir = opts.templatesDir ?? resolveBundledTemplatesDir();
+  if (!templatesDir) {
+    throw new Error(
+      "could not locate bundled CLI templates \u2014 pass `templatesDir` explicitly. (this usually indicates a broken @hachej/boring-ui-cli install)"
+    );
+  }
+  const tplFront = join(templatesDir, "front-canonical.tsx");
+  const tplPackage = join(templatesDir, "package-canonical.json");
+  for (const tpl of [tplFront, tplPackage]) {
+    if (!existsSync(tpl)) {
+      throw new Error(`canonical template missing: ${tpl}`);
+    }
+  }
+  const label = labelFromName(opts.name);
+  const filesCreated = [];
+  const write = (relPath, contents) => {
+    const target = join(pluginDir, relPath);
+    mkdirSync(join(target, ".."), { recursive: true });
+    writeFileSync(target, contents, "utf8");
+    filesCreated.push(target);
+  };
+  const pkgRaw = JSON.parse(readFileSync(tplPackage, "utf8"));
+  delete pkgRaw._doc_;
+  const pkgJson = substitute(JSON.stringify(pkgRaw, null, 2), opts.name, label);
+  write("package.json", `${pkgJson}
+`);
+  const frontSource = substitute(readFileSync(tplFront, "utf8"), opts.name, label);
+  write("front/index.tsx", frontSource);
+  write(".gitignore", "# Machine-managed sidecars written by the boring-ui plugin runtime.\n.boring-signature.json\n");
+  return { pluginDir, filesCreated };
+}
+function labelFromName(name) {
+  return name.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function substitute(source, name, label) {
+  const paneName = `${pascalCase(name)}Pane`;
+  return source.replaceAll("<kebab-name>", name).replaceAll("&lt;kebab-name&gt;", name).replaceAll("<Label>", label).replaceAll(/\bMyPane\b/g, paneName);
+}
+function pascalCase(name) {
+  return name.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function resolveBundledTemplatesDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidate = resolve(here, "..", "..", "templates");
+  return existsSync(candidate) ? candidate : void 0;
+}
+export {
+  scaffoldPlugin
+};

package/dist/server/verifyPlugin.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import {
+  isSafePluginRelativePath,
+  validateBoringPluginManifest
+} from "@hachej/boring-workspace/plugin";
+function pluginFileSignature(path) {
+  if (!path || !existsSync(path)) return "missing";
+  const stat = statSync(path);
+  return `${stat.mtimeMs}:${stat.size}`;
+}
+function readPluginSignatureCache(pluginRootDir) {
+  const path = join(pluginRootDir, ".boring-signature.json");
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  if (obj.version !== 1) return null;
+  const sig = obj.serverSignature;
+  if (sig !== null && typeof sig !== "string") return null;
+  const loadedAt = typeof obj.loadedAt === "number" ? obj.loadedAt : 0;
+  return { version: 1, serverSignature: sig, loadedAt };
+}
+function verifyPlugin(opts) {
+  const workspaceRoot = resolve(opts.workspaceRoot);
+  const extensionsDir = join(workspaceRoot, ".pi", "extensions");
+  if (!existsSync(extensionsDir)) {
+    return {
+      outcomes: [],
+      ok: true,
+      extensionsDir,
+      extensionsDirMissing: true
+    };
+  }
+  const targets = [];
+  if (opts.name) {
+    const dir = join(extensionsDir, opts.name);
+    if (!existsSync(dir)) {
+      return {
+        outcomes: [
+          { id: opts.name, dir, ok: false, errors: [`plugin directory not found: ${dir}`], warnings: [] }
+        ],
+        ok: false,
+        extensionsDir,
+        extensionsDirMissing: false
+      };
+    }
+    targets.push(dir);
+  } else {
+    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".") || entry.name.startsWith("preflight-")) continue;
+      targets.push(join(extensionsDir, entry.name));
+    }
+  }
+  const outcomes = targets.map((dir) => verifySinglePlugin(dir));
+  return {
+    outcomes,
+    ok: outcomes.every((o) => o.ok),
+    extensionsDir,
+    extensionsDirMissing: false
+  };
+}
+function isInsideRoot(rootReal, targetReal) {
+  const rel = relative(rootReal, targetReal);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function resolveExistingContainedPath(pluginDir, value, field) {
+  if (!isSafePluginRelativePath(value)) {
+    return { path: null, error: `${field} must be a safe relative path inside the plugin root: ${JSON.stringify(value)}` };
+  }
+  const abs = resolve(pluginDir, value);
+  if (!existsSync(abs)) return { path: null, error: `${field} points at "${value}" but that file does not exist (looked at ${abs})` };
+  const rootReal = realpathSync(pluginDir);
+  const targetReal = realpathSync(abs);
+  if (!isInsideRoot(rootReal, targetReal)) {
+    return { path: null, error: `${field} points at "${value}" but resolves outside the plugin root (looked at ${abs})` };
+  }
+  return { path: targetReal };
+}
+function verifySinglePlugin(pluginDir) {
+  const id = pluginDir.split(/[\\/]/).pop() ?? "<unknown>";
+  const errors = [];
+  const warnings = [];
+  const pkgPath = join(pluginDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { id, dir: pluginDir, ok: false, errors: ["package.json missing"], warnings };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { id, dir: pluginDir, ok: false, errors: [`package.json is not valid JSON: ${message}`], warnings };
+  }
+  const result = validateBoringPluginManifest(parsed);
+  if (!result.valid) {
+    for (const issue of result.issues) errors.push(formatIssue(issue));
+    return { id, dir: pluginDir, ok: false, errors, warnings };
+  }
+  const manifest = result.packageJson;
+  const boring = manifest.boring;
+  if (boring?.front) {
+    const resolved = resolveExistingContainedPath(pluginDir, boring.front, "boring.front");
+    if (resolved.error) errors.push(resolved.error);
+  }
+  let serverPathAbs = null;
+  if (typeof boring?.server === "string") {
+    const resolved = resolveExistingContainedPath(pluginDir, boring.server, "boring.server");
+    if (resolved.error) {
+      errors.push(resolved.error);
+    } else {
+      serverPathAbs = resolved.path;
+      warnings.push(
+        "boring.server file is valid, but workspace server entries are boot-time/static composition only. /reload does not import or register .pi/extensions server routes/agentTools; restart the workspace with this package passed via defaultPluginPackages or explicit plugins to activate server code."
+      );
+    }
+  }
+  const cache = readPluginSignatureCache(pluginDir);
+  if (cache) {
+    const currentServerSig = serverPathAbs ? pluginFileSignature(serverPathAbs) : null;
+    const cachedSig = cache.serverSignature;
+    if (cachedSig !== currentServerSig) {
+      warnings.push(
+        "server file changed since the workspace last loaded this plugin \u2014 /reload will hot-swap the front, but routes and agent tools stay on the previously loaded code. Stop and restart the workspace process (Ctrl-C, then re-run your dev command) to pick up the new code."
+      );
+    }
+  }
+  const piExt = manifest.pi?.extensions;
+  if (Array.isArray(piExt)) {
+    for (const ext of piExt) {
+      if (typeof ext !== "string") continue;
+      const resolved = resolveExistingContainedPath(pluginDir, ext, "pi.extensions entry");
+      if (resolved.error) errors.push(resolved.error);
+    }
+  }
+  const piSkills = manifest.pi?.skills;
+  if (Array.isArray(piSkills)) {
+    for (const skill of piSkills) {
+      if (typeof skill !== "string") continue;
+      const resolved = resolveExistingContainedPath(pluginDir, skill, "pi.skills entry");
+      if (resolved.error) errors.push(resolved.error);
+    }
+  }
+  return { id, dir: pluginDir, ok: errors.length === 0, errors, warnings };
+}
+function formatIssue(issue) {
+  return `${issue.code}: ${issue.field}: ${issue.message}`;
+}
+function formatVerifyResult(result) {
+  if (result.extensionsDirMissing) {
+    return [
+      `WARNING \u2014 no plugins to verify. Scanned: ${result.extensionsDir} (directory does not exist).`,
+      "",
+      "If you just wrote a plugin: check that you put it under THIS workspace's `.pi/extensions/` and not a different cwd. The scanned path above is `<cwd>/.pi/extensions/`."
+    ].join("\n");
+  }
+  if (result.outcomes.length === 0) {
+    return [
+      `WARNING \u2014 scanned ${result.extensionsDir} but found NO plugin directories.`,
+      "",
+      "If you just wrote a plugin: it is NOT in this dir. Either you wrote to a different `.pi/extensions/` (check your cwd), or the dir name starts with `.` / `preflight-` (skipped)."
+    ].join("\n");
+  }
+  const lines = [];
+  const failures = result.outcomes.filter((o) => !o.ok);
+  const withWarnings = result.outcomes.filter((o) => o.warnings.length > 0);
+  if (failures.length === 0) {
+    lines.push(`OK \u2014 ${result.outcomes.length} plugin(s) have valid manifests + present files. (scanned ${result.extensionsDir})`);
+    for (const outcome of result.outcomes) {
+      const tag = outcome.warnings.length > 0 ? "\u26A0" : "\u2713";
+      lines.push(`  ${tag} ${outcome.id}`);
+      for (const w of outcome.warnings) {
+        lines.push(`      WARN: ${w}`);
+      }
+    }
+    lines.push("");
+    if (withWarnings.length > 0) {
+      const n = withWarnings.length;
+      lines.push(`Manifests are valid, but ${n} plugin${n === 1 ? "" : "s"} need a workspace restart (NOT just /reload) to pick up server-side changes \u2014 see WARN lines above.`);
+      lines.push("");
+    }
+    lines.push("Note: this validator does NOT execute plugin code. Front/Pi syntax / type / runtime errors surface on /reload; boring.server files require static composition plus a process restart.");
+  } else {
+    lines.push(`FAILED \u2014 ${failures.length} of ${result.outcomes.length} plugin(s) have errors.  (scanned ${result.extensionsDir})`);
+    lines.push("");
+    for (const outcome of result.outcomes) {
+      if (outcome.ok) {
+        const tag = outcome.warnings.length > 0 ? "\u26A0" : "\u2713";
+        lines.push(`  ${tag} ${outcome.id}`);
+        for (const w of outcome.warnings) {
+          lines.push(`      WARN: ${w}`);
+        }
+      } else {
+        lines.push(`  \u2717 ${outcome.id}  (${outcome.dir})`);
+        for (const err of outcome.errors) {
+          lines.push(`      ${err}`);
+        }
+        for (const w of outcome.warnings) {
+          lines.push(`      WARN: ${w}`);
+        }
+      }
+    }
+    lines.push("");
+    lines.push("Fix the errors above and run `boring-ui verify-plugin` again. Once it reports OK, ask the user to run /reload for front/Pi assets; boring.server changes require static composition plus restart.");
+  }
+  return lines.join("\n");
+}
+const COMMON_MISTAKE_HINTS = [
+  {
+    pattern: /boring\.server must be a safe relative path or false/i,
+    hint: 'Set `boring.server` to a string path like "server/index.ts", or to `false` (or omit the field). It is NOT a boolean true. For hot-reloadable agent behavior in .pi/extensions, prefer pi.extensions instead.'
+  },
+  {
+    pattern: /package\.json manifest must be an object/i,
+    hint: "package.json must parse as a JSON object \u2014 check for trailing commas or unquoted keys."
+  }
+];
+function findHintForError(message) {
+  for (const m of COMMON_MISTAKE_HINTS) {
+    if (m.pattern.test(message)) return m.hint;
+  }
+  return void 0;
+}
+export {
+  findHintForError,
+  formatVerifyResult,
+  verifyPlugin
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Turn an agent into an app",
   "license": "MIT",
   "type": "module",
@@ -9,15 +9,16 @@
   },
   "files": [
     "dist/",
-    "public/"
+    "public/",
+    "templates/"
   ],
   "dependencies": {
     "@fastify/static": "^8.0.0",
     "fastify": "^5.4.0",
     "lucide-react": "^1.8.0",
-    "@hachej/boring-agent": "0.1.16",
-    "@hachej/boring-workspace": "0.1.16",
-    "@hachej/boring-ui-kit": "0.1.16"
+    "@hachej/boring-agent": "0.1.18",
+    "@hachej/boring-workspace": "0.1.18",
+    "@hachej/boring-ui-kit": "0.1.18"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.0",