@plures/runebook 0.4.0

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

@@ -0,0 +1,105 @@
+// @ts-nocheck
+// Zsh shell adapter for terminal observer
+// Provides hooks for capturing zsh 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 ZshAdapter extends BaseShellAdapter {
+  private hookScriptPath: string;
+
+  constructor() {
+    super();
+    this.hookScriptPath = join(homedir(), '.runebook', 'zsh-hook.sh');
+  }
+
+  getShellType(): ShellType {
+    return 'zsh';
+  }
+
+  getHookScript(): string {
+    // @ts-ignore - Shell script content, not TypeScript
+    return (
+      '# RuneBook Terminal Observer Hook for Zsh\n' +
+      '# Add this to your ~/.zshrc\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 using zsh hooks\n' +
+      '  preexec_functions+=(__runebook_capture_start)\n' +
+      '  precmd_functions+=(__runebook_capture_end)\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
+   */
+  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> {
+    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);
+    }
+    
+    await this.captureExitStatus(commandId, exitCode);
+    await this.captureCommandEnd(commandId);
+  }
+}
+

package/src/lib/core/storage.ts

@@ -0,0 +1,360 @@
+// Event storage layer for terminal observer
+// Supports both PluresDB and local file-based storage
+
+import type {
+  TerminalObserverEvent,
+  EventStore,
+  EventType,
+  ObserverConfig,
+} from './types';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+
+// Re-export EventStore from types for convenience
+export type { EventStore } from './types';
+
+/**
+ * Local file-based storage adapter
+ * Stores events as JSON files in a directory
+ */
+export class LocalFileStore implements EventStore {
+  private events: TerminalObserverEvent[] = [];
+  private config: ObserverConfig;
+  private initialized = false;
+  private storagePath: string;
+  private eventsFile: string;
+  private writePromise: Promise<void> | null = null;
+
+  constructor(config: ObserverConfig) {
+    this.config = config;
+    this.storagePath = config.storagePath || join(homedir(), '.runebook', 'observer');
+    this.eventsFile = join(this.storagePath, 'events.json');
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Create storage directory (mkdir with recursive handles already exists)
+    try {
+      await mkdir(this.storagePath, { recursive: true });
+    } catch (error) {
+      // Directory already exists or can't be created
+      console.error('Failed to create storage directory:', error);
+    }
+
+    // Load existing events from file (handle ENOENT directly)
+    try {
+      const data = await readFile(this.eventsFile, 'utf-8');
+      this.events = JSON.parse(data);
+    } catch (error: unknown) {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+        // File doesn't exist yet, start with empty array
+        this.events = [];
+      } else {
+        console.error('Failed to load events from file:', error);
+        this.events = [];
+      }
+    }
+
+    this.initialized = true;
+  }
+
+  private async persistEvents(): Promise<void> {
+    // Serialize writes to prevent race conditions and data corruption
+    const writeOp = (async () => {
+      // If there's already a write in progress, wait for it
+      while (this.writePromise) {
+        await this.writePromise;
+      }
+      
+      // Now perform this write
+      try {
+        await writeFile(this.eventsFile, JSON.stringify(this.events, null, 2), 'utf-8');
+      } catch (error) {
+        console.error('Failed to persist events to file:', error);
+      }
+    })();
+    
+    this.writePromise = writeOp;
+    await writeOp;
+    
+    // Clear writePromise only if it's still this operation
+    if (this.writePromise === writeOp) {
+      this.writePromise = null;
+    }
+  }
+
+  async saveEvent(event: TerminalObserverEvent): Promise<void> {
+    await this.ensureInitialized();
+    
+    this.events.push(event);
+    
+    // Enforce max events limit
+    if (this.config.maxEvents && this.config.maxEvents > 0) {
+      if (this.events.length > this.config.maxEvents) {
+        // Remove oldest events
+        this.events = this.events.slice(-this.config.maxEvents);
+      }
+    }
+
+    // Persist to file
+    await this.persistEvents();
+  }
+
+  async getEvents(
+    type?: EventType,
+    since?: number,
+    limit?: number
+  ): Promise<TerminalObserverEvent[]> {
+    await this.ensureInitialized();
+    
+    let filtered = this.events;
+    
+    if (type) {
+      filtered = filtered.filter(e => e.type === type);
+    }
+    
+    if (since) {
+      filtered = filtered.filter(e => e.timestamp >= since);
+    }
+    
+    // Sort by timestamp (newest first)
+    filtered.sort((a, b) => b.timestamp - a.timestamp);
+    
+    if (limit && limit > 0) {
+      filtered = filtered.slice(0, limit);
+    }
+    
+    return filtered;
+  }
+
+  async getEventsByCommand(
+    commandId: string
+  ): Promise<TerminalObserverEvent[]> {
+    await this.ensureInitialized();
+    
+    return this.events.filter(e => {
+      // command_start events use their id as the command identifier
+      if (e.type === 'command_start' && e.id === commandId) {
+        return true;
+      }
+      // Other events reference the command via commandId field
+      if ('commandId' in e && e.commandId === commandId) {
+        return true;
+      }
+      return false;
+    }).sort((a, b) => a.timestamp - b.timestamp);
+  }
+
+  async getEventsBySession(
+    sessionId: string,
+    limit?: number
+  ): Promise<TerminalObserverEvent[]> {
+    await this.ensureInitialized();
+    
+    let filtered = this.events.filter(e => e.sessionId === sessionId);
+    
+    filtered.sort((a, b) => b.timestamp - a.timestamp);
+    
+    if (limit && limit > 0) {
+      filtered = filtered.slice(0, limit);
+    }
+    
+    return filtered;
+  }
+
+  async clearEvents(olderThan?: number): Promise<void> {
+    await this.ensureInitialized();
+    
+    if (olderThan) {
+      this.events = this.events.filter(e => e.timestamp >= olderThan);
+    } else {
+      this.events = [];
+    }
+
+    // Persist changes to file
+    await this.persistEvents();
+  }
+
+  async getStats(): Promise<{
+    totalEvents: number;
+    eventsByType: Record<EventType, number>;
+    sessions: number;
+  }> {
+    await this.ensureInitialized();
+    
+    const eventsByType: Record<string, number> = {};
+    const sessions = new Set<string>();
+    
+    for (const event of this.events) {
+      eventsByType[event.type] = (eventsByType[event.type] || 0) + 1;
+      sessions.add(event.sessionId);
+    }
+    
+    return {
+      totalEvents: this.events.length,
+      eventsByType: eventsByType as Record<EventType, number>,
+      sessions: sessions.size,
+    };
+  }
+}
+
+/**
+ * PluresDB storage adapter
+ */
+export class PluresDBEventStore implements EventStore {
+  private db: any = null;
+  private readonly eventPrefix = 'observer:event:';
+  private initialized = false;
+  private config: ObserverConfig;
+
+  constructor(config: ObserverConfig) {
+    this.config = config;
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized && this.db) {
+      return;
+    }
+
+    try {
+      const { SQLiteCompatibleAPI } = await import('pluresdb');
+      
+      this.db = new SQLiteCompatibleAPI({
+        config: {
+          port: 34567,
+          host: 'localhost',
+          dataDir: this.config.storagePath || './pluresdb-data',
+        },
+        autoStart: true,
+      });
+
+      await this.db.start();
+      this.initialized = true;
+    } catch (error) {
+      console.error('Failed to initialize PluresDB for observer storage:', error);
+      throw new Error('PluresDB initialization failed for observer storage');
+    }
+  }
+
+  async saveEvent(event: TerminalObserverEvent): Promise<void> {
+    await this.ensureInitialized();
+    const key = `${this.eventPrefix}${event.id}`;
+    await this.db.put(key, event);
+  }
+
+  async getEvents(
+    type?: EventType,
+    since?: number,
+    limit?: number
+  ): Promise<TerminalObserverEvent[]> {
+    await this.ensureInitialized();
+    const keys = await this.db.list(this.eventPrefix);
+    const events: TerminalObserverEvent[] = [];
+
+    for (const key of keys) {
+      try {
+        const event = await this.db.getValue(key);
+        if (event) {
+          if (type && event.type !== type) {
+            continue;
+          }
+          if (since && event.timestamp < since) {
+            continue;
+          }
+          events.push(event as TerminalObserverEvent);
+        }
+      } catch (error) {
+        console.error('Failed to load event:', error);
+      }
+    }
+
+    events.sort((a, b) => b.timestamp - a.timestamp);
+    return limit && limit > 0 ? events.slice(0, limit) : events;
+  }
+
+  async getEventsByCommand(
+    commandId: string
+  ): Promise<TerminalObserverEvent[]> {
+    const allEvents = await this.getEvents();
+    return allEvents.filter(e => {
+      // command_start events use their id as the command identifier
+      if (e.type === 'command_start' && e.id === commandId) {
+        return true;
+      }
+      // Other events reference the command via commandId field
+      if ('commandId' in e && e.commandId === commandId) {
+        return true;
+      }
+      return false;
+    }).sort((a, b) => a.timestamp - b.timestamp);
+  }
+
+  async getEventsBySession(
+    sessionId: string,
+    limit?: number
+  ): Promise<TerminalObserverEvent[]> {
+    const allEvents = await this.getEvents();
+    let filtered = allEvents.filter(e => e.sessionId === sessionId);
+    
+    filtered.sort((a, b) => b.timestamp - a.timestamp);
+    
+    if (limit && limit > 0) {
+      filtered = filtered.slice(0, limit);
+    }
+    
+    return filtered;
+  }
+
+  async clearEvents(olderThan?: number): Promise<void> {
+    await this.ensureInitialized();
+    const keys = await this.db.list(this.eventPrefix);
+    
+    for (const key of keys) {
+      try {
+        const event = await this.db.getValue(key);
+        if (event && (!olderThan || event.timestamp < olderThan)) {
+          await this.db.delete(key);
+        }
+      } catch (error) {
+        console.error('Failed to delete event:', error);
+      }
+    }
+  }
+
+  async getStats(): Promise<{
+    totalEvents: number;
+    eventsByType: Record<EventType, number>;
+    sessions: number;
+  }> {
+    const events = await this.getEvents();
+    const eventsByType: Record<string, number> = {};
+    const sessions = new Set<string>();
+    
+    for (const event of events) {
+      eventsByType[event.type] = (eventsByType[event.type] || 0) + 1;
+      sessions.add(event.sessionId);
+    }
+    
+    return {
+      totalEvents: events.length,
+      eventsByType: eventsByType as Record<EventType, number>,
+      sessions: sessions.size,
+    };
+  }
+}
+
+/**
+ * Create event store based on config
+ */
+export function createEventStore(config: ObserverConfig): EventStore {
+  if (config.usePluresDB && config.storagePath) {
+    return new PluresDBEventStore(config);
+  }
+  return new LocalFileStore(config);
+}
+

