@bahulam/code 0.1.10 → 0.1.12

package/src/commands/plugin.mjs

@@ -0,0 +1,247 @@
+/**
+ * Plugin CLI Commands — open a workspace with a named plugin loaded.
+ *
+ * Commands:
+ *   bahulam-code plugin <name> [path]    Open workspace with plugin tools
+ *
+ * The named plugin is looked up in the standard plugin directories,
+ * verified to exist, then a local workspace is started at [path]
+ * (or the current directory) with the plugin's tools, handlers,
+ * and optionally sub-agents available.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  createLocalWorkspaceSession,
+  listLocalWorkspaceSessions,
+  loadLocalWorkspaceSession,
+  writeLocalWorkspaceSession,
+} from '../local-service/session-store.mjs';
+import { startLocalWorkspaceService } from '../local-service/server.mjs';
+import { openLocalBrowser } from '../local-service/browser.mjs';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+
+/**
+ * Standard directories to search for plugins.
+ */
+const PLUGIN_SEARCH_DIRS = [
+  path.join(process.cwd(), '.bahulam', 'plugins'),
+  path.join(os.homedir(), '.bahulam', 'plugins'),
+];
+
+/**
+ * Find a plugin directory by name across all standard search paths.
+ * Returns the directory path and manifests on success, null on miss.
+ */
+function findPluginDir(name) {
+  const needle = String(name || '').trim().toLowerCase();
+  if (!needle) return null;
+
+  for (const searchDir of PLUGIN_SEARCH_DIRS) {
+    try {
+      if (!fs.existsSync(searchDir)) continue;
+      const entries = fs.readdirSync(searchDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const pluginDir = path.join(searchDir, entry.name);
+        // Check both plugin.yaml and plugin.json
+        const yamlPath = path.join(pluginDir, 'plugin.yaml');
+        const jsonPath = path.join(pluginDir, 'plugin.json');
+        let manifestPath = null;
+        if (fs.existsSync(yamlPath)) manifestPath = yamlPath;
+        else if (fs.existsSync(jsonPath)) manifestPath = jsonPath;
+
+        if (!manifestPath) continue;
+
+        // Quick name match — match against directory name first (fast path),
+        // then parse the manifest for its metadata.name if needed
+        if (entry.name.toLowerCase() === needle) {
+          return { dir: pluginDir, manifestPath, searchDir };
+        }
+
+        // Parse manifest to check metadata.name
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        let manifest;
+        try {
+          manifest = JSON.parse(raw);
+        } catch {
+          // Might be YAML — try simple YAML top-level name extraction
+          // For speed, check for `name:` line patterns
+          const nameMatch = raw.match(/^(?:name|metadata\.name|metadata:\s*\n\s+name)\s*:\s*(.+)$/m);
+          if (nameMatch) {
+            const metaName = nameMatch[1].trim().replace(/^["']|["']$/g, '').toLowerCase();
+            if (metaName === needle) {
+              return { dir: pluginDir, manifestPath, searchDir };
+            }
+          }
+          continue;
+        }
+
+        const metaName = (
+          manifest?.metadata?.name ||
+          manifest?.name ||
+          ''
+        ).toLowerCase();
+        if (metaName === needle) {
+          return { dir: pluginDir, manifestPath, searchDir };
+        }
+      }
+    } catch {
+      // Skip unreadable directories
+    }
+  }
+  return null;
+}
+
+/**
+ * Main entry point for `bahulam-code plugin` subcommand.
+ * @param {object} args - parsed CLI args
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ */
+export async function handlePluginCommand(args, { cwd = process.cwd() } = {}) {
+  const pluginName = String(args.pluginName || '').trim();
+  const targetPath = String(args.targetPath || cwd).trim();
+
+  if (!pluginName || args.help) {
+    printPluginUsage();
+    process.exit(args.help ? 0 : 1);
+  }
+
+  // 1. Find the plugin
+  const found = findPluginDir(pluginName);
+  if (!found) {
+    process.stderr.write(
+      `${RED}✗ Plugin "${pluginName}" not found.${RESET}\n` +
+      `  ${DIM}Searched:${RESET}\n` +
+      PLUGIN_SEARCH_DIRS.map(d => `    ${d}`).join('\n') + '\n' +
+      `  ${DIM}Create a plugin.yaml or plugin.json in one of these directories.${RESET}\n`
+    );
+    process.exit(1);
+  }
+
+  // 2. Verify the target path exists
+  let resolvedPath;
+  try {
+    resolvedPath = path.resolve(cwd, targetPath);
+    if (!fs.existsSync(resolvedPath)) {
+      process.stderr.write(
+        `${RED}✗ Target path does not exist: ${resolvedPath}${RESET}\n`
+      );
+      process.exit(1);
+    }
+  } catch (err) {
+    process.stderr.write(
+      `${RED}✗ Invalid target path: ${err.message}${RESET}\n`
+    );
+    process.exit(1);
+  }
+
+  // 3. Create a local workspace session with plugin context
+  const sessionTitle = `${pluginName} plugin — ${path.basename(resolvedPath) || resolvedPath}`;
+  const { session, token } = createLocalWorkspaceSession({
+    targetPath: resolvedPath,
+    cwd,
+    kind: `plugin-${pluginName}`,
+    title: sessionTitle,
+  });
+
+  // Augment session with plugin metadata so the workspace knows which
+  // plugin to highlight
+  const stored = loadLocalWorkspaceSession(session.id);
+  if (stored) {
+    stored.plugin = {
+      name: pluginName,
+      plugin_dir: found.dir,
+      manifest_path: found.manifestPath,
+    };
+    writeLocalWorkspaceSession(stored);
+    session.plugin = stored.plugin;
+  }
+
+  // 4. Start the workspace service
+  const service = await startLocalWorkspaceService({
+    session,
+    token,
+    port: args.port || 0,
+  });
+
+  // 5. Output
+  const url = typeof service === 'object' ? service.url : '';
+  if (args.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, session, plugin: pluginName, url, port: service.port }, null, 2)}\n`
+    );
+  } else {
+    process.stderr.write(`\n${BOLD}${CYAN}Bahulam Plugin Workspace${RESET}\n`);
+    process.stderr.write(`  ${DIM}plugin${RESET}    ${pluginName}\n`);
+    process.stderr.write(`  ${DIM}session${RESET}  ${session.id}\n`);
+    process.stderr.write(`  ${DIM}root${RESET}     ${session.root_path}\n`);
+    process.stderr.write(`  ${DIM}url${RESET}      ${CYAN}${url}${RESET}\n\n`);
+    process.stderr.write(
+      `${GREEN}ready${RESET} ${DIM}Plugin workspace started at 127.0.0.1:${service.port}. Press Ctrl+C to stop.${RESET}\n`
+    );
+  }
+
+  if (args.open !== false) {
+    openLocalBrowser(url);
+  }
+
+  // 6. Wait for shutdown
+  await new Promise((resolve) => {
+    let done = false;
+    const stop = async () => {
+      if (done) return;
+      done = true;
+      await service.close();
+      resolve();
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  });
+}
+
+function printPluginUsage() {
+  process.stderr.write(
+    `${BOLD}PLUGIN COMMANDS${RESET}\n` +
+    `  ${CYAN}bahulam plugin <name> [path]${RESET}                Open a workspace with a plugin loaded\n` +
+    `  ${CYAN}bahulam plugin install <src>${RESET}                Install from git URL, tarball, local dir, or registry name\n` +
+    `  ${CYAN}bahulam plugin validate <path|name>${RESET}         Preflight without installing (schema + handlers + collisions)\n` +
+    `  ${CYAN}bahulam plugin list${RESET}                         List installed plugins\n` +
+    `  ${CYAN}bahulam plugin info <name>${RESET}                  Show manifest details\n` +
+    `  ${CYAN}bahulam plugin remove <name>${RESET}                Uninstall a plugin\n` +
+    `  ${CYAN}bahulam plugin enable|disable <name>${RESET}        Toggle without deleting\n` +
+    `  ${CYAN}bahulam plugin update <name>${RESET}                git pull the latest for git-installed plugins\n` +
+    `\n` +
+    `  ${DIM}Install source shapes:${RESET}\n` +
+    `    git URL          https://github.com/foo/bar.git\n` +
+    `    tarball URL      https://.../bar-1.0.0.tgz\n` +
+    `    local directory  ./my-plugin  or  /abs/path\n` +
+    `    registry name    seo-toolkit  (looked up in awesome-bahulam-plugins)\n` +
+    `\n` +
+    `  ${DIM}Options:${RESET}\n` +
+    `    --port <n>        (open) bind a specific localhost port\n` +
+    `    --no-open         (open) start service without opening the browser\n` +
+    `    --json            print machine-readable JSON\n` +
+    `    --project         install into <cwd>/.bahulam/plugins instead of ~/.bahulam/plugins\n` +
+    `    --global          install into ~/.bahulam/plugins (default)\n` +
+    `    --ref <tag|branch>  (install/update) pin a git ref\n` +
+    `    --force           overwrite existing install\n` +
+    `\n` +
+    `  ${DIM}Search paths (later overrides earlier):${RESET}\n` +
+    PLUGIN_SEARCH_DIRS.map(d => `    ${d}`).join('\n') + '\n' +
+    `\n` +
+    `  ${DIM}Example:${RESET}\n` +
+    `    bahulam plugin install https://github.com/community/seo-toolkit\n` +
+    `    bahulam plugin seo-toolkit ~/projects/client-site\n`
+  );
+}

