@plures/runebook 0.4.0

package/src/lib/core/redaction.ts

@@ -0,0 +1,158 @@
+// Secret redaction utilities for terminal observer
+// Redacts sensitive information from environment variables and output
+
+/**
+ * Default patterns for secret detection
+ */
+const DEFAULT_SECRET_PATTERNS = [
+  /token/i,
+  /secret/i,
+  /password/i,
+  /api[_-]?key/i,
+  /auth[_-]?token/i,
+  /access[_-]?token/i,
+  /private[_-]?key/i,
+  /credential/i,
+  /bearer/i,
+  /session[_-]?id/i,
+  /cookie/i,
+];
+
+/**
+ * Redact a value, replacing it with a placeholder
+ * @param value - Value to redact
+ * @param fullRedaction - If true, always use [REDACTED]; if false, show first/last 4 chars for long values
+ */
+export function redactValue(value: string, fullRedaction: boolean = false): string {
+  if (!value || value.length === 0) {
+    return value;
+  }
+  
+  // If full redaction requested or value is short, use [REDACTED]
+  if (fullRedaction || value.length <= 8) {
+    return '[REDACTED]';
+  }
+  
+  // For longer values in partial redaction mode, show first 4 and last 4 chars
+  return `${value.substring(0, 4)}...${value.substring(value.length - 4)}`;
+}
+
+/**
+ * Check if a key matches secret patterns
+ */
+export function isSecretKey(key: string, customPatterns: string[] = []): boolean {
+  const allPatterns = [...DEFAULT_SECRET_PATTERNS];
+  
+  // Add custom patterns as regex
+  for (const pattern of customPatterns) {
+    try {
+      allPatterns.push(new RegExp(pattern, 'i'));
+    } catch (e) {
+      // Invalid regex pattern, skip
+      console.warn(`Invalid secret pattern: ${pattern}`);
+    }
+  }
+  
+  return allPatterns.some(pattern => pattern.test(key));
+}
+
+/**
+ * Sanitize environment variables by redacting secrets
+ */
+export function sanitizeEnv(
+  env: Record<string, string>,
+  customPatterns: string[] = []
+): Record<string, string> {
+  const sanitized: Record<string, string> = {};
+  
+  for (const [key, value] of Object.entries(env)) {
+    if (isSecretKey(key, customPatterns)) {
+      // Use full redaction for environment variables
+      sanitized[key] = '[REDACTED]';
+    } else {
+      sanitized[key] = value;
+    }
+  }
+  
+  return sanitized;
+}
+
+/**
+ * Redact secrets from a string (for stdout/stderr chunks)
+ */
+export function redactSecretsFromText(
+  text: string,
+  customPatterns: string[] = []
+): string {
+  if (!text) {
+    return text;
+  }
+  
+  // Common patterns for secrets in output
+  const outputPatterns = [
+    /(token|secret|password|api[_-]?key|auth[_-]?token|access[_-]?token)\s*[:=]\s*([^\s\n]{8,})/gi,
+    /(Bearer|bearer)\s+([A-Za-z0-9\-._~+/]+=*)/g,
+    /(-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+)?PRIVATE\s+KEY-----)/gi,
+  ];
+  
+  let redacted = text;
+  
+  // Apply default patterns
+  for (const pattern of outputPatterns) {
+    redacted = redacted.replace(pattern, (match, key, value) => {
+      if (value) {
+        return `${key}=[REDACTED]`;
+      }
+      return '[REDACTED]';
+    });
+  }
+  
+  // Apply custom patterns
+  for (const pattern of customPatterns) {
+    try {
+      const regex = new RegExp(pattern, 'gi');
+      redacted = redacted.replace(regex, '[REDACTED]');
+    } catch (e) {
+      // Invalid regex, skip
+      console.warn(`Invalid secret pattern: ${pattern}`);
+    }
+  }
+  
+  return redacted;
+}
+
+/**
+ * Validate that redaction is working correctly
+ */
+export function validateRedaction(): boolean {
+  const testEnv = {
+    PATH: '/usr/bin:/usr/local/bin',
+    HOME: '/home/user',
+    API_KEY: 'sk-1234567890abcdef',
+    TOKEN: 'secret-token-value',
+    NORMAL_VAR: 'normal-value',
+  };
+  
+  const sanitized = sanitizeEnv(testEnv);
+  
+  // Check that secrets are redacted
+  if (sanitized.API_KEY === testEnv.API_KEY) {
+    return false;
+  }
+  
+  if (sanitized.TOKEN === testEnv.TOKEN) {
+    return false;
+  }
+  
+  // Check that non-secrets are preserved
+  if (sanitized.PATH !== testEnv.PATH) {
+    return false;
+  }
+  
+  if (sanitized.HOME !== testEnv.HOME) {
+    return false;
+  }
+  
+  return true;
+}
+

