@build-astron-co/nimbus 0.3.0 → 0.4.0

package/src/tools/schemas/standard.ts

@@ -26,7 +26,7 @@ const execAsync = promisify(exec);
  */
 function spawnAsync(
   command: string,
-  options: { timeout?: number; cwd?: string; maxBuffer?: number; signal?: AbortSignal }
+  options: { timeout?: number; cwd?: string; maxBuffer?: number; signal?: AbortSignal; onChunk?: (chunk: string) => void }
 ): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {
     const maxBuffer = options.maxBuffer ?? 10 * 1024 * 1024;
@@ -74,6 +74,7 @@ function spawnAsync(
     }
 
     child.stdout?.on('data', (data: Buffer) => {
+      options.onChunk?.(data.toString());
       if (stdout.length + data.length > maxBuffer) {
         stdoutOverflow = true;
         return;
@@ -82,6 +83,7 @@ function spawnAsync(
     });
 
     child.stderr?.on('data', (data: Buffer) => {
+      options.onChunk?.(data.toString());
       if (stderr.length + data.length > maxBuffer) {
         stderrOverflow = true;
         return;
@@ -550,11 +552,13 @@ export const bashTool: ToolDefinition = {
     try {
       const input = bashSchema.parse(raw);
       const signal = (raw as Record<string, unknown> | null)?._signal as AbortSignal | undefined;
+      const onChunk = (raw as Record<string, unknown>)?._onChunk as ((chunk: string) => void) | undefined;
       const { stdout, stderr } = await spawnAsync(input.command, {
         timeout: input.timeout,
         cwd: input.workdir,
         maxBuffer: 10 * 1024 * 1024, // 10 MB
         signal,
+        onChunk,
       });
       const combined = [stdout, stderr].filter(Boolean).join('\n');
       return ok(combined || '(no output)');

package/src/tools/schemas/types.ts

@@ -107,6 +107,35 @@ export interface ToolResult {
   isError: boolean;
 }
 
+// ---------------------------------------------------------------------------
+// Tool Execute Context
+// ---------------------------------------------------------------------------
+
+/** Context passed to tool execute() for streaming and cancellation. */
+export interface ToolExecuteContext {
+  /** Callback invoked with each chunk of streaming output. */
+  onProgress?: (chunk: string) => void;
+  /** AbortSignal for cancellation. */
+  signal?: AbortSignal;
+  /**
+   * GAP-20: Per-tool timeout override in milliseconds.
+   * When set, the tool should use this value instead of its built-in default timeout.
+   */
+  timeout?: number;
+  /**
+   * C2: Session infrastructure context — active terraform workspace, kubectl context, etc.
+   * Tools use this as a fallback when the user doesn't explicitly specify a workspace/context.
+   */
+  infraContext?: {
+    terraformWorkspace?: string;
+    kubectlContext?: string;
+    awsProfile?: string;
+    awsRegion?: string;
+    gcpProject?: string;
+    azureSubscription?: string;
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Tool Definition
 // ---------------------------------------------------------------------------
@@ -165,9 +194,10 @@ export interface ToolDefinition {
    * the failure back to the LLM gracefully.
    *
    * @param input - The validated (parsed) input object.
+   * @param ctx - Optional context for streaming output and cancellation.
    * @returns A promise resolving to the tool's output.
    */
-  execute: (input: unknown) => Promise<ToolResult>;
+  execute: (input: unknown, ctx?: ToolExecuteContext) => Promise<ToolResult>;
 
   /**
    * Which permission tier this tool belongs to. Determines whether the

package/src/tools/spawn-exec.ts

@@ -0,0 +1,148 @@
+/**
+ * Streaming subprocess wrapper.
+ *
+ * Replaces `promisify(exec)` for long-running DevOps commands (terraform,
+ * kubectl, helm, bash). Unlike `execAsync`, this streams stdout/stderr chunks
+ * in real-time via the `onChunk` callback so the TUI can show live output
+ * instead of a frozen spinner for multi-minute operations.
+ */
+
+import { spawn } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Secret redaction
+// ---------------------------------------------------------------------------
+
+const SECRET_PATTERNS = [
+  /AKIA[0-9A-Z]{16}/g,
+  /(?:password|secret|token|key)\s*[:=]\s*\S+/gi,
+  /Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+];
+
+function redactSecrets(text: string): string {
+  return SECRET_PATTERNS.reduce((t, p) => t.replace(p, '[REDACTED]'), text);
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SpawnResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface SpawnOptions {
+  /** Working directory for the subprocess. */
+  cwd?: string;
+  /** Environment variables (defaults to process.env). */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Called for each chunk of output (stdout + stderr interleaved).
+   * Chunks are flushed at most every 100ms to avoid excessive React renders.
+   */
+  onChunk?: (chunk: string) => void;
+  /** Milliseconds before the subprocess is killed. Default: no timeout. */
+  timeout?: number;
+  /** AbortSignal for cancellation (e.g. Ctrl+C from TUI). */
+  signal?: AbortSignal;
+  /** Human-readable label for timeout error messages (e.g. 'terraform'). M2 */
+  label?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a shell command and stream its output in real-time.
+ *
+ * - stdout and stderr are both captured and forwarded to `onChunk`.
+ * - The returned promise resolves with the full stdout, stderr, and exit code.
+ * - If `timeout` is set, the process is killed after that many milliseconds
+ *   and the promise rejects with a timeout error.
+ *
+ * @example
+ * ```ts
+ * const result = await spawnExec('terraform apply -auto-approve', {
+ *   cwd: '/infra/aws',
+ *   onChunk: (chunk) => process.stdout.write(chunk),
+ * });
+ * ```
+ */
+export async function spawnExec(
+  command: string,
+  options: SpawnOptions = {}
+): Promise<SpawnResult> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('sh', ['-c', command], {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    // Buffer chunks and flush every 100ms to avoid excessive re-renders
+    let buffer = '';
+    const flushInterval = setInterval(() => {
+      if (buffer && options.onChunk) {
+        options.onChunk(buffer);
+        buffer = '';
+      }
+    }, 100);
+
+    proc.stdout.on('data', (chunk: Buffer) => {
+      const text = chunk.toString();
+      stdout += text;
+      buffer += redactSecrets(text);
+    });
+
+    proc.stderr.on('data', (chunk: Buffer) => {
+      const text = chunk.toString();
+      stderr += text;
+      // C5: Prefix each stderr line with dim-red ANSI so ToolCallDisplay renders them distinctly
+      const tagged = text.split('\n').map(l => l ? `\x1b[2;31m${l}\x1b[0m` : l).join('\n');
+      buffer += tagged;
+    });
+
+    proc.on('close', (code) => {
+      clearInterval(flushInterval);
+      // Flush any remaining buffered content
+      if (buffer && options.onChunk) {
+        options.onChunk(buffer);
+        buffer = '';
+      }
+      resolve({ stdout, stderr, exitCode: code ?? 0 });
+    });
+
+    proc.on('error', (err) => {
+      clearInterval(flushInterval);
+      reject(err);
+    });
+
+    // GAP-9: AbortSignal support — kill process and reject on abort
+    if (options.signal) {
+      const abortHandler = () => {
+        try { proc.kill('SIGTERM'); } catch { /* ignore */ }
+        clearInterval(flushInterval);
+        reject(new Error('Operation cancelled by user (Ctrl+C)'));
+      };
+      options.signal.addEventListener('abort', abortHandler, { once: true });
+      proc.on('close', () => {
+        try { options.signal?.removeEventListener('abort', abortHandler); } catch { /* ignore */ }
+      });
+    }
+
+    if (options.timeout) {
+      setTimeout(() => {
+        proc.kill();
+        clearInterval(flushInterval);
+        const toolLabel = options.label ?? command.split(' ')[0];
+        const seconds = Math.round(options.timeout! / 1000);
+        reject(new Error(`[${toolLabel}] timed out after ${seconds}s. Override via NIMBUS.md "## Tool Timeouts".`));
+      }, options.timeout);
+    }
+  });
+}