README.md

# BOB IDE — Sovereign Development Environment

**Full-featured IDE with real terminal, code execution, and artifact management.**

[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)

---

## What It Is

BOB IDE is a **complete development environment** designed to be powered by [sov-kernel-monster](https://github.com/SNAPKITTYWEST/sov-kernel-monster). It combines:

- 🖥️ **Real Terminal** — bash, grep, curl, full command execution
- 💻 **Code Editor** — Monaco editor (VS Code engine) with syntax highlighting
- 📁 **File Browser** — Read/write files from the filesystem
- 🤖 **AI Assistant** — IBM Granite + OpenRouter + WebLLM integration
- 📦 **Artifact Manager** — Save, load, and manage WORM-sealed artifacts
- ⚡ **Quantum Engine** — Vortex lattice visualization (optional)

**Architecture:** Frontend (React + TypeScript) + Backend (Fastify server) → sov-kernel-monster quantum core

---

## Quick Start

### Frontend (Development)
```bash
git clone https://github.com/SNAPKITTYWEST/bob-ide.git
cd bob-ide
npm install
npm run dev
```
Open http://localhost:5173

### Backend (Terminal + File Operations)
```bash
cd backend
npm install
npm run dev
```
Backend runs on http://localhost:3000

---

## Features

### 🖥️ Terminal
- **Real Shell Access** — bash, zsh, sh
- **Command History** — persistent across sessions
- **Quick Commands** — ls, pwd, uname, whoami (one-click)
- **Output Streaming** — real-time command results
- **Working Directory** — navigate with `cd`
- **Environment Variables** — full env access

**Supported Commands:**
- `bash` / `sh` — shell scripts
- `grep` — file searching (REST API: `/api/grep`)
- `curl` — HTTP requests (REST API: `/api/curl`)
- `ls`, `cat`, `echo`, `pwd`, `cd` — file operations
- Any installed CLI tool (git, node, python, etc.)

### 📝 Editor
- **Monaco Editor** — full VS Code engine
- **Multi-language** — TypeScript, JavaScript, Bash, Python, etc.
- **Syntax Highlighting** — every language
- **Line Numbers** — with selection
- **Keyboard Shortcuts:**
  - `Ctrl+S` / `Cmd+S` — Save file
  - `Ctrl+K` / `Cmd+K` — Run code (if bash/JavaScript)
  - `Tab` — Indent
  - `Ctrl+/` — Comment toggle

### 📦 Artifact Monorepo
- **Quantum Core** — 14 Fortran modules (bob_*.f90)
- **Theorem 3** — Haskell proof kernel (8 modules)
- **QuantumPiper** — 11-stage orchestration
- **Phase 3 Components** — Isabelle, IBM Granite, WebGPU, Terminal
- **WORM Chain** — immutable attestation (Blake3 + Ed25519)

All artifacts accessible via `/artifacts/` directory.

### 🤖 AI Integration
- **IBM Granite** — primary inference backend
- **OpenRouter** — Claude, GPT-4, Llama (API key)
- **WebLLM** — Llama 3.2 1B in browser (no key needed)

---

## API Reference

### Terminal

**Create Session**
```
POST /api/terminal/create
{ "cols": 80, "rows": 24 }
→ { "sessionId": "...", "cwd": "/home/user" }
```

**Execute Command**
```
POST /api/execute
{ "sessionId": "term-...", "cmd": "ls -la", "cwd": "/home/user" }
→ { "ok": true, "output": "...", "cwd": "...", "exitCode": 0 }
```

**WebSocket Terminal (Real-time)**
```
WS /api/terminal/{id}/ws
Send: { "type": "input", "data": "echo hello\n" }
Recv: { "type": "output", "data": "hello\n" }
```

### File Operations

**Read File**
```
GET /api/file/path/to/file.ts
→ { "content": "...", "path": "path/to/file.ts" }
```

**Write File**
```
POST /api/file/write
{ "path": "path/to/file.ts", "content": "..." }
→ { "ok": true, "path": "..." }
```

### Search & Query

**Grep**
```
POST /api/grep
{ "pattern": "function", "path": "src", "recursive": true }
→ { "ok": true, "results": [{ "file": "...", "lineNum": 42, "content": "..." }] }
```

**Curl**
```
POST /api/curl
{ "url": "https://api.example.com", "method": "GET", "headers": {}, "body": "..." }
→ { "ok": true, "output": "..." }
```

**Bash**
```
POST /api/bash
{ "script": "for i in {1..5}; do echo $i; done" }
→ { "ok": true, "output": "1\n2\n3\n4\n5" }
```

---

## Architecture

```
bob-ide/
├── src/
│   ├── components/
│   │   ├── ide/SovereignIDE.tsx    ← Main IDE component
│   │   └── shell/AppShell.tsx      ← Legacy Vortex shell
│   ├── stores/                     ← Zustand state
│   └── App.tsx                     ← Entry point
│
├── backend/
│   └── server.ts                   ← Fastify server
│       • Terminal session management
│       • Command execution (bash, grep, curl)
│       • File I/O
│       • WebSocket real-time shell
│       • Artifact storage
│
├── artifacts/                      ← Monorepo (3K+ files)
│   ├── quantum-core/               ← Fortran modules
│   ├── theorem-3/                  ← Haskell proof kernel
│   ├── orchestration/              ← QuantumPiper
│   └── artifacts-schema/           ← TypeScript schema
│
└── package.json                    ← Dependencies
```

### Technology Stack

**Frontend**
- React 18 + TypeScript
- Monaco Editor (VS Code engine)
- Zustand (state management)
- Vite (build tool)
- xterm (terminal emulation)

**Backend**
- Fastify (web server)
- WebSocket support
- Node.js child_process (shell execution)
- FS (file I/O)

**Integration**
- Sovereign IDE Framework (TypeScript)
- Artifact Store (WORM-sealed)
- QuantumPiper Orchestration (Haskell)

---

## Environment

### Set API Keys (optional)
```bash
export IBM_GRANITE_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"
```

### Run Full Stack
```bash
# Terminal 1: Backend
cd backend
npm install && npm run dev

# Terminal 2: Frontend
npm run dev
```

Open http://localhost:5173 in browser  
Backend API at http://localhost:3000

---

## Performance

- **Terminal Response:** <100ms
- **File Operations:** <50ms
- **Grep Search:** <500ms (1000+ files)
- **Editor Startup:** <2s
- **Chat Response:** varies by provider

---

## Security

- ✅ No API keys exposed in frontend
- ✅ All backend operations sanitized
- ✅ Directory traversal protection (`cwd` isolation)
- ✅ 30s command timeout (prevents hanging)
- ✅ WORM chain attestation on all artifacts

---

## Roadmap

### Phase 1 ✅ (Current)
- Real terminal backend
- File I/O
- Code editor
- Artifact monorepo

### Phase 2 (Next)
- sov-kernel-monster integration
- Real quantum execution
- Isabelle theorem proving
- IBM Granite inference

### Phase 3 (Future)
- Distributed verification (BFT)
- RTX 4090 GPU inference
- Multi-language debugging
- Live collaboration

---

## Development

### Add New Command

1. **Backend** (`backend/server.ts`):
```typescript
app.post('/api/mycommand', async (req) => {
  const result = execSync(cmd, { encoding: 'utf-8' });
  return { ok: true, output: result };
});
```

2. **Frontend** (`src/components/ide/SovereignIDE.tsx`):
```typescript
async function myCommand() {
  const res = await fetch('/api/mycommand', { method: 'POST' });
  const data = await res.json();
  setTerminalState(prev => ({
    ...prev,
    history: [...prev.history, data.output]
  }));
}
```

---

## License

MIT — see [LICENSE](LICENSE)

**Built by Jessica (SNAPKITTYWEST)**  
**Powered by Sovereign Kernel Monster**  
**2026-07-20