@plures/runebook 0.4.0

package/ANALYSIS_LADDER.md

@@ -0,0 +1,231 @@
+# Analysis Ladder
+
+The Analysis Ladder is a multi-layer approach to analyzing command failures and generating actionable suggestions. It runs in the background, is non-blocking, and never auto-executes commands—only suggests.
+
+## Architecture
+
+The analysis pipeline consists of three layers, executed in order:
+
+### Layer 1: Heuristic Classifiers
+
+**Purpose**: Fast, deterministic pattern matching for common errors.
+
+**Analyzers**:
+- **NixErrorAnalyzer**: Detects Nix-specific errors
+  - Missing attributes (e.g., `attribute "cursor" missing`)
+  - Flake-parts template path errors
+  - buildEnv font conflicts
+  - Nix evaluation errors
+
+- **GitAuthAnalyzer**: Detects Git/GitHub authentication issues
+  - GitHub rate limit errors
+  - Git authentication failures
+  - Missing token environment variables
+
+- **SyntaxErrorAnalyzer**: Detects syntax and command errors
+  - Syntax errors with file/line numbers
+  - Command not found errors
+
+**Characteristics**:
+- High confidence (0.7-0.95)
+- Fast execution (< 100ms)
+- No external dependencies
+- Deterministic results
+
+### Layer 2: Local Search
+
+**Purpose**: Search repository and configuration files for context.
+
+**Analyzer**:
+- **LocalSearchAnalyzer**: Uses ripgrep (or grep fallback) to search:
+  - Repository files (flake.nix, *.nix, *.sh, etc.)
+  - Configuration files
+  - Environment variable references
+  - Related error patterns
+
+**Characteristics**:
+- Medium confidence (0.6-0.8)
+- Moderate execution time (100-500ms)
+- Requires repository context
+- May skip if Layer 1 produces high-confidence results
+
+### Layer 3: Optional LLM/MCP (Gated)
+
+**Purpose**: Intelligent analysis using language models or MCP.
+
+**Analyzer**:
+- **LLMAnalyzer**: Placeholder for future LLM/MCP integration
+  - Currently disabled by default
+  - Can be enabled via configuration
+  - Would provide intelligent, context-aware suggestions
+
+**Characteristics**:
+- Variable confidence (depends on model)
+- Slower execution (1-5s)
+- Requires API access
+- Only runs if explicitly enabled
+
+## Job System
+
+### Failure Detection
+
+Failures are detected when:
+1. An `exit_status` event has `success: false` (non-zero exit code)
+2. Known stderr patterns match error signatures
+3. Command context is available (command, args, cwd, env)
+
+### Job Queue
+
+- **Non-blocking**: Jobs run in the background
+- **Cancelable**: Jobs can be cancelled if pending
+- **Context Windows**: Each job includes:
+  - Full command context (command, args, cwd, env)
+  - Complete stdout/stderr output
+  - Previous commands (last 5)
+  - All related events
+
+### Job States
+
+- `pending`: Queued, waiting to run
+- `running`: Currently being analyzed
+- `completed`: Analysis finished, suggestions available
+- `cancelled`: User cancelled the job
+- `failed`: Analysis encountered an error
+
+## Structured Suggestions
+
+Each suggestion includes:
+
+```typescript
+interface AnalysisSuggestion {
+  id: string;
+  type: 'command' | 'optimization' | 'shortcut' | 'warning' | 'tip';
+  priority: 'low' | 'medium' | 'high';
+  title: string;
+  description: string;
+  confidence: number; // 0.0 to 1.0
+  actionableSnippet?: string; // Code snippet or command to fix
+  provenance: {
+    analyzer: string; // Which analyzer produced this
+    layer: number; // Which layer (1, 2, or 3)
+    timestamp: number;
+  };
+  timestamp: number;
+}
+```
+
+### Confidence Scores
+
+- **0.9-1.0**: Very high confidence, likely correct
+- **0.7-0.9**: High confidence, probably correct
+- **0.5-0.7**: Medium confidence, worth checking
+- **< 0.5**: Low confidence, may be speculative
+
+## Usage
+
+### CLI Command
+
+```bash
+# Analyze the last command failure
+runebook analyze last
+```
+
+### Programmatic API
+
+```typescript
+import { getAnalysisService } from './lib/agent/analysis-service';
+import { createObserver } from './lib/core';
+
+const observer = createObserver({ enabled: true });
+await observer.initialize();
+
+const analysisService = getAnalysisService();
+analysisService.initialize(store, config);
+analysisService.setEnabled(true);
+
+// Process exit status events
+const jobId = await analysisService.processExitStatus(exitStatusEvent);
+
+// Get results
+const job = analysisService.getJob(jobId);
+console.log(job.suggestions);
+```
+
+## Pluggable Analyzers
+
+You can create custom analyzers by implementing the `Analyzer` interface:
+
+```typescript
+interface Analyzer {
+  name: string;
+  layer: number; // 1, 2, or 3
+  analyze(context: AnalysisContext, store: EventStore): Promise<AnalysisSuggestion[]>;
+}
+```
+
+Example:
+
+```typescript
+class CustomAnalyzer implements Analyzer {
+  name = 'custom-analyzer';
+  layer = 1;
+
+  async analyze(context: AnalysisContext, store: EventStore): Promise<AnalysisSuggestion[]> {
+    const suggestions: AnalysisSuggestion[] = [];
+    
+    // Your analysis logic here
+    if (context.stderr.includes('your-pattern')) {
+      suggestions.push({
+        id: `suggestion_${Date.now()}`,
+        type: 'warning',
+        priority: 'high',
+        title: 'Your Title',
+        description: 'Your description',
+        confidence: 0.8,
+        actionableSnippet: '# Your fix here',
+        provenance: {
+          analyzer: this.name,
+          layer: this.layer,
+          timestamp: Date.now(),
+        },
+        timestamp: Date.now(),
+      });
+    }
+    
+    return suggestions;
+  }
+}
+
+// Register it
+const queue = new AnalysisJobQueue(store);
+queue.registerAnalyzer(new CustomAnalyzer());
+```
+
+## Best Practices
+
+1. **Layer 1 First**: Use heuristic analyzers for fast, common errors
+2. **Layer 2 for Context**: Use local search when you need repository context
+3. **Layer 3 Sparingly**: Only enable LLM/MCP for complex cases
+4. **High Confidence**: Prefer high-confidence suggestions (>0.7)
+5. **Actionable Snippets**: Always include actionable code/commands
+6. **Provenance**: Track which analyzer produced each suggestion
+
+## Testing
+
+Fixture-based tests verify that analyzers produce expected remediations for:
+
+- GitHub rate limit / token env issues
+- flake-parts template path errors
+- Nix buildEnv font conflicts
+- Missing attribute "cursor"
+
+See `src/lib/agent/__tests__/analysis-pipeline.test.ts` for examples.
+
+## Future Enhancements
+
+- [ ] LLM/MCP integration for Layer 3
+- [ ] Learning from user feedback
+- [ ] Cross-session pattern learning
+- [ ] Suggestion ranking and deduplication
+- [ ] Integration with IDE/editor plugins
+

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+## [0.4.0] — 2026-02-23
+
+- feat: replace hand-styled components with design-dojo primitives (#40) (4ffc4b9)
+- test: Playwright e2e coverage for core RuneBook flows + fix InputNode reactive loop (#38) (766f5cf)
+- chore: add copilot instructions and org standards (6412fee)
+- chore: integrate @plures/design-dojo as UI component library (#31) (d057f91)
+- Add Playwright E2E smoke tests (production-like build) (#26) (14cd86d)
+- Fix node button reactivity by using Praxis store dispatch (#25) (7c29e6a)
+
+# Changelog
+
+All notable changes to RuneBook will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-01-25
+
+### Added
+- **Praxis Integration**: Integrated @plures/praxis v1.2.0 for reactive state management
+  - Type-safe event-driven architecture with defineEvent and defineRule
+  - Reactive logic engine replacing manual Svelte stores
+  - Improved testability and maintainability of state management
+  - Backward-compatible API wrapper for existing components
+
+### Changed
+- Refactored canvas state management to use Praxis reactive engine
+- State updates now use events (AddNodeEvent, UpdateNodeEvent, etc.) for better traceability
+- Improved type safety across the state management layer
+
+## [0.2.0] - 2024-12-27
+
+### Added
+- **Transform Nodes**: New node type for data transformation between nodes
+  - Map transform: Apply functions to array elements
+  - Filter transform: Filter array elements based on conditions
+  - Reduce transform: Aggregate array data into single values
+  - Sudolang transform placeholder (planned for future implementation)
+- **Storage System**: Canvas persistence with localStorage and PluresDB
+  - LocalStorage adapter for browser-based storage
+  - **PluresDB adapter**: Full integration with PluresDB for P2P-enabled storage
+  - Switch between storage adapters in UI
+  - Export canvases as YAML files
+  - Storage abstraction layer with pluggable adapters
+- Transform node button in toolbar
+- Canvas rendering support for transform nodes
+- PluresDB integration (v1.3.1) with key-value API
+- Example canvas file demonstrating transform nodes
+- Storage settings UI to switch between LocalStorage and PluresDB
+
+### Changed
+- Updated all dependencies to latest versions
+- Improved documentation structure
+- README.md now focuses on latest features
+- Version-specific information moved to CHANGELOG.md
+- Toolbar reorganized with save/load options and storage settings
+
+### Security
+- Added "use strict" mode for JavaScript expression execution in transform nodes
+- Input validation for transform node arrays
+- Canvas data validation in storage layer
+- Fixed reduce operation with proper initial value
+- Documented security considerations for transform nodes
+- CodeQL security scan: 0 alerts
+
+### Documentation
+- Created CHANGELOG.md for version history tracking
+- Updated IMPLEMENTATION.md to reflect actual completion status
+- Clarified roadmap items in README.md as implemented vs. planned
+- Added storage documentation to README
+- Added security notes for transform nodes
+- Documented PluresDB integration
+
+## [0.1.0] - 2024-11-21
+
+### Added
+- Initial Tauri + Svelte 5 project structure
+- Canvas UI system with infinite workspace and grid background
+- Three core node types:
+  - **Terminal Nodes**: Execute shell commands with reactive output
+  - **Input Nodes**: User input widgets (text, number, checkbox, slider)
+  - **Display Nodes**: Data visualization (text, JSON, table)
+- Reactive data flow system using Svelte 5 runes
+- YAML canvas loader for save/load functionality
+- Example canvas files:
+  - `hello-world.yaml`: Basic echo and input demonstration
+  - `date-time-example.yaml`: Multiple terminals and displays
+- Rust backend with Tauri for native system access
+- Terminal command execution with security measures:
+  - Direct execution (no shell interpretation)
+  - Input validation
+  - Environment variable validation
+- Toolbar with node creation and canvas management
+- SVG-based connection rendering
+- Comprehensive documentation:
+  - README.md: User guide and getting started
+  - QUICKSTART.md: Step-by-step tutorial
+  - CONTRIBUTING.md: Developer contribution guide
+  - ARCHITECTURE.md: Technical design documentation
+  - INTEGRATIONS.md: Future feature plans
+  - LICENSE: MIT License
+
+### Security
+- Command execution without shell interpretation to prevent injection attacks
+- Environment variable name validation
+- Input validation for commands and arguments
+
+## [Unreleased]
+
+### Planned Features
+- PluresDB integration for persistent storage
+- MCP (Model Context Protocol) integration for AI assistance
+- Sudolang support for natural language scripting
+- Interactive connection creation (drag from ports)
+- Canvas zoom and pan controls
+- Node deletion UI
+- Keyboard shortcuts
+- Undo/redo functionality
+- WebSocket support for real-time data
+- Plugin system for custom nodes
+- Collaborative editing
+- Canvas search and filtering

package/INTEGRATIONS.md

@@ -0,0 +1,242 @@
+# Integration Plans
+
+## PluresDB Integration
+
+PluresDB will provide persistent storage for canvas definitions, node states, and user data.
+
+### Planned Features
+
+- **Canvas Storage**: Save and load canvas configurations from the database
+- **Node State Persistence**: Store terminal outputs and node values
+- **History Tracking**: Version control for canvas changes
+- **Search**: Full-text search across canvas definitions and node content
+
+### Implementation Notes
+
+PluresDB integration will be added in a future iteration. The current YAML-based system provides a foundation for understanding the data model.
+
+## MCP (Model Context Protocol) Integration
+
+MCP will enable AI assistance within RuneBook workflows.
+
+### Planned Features
+
+- **AI Transform Nodes**: Process data using LLM capabilities
+- **Natural Language Commands**: Create and modify canvas elements via text
+- **Code Generation**: Generate terminal commands and scripts
+- **Data Analysis**: Analyze terminal outputs and suggest insights
+- **Autocomplete**: Suggest next nodes based on workflow context
+
+### Use Cases
+
+1. **Command Suggestion**: "Show me disk usage" → generates `du -sh` terminal node
+2. **Data Transformation**: Transform JSON output to different formats
+3. **Error Analysis**: Analyze error messages and suggest fixes
+4. **Workflow Optimization**: Suggest improvements to canvas layouts
+
+### Integration Approach
+
+1. Add MCP client to Tauri backend
+2. Create MCP server connector nodes
+3. Implement prompt templates for common operations
+4. Add AI suggestion UI components
+
+## Sudolang Support
+
+Sudolang will provide a natural language interface for creating and manipulating canvas workflows.
+
+### Planned Features
+
+- **Natural Language Node Creation**: "Create a terminal that lists files"
+- **Flow Description**: Describe entire workflows in prose
+- **Dynamic Scripting**: Write Sudolang scripts that generate canvas configurations
+- **Interactive Refinement**: Conversational workflow building
+
+### Example Sudolang Workflow
+
+```sudolang
+Create a workflow that:
+1. Gets the current date
+2. Lists all files in the current directory
+3. Counts the number of files
+4. Displays all information in separate panels
+
+Connect the outputs appropriately.
+```
+
+This would automatically generate:
+- A terminal node running `date`
+- A terminal node running `ls`
+- A terminal node running `ls | wc -l`
+- Three display nodes showing the outputs
+- Connections between all nodes
+
+### Implementation Notes
+
+Sudolang integration will require:
+1. Parser for Sudolang syntax
+2. Code generator that creates canvas YAML
+3. Interpreter for dynamic execution
+4. REPL-style interface for interactive development
+
+## Transform Nodes
+
+Transform nodes will enable data processing between nodes.
+
+### Types of Transforms
+
+1. **Map**: Transform each item in a collection
+2. **Filter**: Select items matching criteria
+3. **Reduce**: Aggregate data into a single value
+4. **Parse**: Convert between formats (JSON, CSV, XML)
+5. **Sudolang**: Custom transformations using natural language
+
+### Example
+
+```
+Terminal (ls -l) → Transform (parse file listing) → Display (table view)
+```
+
+## Ambient Agent Mode (Term-Agent Capabilities)
+
+Ambient Agent Mode provides intelligent command analysis and suggestions, similar to term-agent capabilities.
+
+### Implemented Features ✅
+
+- **Event Capture**: Automatic capture of terminal commands, outputs, and context
+- **Storage/Memory**: Persistent storage of events and patterns (in-memory or PluresDB)
+- **Analysis Engine**: Pattern detection, failure analysis, performance analysis
+- **Suggestion System**: Generate actionable suggestions (shortcuts, optimizations, warnings)
+- **Headless CLI**: SSH-friendly interface for agent management
+- **Opt-in Design**: Disabled by default, requires explicit enable
+- **Terminal Observer**: Low-level shell event capture with bash/zsh adapters
+- **Analysis Ladder**: 3-layer analysis system (heuristic → local search → optional LLM)
+- **Cognitive Memory**: PluresDB-based persistent storage with Rust API
+- **Event Schema**: Canonical event types for all terminal activities
+- **Memory Schema**: Structured storage for sessions, commands, outputs, errors, insights, suggestions
+- **Security Model**: Secret redaction, opt-in design, local-only storage
+- **Demo Script**: Automated walkthrough (scripts/demo.sh)
+
+### Architecture
+
+```
+Terminal Command → Event Capture → Storage → Analysis → Suggestions
+                      ↓              ↓          ↓
+                 Observer Layer  Memory    Analysis Ladder
+                 (bash/zsh)      (PluresDB) (3 layers)
+                                                      ↓
+                                              CLI / UI Display
+```
+
+### Event Schema
+
+The system captures canonical event types:
+- `command_start`: Command begins execution
+- `command_end`: Command completes
+- `stdout_chunk`: Incremental stdout output
+- `stderr_chunk`: Incremental stderr output
+- `exit_status`: Command exit code
+- `cwd_change`: Working directory changed
+- `env_change`: Environment variables changed
+- `session_start`: Terminal session started
+- `session_end`: Terminal session ended
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for full event schema details.
+
+### Memory Schema
+
+Cognitive memory storage organizes data into:
+- **Sessions**: Terminal session metadata
+- **Commands**: Normalized command records
+- **Outputs**: Chunked stdout/stderr (optionally compressed)
+- **Errors**: Classified error records
+- **Insights**: AI/heuristic annotations
+- **Suggestions**: Ranked recommendations
+- **Provenance**: Source tracking
+
+See [MEMORY.md](./MEMORY.md) for full memory schema details.
+
+### Analysis Ladder
+
+Three-layer analysis system:
+1. **Layer 1**: Heuristic classifiers (fast, deterministic, high confidence)
+2. **Layer 2**: Local search (context-aware, medium confidence)
+3. **Layer 3**: Optional LLM/MCP (gated, disabled by default)
+
+See [ANALYSIS_LADDER.md](./ANALYSIS_LADDER.md) for full details.
+
+### Usage
+
+**Enable via CLI:**
+```bash
+npm run agent enable
+npm run agent status
+npm run agent suggestions
+npm run analyze last
+npm run memory inspect
+```
+
+**Enable Observer (captures all shell commands):**
+```bash
+npm run observer enable
+npm run observer events tail
+```
+
+**Enable via Code:**
+```typescript
+import { initAgent } from './lib/agent/integration';
+
+initAgent({
+  enabled: true,
+  captureEvents: true,
+  analyzePatterns: true,
+  suggestImprovements: true,
+});
+```
+
+### Data Policy
+
+- **Opt-in by default**: Agent is disabled until explicitly enabled
+- **Local-only storage**: All data stored locally, no external services
+- **Secret redaction**: Automatic detection and redaction of API keys, tokens, passwords
+- **Configurable retention**: Default 30 days, customizable
+- **No background daemon**: Runs only when explicitly enabled
+- **Clear data policy**: User controls what is stored and for how long
+
+### CLI Surface
+
+Full headless interface:
+- `npm run agent <command>`: Agent management (enable, disable, status, suggestions, events, clear)
+- `npm run observer <command>`: Observer management (enable, disable, status, events, tail)
+- `npm run analyze <command>`: Analysis commands (last)
+- `npm run memory <command>`: Memory inspection (inspect)
+
+### Demo
+
+Run the automated demo:
+```bash
+bash scripts/demo.sh
+```
+
+Or follow the walkthrough in [docs/demo.md](./docs/demo.md).
+
+### Future Enhancements
+
+- GUI integration for suggestions display
+- Advanced ML-based pattern analysis
+- Cross-session pattern learning
+- Suggestion action buttons (apply directly)
+- Nushell adapter for terminal observer
+- Real-time event streaming (WebSocket-based)
+
+## Future Integration Priorities
+
+1. **Phase 1**: Transform nodes with JavaScript ✅
+2. **Phase 2**: PluresDB for persistence ✅
+3. **Phase 2.5**: Ambient Agent Mode ✅
+4. **Phase 3**: MCP for AI assistance
+5. **Phase 4**: Sudolang for natural language workflows
+
+## Contributing
+
+If you'd like to contribute to any of these integrations, please see the main README for contribution guidelines.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RuneBook Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.