@plures/runebook 0.4.0

package/docs/parallel-execution-plan.md

@@ -0,0 +1,160 @@
+# Parallel Execution Plan
+
+This document describes the parallel execution system for RuneBook agents.
+
+## Overview
+
+The parallel execution plan coordinates multiple agents working on different parts of the RuneBook system simultaneously, with clear ownership boundaries and dependency management.
+
+## Execution Order
+
+### Phase 1: Orchestrator
+**Agent**: Orchestrator  
+**Tasks**:
+- Create roadmap and task breakdown
+- Stub all interfaces
+- Assign file ownership boundaries
+- Initialize coordination system
+
+**Output**: Execution plan with roadmap, tasks, interfaces, and ownership boundaries
+
+### Phase 2: Parallel Agents (Agent 1 + Agent 2)
+**Agents**: Agent 1 (Event Capture) + Agent 2 (Storage APIs)  
+**Execution**: Run in parallel  
+**Dependencies**: Phase 1 (Orchestrator)
+
+**Agent 1 Tasks**:
+- Implement event capture system
+- Owns: `src/lib/agent/capture.ts`, `src/lib/core/observer.ts`
+
+**Agent 2 Tasks**:
+- Implement storage APIs
+- Publish storage API interface (triggers Phase 3)
+- Owns: `src-tauri/src/memory/`
+
+### Phase 3: Analysis Pipeline
+**Agent**: Agent 3 (Analysis Pipeline)  
+**Execution**: Starts after Agent 2 publishes APIs  
+**Dependencies**: Phase 2 (Agent 2 APIs published)
+
+**Tasks**:
+- Implement analysis pipeline
+- Write suggestions to store (triggers Phase 4)
+- Owns: `src/lib/agent/analysis-pipeline.ts`, `analysis-service.ts`, `analyzers/`
+
+### Phase 4: Surfaces
+**Agent**: Agent 4 (Surfaces)  
+**Execution**: Starts after Agent 3 writes suggestions to store  
+**Dependencies**: Phase 3 (Agent 3 suggestions written)
+
+**Tasks**:
+- Implement suggestion surfaces
+- Integrate with tmux, wezterm, vim, neovim
+- Owns: `src/lib/agent/surfaces.ts`, `integrations/`
+
+### Phase 5: Continuous Agents
+**Agents**: Agent 5 (Nix + CI) + Agent 6 (Finalization)  
+**Execution**: Run continuously (start early, Agent 6 finalizes at end)  
+**Dependencies**: Phase 1 (Orchestrator)
+
+**Agent 5 Tasks**:
+- Set up Nix scaffolding (`flake.nix`, `shell.nix`)
+- Set up CI scaffolding (`.github/workflows/`)
+- Runs continuously (can be updated throughout)
+
+**Agent 6 Tasks**:
+- Finalize integration and testing
+- Update `ValidationChecklist.md`
+- Runs continuously but finalizes at the end
+
+## Architecture
+
+### Core Module (`src-tauri/src/core/`)
+
+Shared types and coordination mechanisms:
+
+- **`types.rs`**: Agent IDs, status, tasks, roadmap, interfaces, ownership, coordination messages
+- **`ownership.rs`**: File ownership management and boundary checking
+- **`coordination.rs`**: Coordination channels, API registry, message handling
+
+### Orchestrator (`src-tauri/src/orchestrator/`)
+
+- **`planner.rs`**: Creates execution plan (roadmap, tasks, interfaces, ownership)
+- **`coordinator.rs`**: Coordinates parallel execution, tracks dependencies, manages agent status
+
+### Agents (`src-tauri/src/agents/`)
+
+Each agent implements the `Agent` trait:
+
+- **`base.rs`**: Base agent trait and common functionality
+- **`agent1.rs`**: Event capture agent
+- **`agent2.rs`**: Storage APIs agent
+- **`agent3.rs`**: Analysis pipeline agent
+- **`agent4.rs`**: Surfaces agent
+- **`agent5.rs`**: Nix + CI agent
+- **`agent6.rs`**: Finalization agent
+
+### Execution Runner (`src-tauri/src/execution/`)
+
+- **`runner.rs`**: Parallel execution runner that orchestrates agent execution according to the plan
+
+## Coordination Rules
+
+### Ownership Boundaries
+
+1. **No agent changes another agent's owned module without coordinating via orchestrator**
+   - Agents must request coordination to modify files owned by other agents
+   - Orchestrator approves/rejects coordination requests
+   - Shared types go in `runebook-core` module
+
+2. **File Ownership**:
+   - Each agent has clear ownership of specific files/directories
+   - Ownership is enforced by the `OwnershipManager`
+   - Shared files are marked with `shared: true`
+
+### API Publishing
+
+- Agent 2 publishes storage APIs via `CoordinationMessage::ApiPublished`
+- Agent 3 waits for Agent 2 APIs before starting
+- API registry tracks all published APIs
+
+### Task Completion
+
+- Agents signal task completion via `CoordinationMessage::TaskCompleted`
+- Agent 3 signals when suggestions are written (triggers Agent 4)
+- Coordinator tracks task status and unblocks dependent agents
+
+## Usage
+
+```rust
+use runebook::execution::ParallelExecutionRunner;
+
+// Create runner
+let (mut runner, _handle) = ParallelExecutionRunner::new();
+
+// Execute all agents according to the plan
+runner.execute().await?;
+```
+
+## Integration with Existing Code
+
+The parallel execution plan integrates with existing RuneBook components:
+
+- **Event Capture**: Agent 1 extends `src/lib/agent/capture.ts`
+- **Storage APIs**: Agent 2 extends `src-tauri/src/memory/api.rs`
+- **Analysis Pipeline**: Agent 3 extends `src/lib/agent/analysis-pipeline.ts`
+- **Surfaces**: Agent 4 extends `src/lib/agent/surfaces.ts` and `integrations/`
+- **Nix/CI**: Agent 5 manages `flake.nix`, `shell.nix`, `.github/workflows/`
+- **Finalization**: Agent 6 updates `ValidationChecklist.md`
+
+## Next Steps
+
+1. Implement Agent 1: Complete event capture system
+2. Implement Agent 2: Complete storage APIs and publish interfaces
+3. Implement Agent 3: Complete analysis pipeline and write suggestions
+4. Implement Agent 4: Complete suggestion surfaces
+5. Implement Agent 5: Complete Nix and CI scaffolding
+6. Implement Agent 6: Complete finalization tasks
+
+Each agent should follow the ownership boundaries and coordinate via the orchestrator when needed.
+

