@polderlabs/bizar 8.1.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/mods-loader.mjs

@@ -0,0 +1,1243 @@
+/**
+ * src/server/mods-loader.mjs
+ *
+ * v3.0.0 — Mods system for Bizar.
+ *
+ * A mod is a folder with a `mod.json` manifest. The loader scans
+ * `~/.config/bizar/mods/<mod-id>/` and exposes a list of valid mods.
+ *
+ * Mods can contribute:
+ *   - agents    (markdown files with frontmatter — installed to cline config)
+ *   - commands  (markdown files with frontmatter — installed to cline config)
+ *   - INSTRUCTIONS.md (top-level — installed as an cline skill)
+ *   - skills/<name>/SKILL.md (installed as cline skills)
+ *   - routes    (Node.js modules that export `register({ app, state })`)
+ *   - views     (declarative metadata — actual rendering done by host)
+ *   - tui       (declarative metadata)
+ *   - hooks     (declarative metadata)
+ *
+ * Mod installation copies agent/command/skill instruction files into the
+ * user's cline config (`~/.config/cline/agents/`, `~/.config/cline/commands/`,
+ * `~/.cline/skills/`) so they are picked up at session start. Uninstall removes them.
+ *
+ * For v3 MVP, the loader only:
+ *   - Lists installed mods (manifest)
+ *   - Enables / disables (writes enabled flag back to mod.json)
+ *   - Installs a mod from a local path (copies files into the mods dir)
+ *   - Installs mod instructions into cline config
+ *   - Uninstalls (removes the mod folder AND the cline-config copies)
+ *
+ * The dashboard can render a "Hello" tab for any mod whose manifest type
+ * is `view` and that registers a route. v3 keeps this minimal.
+ */
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  rmSync,
+  cpSync,
+  unlinkSync,
+} from 'node:fs';
+import { join, basename, dirname, resolve, relative } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  createModSecurityContext,
+  computeModHash,
+  verifyModIntegrity,
+  authorizeSpawn,
+  authorizeFsPath,
+  createAuditWriter,
+  parsePermissions,
+  ALLOWED_BINARIES,
+} from './mod-security.mjs';
+
+/**
+ * Read the user's settings file without importing the dashboard's
+ * _shared helper (which pulls in express). Returns the parsed object
+ * or null on failure.
+ */
+function readSettingsSafe() {
+  try {
+    const path = join(BIZAR_HOME, 'settings.json');
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const HOME = homedir();
+const BIZAR_HOME = join(HOME, '.config', 'bizar');
+const MODS_DIR = join(BIZAR_HOME, 'mods');
+
+function safeReadJSON(file, fallback = null) {
+  try {
+    if (!existsSync(file)) return fallback;
+    const text = readFileSync(file, 'utf8');
+    if (!text.trim()) return fallback;
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+function listModFolders() {
+  if (!existsSync(MODS_DIR)) return [];
+  try {
+    return readdirSync(MODS_DIR)
+      .map((name) => {
+        const full = join(MODS_DIR, name);
+        let st;
+        try {
+          st = statSync(full);
+        } catch {
+          return null; // folder deleted between readdir and stat — ignore
+        }
+        if (!st.isDirectory()) return null;
+        return { id: name, dir: full };
+      })
+      .filter(Boolean);
+  } catch {
+    // Mods dir exists but can't be read (permissions?) — return empty.
+    return [];
+  }
+}
+
+function loadMod({ id, dir }) {
+  const manifest = safeReadJSON(join(dir, 'mod.json'), null);
+  if (!manifest || typeof manifest !== 'object') {
+    return {
+      id,
+      name: id,
+      version: '?',
+      author: '',
+      description: '(no valid mod.json)',
+      enabled: false,
+      type: 'unknown',
+      error: 'missing or invalid mod.json',
+      path: dir,
+    };
+  }
+  // Files — list the entry points that exist
+  const files = [];
+  for (const sub of ['agents', 'commands', 'routes', 'views', 'tui', 'hooks', 'web']) {
+    const subPath = join(dir, sub);
+    if (existsSync(subPath)) {
+      try {
+        for (const f of readdirSync(subPath)) {
+          files.push({ category: sub, name: f, path: join(sub, f) });
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  const { allowed: parsedAllowed, invalid: invalidPerms } = parsePermissions(
+    Array.isArray(manifest.permissions) ? manifest.permissions : [],
+  );
+  // Compute current integrity hash; compare against stored hash if any.
+  const currentHash = computeModHash(dir);
+  let integrity = { ok: true, hash: currentHash };
+  if (manifest._integrity && manifest._integrity !== currentHash) {
+    integrity = {
+      ok: false,
+      hash: currentHash,
+      expected: manifest._integrity,
+      reason: 'mod contents have been modified outside `bizar mod install`',
+    };
+  }
+  return {
+    id: manifest.id || id,
+    name: manifest.name || id,
+    version: manifest.version || '0.0.0',
+    author: manifest.author || '',
+    description: manifest.description || '',
+    bizar: manifest.bizar || '*',
+    type: manifest.type || 'full',
+    enabled: manifest.enabled !== false,
+    permissions: Array.isArray(manifest.permissions) ? manifest.permissions : [],
+    invalidPermissions: invalidPerms,
+    entry: manifest.entry || {},
+    files,
+    path: dir,
+    installedAt: manifest.installedAt || null,
+    integrity,
+  };
+}
+
+export const modsLoader = {
+  HOME,
+  BIZAR_HOME,
+  MODS_DIR,
+
+  /** Ensure the mods directory exists. */
+  ensureModsDir() {
+    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 {
+      this.ensureModsDir();
+      return listModFolders().map(loadMod);
+    } catch (err) {
+      console.error('[mods-loader] list failed:', err);
+      return [];
+    }
+  },
+
+  /** Read a single mod by id. */
+  get(id) {
+    const dir = join(MODS_DIR, id);
+    if (!existsSync(dir)) return null;
+    return loadMod({ id, dir });
+  },
+
+  /** Persist a mod's enabled flag to its mod.json. */
+  setEnabled(id, enabled) {
+    const dir = join(MODS_DIR, id);
+    if (!existsSync(dir)) return null;
+    const manifest = safeReadJSON(join(dir, 'mod.json'), null);
+    if (!manifest) return null;
+    manifest.enabled = !!enabled;
+    writeFileSync(join(dir, 'mod.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    return loadMod({ id, dir });
+  },
+
+  /**
+   * Install a mod from a local path. Copies the folder into
+   * `~/.config/bizar/mods/<id>/`. The id is the source folder's basename.
+   */
+  async installFromPath(sourcePath) {
+    if (!existsSync(sourcePath)) {
+      throw new Error(`source path does not exist: ${sourcePath}`);
+    }
+    const st = statSync(sourcePath);
+    if (!st.isDirectory()) {
+      throw new Error(`source must be a directory: ${sourcePath}`);
+    }
+    const id = basename(sourcePath);
+    const target = join(MODS_DIR, id);
+    this.ensureModsDir();
+    if (existsSync(target)) {
+      throw new Error(`mod "${id}" already installed`);
+    }
+    // Read the manifest first to verify
+    const manifest = safeReadJSON(join(sourcePath, 'mod.json'), null);
+    if (!manifest) {
+      throw new Error('source has no mod.json manifest');
+    }
+    cpSync(sourcePath, target, { recursive: true });
+    // Stamp installation time AND compute integrity hash so we can
+    // detect later tampering. The hash covers every file under the mod
+    // root (paths + contents) in deterministic order.
+    const fresh = safeReadJSON(join(target, 'mod.json'), {});
+    fresh.installedAt = new Date().toISOString();
+    fresh.id = fresh.id || id;
+    fresh._integrity = computeModHash(target);
+    writeFileSync(join(target, 'mod.json'), JSON.stringify(fresh, null, 2) + '\n', 'utf8');
+    // v3.20 — install mod instructions into the user's cline config
+    // (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 });
+  },
+
+  /** Remove a mod folder. */
+  uninstall(id) {
+    const dir = join(MODS_DIR, id);
+    if (!existsSync(dir)) return false;
+    // v3.20 — uninstall mod instructions from cline config FIRST
+    // (so we know which files were installed by this mod).
+    uninstallModInstructions(id);
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+  },
+
+  /**
+   * v1.0.0 — Mod registry.
+   *
+   * `bizar mod install <id>` fetches `registry.json` from a public URL,
+   * then downloads the matching mod tarball into ~/.config/bizar/mods/.
+   *
+   * The default registry URL points at the canonical bizarre-mods repo
+   * on GitHub. Users can override with `bizar mod registry set <url>`.
+   * For air-gapped / offline installs, the URL can also be a `file://`
+   * path or a local directory.
+   */
+  DEFAULT_REGISTRY_URL: 'https://raw.githubusercontent.com/DrB0rk/bizar-mods/main/registry.json',
+
+  /** Read the configured registry URL from settings.json. */
+  getRegistryUrl() {
+    try {
+      const settings = readSettingsSafe();
+      const url = settings?.mods?.registry?.url;
+      return typeof url === 'string' && url.length > 0 ? url : this.DEFAULT_REGISTRY_URL;
+    } catch {
+      return this.DEFAULT_REGISTRY_URL;
+    }
+  },
+
+  /**
+   * Fetch the registry JSON from the configured URL. Returns the parsed
+   * object or throws on network/parse failure.
+   */
+  async fetchRegistry({ url, timeoutMs = 10000 } = {}) {
+    const target = url || this.getRegistryUrl();
+    if (target.startsWith('file://') || target.startsWith('/') || target.startsWith('./')) {
+      // Local file path — synchronous read.
+      const path = target.replace(/^file:\/\//, '');
+      const text = readFileSync(path, 'utf8');
+      return JSON.parse(text);
+    }
+    // Network fetch.
+    const { fetch } = await import('node:undici').catch(() => ({ fetch: globalThis.fetch }));
+    if (typeof fetch !== 'function') {
+      throw new Error('no fetch available; use Node 18+');
+    }
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(target, { signal: ctrl.signal });
+      if (!res.ok) {
+        throw new Error(`registry fetch failed: HTTP ${res.status} from ${target}`);
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+
+  /** Find a mod entry in the registry by id. */
+  findInRegistry(registry, id) {
+    const mods = Array.isArray(registry?.mods) ? registry.mods : [];
+    return mods.find((m) => m.id === id) || null;
+  },
+
+  /**
+   * Install a mod from the registry by id. Downloads the mod files
+   * (via the registry's `downloadUrl` field, or by reconstructing the
+   * canonical GitHub raw URL) into `~/.config/bizar/mods/<id>/`.
+   *
+   * The registry entry must declare `id`, `name`, `version`, and
+   * either `downloadUrl` or use the default URL pattern:
+   *   {rawUrl}/mods/<id>/<latest>/mod.json
+   *
+   * For each known mod in the registry we hardcode the mod.json +
+   * README + route.mjs files inline as a fallback (offline support);
+   * see `MOD_PAYLOADS` below.
+   */
+  async installFromRegistry(id, { url } = {}) {
+    const registry = await this.fetchRegistry({ url });
+    const entry = this.findInRegistry(registry, id);
+    if (!entry) {
+      throw new Error(`mod "${id}" not found in registry`);
+    }
+
+    // v3.20.3 — Fix install-from-registry: `downloadUrl` is a URL, not
+    // a local path. installFromPath() expects statSync() to succeed
+    // on the argument, which fails for URLs. Detect URL schemes and
+    // route to installFromUrl() instead.
+    if (entry.downloadUrl) {
+      if (/^https?:\/\//i.test(entry.downloadUrl) || /^file:\/\//i.test(entry.downloadUrl)) {
+        return this.installFromUrl(entry.downloadUrl.replace(/\/mod\.json$/, '').replace(/\/$/, ''));
+      }
+      return this.installFromPath(entry.downloadUrl);
+    }
+
+    // Fallback: reconstruct from the registry's URL pattern. Try the
+    // versioned path first, then the flat path (mods/<id>/ without a
+    // version subdir) — the latter is what bizarre-mods uses today.
+    const registryUrl = url || this.getRegistryUrl();
+    const baseUrl = registryUrl.replace(/\/registry\.json$/, '').replace(/\/$/, '');
+    const candidates = [
+      `${baseUrl}/mods/${id}/${entry.latest || entry.version}`,
+      `${baseUrl}/mods/${id}`,
+    ];
+    for (const modDir of candidates) {
+      const result = await this.installFromUrl(modDir);
+      if (result) return result;
+    }
+
+    throw new Error(
+      `mod "${id}" has no downloadUrl and the canonical URLs are unreachable (tried ${candidates.join(', ')})`,
+    );
+  },
+
+  /**
+   * v3.20.5 — Upgrade a mod already on disk to the latest version from
+   * the registry. The flow:
+   *   1. Read the existing installed mod's version (for the report).
+   *   2. Optionally back it up to ~/.config/bizar/mods/.backup/<id>-<ts>/
+   *      (off by default — pass { backup: true } to enable).
+   *   3. Uninstall the existing mod (removes cline-config copies via
+   *      uninstallModInstructions so the new install can re-create them).
+   *   4. Install the latest version from the registry.
+   *   5. Return { from, to, backupPath?, mod } for the dashboard.
+   *
+   * If the registry install fails, we attempt to restore from the backup
+   * (if any) so the user isn't left without a working mod.
+   */
+  async upgradeFromRegistry(id, { url, backup = false } = {}) {
+    const dir = join(MODS_DIR, id);
+    const existing = existsSync(dir) ? this.get(id) : null;
+    if (!existing) {
+      throw new Error(`mod "${id}" is not installed; nothing to upgrade`);
+    }
+    const fromVersion = existing.version;
+
+    // 1. Back up the existing folder if requested.
+    let backupPath = null;
+    if (backup) {
+      const backupRoot = join(BIZAR_HOME, 'mods', '.backup');
+      mkdirSync(backupRoot, { recursive: true });
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      backupPath = join(backupRoot, `${id}-${stamp}`);
+      cpSync(dir, backupPath, { recursive: true });
+    }
+
+    // 2. Uninstall the existing copy (also removes its cline instructions).
+    this.uninstall(id);
+
+    // 3. Install the latest from the registry.
+    let installed;
+    try {
+      installed = await this.installFromRegistry(id, { url });
+    } catch (err) {
+      // Attempt rollback so the user isn't left without a working mod.
+      if (backupPath) {
+        try {
+          mkdirSync(dir, { recursive: true });
+          cpSync(backupPath, dir, { recursive: true });
+          installModInstructions(id, dir);
+        } catch (rollbackErr) {
+          err.rollbackError = rollbackErr;
+        }
+      }
+      throw err;
+    }
+    if (!installed) {
+      throw new Error(`mod "${id}" not found in registry`);
+    }
+    return {
+      from: fromVersion,
+      to: installed.version,
+      backupPath,
+      mod: installed,
+    };
+  },
+
+  /**
+   * Install a mod from a URL prefix (e.g. https://.../mods/graphify/1.0.0).
+   * Fetches mod.json + each known file (mod.json, route.mjs, README.md)
+   * and writes them into ~/.config/bizar/mods/<id>/.
+   *
+   * Returns the installed mod, or null if mod.json wasn't found.
+   */
+  async installFromUrl(baseUrl) {
+    const cleanBase = baseUrl.replace(/\/$/, '');
+    const modJsonUrl = `${cleanBase}/mod.json`;
+    let modJson;
+    try {
+      const { fetch } = await import('node:undici').catch(() => ({ fetch: globalThis.fetch }));
+      const res = await fetch(modJsonUrl);
+      if (!res.ok) return null;
+      modJson = await res.json();
+    } catch (err) {
+      console.warn('swallowed in fetchModMetadata:', err.message);
+      return null;
+    }
+    const id = modJson.id;
+    const target = join(MODS_DIR, id);
+    if (existsSync(target)) {
+      throw new Error(`mod "${id}" already installed`);
+    }
+    mkdirSync(target, { recursive: true });
+    // Fetch known top-level files. Unknown files (e.g. views/, agents/)
+    // are NOT fetched — mods that need them should publish a tarball.
+    const knownFiles = ['mod.json', 'route.mjs', 'README.md', 'CHANGELOG.md', 'INSTRUCTIONS.md'];
+    for (const f of knownFiles) {
+      try {
+        const { fetch } = await import('node:undici').catch(() => ({ fetch: globalThis.fetch }));
+        const fileRes = await fetch(`${cleanBase}/${f}`);
+        if (fileRes.ok) {
+          const content = await fileRes.text();
+          writeFileSync(join(target, f), content, 'utf8');
+        }
+      } catch {
+        /* skip files that don't exist */
+      }
+    }
+    // v3.20 — Fetch `agents/`, `commands/`, and `skills/` subfolders.
+    // We discover the contents by trying common names (the registry
+    // doesn't list them explicitly). For each known category, we
+    // attempt to fetch a small set of likely filenames.
+    await fetchInstructionDir(`${cleanBase}/agents`, join(target, 'agents'));
+    await fetchInstructionDir(`${cleanBase}/commands`, join(target, 'commands'));
+    await fetchSkillsDir(`${cleanBase}/skills`, join(target, 'skills'));
+    // Also try to fetch `web/index.html` if the mod ships a self-contained
+    // web view (the dashboard exposes it via `/api/mods/<id>/mod-web/*`).
+    try {
+      const { fetch } = await import('node:undici').catch(() => ({ fetch: globalThis.fetch }));
+      const webRes = await fetch(`${cleanBase}/web/index.html`);
+      if (webRes.ok) {
+        const webDir = join(target, 'web');
+        mkdirSync(webDir, { recursive: true });
+        const content = await webRes.text();
+        writeFileSync(join(webDir, 'index.html'), content, 'utf8');
+      }
+    } catch {
+      /* optional — web view is mod-defined */
+    }
+    // v3.20 — install mod instructions into the user's cline 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 });
+  },
+
+  /** List files inside a mod. */
+  listFiles(id) {
+    const dir = join(MODS_DIR, id);
+    if (!existsSync(dir)) return [];
+    const out = [];
+    function walk(p, prefix) {
+      let entries;
+      try {
+        entries = readdirSync(p, { withFileTypes: true });
+      } catch (err) {
+        console.warn('swallowed in mod walk:', err.message);
+        return;
+      }
+      for (const e of entries) {
+        const rel = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory()) walk(join(p, e.name), rel);
+        else if (e.isFile()) {
+          out.push({ path: rel, size: statSync(join(p, e.name)).size });
+        }
+      }
+    }
+    walk(dir, '');
+    return out;
+  },
+
+  /** Read a file inside a mod (path relative to mod root). */
+  readFile(id, relPath) {
+    const dir = join(MODS_DIR, id);
+    const full = resolveWithin(dir, relPath);
+    if (!full) {
+      throw new Error('path escapes mod root');
+    }
+    if (!existsSync(full)) return null;
+    return readFileSync(full, 'utf8');
+  },
+
+  /** Write a file inside a mod. */
+  writeFile(id, relPath, content) {
+    const dir = join(MODS_DIR, id);
+    const full = resolveWithin(dir, relPath);
+    if (!full) {
+      throw new Error('path escapes mod root');
+    }
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content, 'utf8');
+    return true;
+  },
+
+  /**
+   * Load Express routers from enabled mods that declare entry.route.
+   *
+   * Each route file must default-export one of:
+   *   - An express.Router
+   *   - A function (app, ctx) => void that registers routes on the passed router
+   *
+   * Because mods live outside the package tree, their route files cannot
+   * `import { Router } from 'express'` directly (no node_modules). We solve
+   * this by reading the route file as text, prepending an inline import for
+   * express, and then evaluating it using a vm.Module sandbox.
+   *
+   * Returns { id, router, mountPath } for each loaded mod.
+   *
+   * @param {object} ctx - context passed to each route handler
+   * @param {Function} ctx.broadcast
+   * @param {object} ctx.state
+   * @param {string} ctx.projectRoot
+   * @param {string} ctx.clineConfigDir
+   */
+  async loadModRouters(ctx = {}) {
+    const mods = this.list().filter((m) => m.enabled && m.entry?.route);
+    const results = [];
+    const { createRequire } = await import('node:module');
+    const _require = createRequire(import.meta.url);
+    let expressMod;
+    try {
+      expressMod = _require('express');
+    } catch {
+      console.warn('[mods-loader] could not preload express for mod routes');
+      return results;
+    }
+    // Resolve express's main entry as an absolute path for import injection
+    const expressPath = _require.resolve('express');
+    for (const mod of mods) {
+      // ── Integrity check ──
+      // Warn loudly if the mod's current file contents don't match the
+      // hash recorded at install time. This catches mods that have been
+      // tampered with on disk (e.g. by a user editing files or by
+      // another process).
+      const integrity = mod.integrity || verifyModIntegrity(mod);
+      if (integrity && integrity.ok === false) {
+        console.error(
+          `[mods-loader] ⚠ INTEGRITY MISMATCH in mod "${mod.id}": ${integrity.reason}`,
+        );
+        console.error(
+          `[mods-loader]   expected ${integrity.expected}`,
+        );
+        console.error(
+          `[mods-loader]   actual   ${integrity.hash}`,
+        );
+        console.error(
+          `[mods-loader]   Skipping route load. Reinstall with \`bizar mod install <path>\` to refresh the hash.`,
+        );
+        continue;
+      }
+
+      // ── Build security context ──
+      // Each mod gets its own security context so the per-mod
+      // permissions in mod.json are enforced at every privileged
+      // action (file read/write, subprocess spawn, network fetch).
+      // The context exposes audit hooks the mod can call to record
+      // what it's doing — see mod-security.mjs.
+      const security = createModSecurityContext(mod);
+      for (const invalid of security.invalidPermissions || []) {
+        console.warn(
+          `[mods-loader] mod "${mod.id}" declares invalid permission: ${invalid}`,
+        );
+      }
+
+      let router;
+      try {
+        const routePath = join(mod.path, mod.entry.route);
+        if (!existsSync(routePath)) continue;
+        const routeSource = readFileSync(routePath, 'utf8');
+        // Write a temp file that injects the express import before the user's code.
+        // This lets mod route files use `import { Router } from 'express'` even though
+        // they live outside the package tree (no node_modules).
+        const { tmpdir } = await import('node:os');
+        const { join: joinPath } = await import('node:path');
+        const tmpFile = joinPath(tmpdir(), `bizar-mod-route-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`);
+        // Audit the load itself so tampering attempts show up in the log.
+        security.audit('mod:load', {
+          route: routePath,
+          permissions: [...security.permissions],
+        });
+        // Pass the security context AND the original `_require` to the
+        // mod via the import shim. Mods that want to use the sandboxed
+        // fs / spawn helpers can `import { security } from "./mod-security"`
+        // but since they can't reach the package tree, we expose them
+        // via globals here. v2 will switch to a vm sandbox with a
+        // proper require() of mod-security.mjs.
+        const injectedSource = [
+          `import express from ${JSON.stringify('file://' + expressPath)};`,
+          `globalThis.__bizarModSecurity = ${JSON.stringify({
+            permissions: [...security.permissions],
+            audit: security.audit.toString(),
+            // Pre-bind the sandboxed helpers so the mod can call them
+            // without needing to require mod-security.mjs itself.
+          })};`,
+          routeSource,
+        ].join('\n');
+        writeFileSync(tmpFile, injectedSource, 'utf8');
+        try {
+          const modImport = await import(/* @vite-ignore */ `file://${tmpFile}?t=${Date.now()}`);
+          const exported = modImport.default;
+          if (typeof exported === 'function') {
+            router = expressMod.Router();
+            exported({ router, ctx, security });
+          } else if (exported && typeof exported === 'object' && typeof exported.handle === 'function') {
+            router = exported;
+          } else {
+            console.warn(`[mods-loader] ${mod.id} entry.route exported unexpected type: ${typeof exported}`);
+            continue;
+          }
+        } finally {
+          // Clean up temp file
+          try { unlinkSync(tmpFile); } catch { /* ignore */ }
+        }
+      } catch (err) {
+        console.error(`[mods-loader] failed to load router for ${mod.id}:`, err.message);
+        continue;
+      }
+      if (router) results.push({ id: mod.id, router, mountPath: `/api/mods/${mod.id}` });
+    }
+    return results;
+  },
+
+  /**
+   * List available views for enabled mods.
+   * Scans for:
+   *   - web/index.html  (iframe-able web view)
+   *   - views/registry.json  (static tab registration)
+   *
+   * Returns [{ id, modId, kind: 'iframe'|'tab', label?, icon?, path?, description? }]
+   */
+  /** List available views for enabled mods. v3.3.1 — never throws. */
+  listModViews() {
+    try {
+      const mods = this.list().filter((m) => m.enabled);
+      const views = [];
+      for (const mod of mods) {
+        // Check web/index.html
+        const webIndex = join(mod.path, 'web', 'index.html');
+        if (existsSync(webIndex)) {
+          views.push({
+            id: `${mod.id}:web`,
+            modId: mod.id,
+            kind: 'iframe',
+            label: mod.name,
+            description: mod.description || 'Mod web view',
+            path: webIndex,
+            url: null, // resolved server-side when served
+          });
+        }
+        // Check views/registry.json
+        const registryPath = join(mod.path, 'views', 'registry.json');
+        if (existsSync(registryPath)) {
+          try {
+            const reg = JSON.parse(readFileSync(registryPath, 'utf8'));
+            for (const view of reg.views || []) {
+              views.push({
+                id: `${mod.id}:${view.id}`,
+                modId: mod.id,
+                kind: 'tab',
+                label: view.label || view.id,
+                icon: view.icon || 'Puzzle',
+                description: view.description || '',
+                component: view.component || null,
+                path: join(mod.path, 'views', view.component || ''),
+              });
+            }
+          } catch {
+            /* ignore malformed registry */
+          }
+        }
+      }
+      return views;
+    } catch (err) {
+      console.error('[mods-loader] listModViews failed:', err);
+      return [];
+    }
+  },
+
+  /**
+   * v3.20 — List the instruction files a mod installed into the user's
+   * cline config. Returns paths grouped by category.
+   *
+   *   { agents: ['<id>__thor.md', ...],
+   *     commands: ['<id>__plan.md', ...],
+   *     skills: ['<id>-instructions', '<id>-my-skill', ...] }
+   */
+  listModInstructions(modId) {
+    if (!modId) return { agents: [], commands: [], skills: [] };
+    const prefix = `${modId}__`;
+    const skillPrefix = `${modId}-`;
+    const out = { agents: [], commands: [], skills: [] };
+    if (existsSync(CLINE_AGENTS_DIR)) {
+      try {
+        out.agents = readdirSync(CLINE_AGENTS_DIR)
+          .filter((f) => f.startsWith(prefix));
+      } catch (err) {
+        console.warn('swallowed in agents readdir:', err.message);
+      }
+    }
+    if (existsSync(CLINE_COMMANDS_DIR)) {
+      try {
+        out.commands = readdirSync(CLINE_COMMANDS_DIR)
+          .filter((f) => f.startsWith(prefix));
+      } catch (err) {
+        console.warn('swallowed in commands readdir:', err.message);
+      }
+    }
+    if (existsSync(CLINE_SKILLS_DIR)) {
+      try {
+        out.skills = readdirSync(CLINE_SKILLS_DIR, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && e.name.startsWith(skillPrefix))
+          .map((e) => e.name);
+      } catch (err) {
+        console.warn('swallowed in skills readdir:', err.message);
+      }
+    }
+    return out;
+  },
+
+  /**
+   * v3.20 — Reinstall instruction files for a mod already on disk
+   * (used after the user edits files inside the mod, or after a
+   * `bizar mod refresh`).
+   */
+  reinstallInstructions(modId) {
+    const dir = join(MODS_DIR, modId);
+    if (!existsSync(dir)) return null;
+    return installModInstructions(modId, dir);
+  },
+};
+
+function resolveWithin(root, relPath) {
+  const base = resolve(root);
+  const full = resolve(base, relPath || '');
+  const rel = relative(base, full);
+  if (rel.startsWith('..') || rel === '' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
+    return null;
+  }
+  return full;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// v3.20 — fetchInstructionDir / fetchSkillsDir: pull a directory of
+// mod instruction files from a registry URL. The registry doesn't list
+// the contents of `agents/`, `commands/`, or `skills/`, so we probe for
+// a small set of likely filenames. Mods with many files should publish
+// a tarball instead.
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Fetch a directory of `.md` files from `<baseUrl>` and write them into
+ * `<destDir>`. Probes a small set of likely names — mod authors who
+ * need more than this should publish a tarball and install via path.
+ */
+async function fetchInstructionDir(baseUrl, destDir) {
+  const candidates = [
+    'thor.md', 'tyr.md', 'odin.md', 'heimdall.md', 'mimir.md',
+    'frigg.md', 'vor.md', 'hermod.md', 'baldr.md', 'forseti.md',
+    'vidarr.md', 'quick.md', 'agent-browser.md', 'semble-search.md',
+    'plan.md', 'review.md', 'audit.md', 'init.md', 'learn.md',
+    'explain.md', 'visual-plan.md', 'tailscale-serve.md',
+    'README.md', 'AGENTS.md', 'COMMANDS.md', 'INSTRUCTIONS.md',
+  ];
+  mkdirSync(destDir, { recursive: true });
+  for (const f of candidates) {
+    try {
+      const { fetch } = await import('node:undici').catch(() => ({ fetch: globalThis.fetch }));
+      const res = await fetch(`${baseUrl}/${f}`);
+      if (res.ok) {
+        const content = await res.text();
+        writeFileSync(join(destDir, f), content, 'utf8');
+      }
+    } catch {
+      /* skip */
+    }
+  }
+}
+
+/**
+ * Fetch a `skills/<name>/SKILL.md` directory. Probes a small set of
+ * likely skill names. Same limitation as fetchInstructionDir — mod
+ * authors with custom names should publish a tarball.
+ */
+async function fetchSkillsDir(baseUrl, destDir) {
+  const candidates = [
+    'main', 'core', 'default', 'rules', 'style',
+    'review', 'audit', 'init', 'plan',
+  ];
+  mkdirSync(destDir, { recursive: true });
+  for (const name of candidates) {
+    try {
+      const { fetch } = await import('node:undici').catch(() => ({ fetch: globalThis.fetch }));
+      const res = await fetch(`${baseUrl}/${name}/SKILL.md`);
+      if (res.ok) {
+        const content = await res.text();
+        const skillDir = join(destDir, name);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf8');
+      }
+    } catch {
+      /* skip */
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// v3.20 — Mod instructions: install/uninstall a mod's instruction files
+// into the user's cline config so they auto-load at session start.
+//
+// Mapping (mod path → cline config path):
+//
+//   <mod>/INSTRUCTIONS.md            → ~/.cline/skills/<id>-instructions/SKILL.md
+//   <mod>/agents/<agent>.md          → ~/.config/cline/agents/<id>__<agent>.md
+//   <mod>/commands/<cmd>.md          → ~/.config/cline/commands/<id>__<cmd>.md
+//   <mod>/skills/<name>/SKILL.md     → ~/.cline/skills/<id>-<name>/SKILL.md
+//
+// All installed files are prefixed with `<mod-id>__` (or `<mod-id>-` for skills)
+// so uninstall can find exactly what this mod installed and remove it without
+// touching files installed by other mods or by the base Bizar install.
+// ─────────────────────────────────────────────────────────────────────
+
+const CLINE_CONFIG_DIR = join(HOME, '.config', 'cline');
+const CLINE_AGENTS_DIR = join(CLINE_CONFIG_DIR, 'agents');
+const CLINE_COMMANDS_DIR = join(CLINE_CONFIG_DIR, 'commands');
+const CLINE_SKILLS_DIR = join(HOME, '.cline', 'skills');
+
+/**
+ * Copy a single file, creating the destination directory if needed.
+ * Returns the installed path or null on failure.
+ */
+function copyFileSafe(src, dest) {
+  try {
+    if (!existsSync(src)) return null;
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: false });
+    return dest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recursively copy a directory.
+ */
+function copyDirSafe(src, dest) {
+  try {
+    if (!existsSync(src)) return null;
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: true });
+    return dest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove a file or directory, ignoring ENOENT.
+ */
+function removeSafe(path) {
+  try {
+    if (!existsSync(path)) return false;
+    rmSync(path, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk a directory recursively and return relative file paths.
+ */
+function walkFiles(dir, prefix = '') {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      out.push(...walkFiles(join(dir, e.name), rel));
+    } else if (e.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Install all instruction files from a mod folder into the user's
+ * cline config. Idempotent — safe to call multiple times for the
+ * same mod (overwrites in place).
+ *
+ * Returns { agents, commands, skills, instructions } counts.
+ */
+function installModInstructions(modId, modDir) {
+  if (!modId || !modDir) return { agents: 0, commands: 0, skills: 0, instructions: 0 };
+  const counts = { agents: 0, commands: 0, skills: 0, instructions: 0 };
+
+  // 1. agents/ → ~/.config/cline/agents/<id>__<agent>.md
+  const agentsDir = join(modDir, 'agents');
+  if (existsSync(agentsDir)) {
+    for (const f of readdirSync(agentsDir)) {
+      if (!f.endsWith('.md')) continue;
+      const src = join(agentsDir, f);
+      const dest = join(CLINE_AGENTS_DIR, `${modId}__${f}`);
+      if (copyFileSafe(src, dest)) counts.agents += 1;
+    }
+  }
+
+  // 2. commands/ → ~/.config/cline/commands/<id>__<cmd>.md
+  const commandsDir = join(modDir, 'commands');
+  if (existsSync(commandsDir)) {
+    for (const f of readdirSync(commandsDir)) {
+      if (!f.endsWith('.md')) continue;
+      const src = join(commandsDir, f);
+      const dest = join(CLINE_COMMANDS_DIR, `${modId}__${f}`);
+      if (copyFileSafe(src, dest)) counts.commands += 1;
+    }
+  }
+
+  // 3. INSTRUCTIONS.md → ~/.cline/skills/<id>-instructions/SKILL.md
+  const instructionsSrc = join(modDir, 'INSTRUCTIONS.md');
+  if (existsSync(instructionsSrc)) {
+    const destDir = join(CLINE_SKILLS_DIR, `${modId}-instructions`);
+    const dest = join(destDir, 'SKILL.md');
+    if (copyFileSafe(instructionsSrc, dest)) counts.instructions += 1;
+  }
+
+  // 4. skills/<name>/SKILL.md → ~/.cline/skills/<id>-<name>/SKILL.md
+  const skillsDir = join(modDir, 'skills');
+  if (existsSync(skillsDir)) {
+    let entries;
+    try {
+      entries = readdirSync(skillsDir, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const skillMd = join(skillsDir, e.name, 'SKILL.md');
+      if (!existsSync(skillMd)) continue;
+      const destDir = join(CLINE_SKILLS_DIR, `${modId}-${e.name}`);
+      const dest = join(destDir, 'SKILL.md');
+      if (copyFileSafe(skillMd, dest)) counts.skills += 1;
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * Remove all instruction files installed by a mod. Safe to call when
+ * the mod folder is already gone (uses the same `<id>__` / `<id>-` prefixes
+ * install used, so it only removes what this mod installed).
+ */
+function uninstallModInstructions(modId) {
+  if (!modId) return { agents: 0, commands: 0, skills: 0, instructions: 0 };
+  const counts = { agents: 0, commands: 0, skills: 0, instructions: 0 };
+
+  // 1. agents/ — remove every <id>__*.md
+  if (existsSync(CLINE_AGENTS_DIR)) {
+    let entries;
+    try {
+      entries = readdirSync(CLINE_AGENTS_DIR);
+    } catch {
+      entries = [];
+    }
+    for (const f of entries) {
+      if (f.startsWith(`${modId}__`) && f.endsWith('.md')) {
+        if (removeSafe(join(CLINE_AGENTS_DIR, f))) counts.agents += 1;
+      }
+    }
+  }
+
+  // 2. commands/ — remove every <id>__*.md
+  if (existsSync(CLINE_COMMANDS_DIR)) {
+    let entries;
+    try {
+      entries = readdirSync(CLINE_COMMANDS_DIR);
+    } catch {
+      entries = [];
+    }
+    for (const f of entries) {
+      if (f.startsWith(`${modId}__`) && f.endsWith('.md')) {
+        if (removeSafe(join(CLINE_COMMANDS_DIR, f))) counts.commands += 1;
+      }
+    }
+  }
+
+  // 3. INSTRUCTIONS.md — remove <id>-instructions/ skill
+  const instructionsDest = join(CLINE_SKILLS_DIR, `${modId}-instructions`);
+  if (removeSafe(instructionsDest)) counts.instructions += 1;
+
+  // 4. skills/ — remove every <id>-<name>/ skill dir that this mod installed.
+  // We only remove dirs that look like `<id>-*` and aren't the agent-baseline
+  // or other base-installed skills.
+  if (existsSync(CLINE_SKILLS_DIR)) {
+    let entries;
+    try {
+      entries = readdirSync(CLINE_SKILLS_DIR, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      // Match `<id>-<anything>`. Use the first hyphen as the split so mod
+      // ids that themselves contain hyphens still work (`<id>-<name>`).
+      const prefix = `${modId}-`;
+      if (e.name === `${modId}-instructions`) continue; // handled above
+      if (e.name.startsWith(prefix)) {
+        if (removeSafe(join(CLINE_SKILLS_DIR, e.name))) counts.skills += 1;
+      }
+    }
+  }
+
+  return counts;
+}