Novora Forge - VS Code Extension

Self-evolution system for code, directly in your editor

Features

Syntax Highlighting: Full support for .forge and .evolution files
Evolution Sidebar: Real-time status of cycles, proposals, and reviews
Command Palette: Run cycles, seed mutations, and manage reviews
Inline Decorations: Fitness scores displayed directly in editor
Real-time Sync (Session 3): Automatic file watching with debounced sync
Status Bar Indicator: Sync state at a glance (idle/syncing/synced/error/conflict)
Hub Integration (Session 3): Multi-repo coordination via WebSocket
Error Boundaries: Network detection, exponential backoff, graceful recovery
Settings Validation: Automatic validation with dev/prod/minimal presets

Installation

From VSIX

code --install-extension novora-forge-vscode-0.1.0.vsix

From Source

git clone https://github.com/novora/forge-vscode
cd forge-vscode
npm install
npm run compile

Press F5 in VS Code to launch the Extension Development Host.

Usage

Commands

Command	Description
`Forge: Run Evolution Cycle`	Start a new evolution cycle
`Forge: List Pending Reviews`	View and manage pending proposals
`Forge: Seed New Mutation`	Create a new mutation proposal
`Forge: Show Statistics`	Display evolution statistics
`Forge: Show Sync Status`	View sync state and pending changes
`Forge: Manual Sync`	Trigger immediate sync
`Forge: Connect to Hub`	Connect to multi-repo coordination server
`Forge: Validate Settings`	Check configuration for errors
`Forge: Apply Development Settings`	Quick preset for dev environment
`Forge: Apply Production Settings`	Quick preset for production
`Forge: Apply Minimal Settings`	Quick preset for minimal overhead

The Forge Explorer sidebar shows:

Cycles completed
Pending reviews
Current fitness score
Active proposals

Status Bar

The status bar shows sync state:

Forge: Ready — Idle, waiting for changes
Forge: Syncing... — Processing changes
Forge: Synced — Up to date
Forge: Error — Sync failed (check logs)
Forge: Conflicts — Manual resolution needed
Forge: Disconnected — Hub unreachable

Configuration

Setting	Default	Description
`forge.path`	auto-detect	Path to Forge installation
`forge.autoRefresh`	`true`	Auto-refresh evolution status
`forge.refreshInterval`	`5000`	Refresh interval (ms)
`forge.sync.autoSync`	`true`	Enable automatic background sync
`forge.sync.interval`	`30000`	Sync interval (ms)
`forge.sync.watchEnabled`	`true`	Watch for file changes
`forge.sync.watchPatterns`	`["*/.forge", "*/.evolution"]`	File patterns to watch
`forge.sync.excludePatterns`	`["/node_modules/", "/.git/"]`	Patterns to exclude
`forge.sync.conflictDetection`	`true`	Detect conflicts between local and proposals
`forge.hub.url`	`http://localhost:3000`	Hub server URL
`forge.hub.authToken`	`""`	Auth token for remote Hub
`forge.debug.mode`	`false`	Enable debug logging

Architecture

┌─────────────────────────────────────────────┐
│           VS Code Extension                 │
├─────────────────────────────────────────────┤
│  ┌──────────┐  ┌───────────┐  ┌──────────┐ │
│  │ Sidebar  │  │ Commands  │  │ Status   │ │
│  │ Provider │  │ (11 cmds)│  │ Bar      │ │
│  └────┬─────┘  └─────┬─────┘  └────┬─────┘ │
│       │              │              │       │
│  ┌────▼──────────────▼──────────────▼─────┐│
│  │            ForgeManager                 ││
│  │  - CLI integration                      ││
│  │  - Status tracking                     ││
│  │  - Proposal management                  ││
│  └────────────────┬───────────────────────┘│
│                   │                         │
│  ┌────────────────▼───────────────────────┐ │
│  │            SyncManager                 │ │
│  │  - File watching (debounced)           │ │
│  │  - Conflict detection                  │ │
│  │  - Error boundaries                    │ │
│  │  - Status bar updates                  │ │
│  └────────────────┬───────────────────────┘ │
│                   │                         │
│  ┌────────────────▼───────────────────────┐ │
│  │            HubClient                   │ │
│  │  - WebSocket (real-time)               │ │
│  │  - REST API (/hub/conflicts)           │ │
│  │  - Auth token support                  │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
                        │
                        ▼
              ┌─────────────────┐
              │   Forge Hub     │
              │   (optional)    │
              │   Multi-repo    │
              └─────────────────┘

Conflict Detection

When a proposal targets a file with local modifications:

SyncManager detects the conflict
Status bar shows Forge: Conflicts
Click status bar to view details
Resolve conflict or view affected file

Error Handling

Network errors: Detected and retried with exponential backoff
CLI unavailable: Graceful fallback to mock data
Hub disconnected: Status shows "Disconnected", auto-reconnects
Invalid settings: Validation on startup with actionable error messages

Development

# Build
npm run compile

# Watch mode
npm run watch

# Package VSIX
npm run package

# Lint
npm run lint

# Test
npm run test

Requirements

VS Code 1.85.0 or higher
@novora/forge package (npm) - optional for CLI features

Changelog

0.1.0 (Session 3)

Real-time sync with debounced file watching
Status bar indicator (6 states)
Hub client for multi-repo coordination
Conflict detection (local + Hub)
Network error detection and recovery
Settings validation with presets
11 commands registered

0.0.1 (Sessions 1-2)

Extension scaffold
Syntax highlighting for .forge files
Evolution sidebar
CLI integration
Basic commands

License

MIT

Repository

https://github.com/novora/forge-vscode

Enjoy evolving your code! 🦞