package/flake.nix

@@ -0,0 +1,228 @@
+{
+  description = "RuneBook - A reactive, canvas-native computing environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+    rust-overlay.url = "github:oxalica/rust-overlay";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, rust-overlay }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        overlays = [ (import rust-overlay) ];
+        pkgs = import nixpkgs {
+          inherit system overlays;
+          config = {
+            # TODO: Migrate to libsoup 3 or newer webkitgtk version
+            # libsoup 2.74.3 is EOL with known CVEs but required by webkitgtk_4_1
+            permittedInsecurePackages = [
+              "libsoup-2.74.3"
+            ];
+          };
+        };
+
+        # Rust toolchain (stable)
+        rustToolchain = pkgs.rust-bin.stable.latest.default.override {
+          extensions = [ "rust-src" "rustfmt" "clippy" ];
+        };
+
+        # Node.js
+        nodejs = pkgs.nodejs_20;
+
+        # Build the frontend (SvelteKit)
+        frontend = pkgs.buildNpmPackage {
+          pname = "runebook-frontend";
+          version = "0.2.0";
+          src = ./.;
+          
+          npmDepsHash = "sha256-0HEvw24urS7Kbu/Qj8wkx0L/wZye4oZdI6z2EL+K2PE=";
+          
+          nativeBuildInputs = [
+            nodejs
+            pkgs.python3
+          ];
+
+          buildPhase = ''
+            export HOME=$(mktemp -d)
+            npm run build
+          '';
+
+          installPhase = ''
+            mkdir -p $out
+            cp -r build $out/
+          '';
+        };
+
+        # Build the Rust backend (Tauri)
+        runebook = pkgs.rustPlatform.buildRustPackage {
+          pname = "runebook";
+          version = "0.2.0";
+          
+          # Point src directly to src-tauri directory
+          src = ./src-tauri;
+
+          # Use Cargo.lock from the source
+          cargoLock = {
+            lockFile = ./src-tauri/Cargo.lock;
+          };
+          
+          nativeBuildInputs = [
+            nodejs
+            pkgs.pkg-config
+            pkgs.wrapGAppsHook3
+          ];
+
+          buildInputs = [
+            pkgs.openssl
+            pkgs.webkitgtk_4_1
+            pkgs.librsvg
+            pkgs.glib
+            pkgs.gtk3
+            pkgs.libayatana-appindicator
+            pkgs.libsoup_2_4
+          ];
+
+          preBuild = ''
+            # Copy frontend build to expected location (Tauri expects it at ../build)
+            mkdir -p ../build
+            cp -r ${frontend}/build/* ../build/ || true
+            
+            # Set up Rust environment
+            export RUST_BACKTRACE=1
+            export TAURI_DIST_DIR="../build"
+            export TAURI_PRIVATE_KEY=""
+            export TAURI_KEY_PASSWORD=""
+          '';
+
+          # Don't run tests during build
+          doCheck = false;
+
+          postInstall = ''
+            # wrapGAppsHook3 will handle wrapping for GTK/WebKit
+            mkdir -p $out/share/applications
+            mkdir -p $out/share/icons/hicolor
+          '';
+        };
+
+        # Headless CLI agent wrapper
+        runebook-agent = pkgs.writeShellApplication {
+          name = "runebook-agent";
+          runtimeInputs = [ nodejs ];
+          text = ''
+            exec ${nodejs}/bin/node ${./src/cli/index.ts} "$@"
+          '';
+        };
+
+        # Build the CLI as a standalone Node.js package
+        runebook-agent-pkg = pkgs.buildNpmPackage {
+          pname = "runebook-agent";
+          version = "0.2.0";
+          src = ./.;
+          
+          npmDepsHash = "sha256-0HEvw24urS7Kbu/Qj8wkx0L/wZye4oZdI6z2EL+K2PE=";
+          
+          nativeBuildInputs = [
+            nodejs
+            pkgs.nodePackages.typescript
+          ];
+
+          # Don't build the frontend, just install deps
+          buildPhase = ''
+            export HOME=$(mktemp -d)
+            # Install dependencies only (no build)
+            npm install --offline --no-audit --no-fund
+          '';
+
+          installPhase = ''
+            mkdir -p $out/bin
+            mkdir -p $out/lib/node_modules/runebook-agent
+            
+            # Copy package files and source
+            cp -r package.json package-lock.json $out/lib/node_modules/runebook-agent/
+            cp -r src $out/lib/node_modules/runebook-agent/
+            # Copy workspace packages so that symlinks in node_modules resolve correctly
+            cp -r packages $out/lib/node_modules/runebook-agent/
+            cp -r node_modules $out/lib/node_modules/runebook-agent/
+            
+            # Create wrapper script that uses tsx to run TypeScript directly
+            # Note: tsx is included in node_modules, so we can use it directly
+            cat > $out/bin/runebook-agent <<EOF
+            #!${pkgs.runtimeShell}
+            export NODE_PATH=$out/lib/node_modules/runebook-agent/node_modules
+            exec ${nodejs}/bin/node $out/lib/node_modules/runebook-agent/node_modules/.bin/tsx $out/lib/node_modules/runebook-agent/src/cli/index.ts "\$@"
+            EOF
+            chmod +x $out/bin/runebook-agent
+          '';
+        };
+
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          buildInputs = [
+            nodejs
+            rustToolchain
+            pkgs.pkg-config
+            pkgs.openssl
+            pkgs.webkitgtk_4_1
+            pkgs.librsvg
+            pkgs.glib
+            pkgs.gtk3
+            pkgs.libayatana-appindicator
+            pkgs.libsoup_2_4
+            pkgs.nodePackages.typescript
+            # Optional: pre-commit hooks
+            pkgs.pre-commit
+            pkgs.nixpkgs-fmt
+            pkgs.rustfmt
+          ];
+
+          shellHook = ''
+            echo "RuneBook Development Environment"
+            echo "Node.js: $(node --version)"
+            echo "Rust: $(rustc --version)"
+            echo "Cargo: $(cargo --version)"
+            echo ""
+            echo "Available commands:"
+            echo "  npm install    - Install dependencies"
+            echo "  npm run dev    - Start development server"
+            echo "  npm run build  - Build the application"
+            echo "  npm test       - Run tests"
+            echo "  npm run agent  - Run agent CLI"
+            echo ""
+            echo "Nix commands:"
+            echo "  nix build .#runebook        - Build the Tauri app"
+            echo "  nix build .#runebook-agent  - Build the headless agent"
+            echo "  nix run .#runebook-agent -- <command>  - Run agent CLI"
+            echo ""
+            echo "⚠️  Note: OpenAI keys and other secrets must be provided"
+            echo "   via environment variables at runtime, never in Nix store."
+          '';
+        };
+
+        packages = {
+          default = runebook;
+          runebook = runebook;
+          runebook-agent = runebook-agent-pkg;
+        };
+
+        apps = {
+          default = {
+            type = "app";
+            program = "${runebook}/bin/runebook";
+          };
+          runebook = {
+            type = "app";
+            program = "${runebook}/bin/runebook";
+          };
+          "runebook-agent" = {
+            type = "app";
+            program = "${runebook-agent-pkg}/bin/runebook-agent";
+          };
+        };
+
+        # NixOS module (separate file)
+        nixosModules.default = ./nixos-module.nix;
+      }
+    );
+}

package/integrations/README.md

@@ -0,0 +1,242 @@
+# RuneBook Integration Guide
+
+This directory contains integration snippets for displaying RuneBook suggestions in various terminal environments.
+
+## Overview
+
+All integrations read from the same shared suggestion store located at `~/.runebook/suggestions.json` and status file at `~/.runebook/agent-status.json`. This ensures consistency across all surfaces.
+
+## CLI Commands
+
+### Basic Usage
+
+```bash
+# Show current agent status
+runebook suggest status
+
+# Show top suggestion
+runebook suggest top
+
+# Show suggestions for last command
+runebook suggest last
+```
+
+## Tmux Integration
+
+### Setup
+
+1. Copy `tmux-status.sh` to your home directory:
+   ```bash
+   mkdir -p ~/.runebook/integrations
+   cp integrations/tmux-status.sh ~/.runebook/integrations/
+   chmod +x ~/.runebook/integrations/tmux-status.sh
+   ```
+
+2. Add to your `~/.tmux.conf`:
+   ```tmux
+   set -g status-right '#(bash ~/.runebook/integrations/tmux-status.sh)'
+   ```
+
+3. Reload tmux config:
+   ```bash
+   tmux source-file ~/.tmux.conf
+   ```
+
+### Status Indicators
+
+- `●` (green) - Agent idle
+- `⟳` (yellow) - Agent analyzing
+- `⚠` (red) - Issues found (shows count)
+
+## WezTerm Integration
+
+### Setup
+
+1. Copy the integration file to your WezTerm config directory:
+   ```bash
+   mkdir -p ~/.config/wezterm
+   cp integrations/wezterm-status-simple.lua ~/.config/wezterm/
+   ```
+
+2. Add to your `~/.config/wezterm/wezterm.lua`:
+   ```lua
+   wezterm.on('update-right-status', function(window, pane)
+     local status_file = wezterm.home_dir .. '/.runebook/agent-status.json'
+     local file = io.open(status_file, 'r')
+     if not file then
+       window:set_right_status('')
+       return
+     end
+     
+     local content = file:read('*all')
+     file:close()
+     
+     -- Simple JSON parsing (for status field only)
+     local status = content:match('"status"%s*:%s*"([^"]*)"')
+     local high_priority = content:match('"highPriorityCount"%s*:%s*([0-9]+)')
+     
+     local symbol = ''
+     local color = ''
+     local text = ''
+     
+     if status == 'idle' then
+       symbol = '●'
+       color = '#00ff00'
+     elseif status == 'analyzing' then
+       symbol = '⟳'
+       color = '#ffff00'
+     elseif status == 'issues_found' then
+       symbol = '⚠'
+       color = '#ff0000'
+       if high_priority then
+         text = high_priority
+       end
+     end
+     
+     if symbol ~= '' then
+       window:set_right_status(wezterm.format({
+         { Foreground = { Color = color } },
+         { Text = symbol .. text },
+         { Foreground = { Color = '#ffffff' } },
+         { Text = ' ' },
+       }))
+     else
+       window:set_right_status('')
+     end
+   end)
+   ```
+
+3. Restart WezTerm
+
+## Vim/Neovim Integration
+
+### Vim Setup
+
+1. Copy the plugin file:
+   ```bash
+   mkdir -p ~/.vim/plugin
+   cp integrations/vim-runebook.vim ~/.vim/plugin/
+   ```
+
+2. Use the command:
+   ```
+   :RunebookSuggestion
+   ```
+
+### Neovim Setup (Lua)
+
+1. Copy the plugin file:
+   ```bash
+   mkdir -p ~/.config/nvim/lua
+   cp integrations/nvim-runebook.lua ~/.config/nvim/lua/runebook.lua
+   ```
+
+2. Or place in plugin directory:
+   ```bash
+   mkdir -p ~/.config/nvim/plugin
+   cp integrations/nvim-runebook.lua ~/.config/nvim/plugin/runebook.lua
+   ```
+
+3. Use the command:
+   ```
+   :RunebookSuggestion
+   ```
+
+### Optional: Auto-display in Virtual Text (Neovim)
+
+Uncomment the autocmd in `nvim-runebook.lua` to automatically display suggestions in virtual text.
+
+## Status File Format
+
+The status file (`~/.runebook/agent-status.json`) contains:
+
+```json
+{
+  "status": "idle" | "analyzing" | "issues_found",
+  "lastCommand": "command-name",
+  "lastCommandTimestamp": 1234567890,
+  "suggestionCount": 5,
+  "highPriorityCount": 2,
+  "lastUpdated": 1234567890
+}
+```
+
+## Suggestions File Format
+
+The suggestions file (`~/.runebook/suggestions.json`) contains:
+
+```json
+{
+  "suggestions": [
+    {
+      "id": "suggestion-id",
+      "type": "warning" | "command" | "optimization" | "shortcut" | "tip",
+      "priority": "low" | "medium" | "high",
+      "title": "Suggestion Title",
+      "description": "Detailed description",
+      "command": "optional-command",
+      "args": ["arg1", "arg2"],
+      "timestamp": 1234567890
+    }
+  ],
+  "lastUpdated": 1234567890
+}
+```
+
+## Testing
+
+Run the demo script to see all features:
+
+```bash
+./integrations/demo-steps.sh
+```
+
+## Requirements
+
+- All integrations work over SSH (no GUI dependencies)
+- No system notifications (passive display only)
+- All surfaces read from the same shared store
+- Works in headless environments
+
+## Troubleshooting
+
+### Status not updating
+
+1. Check that the agent is enabled:
+   ```bash
+   runebook agent status
+   ```
+
+2. Verify the status file exists:
+   ```bash
+   cat ~/.runebook/agent-status.json
+   ```
+
+3. Check file permissions:
+   ```bash
+   ls -la ~/.runebook/
+   ```
+
+### Tmux status not showing
+
+1. Verify the script is executable:
+   ```bash
+   chmod +x ~/.runebook/integrations/tmux-status.sh
+   ```
+
+2. Test the script directly:
+   ```bash
+   ~/.runebook/integrations/tmux-status.sh
+   ```
+
+3. Check tmux config syntax:
+   ```bash
+   tmux show-options -g status-right
+   ```
+
+### WezTerm status not showing
+
+1. Check WezTerm logs for errors
+2. Verify the status file exists and is readable
+3. Test JSON parsing manually
+

package/integrations/demo-steps.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Manual demo steps for RuneBook suggestion rendering
+# This script demonstrates the UX surfaces for suggestions
+
+set -e
+
+echo "=== RuneBook Suggestion Rendering Demo ==="
+echo ""
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}Step 1: Enable the agent${NC}"
+echo "Command: runebook agent enable"
+runebook agent enable
+echo ""
+
+echo -e "${BLUE}Step 2: Check initial status${NC}"
+echo "Command: runebook suggest status"
+runebook suggest status
+echo ""
+
+echo -e "${BLUE}Step 3: Simulate some commands (these would normally be captured)${NC}"
+echo "Note: In a real scenario, commands would be executed and captured automatically"
+echo "For demo purposes, we'll manually trigger some analysis"
+echo ""
+
+echo -e "${BLUE}Step 4: Show top suggestion${NC}"
+echo "Command: runebook suggest top"
+runebook suggest top
+echo ""
+
+echo -e "${BLUE}Step 5: Show suggestions for last command${NC}"
+echo "Command: runebook suggest last"
+runebook suggest last
+echo ""
+
+echo -e "${BLUE}Step 6: Check status again${NC}"
+echo "Command: runebook suggest status"
+runebook suggest status
+echo ""
+
+echo -e "${GREEN}=== Integration Examples ===${NC}"
+echo ""
+echo -e "${YELLOW}Tmux Integration:${NC}"
+echo "Add to ~/.tmux.conf:"
+echo "  set -g status-right '#(bash ~/.runebook/integrations/tmux-status.sh)'"
+echo ""
+
+echo -e "${YELLOW}WezTerm Integration:${NC}"
+echo "Add to ~/.config/wezterm/wezterm.lua:"
+echo "  See integrations/wezterm-status-simple.lua for example code"
+echo ""
+
+echo -e "${YELLOW}Vim/Neovim Integration:${NC}"
+echo "Place integrations/vim-runebook.vim in ~/.vim/plugin/ or ~/.config/nvim/plugin/"
+echo "Use :RunebookSuggestion command to show suggestions"
+echo ""
+
+echo -e "${GREEN}Demo complete!${NC}"
+