vibe-forge 0.4.0 → 0.8.2

package/docs/architecture.md

@@ -1,162 +1,194 @@
-# Vibe Forge Architecture
-
-This document describes the architectural decisions and structure of the Vibe Forge codebase.
-
-## Language Strategy
-
-Vibe Forge uses a **hybrid Bash/Node.js architecture** with the following rationale:
-
-### Bash (Primary for Scripts)
-
-The core CLI and daemon are implemented in Bash because:
-
-1. **Native shell integration** - Vibe Forge orchestrates terminal sessions and Claude Code processes, which are inherently shell operations
-2. **Unix philosophy** - Small composable scripts that can be debugged, piped, and modified easily
-3. **Transparency** - Users can inspect and modify scripts without build steps
-4. **Git Bash compatibility** - Windows users with Git Bash can run the same scripts
-
-Files in Bash:
-- `bin/forge.sh` - Main CLI entry point
-- `bin/forge-setup.sh` - Setup and initialization
-- `bin/forge-spawn.sh` - Terminal spawning orchestration
-- `bin/forge-daemon.sh` - Background daemon for task monitoring
-- `bin/lib/*.sh` - Shared libraries (colors, config, agents, database, json, util)
-
-### Node.js (Cross-Platform Utilities)
-
-Node.js is used where cross-platform compatibility or complex logic is needed:
-
-1. **npx installer** - `bin/cli.js` runs via npx before Vibe Forge is installed
-2. **Terminal detection** - `bin/lib/terminal.js` detects and spawns terminals across Windows/macOS/Linux
-3. **JSON parsing** - All Bash scripts use Node.js for JSON via `bin/lib/json.sh` wrapper
-4. **Claude hooks** - `.claude/hooks/worker-loop.js` runs as Claude Code hook
-
-### Design Principles
-
-1. **Single Source of Truth** - Configuration in `config/agents.json`, loaded by both languages
-2. **Node.js for JSON** - All JSON parsing uses `bin/lib/json.sh` which calls Node.js (no jq dependency)
-3. **Bash for orchestration** - Process management, file watching, terminal control
-4. **Thin wrappers** - `forge.cmd` on Windows calls Bash via Git Bash
-
-### JSON Handling
-
-All JSON operations use the `json.sh` library which provides:
-
-```bash
-# Reading JSON
-value=$(json_read "$file" "key" "default")
-
-# Reading multiple keys efficiently
-read -r name status task <<< "$(json_read_multi "$file" name status task)"
-
-# Writing JSON
-json_write "$file" "key" "value"
-json_write_bool "$file" "enabled" true
-
-# Pretty printing
-json_pretty "$file"
-
-# Key existence check
-if json_has_key "$file" "key"; then ...
-```
-
-This eliminates the jq dependency while maintaining security (arguments passed to Node.js, not interpolated).
-
-## Directory Structure
-
-```
-vibe-forge/
-├── agents/                    # Agent personality definitions
-│   ├── anvil/
-│   │   └── personality.md
-│   ├── furnace/
-│   └── ...
-├── bin/                       # Executables
-│   ├── cli.js                 # npx entry point (Node.js)
-│   ├── forge.sh               # Main CLI (Bash)
-│   ├── forge.cmd              # Windows wrapper
-│   ├── forge-setup.sh         # Setup script
-│   ├── forge-spawn.sh         # Terminal spawning
-│   ├── forge-daemon.sh        # Background daemon
-│   └── lib/                   # Shared libraries
-│       ├── agents.sh          # Agent resolution
-│       ├── colors.sh          # Terminal colors
-│       ├── config.sh          # Configuration loading
-│       ├── constants.sh       # Constants (fallback)
-│       ├── database.sh        # SQLite operations
-│       ├── json.sh            # JSON utilities (Node.js based)
-│       ├── terminal.js        # Terminal detection (Node.js)
-│       └── util.sh            # Utility functions
-├── config/                    # Configuration files
-│   ├── agents.json            # Agent roster (source of truth)
-│   └── agent-manifest.yaml    # Rich documentation (non-normative)
-├── context/                   # Runtime context
-│   ├── agent-status/          # Agent status files
-│   └── forge-state.yaml       # Current forge state
-├── docs/                      # Documentation
-├── tasks/                     # Task lifecycle folders
-│   ├── pending/
-│   ├── in-progress/
-│   ├── completed/
-│   └── ...
-└── tests/                     # Test suites
-    ├── unit/                  # Jest unit tests (shell functions tested via child_process)
-    └── helpers/               # Test utilities
-```
-
-## Data Flow
-
-```
-┌──────────────┐     ┌────────────────┐     ┌──────────────┐
-│  CLI Input   │ --> │   forge.sh     │ --> │   Command    │
-│  (user)      │     │   (dispatch)   │     │   Handler    │
-└──────────────┘     └────────────────┘     └──────────────┘
-                                                   │
-                                                   v
-┌──────────────┐     ┌────────────────┐     ┌──────────────┐
-│   Claude     │ <-- │ forge-spawn.sh │ <-- │  Terminal    │
-│    Code      │     │ + terminal.js  │     │   Spawning   │
-└──────────────┘     └────────────────┘     └──────────────┘
-       │
-       v
-┌──────────────┐     ┌────────────────┐     ┌──────────────┐
-│   Tasks      │ <-> │ forge-daemon   │ <-> │   SQLite     │
-│   (files)    │     │   (monitor)    │     │   Database   │
-└──────────────┘     └────────────────┘     └──────────────┘
-```
-
-## Future Considerations
-
-### Potential Node.js Migration
-
-While Option B (hybrid) is the current strategy, a future Node.js migration could provide:
-
-1. **Better Windows support** - Native Node.js without Git Bash dependency
-2. **Unified codebase** - Single language to maintain
-3. **Type safety** - TypeScript for larger refactors
-4. **npm ecosystem** - Libraries for terminal control, process management
-
-Migration path if pursued:
-1. `src/lib/config.ts` - Configuration management
-2. `src/lib/agents.ts` - Agent resolution
-3. `src/lib/database.ts` - SQLite operations
-4. `src/daemon.ts` - Background daemon
-5. `src/forge.ts` - Main CLI (keeping forge.sh as thin wrapper initially)
-
-### Requirements for Migration
-
-Before pursuing full Node.js migration:
-- Ensure all Bash-specific functionality can be replicated
-- Maintain transparency (scripts users can inspect)
-- Keep startup time fast (current scripts are instant)
-- Preserve Unix composability where valuable
-
-## ADR Summary
-
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| Primary language | Bash | Native shell integration, transparency |
-| JSON parsing | Node.js via json.sh | Security, cross-platform |
-| Terminal detection | Node.js | Cross-platform compatibility |
-| Windows support | Git Bash + forge.cmd | Maintains Unix-like experience |
-| Configuration | JSON (agents.json) | Machine-readable, single source |
+# Vibe Forge Architecture
+
+This document describes the architectural decisions and structure of the Vibe Forge codebase.
+
+## Language Strategy
+
+Vibe Forge uses a **hybrid Bash/Node.js architecture** with the following rationale:
+
+### Bash (Primary for Scripts)
+
+The core CLI and daemon are implemented in Bash because:
+
+1. **Native shell integration** - Vibe Forge orchestrates terminal sessions and Claude Code processes, which are inherently shell operations
+2. **Unix philosophy** - Small composable scripts that can be debugged, piped, and modified easily
+3. **Transparency** - Users can inspect and modify scripts without build steps
+4. **Git Bash compatibility** - Windows users with Git Bash can run the same scripts
+
+Files in Bash:
+- `bin/forge.sh` - Main CLI entry point
+- `bin/forge-setup.sh` - Setup and initialization
+- `bin/forge-spawn.sh` - Terminal spawning orchestration
+- `bin/forge-daemon.sh` - Background daemon for task monitoring
+- `bin/lib/*.sh` - Shared libraries (colors, config, agents, database, json, util)
+
+### Node.js (Cross-Platform Utilities)
+
+Node.js is used where cross-platform compatibility or complex logic is needed:
+
+1. **npx installer** - `bin/cli.js` runs via npx before Vibe Forge is installed
+2. **Terminal detection** - `bin/lib/terminal.js` detects and spawns terminals across Windows/macOS/Linux
+3. **JSON parsing** - All Bash scripts use Node.js for JSON via `bin/lib/json.sh` wrapper
+4. **Claude hooks** - `.claude/hooks/worker-loop.js` runs as Claude Code hook
+5. **Dashboard server** - `bin/dashboard/server.js` provides HTTP + WebSocket for the web UI
+
+### Design Principles
+
+1. **Single Source of Truth** - Configuration in `config/agents.json`, loaded by both languages
+2. **Node.js for JSON** - All JSON parsing uses `bin/lib/json.sh` which calls Node.js (no jq dependency)
+3. **Bash for orchestration** - Process management, file watching, terminal control
+4. **Thin wrappers** - `forge.cmd` on Windows calls Bash via Git Bash
+
+### JSON Handling
+
+All JSON operations use the `json.sh` library which provides:
+
+```bash
+# Reading JSON
+value=$(json_read "$file" "key" "default")
+
+# Reading multiple keys efficiently
+read -r name status task <<< "$(json_read_multi "$file" name status task)"
+
+# Writing JSON
+json_write "$file" "key" "value"
+json_write_bool "$file" "enabled" true
+
+# Pretty printing
+json_pretty "$file"
+
+# Key existence check
+if json_has_key "$file" "key"; then ...
+```
+
+This eliminates the jq dependency while maintaining security (arguments passed to Node.js, not interpolated).
+
+## Directory Structure
+
+```
+vibe-forge/
+├── agents/                    # Agent personality definitions
+│   ├── anvil/
+│   │   └── personality.md
+│   ├── furnace/
+│   └── ...
+├── bin/                       # Executables
+│   ├── cli.js                 # npx entry point (Node.js)
+│   ├── forge.sh               # Main CLI (Bash)
+│   ├── forge.cmd              # Windows wrapper
+│   ├── forge-setup.sh         # Setup script
+│   ├── forge-spawn.sh         # Terminal spawning
+│   ├── forge-daemon.sh        # Background daemon
+│   ├── dashboard/             # Web dashboard (Node.js)
+│   │   ├── server.js          # HTTP + WebSocket server
+│   │   ├── api/               # REST API endpoints
+│   │   │   ├── tasks.js       # Task CRUD
+│   │   │   ├── agents.js      # Agent status
+│   │   │   └── dispatch.js    # Task dispatch
+│   │   └── public/            # Frontend assets
+│   │       ├── index.html     # Dashboard UI
+│   │       ├── style.css      # Styles (dark mode)
+│   │       └── app.js         # Frontend logic
+│   └── lib/                   # Shared libraries
+│       ├── agents.sh          # Agent resolution
+│       ├── colors.sh          # Terminal colors
+│       ├── config.sh          # Configuration loading
+│       ├── constants.sh       # Constants (fallback)
+│       ├── database.sh        # SQLite operations
+│       ├── json.sh            # JSON utilities (Node.js based)
+│       ├── terminal.js        # Terminal detection (Node.js)
+│       └── util.sh            # Utility functions
+├── config/                    # Configuration files
+│   ├── agents.json            # Agent roster (source of truth)
+│   └── agent-manifest.yaml    # Rich documentation (non-normative)
+├── context/                   # Runtime context
+│   ├── agent-status/          # Agent status files
+│   └── forge-state.yaml       # Current forge state
+├── docs/                      # Documentation
+├── tasks/                     # Task lifecycle folders
+│   ├── pending/
+│   ├── in-progress/
+│   ├── completed/
+│   └── ...
+└── tests/                     # Test suites
+    ├── unit/                  # Jest unit tests (shell functions tested via child_process)
+    └── helpers/               # Test utilities
+```
+
+## Data Flow
+
+```
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│  CLI Input   │ --> │   forge.sh     │ --> │   Command    │
+│  (user)      │     │   (dispatch)   │     │   Handler    │
+└──────────────┘     └────────────────┘     └──────────────┘
+                                                   │
+                                                   v
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│   Claude     │ <-- │ forge-spawn.sh │ <-- │  Terminal    │
+│    Code      │     │ + terminal.js  │     │   Spawning   │
+└──────────────┘     └────────────────┘     └──────────────┘
+       │
+       v
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│   Tasks      │ <-> │ forge-daemon   │ <-> │   SQLite     │
+│   (files)    │     │   (monitor)    │     │   Database   │
+└──────────────┘     └────────────────┘     └──────────────┘
+       ^                                           ^
+       │                                           │
+       └─────────────────┬─────────────────────────┘
+                         │
+                         v
+              ┌────────────────────┐
+              │  Dashboard Server  │ <-- Browser (http://localhost:2800)
+              │  (port 2800 🔥)    │
+              │  + WebSocket /ws   │
+              └────────────────────┘
+```
+
+### Dashboard Architecture
+
+The dashboard is a self-contained Node.js server that provides:
+
+1. **Static file serving** - HTML, CSS, JS from `bin/dashboard/public/`
+2. **REST API** - Task management, agent status, dispatch at `/api/*`
+3. **WebSocket** - Real-time updates at `/ws`
+4. **Issue detection** - Stale docs, failing tests, security issues
+
+Port **2800** was chosen as the default because it's the operating temperature of a forge in degrees Fahrenheit. 🔥
+
+## Future Considerations
+
+### Potential Node.js Migration
+
+While Option B (hybrid) is the current strategy, a future Node.js migration could provide:
+
+1. **Better Windows support** - Native Node.js without Git Bash dependency
+2. **Unified codebase** - Single language to maintain
+3. **Type safety** - TypeScript for larger refactors
+4. **npm ecosystem** - Libraries for terminal control, process management
+
+Migration path if pursued:
+1. `src/lib/config.ts` - Configuration management
+2. `src/lib/agents.ts` - Agent resolution
+3. `src/lib/database.ts` - SQLite operations
+4. `src/daemon.ts` - Background daemon
+5. `src/forge.ts` - Main CLI (keeping forge.sh as thin wrapper initially)
+
+### Requirements for Migration
+
+Before pursuing full Node.js migration:
+- Ensure all Bash-specific functionality can be replicated
+- Maintain transparency (scripts users can inspect)
+- Keep startup time fast (current scripts are instant)
+- Preserve Unix composability where valuable
+
+## ADR Summary
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Primary language | Bash | Native shell integration, transparency |
+| JSON parsing | Node.js via json.sh | Security, cross-platform |
+| Terminal detection | Node.js | Cross-platform compatibility |
+| Windows support | Git Bash + forge.cmd | Maintains Unix-like experience |
+| Configuration | JSON (agents.json) | Machine-readable, single source |