@plures/runebook 0.4.0

package/src/lib/agent/analyzers/local-search.ts

@@ -0,0 +1,215 @@
+// Layer 2: Local Search Analyzer
+// Uses ripgrep to search repository and config files for relevant patterns
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import type { Analyzer, AnalysisContext, AnalysisSuggestion } from '../analysis-pipeline';
+import type { EventStore } from '../../core/types';
+
+/**
+ * Local search analyzer using ripgrep
+ */
+export class LocalSearchAnalyzer implements Analyzer {
+  name = 'local-search';
+  layer = 2;
+
+  async analyze(context: AnalysisContext, _store: EventStore): Promise<AnalysisSuggestion[]> {
+    const suggestions: AnalysisSuggestion[] = [];
+    
+    // Find repository root (look for .git, flake.nix, etc.)
+    const repoRoot = this.findRepoRoot(context.cwd);
+    if (!repoRoot) {
+      return suggestions; // Not in a repository
+    }
+
+    // Search for relevant patterns based on error
+    const stderr = context.stderr.toLowerCase();
+    
+    // Search for missing attributes in Nix files
+    if (stderr.includes('attribute') && (stderr.includes('missing') || stderr.includes('undefined'))) {
+      const attrMatch = context.stderr.match(/attribute ['"]([^'"]+)['"]/i);
+      if (attrMatch) {
+        const attrName = attrMatch[1];
+        const results = this.searchInRepo(repoRoot, attrName, ['*.nix', 'flake.nix']);
+        
+        if (results.length > 0) {
+          suggestions.push({
+            id: `suggestion_${Date.now()}_local_search_attr`,
+            type: 'tip',
+            priority: 'medium',
+            title: 'Found Attribute References',
+            description: `Found references to "${attrName}" in your repository. Check these files for context.`,
+            confidence: 0.7,
+            actionableSnippet: `# Found in files:\n${results.slice(0, 5).map(r => `# - ${r}`).join('\n')}`,
+            provenance: {
+              analyzer: this.name,
+              layer: this.layer,
+              timestamp: Date.now(),
+            },
+            timestamp: Date.now(),
+          });
+        }
+      }
+    }
+
+    // Search for template paths in flake-parts
+    if (stderr.includes('template') && (stderr.includes('path') || stderr.includes('not found'))) {
+      const results = this.searchInRepo(repoRoot, 'template', ['*.nix', 'flake.nix']);
+      
+      if (results.length > 0) {
+        suggestions.push({
+          id: `suggestion_${Date.now()}_local_search_template`,
+          type: 'tip',
+          priority: 'medium',
+          title: 'Found Template References',
+          description: 'Found template references in your Nix files. Check these for path configuration.',
+          confidence: 0.65,
+          actionableSnippet: `# Template references found in:\n${results.slice(0, 5).map(r => `# - ${r}`).join('\n')}`,
+          provenance: {
+            analyzer: this.name,
+            layer: this.layer,
+            timestamp: Date.now(),
+          },
+          timestamp: Date.now(),
+        });
+      }
+    }
+
+    // Search for environment variable references
+    if (context.stderr.includes('TOKEN') || context.stderr.includes('token')) {
+      const tokenMatch = context.stderr.match(/([A-Z_]+TOKEN)/);
+      if (tokenMatch) {
+        const tokenName = tokenMatch[1];
+        const results = this.searchInRepo(repoRoot, tokenName, ['*.sh', '*.env', '.env*', '*.nix']);
+        
+        if (results.length > 0) {
+          suggestions.push({
+            id: `suggestion_${Date.now()}_local_search_token`,
+            type: 'tip',
+            priority: 'medium',
+            title: 'Found Token References',
+            description: `Found references to ${tokenName} in your repository. Check these files for configuration.`,
+            confidence: 0.7,
+            actionableSnippet: `# ${tokenName} references found in:\n${results.slice(0, 5).map(r => `# - ${r}`).join('\n')}\n\n# Check if ${tokenName} is set:\necho $${tokenName}`,
+            provenance: {
+              analyzer: this.name,
+              layer: this.layer,
+              timestamp: Date.now(),
+            },
+            timestamp: Date.now(),
+          });
+        }
+      }
+    }
+
+    // Check for flake.nix and suggest checking it
+    const flakePath = join(repoRoot, 'flake.nix');
+    if (existsSync(flakePath) && stderr.includes('nix')) {
+      const flakeContent = readFileSync(flakePath, 'utf-8');
+      
+      // Check for common issues
+      if (stderr.includes('missing') && !flakeContent.includes('inputs')) {
+        suggestions.push({
+          id: `suggestion_${Date.now()}_local_search_flake`,
+          type: 'tip',
+          priority: 'medium',
+          title: 'Check flake.nix Configuration',
+          description: 'Your flake.nix may be missing inputs or outputs. Review the file structure.',
+          confidence: 0.6,
+          actionableSnippet: `# Review your flake.nix:
+cat ${flakePath}
+
+# Common structure:
+# {
+#   inputs = { ... };
+#   outputs = { ... };
+# }`,
+          provenance: {
+            analyzer: this.name,
+            layer: this.layer,
+            timestamp: Date.now(),
+          },
+          timestamp: Date.now(),
+        });
+      }
+    }
+
+    return suggestions;
+  }
+
+  /**
+   * Find repository root by looking for markers
+   */
+  private findRepoRoot(cwd: string): string | null {
+    let current = cwd;
+    const maxDepth = 10;
+    let depth = 0;
+
+    while (depth < maxDepth) {
+      // Check for common repository markers
+      if (existsSync(join(current, '.git')) ||
+          existsSync(join(current, 'flake.nix')) ||
+          existsSync(join(current, '.gitignore'))) {
+        return current;
+      }
+
+      const parent = dirname(current);
+      if (parent === current) {
+        break; // Reached filesystem root
+      }
+      current = parent;
+      depth++;
+    }
+
+    return null;
+  }
+
+  /**
+   * Search repository using ripgrep (or fallback to grep)
+   */
+  private searchInRepo(repoRoot: string, pattern: string, filePatterns: string[]): string[] {
+    try {
+      // Try ripgrep first
+      const rgPattern = filePatterns.map(p => `-g "${p}"`).join(' ');
+      const command = `rg -l "${pattern}" ${rgPattern} "${repoRoot}" 2>/dev/null || true`;
+      const output = execSync(command, { 
+        cwd: repoRoot,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024, // 1MB
+      });
+      
+      return output
+        .split('\n')
+        .filter(line => line.trim().length > 0)
+        .map(line => line.replace(repoRoot + '/', ''));
+    } catch (error) {
+      // Fallback to grep if ripgrep not available
+      try {
+        const grepPattern = filePatterns.map(p => `--include="${p}"`).join(' ');
+        const command = `grep -r -l "${pattern}" ${grepPattern} "${repoRoot}" 2>/dev/null || true`;
+        const output = execSync(command, {
+          cwd: repoRoot,
+          encoding: 'utf-8',
+          maxBuffer: 1024 * 1024,
+        });
+        
+        return output
+          .split('\n')
+          .filter(line => line.trim().length > 0)
+          .map(line => line.replace(repoRoot + '/', ''));
+      } catch (grepError) {
+        // Both failed, return empty
+        return [];
+      }
+    }
+  }
+}
+
+/**
+ * Create local search analyzer
+ */
+export function createLocalSearchAnalyzer(): Analyzer {
+  return new LocalSearchAnalyzer();
+}
+