package/src/lib/core/types.ts

@@ -0,0 +1,176 @@
+// Canonical event schema for terminal observer layer
+// Low-level shell event capture
+
+export type ShellType = 'bash' | 'zsh' | 'nushell' | 'unknown';
+
+export type EventType = 
+  | 'command_start'
+  | 'command_end'
+  | 'stdout_chunk'
+  | 'stderr_chunk'
+  | 'exit_status'
+  | 'cwd_change'
+  | 'env_change'
+  | 'session_start'
+  | 'session_end';
+
+/**
+ * Base event structure for all terminal observer events
+ */
+export interface BaseTerminalEvent {
+  id: string;
+  type: EventType;
+  timestamp: number;
+  sessionId: string;
+  shellType: ShellType;
+  paneId?: string; // Terminal pane/tab identifier
+  tabId?: string;  // Terminal tab identifier (if applicable)
+}
+
+/**
+ * Command start event - fired when a command begins execution
+ */
+export interface CommandStartEvent extends BaseTerminalEvent {
+  type: 'command_start';
+  command: string;
+  args: string[];
+  cwd: string;
+  envSummary: Record<string, string>; // Sanitized environment variables
+  pid?: number; // Process ID if available
+}
+
+/**
+ * Command end event - fired when a command completes
+ */
+export interface CommandEndEvent extends BaseTerminalEvent {
+  type: 'command_end';
+  commandId: string; // Reference to command_start event
+  duration: number; // Milliseconds
+}
+
+/**
+ * Stdout chunk event - incremental stdout output
+ */
+export interface StdoutChunkEvent extends BaseTerminalEvent {
+  type: 'stdout_chunk';
+  commandId: string; // Reference to command_start event
+  chunk: string;
+  chunkIndex: number; // Sequential chunk number for this command
+}
+
+/**
+ * Stderr chunk event - incremental stderr output
+ */
+export interface StderrChunkEvent extends BaseTerminalEvent {
+  type: 'stderr_chunk';
+  commandId: string; // Reference to command_start event
+  chunk: string;
+  chunkIndex: number; // Sequential chunk number for this command
+}
+
+/**
+ * Exit status event - command exit code
+ */
+export interface ExitStatusEvent extends BaseTerminalEvent {
+  type: 'exit_status';
+  commandId: string; // Reference to command_start event
+  exitCode: number;
+  success: boolean;
+}
+
+/**
+ * CWD change event - working directory changed
+ */
+export interface CwdChangeEvent extends BaseTerminalEvent {
+  type: 'cwd_change';
+  cwd: string;
+  previousCwd?: string;
+}
+
+/**
+ * Environment change event - environment variables changed
+ */
+export interface EnvChangeEvent extends BaseTerminalEvent {
+  type: 'env_change';
+  envSummary: Record<string, string>; // Sanitized environment variables
+  changedKeys: string[]; // Keys that were added/modified
+}
+
+/**
+ * Session start event
+ */
+export interface SessionStartEvent extends BaseTerminalEvent {
+  type: 'session_start';
+  shellType: ShellType;
+  cwd: string;
+  envSummary: Record<string, string>;
+}
+
+/**
+ * Session end event
+ */
+export interface SessionEndEvent extends BaseTerminalEvent {
+  type: 'session_end';
+  duration: number; // Session duration in milliseconds
+}
+
+/**
+ * Union type for all terminal observer events
+ */
+export type TerminalObserverEvent =
+  | CommandStartEvent
+  | CommandEndEvent
+  | StdoutChunkEvent
+  | StderrChunkEvent
+  | ExitStatusEvent
+  | CwdChangeEvent
+  | EnvChangeEvent
+  | SessionStartEvent
+  | SessionEndEvent;
+
+// Re-export LLMProviderConfig from agent/llm/types
+export type { LLMProviderConfig } from '../agent/llm/types';
+
+/**
+ * Configuration for terminal observer
+ */
+export interface ObserverConfig {
+  enabled: boolean; // Opt-in flag
+  shellType?: ShellType; // Auto-detect if not specified
+  sessionId?: string; // Auto-generate if not specified
+  paneId?: string;
+  tabId?: string;
+  storagePath?: string; // Path for local storage or PluresDB
+  usePluresDB?: boolean; // Use PluresDB if available, otherwise local store
+  redactSecrets: boolean; // Enable secret redaction
+  secretPatterns?: string[]; // Additional patterns to redact
+  chunkSize?: number; // Max size for stdout/stderr chunks (bytes)
+  maxEvents?: number; // Maximum events to store (0 = unlimited)
+  retentionDays?: number; // Days to retain events (0 = unlimited)
+}
+
+/**
+ * Event storage interface
+ */
+export interface EventStore {
+  saveEvent(event: TerminalObserverEvent): Promise<void>;
+  getEvents(
+    type?: EventType,
+    since?: number,
+    limit?: number
+  ): Promise<TerminalObserverEvent[]>;
+  getEventsByCommand(
+    commandId: string
+  ): Promise<TerminalObserverEvent[]>;
+  getEventsBySession(
+    sessionId: string,
+    limit?: number
+  ): Promise<TerminalObserverEvent[]>;
+  clearEvents(olderThan?: number): Promise<void>;
+  getStats(): Promise<{
+    totalEvents: number;
+    eventsByType: Record<EventType, number>;
+    sessions: number;
+  }>;
+}
+

