@polderlabs/bizar 4.4.10 → 4.4.11

package/bizar-dash/src/server/mods-loader.mjs

@@ -178,6 +178,138 @@ export const modsLoader = {
     mkdirSync(MODS_DIR, { recursive: true });
   },
 
+  /**
+   * v4.4.11 — Validate an installed mod without mounting it.
+   *
+   * Runs after a copy (in `installFromPath` + `installFromRegistry`) and
+   * before the install is reported as successful. Returns a structured
+   * `{ ok, errors, warnings }` so callers (the API + the CLI + the
+   * provisioner) can surface failures consistently.
+   *
+   * Checks performed:
+   *   1. `mod.json` is valid JSON with required fields (id, name, version).
+   *   2. `entry.route` (if declared) is a file that exists and is readable.
+   *      We pre-parse it with `node --check` to catch syntax errors.
+   *   3. Permissions declared in mod.json are validated against the
+   *      allowed list (delegates to mod-security.mjs).
+   *   4. If `entry.validate` is declared, we dynamic-import that file
+   *      and call its `default` or named `validate` export. The hook can
+   *      throw to fail the install.
+   *
+   * Never throws — always returns a structured result.
+   */
+  async validateModInstallation(id) {
+    const errors = [];
+    const warnings = [];
+    const dir = join(MODS_DIR, id);
+    if (!existsSync(dir)) {
+      return { ok: false, errors: [`mod directory not found: ${dir}`], warnings };
+    }
+
+    // 1. mod.json valid + required fields
+    const manifest = safeReadJSON(join(dir, 'mod.json'), null);
+    if (!manifest || typeof manifest !== 'object') {
+      return {
+        ok: false,
+        errors: ['mod.json is missing or invalid JSON'],
+        warnings,
+      };
+    }
+    for (const field of ['id', 'name', 'version']) {
+      if (!manifest[field] || typeof manifest[field] !== 'string') {
+        errors.push(`mod.json is missing required field "${field}"`);
+      }
+    }
+    if (manifest.id && manifest.id !== id) {
+      errors.push(`mod.json "id" field ("${manifest.id}") does not match the directory name ("${id}")`);
+    }
+
+    // 2. entry.route exists + parses
+    const entry = manifest.entry || {};
+    if (entry.route) {
+      const routePath = join(dir, entry.route);
+      if (!existsSync(routePath)) {
+        errors.push(`entry.route "${entry.route}" does not exist at ${routePath}`);
+      } else {
+        // Pre-parse the route.mjs with `node --check` to catch syntax
+        // errors without executing it. Skipped if node is not available.
+        try {
+          const { spawnSync } = await import('node:child_process');
+          const probe = spawnSync(process.execPath, ['--check', routePath], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000,
+          });
+          if (probe.status !== 0) {
+            // Extract the first error line from the syntax checker
+            // output. `node --check` prints something like:
+            //   /path/to/route.mjs:5
+            //   syntax is wrong here
+            //   ^^^
+            //   SyntaxError: message
+            // We want the last "SyntaxError:" line.
+            const stderr = (probe.stderr || '').toString();
+            const lines = stderr.split('\n').map((l) => l.trim()).filter(Boolean);
+            const errLine = lines.reverse().find((l) => l.toLowerCase().includes('syntaxerror')) || lines[0] || 'unknown';
+            errors.push(`entry.route "${entry.route}" has a syntax error: ${errLine}`);
+          }
+        } catch {
+          // node --check unavailable — skip (not fatal)
+        }
+      }
+    }
+
+    // 3. Permissions valid
+    if (Array.isArray(manifest.permissions)) {
+      const { invalid } = parsePermissions(manifest.permissions);
+      for (const p of invalid) {
+        warnings.push(`mod declares unknown permission: ${p}`);
+      }
+    }
+
+    // 4. Optional entry.validate hook
+    if (entry.validate) {
+      const validatePath = join(dir, entry.validate);
+      if (!existsSync(validatePath)) {
+        errors.push(`entry.validate "${entry.validate}" does not exist at ${validatePath}`);
+      } else {
+        try {
+          // Dynamic import — the validate hook is opt-in. The mod may
+          // export `default` (function) or named export `validate`.
+          const mod = await import(/* @vite-ignore */ `file://${validatePath}`);
+          const fn = mod.default || mod.validate;
+          if (typeof fn !== 'function') {
+            warnings.push(
+              `entry.validate "${entry.validate}" does not export a function (got ${typeof fn})`,
+            );
+          } else {
+            // Run the validate hook with a 5s timeout. The hook is
+            // trusted (it's part of the mod) but we don't want a bad
+            // hook to hang the install.
+            const result = await Promise.race([
+              Promise.resolve()
+                .then(() => fn({ mod: manifest, dir }))
+                .catch((err) => ({ ok: false, error: err.message })),
+              new Promise((resolve) =>
+                setTimeout(() => resolve({ ok: false, error: 'validate hook timed out after 5s' }), 5000),
+              ),
+            ]);
+            if (result && result.ok === false) {
+              errors.push(`mod validate hook failed: ${result.error || 'unknown'}`);
+            }
+          }
+        } catch (err) {
+          errors.push(`failed to load entry.validate "${entry.validate}": ${err.message}`);
+        }
+      }
+    }
+
+    return {
+      ok: errors.length === 0,
+      errors,
+      warnings,
+    };
+  },
+
   /** List all installed mods. v3.3.1 — never throws. */
   list() {
     try {
@@ -211,7 +343,7 @@ export const modsLoader = {
    * Install a mod from a local path. Copies the folder into
    * `~/.config/bizar/mods/<id>/`. The id is the source folder's basename.
    */
-  installFromPath(sourcePath) {
+  async installFromPath(sourcePath) {
     if (!existsSync(sourcePath)) {
       throw new Error(`source path does not exist: ${sourcePath}`);
     }
@@ -243,6 +375,24 @@ export const modsLoader = {
     // (agents/, commands/, skills/). This makes the mod's rules binding
     // on every agent at session start.
     installModInstructions(id, target);
+    // v4.4.11 — Smoke-test the mod before reporting success. We
+    // uninstall on failure so a broken mod doesn't leave a half-
+    // copied directory the user has to clean up manually.
+    const validation = await this.validateModInstallation(id);
+    if (!validation.ok) {
+      uninstallModInstructions(id);
+      rmSync(target, { recursive: true, force: true });
+      const err = new Error(
+        `mod "${id}" failed post-install validation: ${validation.errors.join('; ')}`,
+      );
+      err.validation = validation;
+      throw err;
+    }
+    if (validation.warnings.length > 0) {
+      console.warn(
+        `[mods-loader] mod "${id}" installed with warnings: ${validation.warnings.join('; ')}`,
+      );
+    }
     return loadMod({ id, dir: target });
   },
 
@@ -494,6 +644,24 @@ export const modsLoader = {
     // v3.20 — install mod instructions into the user's opencode config
     // (agents/, commands/, skills/). Triggered on registry install too.
     installModInstructions(id, target);
+    // v4.4.11 — Smoke-test the mod before reporting success. We
+    // uninstall on failure so a broken mod doesn't leave a half-
+    // copied directory the user has to clean up manually.
+    const validation = await this.validateModInstallation(id);
+    if (!validation.ok) {
+      uninstallModInstructions(id);
+      rmSync(target, { recursive: true, force: true });
+      const err = new Error(
+        `mod "${id}" failed post-install validation: ${validation.errors.join('; ')}`,
+      );
+      err.validation = validation;
+      throw err;
+    }
+    if (validation.warnings.length > 0) {
+      console.warn(
+        `[mods-loader] mod "${id}" installed with warnings: ${validation.warnings.join('; ')}`,
+      );
+    }
     return loadMod({ id, dir: target });
   },
 

package/cli/bin.mjs

@@ -156,10 +156,11 @@ function showInstallHelp() {
   bizar install — Run the unified BizarHarness installer
 
   Usage:
-    bizar install                 Install (or refresh) every component
-    bizar install --dry-run       Print what would happen, change nothing
-    bizar install --force         Overwrite existing files
-    bizar install --help          Show this help
+    bizar install                       Install (or refresh) every component
+    bizar install --dry-run             Print what would happen, change nothing
+    bizar install --force               Overwrite existing files
+    bizar install --with-mods a,b,c     Opt-in: install specific mods as part of the run
+    bizar install --help                Show this help
 
   Description:
     v4.4.7+ — unified installer. Same code path as 'bizar update'; the
@@ -194,6 +195,7 @@ function showUpdateHelp() {
     bizar update --dry-run             Print what would happen, change nothing
     bizar update --force               Override .bizar/PRE_PUSH_NOTES.md blockers
     bizar update --yes                 Same as --force, but named for one-line scripts
+    bizar update --with-mods a,b,c     Opt-in: install specific mods as part of the run
     bizar update --help                Show this help
 
   Components updated:
@@ -580,6 +582,22 @@ function parseFlag(name) {
   return args[idx + 1] || null;
 }
 
+/**
+ * v4.4.11 — Parse `--with-mods <csv>` from the given subargs slice.
+ * Returns `null` if the flag isn't present (the provisioner's
+ * "don't touch mods" default), or a string[] of mod ids if it is.
+ */
+function parseWithModsFlag(subargs) {
+  const idx = subargs.indexOf('--with-mods');
+  if (idx === -1) return null;
+  const raw = subargs[idx + 1];
+  if (!raw || raw.startsWith('--')) return [];
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
 async function readAutoLaunchWeb() {
   try {
     const fs = await import('node:fs');
@@ -677,7 +695,19 @@ async function main() {
     else await runTestGate();
   } else if (args[0] === 'update') {
     if (isHelpRequest) showUpdateHelp();
-    else await runUpdate(args.slice(1));
+    else {
+      // v4.4.11 — Same --with-mods opt-in for update.
+      const withMods = parseWithModsFlag(args.slice(1));
+      // runUpdate expects (subargs: string[], opts?: object). Splice
+      // --with-mods <csv> out of subargs since the provisioner now
+      // takes it via opts, not as a positional arg.
+      const subargs = args.slice(1).filter((a, i, arr) => {
+        if (a === '--with-mods') return false;
+        if (arr[i - 1] === '--with-mods') return false;
+        return true;
+      });
+      await runUpdate(subargs, { withMods });
+    }
   } else if (args[0] === 'dev-link') {
     if (isHelpRequest) showDevLinkHelp();
     else {
@@ -741,7 +771,10 @@ async function main() {
   } else if (args[0] === 'install') {
     if (isHelpRequest) showInstallHelp();
     else {
-      await runInstaller();
+      // v4.4.11 — Parse --with-mods <csv> to opt into mod installs
+      // during the run. Default: mods are NEVER touched.
+      const withMods = parseWithModsFlag(args.slice(1));
+      await runInstaller({ withMods });
       // v4.4.3 — After install, repair any stale bin symlinks so the
       // user picks up the new code (the installer itself may have
       // been running from a stale install path).

package/cli/provision.mjs

@@ -38,7 +38,7 @@
 
 import chalk from 'chalk';
 import { execSync, spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -272,6 +272,13 @@ export function detectState({ cwd = process.cwd() } = {}) {
   // ── Git checkout? ─────────────────────────────────────────────────
   const gitRepo = existsSync(join(REPO_ROOT, '.git'));
 
+  // ── Installed mods ─────────────────────────────────────────────────
+  // v4.4.11 — `bizar install` and `bizar update` never install or
+  // upgrade mods. The list below is informational only. Use
+  // `bizar mod install <id>` to add a mod explicitly.
+  const MODS_DIR = join(BIZAR_HOME, 'mods');
+  const installedMods = listInstalledMods(MODS_DIR);
+
   return {
     pkgRoot,
     pkgVersion,
@@ -302,9 +309,52 @@ export function detectState({ cwd = process.cwd() } = {}) {
     opencodeCli,
     headsUpState,
     gitRepo,
+    installedMods,
   };
 }
 
+/**
+ * v4.4.11 — Lightweight read-only scan of `~/.config/bizar/mods/`.
+ * Returns one entry per mod folder with the id + enabled flag parsed
+ * from mod.json. Never throws; mods with a missing or invalid mod.json
+ * are reported as `{id, error}` so the provisioner can surface them.
+ */
+function listInstalledMods(modsDir) {
+  const out = [];
+  if (!existsSync(modsDir)) return out;
+  let entries;
+  try {
+    entries = readdirSync(modsDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(modsDir, entry.name);
+    const manifestPath = join(dir, 'mod.json');
+    if (!existsSync(manifestPath)) {
+      out.push({ id: entry.name, error: 'missing mod.json' });
+      continue;
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+      out.push({ id: entry.name, error: 'invalid mod.json' });
+      continue;
+    }
+    out.push({
+      id: manifest.id || entry.name,
+      name: manifest.name || entry.name,
+      version: manifest.version || '?',
+      enabled: manifest.enabled !== false,
+      installedAt: manifest.installedAt || null,
+      path: dir,
+    });
+  }
+  return out;
+}
+
 /**
  * Lightweight CommonJS-ish require for ESM contexts. Used to detect the
  * service-controller + heads-up modules without paying the static-import
@@ -681,6 +731,125 @@ export async function runDoctor({ silent = false } = {}) {
   }
 }
 
+/**
+ * v4.4.11 — The mods step. By default, NEVER install or upgrade mods
+ * during `bizar install` or `bizar update`. The step just reports the
+ * current mod list so the user can see what's installed.
+ *
+ * To install a mod as part of the run, the user must opt in by:
+ *   - passing `--with-mods <id1,id2>` to `bizar install` / `bizar update`
+ *   - or setting the env var `BIZAR_MODS_AUTO_INSTALL=allow`
+ *
+ * When opted in, we shell to the running dashboard's `/api/mods`
+ * endpoint (which already validates the mod) — we don't duplicate the
+ * install logic here.
+ */
+export async function runModsStep({ mode, dryRun, force, withMods, state }) {
+  // List the current mods (from the state we already detected).
+  const installed = state?.installedMods ?? [];
+  if (installed.length === 0) {
+    console.log(chalk.dim('  Mods: 0 installed.'));
+    return { ok: true, message: 'no mods installed', touched: false };
+  }
+
+  const enabled = installed.filter((m) => m.enabled).length;
+  const disabled = installed.length - enabled;
+  const summary = `${installed.length} installed (${enabled} enabled${disabled ? `, ${disabled} disabled` : ''})`;
+
+  // Resolve which mods the user asked us to install. The CLI parses
+  // `--with-mods a,b,c` into a string array; the provisioner accepts
+  // the same. We also accept a single env var as a comma-separated list.
+  const envList = (process.env.BIZAR_MODS_AUTO_INSTALL || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const wantedMods = Array.isArray(withMods) && withMods.length > 0
+    ? withMods
+    : (process.env.BIZAR_MODS_AUTO_INSTALL === 'allow' ? [] : envList);
+
+  // Default behavior: no install. Just print the list.
+  if (!wantedMods || wantedMods.length === 0) {
+    console.log(chalk.dim(`  Mods: ${summary}. Not modified (use \`bizar mod install <id>\` to add one).`));
+    // Surface mods with errors so the user knows they need attention.
+    const broken = installed.filter((m) => m.error);
+    for (const m of broken) {
+      console.log(chalk.yellow(`    ⚠ ${m.id}: ${m.error}`));
+    }
+    return { ok: true, message: `${summary}, not modified`, touched: false };
+  }
+
+  // Opt-in install path. Talk to the dashboard over HTTP — the
+  // dashboard's `POST /api/mods` endpoint already does the actual
+  // install + validation. If the dashboard isn't reachable, the
+  // install fails loudly.
+  console.log(chalk.cyan(`  Installing ${wantedMods.length} mod(s) via dashboard API: ${wantedMods.join(', ')}`));
+  const errors = [];
+  for (const id of wantedMods) {
+    try {
+      const result = await installModViaDashboard(id, { dryRun });
+      if (result.ok) {
+        console.log(chalk.green(`    ✓ ${id}: ${result.message}`));
+      } else {
+        console.log(chalk.red(`    ✗ ${id}: ${result.message}`));
+        errors.push(`${id}: ${result.message}`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(chalk.red(`    ✗ ${id}: ${msg}`));
+      errors.push(`${id}: ${msg}`);
+    }
+  }
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      message: `mod install failed for ${errors.length} mod(s): ${errors.join('; ')}`,
+      touched: true,
+    };
+  }
+  return { ok: true, message: `${wantedMods.length} mod(s) installed`, touched: true };
+}
+
+/**
+ * v4.4.11 — POST to the dashboard's /api/mods endpoint to install a mod.
+ * We re-use the dashboard's own validation pipeline (mod-loader.mjs
+ * runs the same manifest + route.mjs + permissions checks) so we
+ * don't have to duplicate them here.
+ */
+async function installModViaDashboard(id, { dryRun }) {
+  if (dryRun) {
+    return { ok: true, message: '[dry-run] would install via dashboard' };
+  }
+  // Find the dashboard's port from BIZAR_HOME/dashboard.port.
+  const portFile = join(BIZAR_HOME, 'dashboard.port');
+  let port = 4321;
+  try {
+    if (existsSync(portFile)) {
+      const parsed = parseInt(readTextSafe(portFile, '4321').trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) port = parsed;
+    }
+  } catch { /* ignore */ }
+  // We need an auth token. The dashboard's install endpoint is under
+  // /api/* which is auth-gated. Fetch the auth status + token via
+  // /api/auth/status (skipped from auth via the skipPaths list in
+  // server.mjs). If the dashboard has auth enabled, the user needs to
+  // supply a token via BIZAR_DASHBOARD_TOKEN.
+  const headers = { 'content-type': 'application/json' };
+  const token = process.env.BIZAR_DASHBOARD_TOKEN;
+  if (token) headers['authorization'] = `Basic ${Buffer.from(`opencode:${token}`).toString('base64')}`;
+  const url = `http://127.0.0.1:${port}/api/mods`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ id }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    return { ok: false, message: `dashboard returned ${res.status}: ${text.slice(0, 200) || '(no body)'}` };
+  }
+  const data = await res.json().catch(() => ({}));
+  return { ok: true, message: data?.name ? `installed ${data.name}@${data.version}` : 'installed' };
+}
+
 // ─── Top-level orchestration ──────────────────────────────────────────────────
 
 /**
@@ -785,6 +954,7 @@ export async function runProvision(opts = {}) {
     skipSystemDeps = false,
     skipHeadsUps = false,
     yes = false,
+    withMods = null,  // string[] — opt-in mod install. Default null = don't touch mods.
   } = opts;
 
   const banner = mode === 'update'
@@ -897,7 +1067,17 @@ export async function runProvision(opts = {}) {
     stepResults.push({ label: 'dashboard-restart', ...r });
   }
 
-  // ── 11. Doctor health check ────────────────────────────────────────
+  // ── 11. Mods (opt-in only) ─────────────────────────────────────────
+  // v4.4.11 — `bizar install` and `bizar update` never install or
+  // upgrade mods by default. The provisioner reports the current mod
+  // list so the user can see what's installed, then exits the mod step
+  // without touching anything. To install a mod, pass
+  // `--with-mods <id1,id2>` or set `BIZAR_MODS_AUTO_INSTALL=allow`.
+  console.log('');
+  const modsStep = await runModsStep({ mode, dryRun, force, withMods, state });
+  stepResults.push({ label: 'mods', ...modsStep });
+
+  // ── 12. Doctor health check ───────────────────────────────────────
   console.log('');
   const doctor = await runDoctor({ silent: true });
   if (doctor.failed > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "4.4.10",
+  "version": "4.4.11",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, opencode plugin, and typed SDK.",
   "type": "module",
   "bin": {