@build-astron-co/nimbus 0.2.0

package/src/hooks/engine.ts

@@ -0,0 +1,391 @@
+/**
+ * Hook Execution Engine
+ *
+ * Executes user-defined hooks before and after tool invocations.
+ * Hook scripts receive JSON context on stdin and communicate results
+ * via exit codes:
+ *
+ *   - Exit 0  = allow (proceed with the tool call)
+ *   - Exit 2  = block (prevent the tool call; stderr/stdout used as message)
+ *   - Other   = error (proceed but log a warning)
+ *
+ * Hooks are killed after their configured timeout (default 30 seconds).
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import {
+  loadHooksConfig,
+  DEFAULT_HOOK_TIMEOUT,
+  type HooksConfig,
+  type HookEvent,
+  type HookDefinition,
+} from './config';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Context passed to hook scripts as JSON via stdin.
+ *
+ * For `PostToolUse` hooks the `result` field is populated with the
+ * tool's output and error status.
+ */
+export interface HookContext {
+  /** Name of the tool being invoked (e.g. "edit_file", "terraform") */
+  tool: string;
+  /** Input parameters supplied to the tool */
+  input: Record<string, unknown>;
+  /** Current session identifier */
+  sessionId: string;
+  /** Agent mode that triggered the call */
+  agent: string;
+  /** ISO 8601 timestamp of the event */
+  timestamp: string;
+  /** Tool output -- only present for PostToolUse events */
+  result?: { output: string; isError: boolean };
+}
+
+/**
+ * Outcome of a single hook execution.
+ */
+export interface HookResult {
+  /** Whether the tool call should proceed (`true`) or be blocked (`false`) */
+  allowed: boolean;
+  /** Human-readable message from the hook (stderr, or stdout when blocked) */
+  message?: string;
+  /** Process exit code (0 = allow, 2 = block, other = error) */
+  exitCode: number;
+  /** Wall-clock duration of the hook execution in milliseconds */
+  duration: number;
+}
+
+// ---------------------------------------------------------------------------
+// HookEngine
+// ---------------------------------------------------------------------------
+
+/**
+ * Core engine that loads hook configuration and executes matching hooks.
+ *
+ * @example
+ * ```ts
+ * const engine = new HookEngine('/path/to/project');
+ *
+ * const results = await engine.executeHooks('PreToolUse', {
+ *   tool: 'edit_file',
+ *   input: { path: 'main.tf' },
+ *   sessionId: 'abc-123',
+ *   agent: 'build',
+ *   timestamp: new Date().toISOString(),
+ * });
+ *
+ * if (results.some(r => !r.allowed)) {
+ *   console.log('Tool call blocked by hook');
+ * }
+ * ```
+ */
+export class HookEngine {
+  private config: HooksConfig | null = null;
+
+  /**
+   * Create a new HookEngine, optionally loading config immediately.
+   *
+   * @param projectDir - If provided, loads `.nimbus/hooks.yaml` from this directory
+   */
+  constructor(projectDir?: string) {
+    if (projectDir) {
+      this.loadConfig(projectDir);
+    }
+  }
+
+  /**
+   * Load (or reload) hooks configuration from disk.
+   *
+   * @param projectDir - Absolute path to the project root
+   */
+  loadConfig(projectDir: string): void {
+    this.config = loadHooksConfig(projectDir);
+  }
+
+  /**
+   * Check whether any hooks are registered for the given event and tool name.
+   *
+   * @param event    - Hook lifecycle event
+   * @param toolName - Name of the tool being invoked
+   * @returns `true` if at least one hook matches
+   */
+  hasHooks(event: HookEvent, toolName: string): boolean {
+    return this.getMatchingHooks(event, toolName).length > 0;
+  }
+
+  /**
+   * Return all hook definitions whose `match` pattern matches the tool name.
+   *
+   * @param event    - Hook lifecycle event
+   * @param toolName - Name of the tool being invoked
+   * @returns Array of matching hook definitions (may be empty)
+   */
+  getMatchingHooks(event: HookEvent, toolName: string): HookDefinition[] {
+    if (!this.config) {
+      return [];
+    }
+
+    const hooks = this.config.hooks[event];
+    if (!hooks || hooks.length === 0) {
+      return [];
+    }
+
+    return hooks.filter(hook => {
+      try {
+        const regex = new RegExp(hook.match);
+        return regex.test(toolName);
+      } catch {
+        // Invalid regex -- skip silently (was validated at load time,
+        // but be defensive)
+        return false;
+      }
+    });
+  }
+
+  /**
+   * Execute all hooks matching the given event and tool name.
+   *
+   * Hooks are executed sequentially in definition order. For `PreToolUse`
+   * events, if **any** hook returns exit code 2 the tool call is blocked
+   * (but remaining hooks still execute for auditing purposes).
+   *
+   * @param event   - Hook lifecycle event
+   * @param context - Context object passed to each hook via stdin
+   * @returns Array of results, one per matching hook
+   */
+  async executeHooks(event: HookEvent, context: HookContext): Promise<HookResult[]> {
+    const hooks = this.getMatchingHooks(event, context.tool);
+    if (hooks.length === 0) {
+      return [];
+    }
+
+    const results: HookResult[] = [];
+    for (const hook of hooks) {
+      const result = await this.executeHook(hook, context);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Execute a single hook definition.
+   *
+   * The hook command is spawned as a child process using `spawn` with
+   * `shell: true` and `detached: true` so that the entire process group
+   * can be killed on timeout. The JSON-serialised `HookContext` is
+   * written to the process's stdin.
+   *
+   * Exit code semantics:
+   *   - 0:     allowed (proceed)
+   *   - 2:     blocked (do not proceed; message taken from stderr then stdout)
+   *   - other: treated as an error; tool call is still allowed but a
+   *            warning should be logged by the caller
+   *
+   * @param hook    - Hook definition to execute
+   * @param context - Context to pass via stdin
+   * @returns Execution result
+   */
+  private async executeHook(hook: HookDefinition, context: HookContext): Promise<HookResult> {
+    const timeout = hook.timeout ?? DEFAULT_HOOK_TIMEOUT;
+    const startTime = Date.now();
+
+    return new Promise<HookResult>(resolve => {
+      let child: ChildProcess;
+      let timedOut = false;
+      let resolved = false;
+      // eslint-disable-next-line prefer-const
+      let timer: ReturnType<typeof setTimeout> | undefined;
+
+      /**
+       * Resolve exactly once, clearing the timeout timer.
+       */
+      const resolveOnce = (result: HookResult): void => {
+        if (resolved) {
+          return;
+        }
+        resolved = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        resolve(result);
+      };
+
+      try {
+        child = spawn(hook.command, {
+          shell: true,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          detached: true, // Creates a process group for clean cleanup
+          env: {
+            ...process.env,
+            NIMBUS_HOOK_EVENT: context.tool,
+            NIMBUS_HOOK_AGENT: context.agent,
+            NIMBUS_HOOK_SESSION: context.sessionId,
+          },
+        });
+      } catch (spawnError: unknown) {
+        const duration = Date.now() - startTime;
+        resolveOnce({
+          allowed: true,
+          message: `Failed to spawn hook command "${hook.command}": ${
+            spawnError instanceof Error ? spawnError.message : String(spawnError)
+          }`,
+          exitCode: 1,
+          duration,
+        });
+        return;
+      }
+
+      // Write context JSON to stdin
+      try {
+        if (child.stdin) {
+          child.stdin.write(JSON.stringify(context));
+          child.stdin.end();
+        }
+      } catch {
+        // stdin may already be closed -- ignore
+      }
+
+      // Collect stdout and stderr
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout?.on('data', (data: Buffer | string) => {
+        stdout += String(data);
+      });
+
+      child.stderr?.on('data', (data: Buffer | string) => {
+        stderr += String(data);
+      });
+
+      // Timeout handler -- kill the entire process group
+      timer = setTimeout(() => {
+        timedOut = true;
+        try {
+          // Negative PID kills the entire process group
+          if (child.pid) {
+            process.kill(-child.pid, 'SIGKILL');
+          }
+        } catch {
+          // Process group may already have exited
+          try {
+            child.kill('SIGKILL');
+          } catch {
+            // Already dead
+          }
+        }
+      }, timeout);
+
+      child.on('close', (code: number | null) => {
+        const duration = Date.now() - startTime;
+        const exitCode = code ?? 1;
+
+        if (timedOut) {
+          resolveOnce({
+            allowed: true,
+            message: `Hook "${hook.command}" timed out after ${timeout}ms`,
+            exitCode: 1,
+            duration,
+          });
+          return;
+        }
+
+        if (exitCode === 0) {
+          // Allowed
+          resolveOnce({
+            allowed: true,
+            message: stderr.trim() || stdout.trim() || undefined,
+            exitCode: 0,
+            duration,
+          });
+        } else if (exitCode === 2) {
+          // Blocked
+          const message = stderr.trim() || stdout.trim() || 'Blocked by hook';
+          resolveOnce({
+            allowed: false,
+            message,
+            exitCode: 2,
+            duration,
+          });
+        } else {
+          // Error -- allow but surface the message
+          const message =
+            stderr.trim() || stdout.trim() || `Hook "${hook.command}" exited with code ${exitCode}`;
+          resolveOnce({
+            allowed: true,
+            message,
+            exitCode,
+            duration,
+          });
+        }
+      });
+
+      child.on('error', (err: Error) => {
+        const duration = Date.now() - startTime;
+        resolveOnce({
+          allowed: true,
+          message: `Hook "${hook.command}" error: ${err.message}`,
+          exitCode: 1,
+          duration,
+        });
+      });
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all `PreToolUse` hooks and return an aggregate allow/block decision.
+ *
+ * If **any** hook returns `allowed: false` (exit code 2), the overall result
+ * is blocked and the first blocking message is returned.
+ *
+ * @param engine  - Configured HookEngine instance
+ * @param context - Hook context for the current tool invocation
+ * @returns Object indicating whether the tool call should proceed
+ */
+export async function runPreToolHooks(
+  engine: HookEngine,
+  context: HookContext
+): Promise<{ allowed: boolean; message?: string }> {
+  const results = await engine.executeHooks('PreToolUse', context);
+
+  for (const result of results) {
+    if (!result.allowed) {
+      return { allowed: false, message: result.message };
+    }
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Run all `PostToolUse` hooks. Results are intentionally discarded since
+ * post-tool hooks are informational/side-effect-only (e.g. auto-formatting,
+ * logging).
+ *
+ * @param engine  - Configured HookEngine instance
+ * @param context - Hook context including `result` from the tool execution
+ */
+export async function runPostToolHooks(engine: HookEngine, context: HookContext): Promise<void> {
+  await engine.executeHooks('PostToolUse', context);
+}
+
+/**
+ * Run all `PermissionRequest` hooks. These are fire-and-forget audit hooks
+ * that are invoked when a permission escalation is requested.
+ *
+ * @param engine  - Configured HookEngine instance
+ * @param context - Hook context for the permission request
+ */
+export async function runPermissionHooks(engine: HookEngine, context: HookContext): Promise<void> {
+  await engine.executeHooks('PermissionRequest', context);
+}

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { HookEngine, runPreToolHooks, runPostToolHooks, runPermissionHooks } from './engine';
+export type { HookContext, HookResult } from './engine';
+export { loadHooksConfig, validateHookDefinition } from './config';
+export type { HooksConfig, HookEvent, HookDefinition } from './config';

package/src/llm/auth-bridge.ts

@@ -0,0 +1,198 @@
+/**
+ * Auth Bridge - API Key Resolution from ~/.nimbus/auth.json
+ *
+ * Provides synchronous API key and base URL resolution for LLM provider constructors.
+ * Uses fs.readFileSync for constructor compatibility (constructors can't be async).
+ * Implements caching to avoid repeated file reads.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import type { LLMProviderName } from '../auth/types';
+
+/**
+ * Provider credential from auth file
+ */
+interface LLMProviderCredential {
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+}
+
+/**
+ * Auth file structure (partial - only what we need)
+ */
+interface AuthFile {
+  version: number;
+  providers: Partial<Record<LLMProviderName, LLMProviderCredential>>;
+}
+
+/**
+ * Cache for auth file to avoid repeated reads
+ */
+let authFileCache: AuthFile | null = null;
+let cacheTimestamp: number = 0;
+const CACHE_TTL_MS = 5000; // 5 second cache TTL
+
+/**
+ * Get the path to the auth file
+ */
+function getAuthFilePath(): string {
+  return path.join(os.homedir(), '.nimbus', 'auth.json');
+}
+
+/**
+ * Load auth file synchronously with caching
+ */
+function loadAuthFile(): AuthFile | null {
+  const now = Date.now();
+
+  // Return cached version if still valid
+  if (authFileCache && now - cacheTimestamp < CACHE_TTL_MS) {
+    return authFileCache;
+  }
+
+  const authPath = getAuthFilePath();
+
+  try {
+    if (!fs.existsSync(authPath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(authPath, 'utf-8');
+    const parsed = JSON.parse(content) as AuthFile;
+
+    // Update cache
+    authFileCache = parsed;
+    cacheTimestamp = now;
+
+    return parsed;
+  } catch {
+    // File doesn't exist or is invalid
+    return null;
+  }
+}
+
+/**
+ * Get API key for a provider
+ *
+ * Resolution order:
+ * 1. auth.json provider credential
+ * 2. Environment variable (fallback)
+ *
+ * @param providerName - The provider name
+ * @returns API key or undefined
+ */
+export function getProviderApiKey(providerName: LLMProviderName): string | undefined {
+  // Try auth.json first
+  const authFile = loadAuthFile();
+  const credential = authFile?.providers?.[providerName];
+
+  if (credential?.apiKey) {
+    return credential.apiKey;
+  }
+
+  // Fall back to environment variables
+  const envVarMap: Partial<Record<LLMProviderName, string | undefined>> = {
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+    google: process.env.GOOGLE_API_KEY,
+    openrouter: process.env.OPENROUTER_API_KEY,
+    ollama: undefined,
+    groq: process.env.GROQ_API_KEY,
+    together: process.env.TOGETHER_API_KEY,
+    deepseek: process.env.DEEPSEEK_API_KEY,
+    fireworks: process.env.FIREWORKS_API_KEY,
+    perplexity: process.env.PERPLEXITY_API_KEY,
+  };
+
+  return envVarMap[providerName];
+}
+
+/**
+ * Get base URL for a provider
+ *
+ * Resolution order:
+ * 1. auth.json provider credential
+ * 2. Environment variable (fallback)
+ * 3. Default value
+ *
+ * @param providerName - The provider name
+ * @returns Base URL or undefined
+ */
+export function getProviderBaseUrl(providerName: LLMProviderName): string | undefined {
+  // Try auth.json first
+  const authFile = loadAuthFile();
+  const credential = authFile?.providers?.[providerName];
+
+  if (credential?.baseUrl) {
+    return credential.baseUrl;
+  }
+
+  // Fall back to environment variables for Ollama
+  if (providerName === 'ollama') {
+    return process.env.OLLAMA_BASE_URL;
+  }
+
+  return undefined;
+}
+
+/**
+ * Get the configured model for a provider
+ *
+ * @param providerName - The provider name
+ * @returns Model ID or undefined
+ */
+export function getProviderModel(providerName: LLMProviderName): string | undefined {
+  const authFile = loadAuthFile();
+  return authFile?.providers?.[providerName]?.model;
+}
+
+/**
+ * Check if a provider is configured (auth.json or env vars)
+ *
+ * @param providerName - The provider name
+ * @returns true if provider has credentials in auth.json or env vars
+ */
+export function isProviderConfigured(providerName: LLMProviderName): boolean {
+  // Check auth.json first
+  const authFile = loadAuthFile();
+  const credential = authFile?.providers?.[providerName];
+
+  if (credential) {
+    // For Ollama, just needs to exist (no API key required)
+    if (providerName === 'ollama') {
+      return true;
+    }
+    // For others, needs an API key in auth.json
+    if (credential.apiKey) {
+      return true;
+    }
+  }
+
+  // Fall back to environment variables
+  const envVarMap: Partial<Record<LLMProviderName, string | undefined>> = {
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+    google: process.env.GOOGLE_API_KEY,
+    openrouter: process.env.OPENROUTER_API_KEY,
+    ollama: process.env.OLLAMA_BASE_URL,
+    groq: process.env.GROQ_API_KEY,
+    together: process.env.TOGETHER_API_KEY,
+    deepseek: process.env.DEEPSEEK_API_KEY,
+    fireworks: process.env.FIREWORKS_API_KEY,
+    perplexity: process.env.PERPLEXITY_API_KEY,
+  };
+
+  return !!envVarMap[providerName];
+}
+
+/**
+ * Clear the auth file cache
+ * Useful for testing or when auth.json is known to have changed
+ */
+export function clearAuthCache(): void {
+  authFileCache = null;
+  cacheTimestamp = 0;
+}