package/src/config/cli-args.mjs

@@ -11,6 +11,8 @@
  * --max-turns          Maximum conversation turns
  * --allowedTools       Comma-separated allowed tools
  * --disallowedTools    Comma-separated denied tools
+ * --agent <slug>       Run a named agent (local deterministic graph)
+ * --workflow <name>    Run a named workflow (local deterministic graph)
  * --verbose, -v        Verbose output
  * --debug, -d          Debug mode
  * --version            Show version
@@ -34,6 +36,8 @@ export function parseArgs(args) {
         resumeSessionId: null,
         headless: false,
         skipPermissions: false,
+        agent: null,
+        workflow: null,
         vision: [],
         verbose: false,
         debug: false,
@@ -109,6 +113,14 @@ export function parseArgs(args) {
                 result.skipPermissions = true; // headless implies skip permissions
                 break;
 
+            case '--agent':
+                result.agent = args[++i];
+                break;
+
+            case '--workflow':
+                result.workflow = args[++i];
+                break;
+
             case '--cache-report':
                 // PRD-071 §1.5 — write a machine-readable cache summary to
                 // <path> at end of run. Consumed by benchmark/cache-check.sh.
@@ -184,6 +196,8 @@ Options:
   --disallowedTools <tools>  Comma-separated list of denied tools
   --resume, -r [sessionId]   Resume last session (or specific session)
   --continue                 Alias for --resume
+  --agent <slug>             Run a named agent as a deterministic local graph
+  --workflow <name>          Run a named workflow as a deterministic local graph
   --headless                 Non-interactive mode: auto-approve, JSONL output
   --cache-report <file>      Write prompt-cache summary JSON to <file> (headless only)
   --vision <image-path>      Attach image path in headless mode
@@ -197,6 +211,8 @@ Examples:
   occ                        Start interactive REPL
   occ -p "What is 2+2?"     Run prompt and exit
   occ -m claude-haiku-4-5    Use Haiku model
+  occ --agent explore -p "Map auth flow"  Run the explore agent headlessly
+  occ --workflow deploy -p "Deploy"       Run a workflow headlessly
   occ --debug -p "Fix bug"  Debug mode with prompt
 `.trim();
 }

package/src/config/env.mjs

@@ -116,6 +116,8 @@ export const ENV_SCHEMA = {
     // Extended: Plugins
     CLAUDE_CODE_PLUGIN_DIR: { type: 'string', description: 'Custom plugin directory' },
     CLAUDE_CODE_DISABLE_PLUGINS: { type: 'boolean', default: false, description: 'Disable all plugins' },
+    BAHULAM_PLUGIN_DIR: { type: 'string', description: 'Bahulam plugin directory (comma-separated paths)' },
+    BAHULAM_DISABLE_PLUGINS: { type: 'string', description: 'Comma-separated plugin names to disable' },
 
     // Extended: Session
     CLAUDE_CODE_SESSION_TTL: { type: 'number', default: 86400000, description: 'Session TTL in ms (default 24h)' },

package/src/config/hook-runner.mjs

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import * as path from 'node:path';
-import { loadKeplerSettings } from './settings-loader.mjs';
+import { loadBahulamSettings } from './settings-loader.mjs';
 
 function asArray(value) {
   if (!value) return [];
@@ -46,11 +46,11 @@ export class HookRunner {
   constructor({ cwd = process.cwd(), settings = null, sessionId = null } = {}) {
     this.cwd = cwd;
     this.sessionId = sessionId;
-    this.settings = settings || loadKeplerSettings({ cwd }).settings;
+    this.settings = settings || loadBahulamSettings({ cwd }).settings;
   }
 
   reload() {
-    this.settings = loadKeplerSettings({ cwd: this.cwd }).settings;
+    this.settings = loadBahulamSettings({ cwd: this.cwd }).settings;
   }
 
   hooksFor(event) {
@@ -74,11 +74,11 @@ export class HookRunner {
       const env = {
         ...process.env,
         ...(this.settings?.env || {}),
-        KEPLER_TOOL_NAME: toolName,
-        KEPLER_TOOL_INPUT_FILE_PATH: input.tool_input.file_path || input.tool_input.path || '',
-        KEPLER_PROJECT_DIR: this.cwd,
-        KEPLER_SESSION_ID: this.sessionId || '',
-        KEPLER_TURN_ID: payload.turnId || '',
+        BAHULAM_TOOL_NAME: toolName,
+        BAHULAM_TOOL_INPUT_FILE_PATH: input.tool_input.file_path || input.tool_input.path || '',
+        BAHULAM_PROJECT_DIR: this.cwd,
+        BAHULAM_SESSION_ID: this.sessionId || '',
+        BAHULAM_TURN_ID: payload.turnId || '',
       };
       const result = await runCommand(hook.command, {
         cwd: path.resolve(this.cwd),

package/src/config/memory-loader.mjs

@@ -17,15 +17,19 @@ function readIfExists(filePath, maxChars = 12000) {
   }
 }
 
+function readMemoryFile(dir, maxChars) {
+  return readIfExists(path.join(dir, 'BAHULAM.md'), maxChars);
+}
+
 export function loadBahulamMemory({ cwd = process.cwd() } = {}) {
   const files = [];
-  const global = readIfExists(path.join(bahulamHome(), 'KEPLER.md'));
+  const global = readMemoryFile(bahulamHome());
   if (global) files.push({ source: 'global', ...global });
 
-  const topLevel = readIfExists(path.join(cwd, 'KEPLER.md'));
+  const topLevel = readMemoryFile(cwd);
   if (topLevel) files.push({ source: 'project-top-level', ...topLevel });
 
-  const project = readIfExists(path.join(projectConfigDir(cwd), 'KEPLER.md'));
+  const project = readMemoryFile(projectConfigDir(cwd));
   if (project) files.push({ source: 'project', ...project });
 
   return files;

package/src/config/settings-loader.mjs

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { deepMerge } from '../core/policy-resolver.mjs';
 
-export const DEFAULT_KEPLER_SETTINGS = Object.freeze({
+export const DEFAULT_BAHULAM_SETTINGS = Object.freeze({
   env: {},
   permissions: {
     shellAllowlist: [],
@@ -16,6 +16,7 @@ export const DEFAULT_KEPLER_SETTINGS = Object.freeze({
   },
 });
 
+
 function readJson(filePath) {
   try {
     if (!fs.existsSync(filePath)) return null;
@@ -25,10 +26,10 @@ function readJson(filePath) {
   }
 }
 
-export function loadKeplerSettings({ cwd = process.cwd() } = {}) {
+export function loadBahulamSettings({ cwd = process.cwd() } = {}) {
   const base = path.join(cwd, '.bahulam');
   const layers = [
-    { name: 'default', path: null, data: DEFAULT_KEPLER_SETTINGS },
+    { name: 'default', path: null, data: DEFAULT_BAHULAM_SETTINGS },
   ];
   for (const [name, file] of [
     ['project', path.join(base, 'settings.json')],
@@ -43,3 +44,4 @@ export function loadKeplerSettings({ cwd = process.cwd() } = {}) {
   for (const layer of layers) settings = deepMerge(settings, layer.data || {});
   return { settings, layers };
 }
+

package/src/core/attachments.mjs

@@ -419,8 +419,8 @@ export function loadImageAttachment(filePath, { cwd = process.cwd(), maxBytes =
 export function prepareImageAttachments(input, {
   cwd = process.cwd(),
   extraPaths = [],
-  maxImageBytes = envInt('KEPLER_VISION_MAX_IMAGE_BYTES', DEFAULT_MAX_IMAGE_BYTES),
-  maxTurnBytes = envInt('KEPLER_VISION_MAX_TURN_BYTES', DEFAULT_MAX_TURN_BYTES),
+  maxImageBytes = envInt('BAHULAM_VISION_MAX_IMAGE_BYTES', DEFAULT_MAX_IMAGE_BYTES),
+  maxTurnBytes = envInt('BAHULAM_VISION_MAX_TURN_BYTES', DEFAULT_MAX_TURN_BYTES),
 } = {}) {
   const parsed = parseImageReferences(input, { cwd });
   const paths = [

package/src/core/background-tasks.mjs

@@ -0,0 +1,186 @@
+/**
+ * BackgroundTasks — the one registry for long-running processes the agent
+ * starts (docker build, npm run dev, test suites). Jobs get a run id,
+ * a per-job timeout with SIGTERM→SIGKILL escalation, output spooled to
+ * .bahulam/tmp/jobs/<id>.log (with a bounded in-memory tail), completion
+ * listeners for wake-on-finish delivery, and best-effort cleanup of the
+ * whole process group when the CLI exits.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const KILL_ESCALATION_MS = 5000;
+const MAX_TAIL_BYTES = 64 * 1024;
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return String(str || '').replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+class BackgroundTasks {
+  constructor() {
+    this.jobs = new Map();
+    this._seq = 0;
+    this._listeners = new Set();
+    this._exitHookInstalled = false;
+  }
+
+  onExit(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  start({ command, cwd = process.cwd(), timeoutMs = DEFAULT_TIMEOUT_MS, name = '', on_complete = null }) {
+    this._installExitHook();
+    const id = `job-${++this._seq}-${Date.now().toString(36)}`;
+    const logDir = path.join(cwd, '.bahulam', 'tmp', 'jobs');
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = path.join(logDir, `${id}.log`);
+    const logStream = fs.createWriteStream(logPath);
+
+    const proc = spawn('bash', ['-c', command], {
+      cwd,
+      env: { ...process.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+
+    const job = {
+      id,
+      name: name || command.slice(0, 60),
+      command,
+      cwd,
+      pid: proc.pid,
+      status: 'running',
+      exit_code: null,
+      started_at: Date.now(),
+      ended_at: null,
+      log_path: logPath,
+      tail: '',
+      timed_out: false,
+      on_complete,
+      _proc: proc,
+      _done: null,
+    };
+
+    const appendTail = (chunk) => {
+      const next = job.tail + chunk.toString();
+      job.tail = next.length > MAX_TAIL_BYTES ? next.slice(next.length - MAX_TAIL_BYTES) : next;
+    };
+    proc.stdout.on('data', (d) => { logStream.write(d); appendTail(d); });
+    proc.stderr.on('data', (d) => { logStream.write(d); appendTail(d); });
+
+    let killTimer = null;
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      job.timed_out = true;
+      this._kill(job, 'SIGTERM');
+      killTimer = setTimeout(() => this._kill(job, 'SIGKILL'), KILL_ESCALATION_MS);
+    }, timeoutMs) : null;
+    if (timer?.unref) timer.unref();
+
+    job._done = new Promise((resolve) => {
+      proc.on('close', (code) => {
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        job.exit_code = code;
+        job.ended_at = Date.now();
+        job.status = job.timed_out ? 'timeout'
+          : job.status === 'killed' ? 'killed'
+          : code === 0 ? 'completed' : 'failed';
+        job.tail = stripAnsi(job.tail);
+        logStream.end();
+        for (const listener of this._listeners) {
+          try { listener(this.describe(job.id)); } catch { /* listeners are best-effort */ }
+        }
+        resolve(this.describe(job.id));
+      });
+      proc.on('error', (err) => {
+        job.status = 'failed';
+        job.tail = `${job.tail}\n${err.message}`.trim();
+        job.ended_at = Date.now();
+        logStream.end();
+        resolve(this.describe(job.id));
+      });
+    });
+
+    proc.unref();
+    this.jobs.set(id, job);
+    return this.describe(id);
+  }
+
+  /** Await a job's completion; resolves with its final description. */
+  wait(id) {
+    const job = this.jobs.get(id);
+    if (!job) return Promise.resolve(null);
+    if (job.status !== 'running') return Promise.resolve(this.describe(id));
+    // Background jobs are unref'd so fire-and-forget tasks do not pin the CLI
+    // open. When a caller explicitly awaits wait(id), temporarily ref the
+    // process so fast commands still get their close event before Node decides
+    // the top-level await is unsettled.
+    try { job._proc?.ref?.(); } catch { /* best effort */ }
+    return job._done.finally(() => {
+      try { job._proc?.unref?.(); } catch { /* best effort */ }
+    });
+  }
+
+  describe(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    return {
+      id: job.id,
+      name: job.name,
+      command: job.command,
+      pid: job.pid,
+      status: job.status,
+      exit_code: job.exit_code,
+      duration_s: Math.round(((job.ended_at || Date.now()) - job.started_at) / 1000),
+      log_path: job.log_path,
+      tail: job.tail,
+      timed_out: job.timed_out,
+      on_complete: job.on_complete || null,
+    };
+  }
+
+  list() {
+    return [...this.jobs.keys()].map(id => {
+      const d = this.describe(id);
+      return { ...d, tail: undefined };
+    });
+  }
+
+  kill(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    if (job.status === 'running') {
+      job.status = 'killed';
+      this._kill(job, 'SIGTERM');
+      setTimeout(() => this._kill(job, 'SIGKILL'), KILL_ESCALATION_MS)?.unref?.();
+    }
+    return this.describe(id);
+  }
+
+  _kill(job, signal) {
+    if (!job?._proc?.pid) return;
+    try {
+      if (process.platform !== 'win32') {
+        process.kill(-job._proc.pid, signal);
+        return;
+      }
+    } catch { /* fall through */ }
+    try { job._proc.kill(signal); } catch { /* already exited */ }
+  }
+
+  _installExitHook() {
+    if (this._exitHookInstalled) return;
+    this._exitHookInstalled = true;
+    process.on('exit', () => {
+      for (const job of this.jobs.values()) {
+        if (job.status === 'running') this._kill(job, 'SIGKILL');
+      }
+    });
+  }
+}
+
+export const backgroundTasks = new BackgroundTasks();