package/src/lib/agent/capture.ts

@@ -0,0 +1,123 @@
+// Event capture system for Ambient Agent Mode
+// Captures terminal commands, outputs, and context
+
+import type { TerminalEvent, EventContext } from '../types/agent';
+
+let sessionId: string | null = null;
+let currentContext: EventContext | null = null;
+let captureEnabled = false;
+
+/**
+ * Initialize event capture with a session ID
+ */
+export function initCapture(sessionIdParam: string, context?: Partial<EventContext>): void {
+  sessionId = sessionIdParam;
+  currentContext = {
+    sessionId: sessionIdParam,
+    workingDirectory: context?.workingDirectory || '',
+    environment: context?.environment || {},
+    ...context,
+  };
+  captureEnabled = true;
+}
+
+/**
+ * Stop event capture
+ */
+export function stopCapture(): void {
+  captureEnabled = false;
+  sessionId = null;
+  currentContext = null;
+}
+
+/**
+ * Check if capture is enabled
+ */
+export function isCaptureEnabled(): boolean {
+  return captureEnabled && sessionId !== null;
+}
+
+/**
+ * Update the current context
+ */
+export function updateContext(updates: Partial<EventContext>): void {
+  if (currentContext) {
+    currentContext = { ...currentContext, ...updates };
+  }
+}
+
+/**
+ * Capture a terminal command execution
+ */
+export function captureCommand(
+  command: string,
+  args: string[],
+  env: Record<string, string>,
+  cwd: string,
+  startTime: number
+): TerminalEvent {
+  if (!isCaptureEnabled()) {
+    throw new Error('Capture not initialized. Call initCapture() first.');
+  }
+
+  return {
+    id: generateEventId(),
+    timestamp: startTime,
+    command,
+    args,
+    env,
+    cwd,
+    success: false, // Will be updated when result is captured
+    context: currentContext ? { ...currentContext } : undefined,
+  };
+}
+
+/**
+ * Capture command result
+ */
+export function captureResult(
+  event: TerminalEvent,
+  stdout: string,
+  stderr: string,
+  exitCode: number,
+  endTime: number
+): TerminalEvent {
+  const duration = endTime - event.timestamp;
+  const success = exitCode === 0;
+
+  // Update context with previous command
+  if (currentContext) {
+    currentContext.previousCommand = event.command;
+  }
+
+  return {
+    ...event,
+    stdout,
+    stderr,
+    exitCode,
+    duration,
+    success,
+  };
+}
+
+/**
+ * Generate a unique event ID
+ */
+function generateEventId(): string {
+  return `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Get current session ID
+ */
+export function getSessionId(): string | null {
+  return sessionId;
+}
+
+/**
+ * Get current context
+ */
+export function getContext(): EventContext | null {
+  return currentContext;
+}
+

package/src/lib/agent/index.ts

@@ -0,0 +1,244 @@
+// Main Ambient Agent Mode coordinator
+// Orchestrates event capture, storage, analysis, and suggestions
+
+import { initCapture, stopCapture, captureCommand, captureResult, updateContext } from './capture';
+import { createStorage, type EventStorage } from './memory';
+import { createAnalyzer, type Analyzer } from './analysis';
+import { MemorySuggestionStore, formatSuggestionsForCLI, type SuggestionStore } from './suggestions';
+import { updateAgentStatus, getAgentStatus } from './status';
+import type { TerminalEvent, AgentConfig, Suggestion } from '../types/agent';
+
+export class AmbientAgent {
+  private storage: EventStorage;
+  private analyzer: Analyzer;
+  private suggestionStore: SuggestionStore;
+  private config: AgentConfig;
+  private sessionId: string;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.storage = createStorage(config);
+    this.analyzer = createAnalyzer();
+    
+    // Initialize with MemorySuggestionStore (browser-safe)
+    this.suggestionStore = new MemorySuggestionStore();
+    
+    // In Node.js environment, upgrade to file-based store
+    if (typeof process !== 'undefined' && process.versions?.node) {
+      import('./node-suggestions').then(({ FileSuggestionStore }) => {
+        this.suggestionStore = new FileSuggestionStore();
+        this.suggestionStore.load().catch(err => 
+          console.error('Failed to load suggestions:', err)
+        );
+      }).catch(() => {
+        // Fallback already initialized with MemorySuggestionStore
+        console.warn('FileSuggestionStore not available, using MemorySuggestionStore');
+      });
+    }
+
+    if (config.enabled && config.captureEvents) {
+      initCapture(this.sessionId, {
+        workingDirectory: process.cwd?.() || '',
+        environment: process.env as Record<string, string>,
+      });
+    }
+    
+    // Initialize status
+    updateAgentStatus({ status: 'idle' });
+  }
+
+  /**
+   * Capture and analyze a terminal command execution
+   */
+  async captureAndAnalyze(
+    command: string,
+    args: string[],
+    env: Record<string, string>,
+    cwd: string,
+    startTime: number
+  ): Promise<TerminalEvent> {
+    if (!this.config.enabled || !this.config.captureEvents) {
+      throw new Error('Agent not enabled or capture disabled');
+    }
+
+    const event = captureCommand(command, args, env, cwd, startTime);
+    return event;
+  }
+
+  /**
+   * Record command result and generate suggestions
+   */
+  async recordResult(
+    event: TerminalEvent,
+    stdout: string,
+    stderr: string,
+    exitCode: number,
+    endTime: number
+  ): Promise<Suggestion[]> {
+    if (!this.config.enabled || !this.config.captureEvents) {
+      return [];
+    }
+
+    // Update status to analyzing
+    updateAgentStatus({ 
+      status: 'analyzing',
+      lastCommand: event.command,
+      lastCommandTimestamp: event.timestamp,
+    });
+
+    const completedEvent = captureResult(event, stdout, stderr, exitCode, endTime);
+    
+    // Save to storage
+    await this.storage.saveEvent(completedEvent);
+
+    // Update context
+    updateContext({
+      previousCommand: completedEvent.command,
+      workingDirectory: completedEvent.cwd,
+    });
+
+    // Analyze and generate suggestions
+    let suggestions: Suggestion[] = [];
+    if (this.config.analyzePatterns && this.config.suggestImprovements) {
+      suggestions = await this.analyzer.analyzeEvent(completedEvent, this.storage);
+      
+      for (const suggestion of suggestions) {
+        this.suggestionStore.add(suggestion);
+      }
+    }
+
+    // Update status based on suggestions
+    const allSuggestions = this.suggestionStore.suggestions;
+    const highPriorityCount = allSuggestions.filter(s => s.priority === 'high').length;
+    const status = highPriorityCount > 0 ? 'issues_found' : 'idle';
+    
+    updateAgentStatus({
+      status,
+      suggestionCount: allSuggestions.length,
+      highPriorityCount,
+      lastCommand: event.command,
+      lastCommandTimestamp: event.timestamp,
+    });
+
+    return suggestions;
+  }
+
+  /**
+   * Get current suggestions
+   */
+  getSuggestions(priority?: 'low' | 'medium' | 'high'): Suggestion[] {
+    if (priority) {
+      return this.suggestionStore.getByPriority(priority);
+    }
+    return this.suggestionStore.suggestions;
+  }
+
+  /**
+   * Get suggestions formatted for CLI
+   */
+  getSuggestionsCLI(priority?: 'low' | 'medium' | 'high'): string {
+    const suggestions = this.getSuggestions(priority);
+    return formatSuggestionsForCLI(suggestions);
+  }
+
+  /**
+   * Get suggestions for the last command
+   */
+  getSuggestionsForLastCommand(): Suggestion[] {
+    const status = getAgentStatus();
+    if (!status.lastCommand) {
+      return [];
+    }
+    return this.suggestionStore.getForCommand(status.lastCommand);
+  }
+
+  /**
+   * Get top suggestion
+   */
+  getTopSuggestion(limit: number = 1): Suggestion[] {
+    return this.suggestionStore.getTop(limit);
+  }
+
+  /**
+   * Analyze all patterns and generate suggestions
+   */
+  async analyzeAllPatterns(): Promise<Suggestion[]> {
+    if (!this.config.enabled || !this.config.analyzePatterns) {
+      return [];
+    }
+
+    const suggestions = await this.analyzer.analyzePatterns(this.storage);
+    
+    for (const suggestion of suggestions) {
+      this.suggestionStore.add(suggestion);
+    }
+
+    return suggestions;
+  }
+
+  /**
+   * Get storage statistics
+   */
+  async getStats() {
+    return await this.storage.getStats();
+  }
+
+  /**
+   * Get recent events
+   */
+  async getRecentEvents(limit: number = 10): Promise<TerminalEvent[]> {
+    return await this.storage.getEvents(limit);
+  }
+
+  /**
+   * Clear old events
+   */
+  async clearOldEvents(days: number = 30): Promise<void> {
+    const cutoff = Date.now() - (days * 24 * 60 * 60 * 1000);
+    await this.storage.clearEvents(cutoff);
+  }
+
+  /**
+   * Stop the agent
+   */
+  stop(): void {
+    stopCapture();
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(updates: Partial<AgentConfig>): void {
+    this.config = { ...this.config, ...updates };
+    
+    if (!this.config.enabled) {
+      stopCapture();
+    } else if (this.config.captureEvents) {
+      initCapture(this.sessionId, {
+        workingDirectory: process.cwd?.() || '',
+        environment: process.env as Record<string, string>,
+      });
+    }
+  }
+}
+
+/**
+ * Create an Ambient Agent instance
+ */
+export function createAgent(config: AgentConfig): AmbientAgent {
+  return new AmbientAgent(config);
+}
+
+/**
+ * Default agent configuration
+ */
+export const defaultAgentConfig: AgentConfig = {
+  enabled: false, // Opt-in by default
+  captureEvents: true,
+  analyzePatterns: true,
+  suggestImprovements: true,
+  maxEvents: 10000,
+  retentionDays: 30,
+};
+

package/src/lib/agent/integration.ts

@@ -0,0 +1,81 @@
+// Integration layer for Ambient Agent Mode
+// Connects agent to terminal execution
+
+import { createAgent, defaultAgentConfig, type AmbientAgent } from './index';
+import type { AgentConfig, TerminalEvent } from '../types/agent';
+
+let agentInstance: AmbientAgent | null = null;
+let agentConfig: AgentConfig = { ...defaultAgentConfig };
+
+/**
+ * Initialize the agent (opt-in)
+ */
+export function initAgent(config?: Partial<AgentConfig>): AmbientAgent {
+  agentConfig = { ...defaultAgentConfig, ...config };
+  agentInstance = createAgent(agentConfig);
+  return agentInstance;
+}
+
+/**
+ * Get the current agent instance
+ */
+export function getAgent(): AmbientAgent | null {
+  return agentInstance;
+}
+
+/**
+ * Check if agent is enabled
+ */
+export function isAgentEnabled(): boolean {
+  return agentInstance !== null && agentConfig.enabled;
+}
+
+/**
+ * Capture terminal command before execution
+ */
+export async function captureCommandStart(
+  command: string,
+  args: string[],
+  env: Record<string, string>,
+  cwd: string
+): Promise<TerminalEvent | null> {
+  if (!isAgentEnabled()) {
+    return null;
+  }
+
+  const startTime = Date.now();
+  return await agentInstance!.captureAndAnalyze(command, args, env, cwd, startTime);
+}
+
+/**
+ * Capture terminal command result
+ */
+export async function captureCommandResult(
+  event: TerminalEvent | null,
+  stdout: string,
+  stderr: string,
+  exitCode: number
+): Promise<void> {
+  if (!isAgentEnabled() || !event) {
+    return;
+  }
+
+  const endTime = Date.now();
+  const suggestions = await agentInstance!.recordResult(event, stdout, stderr, exitCode, endTime);
+  
+  // Log suggestions if any (can be enhanced to show in UI)
+  if (suggestions.length > 0 && agentConfig.suggestImprovements) {
+    console.log('Agent suggestions:', suggestions);
+  }
+}
+
+/**
+ * Stop the agent
+ */
+export function stopAgent(): void {
+  if (agentInstance) {
+    agentInstance.stop();
+    agentInstance = null;
+  }
+}
+