package/src/lib/core/shell-adapters/base.ts

@@ -0,0 +1,325 @@
+// Base shell adapter interface
+// All shell adapters must implement this interface
+
+import type {
+  TerminalObserverEvent,
+  ObserverConfig,
+  ShellType,
+  CommandStartEvent,
+} from '../types';
+import type { EventStore } from '../storage';
+
+export interface ShellAdapter {
+  /**
+   * Get the shell type this adapter supports
+   */
+  getShellType(): ShellType;
+
+  /**
+   * Initialize the adapter with config and event store
+   */
+  initialize(config: ObserverConfig, store: EventStore): Promise<void>;
+
+  /**
+   * Start capturing events
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stop capturing events
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Check if the adapter is active
+   */
+  isActive(): boolean;
+
+  /**
+   * Get shell hook script (for integration into shell init files)
+   */
+  getHookScript(): string;
+}
+
+/**
+ * Base implementation with common functionality
+ */
+export abstract class BaseShellAdapter implements ShellAdapter {
+  protected config: ObserverConfig | null = null;
+  protected store: EventStore | null = null;
+  protected active = false;
+  protected currentCommandId: string | null = null;
+  protected commandStartTime: number = 0;
+  protected stdoutChunks: string[] = [];
+  protected stderrChunks: string[] = [];
+  protected stdoutChunkIndex = 0;
+  protected stderrChunkIndex = 0;
+
+  abstract getShellType(): ShellType;
+  abstract getHookScript(): string;
+
+  async initialize(config: ObserverConfig, store: EventStore): Promise<void> {
+    this.config = config;
+    this.store = store;
+  }
+
+  async start(): Promise<void> {
+    if (!this.config || !this.store) {
+      throw new Error('Adapter not initialized. Call initialize() first.');
+    }
+    
+    if (!this.config.enabled) {
+      return;
+    }
+    
+    this.active = true;
+    
+    // Emit session start event
+    await this.emitSessionStart();
+  }
+
+  async stop(): Promise<void> {
+    if (this.active) {
+      // Emit session end event
+      await this.emitSessionEnd();
+    }
+    this.active = false;
+  }
+
+  isActive(): boolean {
+    return this.active;
+  }
+
+  /**
+   * Generate a unique event ID
+   */
+  protected generateEventId(): string {
+    return `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Generate a unique command ID
+   */
+  protected generateCommandId(): string {
+    return `cmd_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Emit an event to the store
+   */
+  protected async emitEvent(event: TerminalObserverEvent): Promise<void> {
+    if (!this.store) {
+      return;
+    }
+    
+    await this.store.saveEvent(event);
+  }
+
+  /**
+   * Capture command start
+   */
+  protected async captureCommandStart(
+    command: string,
+    args: string[],
+    cwd: string,
+    env: Record<string, string>
+  ): Promise<string> {
+    if (!this.config || !this.store) {
+      throw new Error('Adapter not initialized');
+    }
+
+    const commandId = this.generateCommandId();
+    this.currentCommandId = commandId;
+    this.commandStartTime = Date.now();
+    this.stdoutChunks = [];
+    this.stderrChunks = [];
+    this.stdoutChunkIndex = 0;
+    this.stderrChunkIndex = 0;
+
+    const { sanitizeEnv } = await import('../redaction.js');
+    const envSummary = this.config.redactSecrets
+      ? sanitizeEnv(env, this.config.secretPatterns || [])
+      : env;
+
+    const event: CommandStartEvent = {
+      id: commandId,
+      type: 'command_start',
+      timestamp: this.commandStartTime,
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      command,
+      args,
+      cwd,
+      envSummary,
+    };
+
+    await this.emitEvent(event);
+    return commandId;
+  }
+
+  /**
+   * Capture command end
+   */
+  protected async captureCommandEnd(commandId: string): Promise<void> {
+    if (!this.config || !this.store) {
+      return;
+    }
+
+    const duration = Date.now() - this.commandStartTime;
+
+    await this.emitEvent({
+      id: this.generateEventId(),
+      type: 'command_end',
+      timestamp: Date.now(),
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      commandId,
+      duration,
+    });
+  }
+
+  /**
+   * Capture stdout chunk
+   */
+  protected async captureStdoutChunk(
+    commandId: string,
+    chunk: string
+  ): Promise<void> {
+    if (!this.config || !this.store) {
+      return;
+    }
+
+    const { redactSecretsFromText } = await import('../redaction.js');
+    const processedChunk = this.config.redactSecrets
+      ? redactSecretsFromText(chunk, this.config.secretPatterns || [])
+      : chunk;
+
+    await this.emitEvent({
+      id: this.generateEventId(),
+      type: 'stdout_chunk',
+      timestamp: Date.now(),
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      commandId,
+      chunk: processedChunk,
+      chunkIndex: this.stdoutChunkIndex++,
+    });
+  }
+
+  /**
+   * Capture stderr chunk
+   */
+  protected async captureStderrChunk(
+    commandId: string,
+    chunk: string
+  ): Promise<void> {
+    if (!this.config || !this.store) {
+      return;
+    }
+
+    const { redactSecretsFromText } = await import('../redaction.js');
+    const processedChunk = this.config.redactSecrets
+      ? redactSecretsFromText(chunk, this.config.secretPatterns || [])
+      : chunk;
+
+    await this.emitEvent({
+      id: this.generateEventId(),
+      type: 'stderr_chunk',
+      timestamp: Date.now(),
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      commandId,
+      chunk: processedChunk,
+      chunkIndex: this.stderrChunkIndex++,
+    });
+  }
+
+  /**
+   * Capture exit status
+   */
+  protected async captureExitStatus(
+    commandId: string,
+    exitCode: number
+  ): Promise<void> {
+    if (!this.config || !this.store) {
+      return;
+    }
+
+    await this.emitEvent({
+      id: this.generateEventId(),
+      type: 'exit_status',
+      timestamp: Date.now(),
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      commandId,
+      exitCode,
+      success: exitCode === 0,
+    });
+  }
+
+  /**
+   * Emit session start event
+   */
+  protected async emitSessionStart(): Promise<void> {
+    if (!this.config || !this.store) {
+      return;
+    }
+
+    const { sanitizeEnv } = await import('../redaction.js');
+    const envSummary = this.config.redactSecrets
+      ? sanitizeEnv(process.env as Record<string, string>, this.config.secretPatterns || [])
+      : (process.env as Record<string, string>);
+
+    await this.emitEvent({
+      id: this.generateEventId(),
+      type: 'session_start',
+      timestamp: Date.now(),
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      cwd: process.cwd(),
+      envSummary,
+    });
+  }
+
+  /**
+   * Emit session end event
+   */
+  protected async emitSessionEnd(): Promise<void> {
+    if (!this.config || !this.store) {
+      return;
+    }
+
+    const sessionStart = this.config.sessionId 
+      ? await this.store.getEventsBySession(this.config.sessionId, 1)
+      : [];
+    
+    const startEvent = sessionStart.find((e: TerminalObserverEvent) => e.type === 'session_start');
+    const duration = startEvent
+      ? Date.now() - startEvent.timestamp
+      : 0;
+
+    await this.emitEvent({
+      id: this.generateEventId(),
+      type: 'session_end',
+      timestamp: Date.now(),
+      sessionId: this.config.sessionId || 'unknown',
+      shellType: this.getShellType(),
+      paneId: this.config.paneId,
+      tabId: this.config.tabId,
+      duration,
+    });
+  }
+}
+

package/src/lib/core/shell-adapters/bash.ts

@@ -0,0 +1,110 @@
+// @ts-nocheck
+// Bash shell adapter for terminal observer
+// Provides hooks for capturing bash shell events
+
+import { BaseShellAdapter } from './base';
+import type { ShellType, ObserverConfig } from '../types';
+import type { EventStore } from '../storage';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export class BashAdapter extends BaseShellAdapter {
+  private hookScriptPath: string;
+
+  constructor() {
+    super();
+    this.hookScriptPath = join(homedir(), '.runebook', 'bash-hook.sh');
+  }
+
+  getShellType(): ShellType {
+    return 'bash';
+  }
+
+  getHookScript(): string {
+    // @ts-ignore - Shell script content, not TypeScript
+    return (
+      '# RuneBook Terminal Observer Hook for Bash\n' +
+      '# Add this to your ~/.bashrc or ~/.bash_profile\n\n' +
+      'if [ -n "$RUNBOOK_OBSERVER_ENABLED" ]; then\n' +
+      '  # Function to capture command start\n' +
+      '  __runebook_capture_start() {\n' +
+      '    local cmd="$1"\n' +
+      '    local args="${@:2}"\n' +
+      '    local cwd="$PWD"\n    \n' +
+      '    # Call runebook observer API (if available)\n' +
+      '    if command -v runebook >/dev/null 2>&1; then\n' +
+      '      runebook observer capture-start "$cmd" "$args" "$cwd" &\n' +
+      '    fi\n' +
+      '  }\n\n' +
+      '  # Function to capture command end\n' +
+      '  __runebook_capture_end() {\n' +
+      '    local exit_code=$?\n    \n' +
+      '    if command -v runebook >/dev/null 2>&1; then\n' +
+      '      runebook observer capture-end $exit_code &\n' +
+      '    fi\n    \n' +
+      '    return $exit_code\n' +
+      '  }\n\n' +
+      '  # Hook into command execution\n' +
+      '  trap \'__runebook_capture_start "$BASH_COMMAND"\' DEBUG\n' +
+      '  trap \'__runebook_capture_end\' ERR\n' +
+      'fi\n'
+    );
+  }
+
+  async initialize(config: ObserverConfig, store: EventStore): Promise<void> {
+    await super.initialize(config, store);
+  }
+
+  async start(): Promise<void> {
+    await super.start();
+  }
+
+  async stop(): Promise<void> {
+    await super.stop();
+  }
+
+  /**
+   * Programmatic capture - for use when shell hooks are not available
+   * This can be called from Node.js to capture command execution
+   */
+  async captureCommand(
+    command: string,
+    args: string[],
+    cwd: string,
+    env: Record<string, string>
+  ): Promise<string> {
+    return await this.captureCommandStart(command, args, cwd, env);
+  }
+
+  /**
+   * Programmatic capture of command result
+   */
+  async captureCommandResult(
+    commandId: string,
+    stdout: string,
+    stderr: string,
+    exitCode: number
+  ): Promise<void> {
+    // Split stdout/stderr into chunks if configured
+    const chunkSize = this.config?.chunkSize || 4096;
+    
+    // Capture stdout chunks
+    for (let i = 0; i < stdout.length; i += chunkSize) {
+      const chunk = stdout.substring(i, i + chunkSize);
+      await this.captureStdoutChunk(commandId, chunk);
+    }
+    
+    // Capture stderr chunks
+    for (let i = 0; i < stderr.length; i += chunkSize) {
+      const chunk = stderr.substring(i, i + chunkSize);
+      await this.captureStderrChunk(commandId, chunk);
+    }
+    
+    // Capture exit status
+    await this.captureExitStatus(commandId, exitCode);
+    
+    // Capture command end
+    await this.captureCommandEnd(commandId);
+  }
+}
+

package/src/lib/core/shell-adapters/index.ts

@@ -0,0 +1,62 @@
+// Shell adapter factory and utilities
+
+import { BashAdapter } from './bash';
+import { ZshAdapter } from './zsh';
+import type { ShellAdapter } from './base';
+import type { ShellType, ObserverConfig } from '../types';
+import type { EventStore } from '../storage';
+
+/**
+ * Detect the current shell type
+ */
+export function detectShellType(): ShellType {
+  const shell = process.env.SHELL || '';
+  
+  if (shell.includes('bash')) {
+    return 'bash';
+  }
+  
+  if (shell.includes('zsh')) {
+    return 'zsh';
+  }
+  
+  if (shell.includes('nu')) {
+    return 'nushell';
+  }
+  
+  return 'unknown';
+}
+
+/**
+ * Create a shell adapter for the specified shell type
+ */
+export function createShellAdapter(shellType?: ShellType): ShellAdapter {
+  const type = shellType || detectShellType();
+  
+  switch (type) {
+    case 'bash':
+      return new BashAdapter();
+    case 'zsh':
+      return new ZshAdapter();
+    case 'nushell':
+      // TODO: Implement nushell adapter
+      throw new Error('Nushell adapter not yet implemented');
+    default:
+      throw new Error(`Unsupported shell type: ${type}`);
+  }
+}
+
+/**
+ * Get all available shell adapters
+ */
+export function getAvailableAdapters(): ShellAdapter[] {
+  return [
+    new BashAdapter(),
+    new ZshAdapter(),
+    // Nushell adapter will be added later
+  ];
+}
+
+export { BashAdapter, ZshAdapter };
+export type { ShellAdapter } from './base';
+