package/src/lib/design-dojo/Box.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    tui?: boolean;
+    surface?: 1 | 2 | 3 | 4;
+    border?: boolean;
+    pad?: 1 | 2 | 3 | 4 | 5 | 6;
+    radius?: 1 | 2 | 3 | 4;
+    shadow?: 1 | 2 | 3;
+    class?: string;
+    style?: string;
+    children?: Snippet;
+  }
+
+  let {
+    tui = false,
+    surface,
+    border = false,
+    pad,
+    radius,
+    shadow,
+    class: cls = '',
+    style = '',
+    children
+  }: Props = $props();
+
+  const inlineStyle = $derived([
+    surface != null ? `background: var(--surface-${surface})` : null,
+    border ? `border: 1px solid var(--border-color)` : null,
+    pad != null ? `padding: var(--space-${pad})` : null,
+    radius != null ? `border-radius: var(--radius-${radius})` : null,
+    shadow != null ? `box-shadow: var(--shadow-${shadow})` : null,
+    style || null,
+  ].filter(Boolean).join('; '));
+</script>
+
+<div class="dd-box {cls}" style={inlineStyle} data-tui={tui}>
+  {@render children?.()}
+</div>
+
+<style>
+  .dd-box {
+    color: var(--text-1);
+    box-sizing: border-box;
+  }
+</style>