orka-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Orka
 
-Multi-agent coding orchestration CLI. Orka mengorkestrasi AI agents untuk bekerja seperti tim engineering — Coordinator dekomposisi goal, Scout analisis codebase, Builder implementasi paralel, Reviewer jaga kualitas — semua terkoordinasi otomatis tanpa konflik file.
+**Multi-agent coding orchestration CLI.** Orka coordinates a swarm of AI agents that work like an engineering team — Coordinator breaks down goals, Scout analyzes the codebase, Builders implement in parallel, and Reviewer ensures quality — all automatically coordinated without file conflicts.
 
 ```
 $ orka run "build user authentication with OAuth2 and JWT"
@@ -18,64 +18,86 @@ $ orka run "build user authentication with OAuth2 and JWT"
   │  ⚡ BUILD │  API routes & middleware │  bld-2 │  4 files │
   │  ⏳ QUEUE │  Login & signup UI       │  —     │  5 files │
   └──────────┴──────────────────────────┴────────┴──────────┘
-  [P]ause  [L]ogs  [C]ost detail  [Q]uit
 ```
 
-## Fitur
+## Features
 
-- **Multi-agent paralel** — Coordinator + Scout + N Builders + Reviewer bekerja serentak
-- **Zero file conflict** — file ownership via atomic SQLite lock, tidak ada dua agent edit file yang sama
-- **Review gate** — setiap perubahan di-review Reviewer sebelum di-commit, max 3x retry sebelum eskalasi ke user
-- **Agent-agnostic** — Claude, Ollama (gratis/lokal), OpenAI, Gemini — bisa dicampur per role
-- **Git integration** — auto-branch per task, auto-merge setelah approved, rebase in-flight branches
-- **Survive crash** — state di SQLite, `orka resume` lanjut dari titik terakhir
-- **Cost tracking** — token dan biaya per agent, real-time di TUI
+- **Parallel multi-agent swarm** — Coordinator + Scout + N Builders + Reviewer work concurrently
+- **Zero file conflicts** — atomic SQLite file ownership locks prevent two agents from editing the same file
+- **AI self-healing loop** — TesterAgent runs your test suite after each build; if tests fail, Builder retries with the test output as feedback
+- **Human gate** — optionally require human approval before any task is marked done, with a full diff preview
+- **Web dashboard** — built-in HTTP server with real-time WebSocket updates; monitor and control sessions from any browser
+- **Remote access** — built-in Cloudflare Tunnel support (`--tunnel`) for iPad/remote access without VPN
+- **Provider-agnostic** — Claude, OpenAI, Gemini, Ollama (local/free), OpenRouter — mix and match per role
+- **Git integration** — auto-branch per session, auto-commit after approval, safe rollback
+- **Crash recovery** — full state persisted in SQLite; `orka resume` picks up exactly where it left off
+- **Cost tracking** — real-time token usage and estimated cost per agent
+- **Plugin system** — extend with custom roles, providers, and hooks
+- **MCP server** — expose Orka as an MCP tool for use inside Claude, Cursor, and other AI editors
 
-## Instalasi
+## Installation
 
 ```bash
 npm install -g orka-cli
 ```
 
-Atau run tanpa install:
+**Requirements:** Node.js v20+, at least one LLM provider (API key or local Ollama)
+
+## Quickstart
+
 ```bash
-npx orka-cli init
+# 1. Initialize config in your project
+cd your-project
+orka init
+
+# 2. Add your API key
+orka login --provider claude
+
+# 3. Run your first session
+orka run "add input validation to all API endpoints"
 ```
 
-**Prasyarat:** Node.js v20+, minimal satu LLM provider (API key atau Ollama)
+## Web Dashboard (Mission Control)
 
-## Quickstart
+Run Orka as a persistent server and control everything from your browser — no terminal needed after startup.
 
 ```bash
-# Bootstrap config awal
-orka init --profile ollama
+# Start the server (point --static to the GUI build)
+orka serve --project /path/to/your-project --static /path/to/gui/dist
 
-# Mode core (default): goal -> scout -> coordinator -> builder/reviewer
-orka run "buat CRUD endpoint untuk /api/products"
+# With Cloudflare Tunnel for iPad/remote access
+orka serve --project /path/to/your-project --static /path/to/gui/dist --tunnel
+# → 🌐 Tunnel URL: https://xxxxx.trycloudflare.com
+```
 
-# Mode manual: pakai target file eksplisit untuk single-task run
-orka run "buat CRUD endpoint untuk /api/products" --files src/api/products.ts
+From the dashboard you can:
+- **Start new sessions** — type a goal and click Run
+- **Monitor agents** — real-time swarm canvas with task status
+- **Review diffs** — click any `AWAITING APPROVAL` task to see the full git diff
+- **Approve or reject** — with optional feedback sent back to the Builder
 
-# Rollback ke base commit session terakhir
-orka rollback
+Alternatively, run server + session together in one command:
 
-# Lihat status implementasi yang sudah tersedia
-orka status
+```bash
+orka run "your goal" --serve --serve-static /path/to/gui/dist [--tunnel]
 ```
 
-## Konfigurasi
+## Configuration
 
-`orka init` akan generate `orka.config.yaml` di root project. Edit manual jika perlu:
+`orka init` generates `orka.config.yaml` in your project root:
 
 ```yaml
 providers:
   claude:
-    apiKey: ${ANTHROPIC_API_KEY}      # dari environment variable
+    apiKey: ${ANTHROPIC_API_KEY}      # reads from environment variable
   ollama:
     baseUrl: http://localhost:11434
 
 swarm:
-  builders: 2   # jumlah Builder agent paralel
+  builders: 2                         # number of parallel Builder agents
+  review: true                        # enable Reviewer agent
+  maxReviewRetries: 3
+  humanGate: false                    # set true to require human approval before done
 
 roles:
   coordinator: { provider: claude, model: claude-sonnet-4-20250514 }
@@ -84,14 +106,20 @@ roles:
   reviewer:    { provider: claude, model: claude-sonnet-4-20250514 }
 
 git:
-  auto_branch: true
-  auto_merge: true
-  commit_prefix: "[orka]"
-  push: false                         # tidak pernah push tanpa izin user
-  conflict_resolution: prompt         # prompt | auto | manual
+  autoBranch: true
+  autoMerge: true
+  commitPrefix: "[orka]"
+  push: false                         # never pushes without explicit confirmation
+  conflictResolution: prompt          # prompt | auto | manual
+
+tester:
+  enabled: false                      # set true to enable self-healing test loop
+  command: "npm test"
+  timeout: 60000
+  maxRetries: 3
 ```
 
-### Setup Hemat (semua Ollama, gratis)
+### Budget Setup (fully local, free)
 
 ```yaml
 roles:
@@ -101,7 +129,7 @@ roles:
   reviewer:    { provider: ollama, model: llama3 }
 ```
 
-### Setup Quality (cloud untuk Coordinator & Reviewer)
+### Quality Setup (cloud for planning and review)
 
 ```yaml
 roles:
@@ -111,97 +139,194 @@ roles:
   reviewer:    { provider: claude, model: claude-sonnet-4-20250514 }
 ```
 
+## Human Gate (Approval Workflow)
+
+Enable `humanGate: true` in your config to require human review before any task is finalized.
+
+**Pipeline with human gate:**
+```
+Builder → TesterAgent → ReviewerAgent → awaiting_approval → [you approve] → done
+                                                           ↘ [you reject]  → Builder retries
+```
+
+When a task reaches `awaiting_approval`:
+- The web dashboard shows a purple **APPROVE** badge
+- Click the task to open a diff preview modal
+- Click **Approve** to finalize, or **Reject** with optional feedback
+- On rejection, the Builder retries with your feedback as context
+
+## Self-Healing Test Loop
+
+Enable `tester.enabled: true` to have Orka automatically run your test suite after each build:
+
+```yaml
+tester:
+  enabled: true
+  command: "npm test"
+  timeout: 60000
+  maxRetries: 3
+```
+
+**Pipeline:**
+```
+Builder writes code → TesterAgent runs tests → pass: send to Reviewer
+                                             → fail: Builder retries with test output
+```
+
 ## Rules System
 
-Buat `orka.rules.md` di root project untuk mengatur perilaku semua agent:
+Create `orka.rules.md` in your project root to guide all agents:
 
 ```markdown
 ## Code Style
-- Gunakan Bahasa Indonesia untuk error messages
-- Naming: camelCase untuk functions, PascalCase untuk types
+- Use TypeScript strict mode
+- Prefer named exports over default exports
+- All functions must have explicit return types
 
 ## Architecture
-- Semua API routes di src/app/api/
-- Pakai Zod untuk validation, bukan manual type checking
+- API routes go in src/app/api/
+- Use Zod for validation, not manual type checking
+- No direct database calls outside of repository files
 ```
 
-Global rules (berlaku semua project): `~/.orka/rules.md`
+Global rules (applied to all projects): `~/.orka/rules.md`
 
-## Commands
+## All Commands
 
+### Session Management
 ```bash
-orka init                              # generate config dari preset
-orka init --wizard                     # setup wizard interaktif
-orka init --profile ollama             # local-first preset (tanpa Claude)
-orka run "goal"                        # auto-planning orchestration flow
-orka run "goal" --files src/app.ts     # manual single-task run
-orka run "goal" --no-git               # nonaktifkan session branch + auto-commit
-orka status                            # tampilkan status board session terakhir
-orka status --ink                      # status board interaktif via Ink
-orka status --watch                    # status board live refresh (text)
-orka board                             # tampilkan session board terakhir
-orka board --watch                     # board mode live refresh
-orka board --ink                       # board interaktif berbasis Ink
-orka board --ink --watch               # board Ink + live refresh
-orka logs                              # activity log session terakhir
-orka logs --session session-123        # filter ke session tertentu
-orka logs --type task:completed        # filter berdasarkan message type
-orka pause                             # pause semua agent
-orka resume                            # lanjut dari pause / crash
-orka rollback                          # rollback session branch terakhir ke base commit
-orka fix                               # resolve git conflict otomatis (LLM)
-orka fix --strategy ours               # pakai versi branch saat ini
-orka fix --strategy theirs             # pakai versi incoming branch
-orka cost                              # token & cost summary
-orka rules edit                        # edit orka.rules.md
-orka memory show                       # tampilkan memory
-orka memory add "catatan"              # tambah entry
-orka memory clear                      # hapus semua memory
-orka plugin add my-plugin              # pasang plugin ke registry lokal
-orka plugin list                       # lihat plugin aktif
+orka run "goal"                          # start an orchestration session
+orka run "goal" --files src/app.ts       # single-task run targeting specific files
+orka run "goal" --no-git                 # disable session branch and auto-commit
+orka run "goal" --builders 4             # use 4 parallel Builder agents
+orka run "goal" --provider claude        # override all roles to one provider
+orka run "goal" --dry-run                # preview plan without calling any LLM
+orka run "goal" --mock                   # use mock provider (no API calls, for testing)
+orka run "goal" --serve                  # start HTTP server alongside the session
+orka run "goal" --serve --tunnel         # + expose via Cloudflare Tunnel
+orka pause                               # pause all agents gracefully
+orka resume                              # resume from pause or crash
+orka rollback                            # rollback last session branch to base commit
 ```
 
-## Git Flow
+### Monitoring
+```bash
+orka status                              # show last session status board
+orka status --watch                      # live-refresh status board
+orka status --ink                        # interactive Ink TUI board
+orka board                               # alias for status
+orka logs                                # show event log for last session
+orka logs --session session-123          # filter to a specific session
+orka logs --type task:completed          # filter by message type
+orka cost                                # show token usage and cost summary
+```
 
-Orka tidak pernah mengubah branch aktif kamu secara langsung:
+### Web Server
+```bash
+orka serve                               # start HTTP server + web dashboard
+orka serve --port 8080                   # custom port (default: 4242)
+orka serve --project /path/to/project   # set project directory
+orka serve --static /path/to/gui/dist   # serve web dashboard
+orka serve --tunnel                      # expose via Cloudflare Tunnel
+```
 
+### Provider & Credentials
+```bash
+orka login --provider claude             # save Claude API key
+orka login --provider openai             # save OpenAI API key
+orka login --provider gemini             # save Gemini API key
+orka login --provider ollama             # configure Ollama base URL
+orka logout --provider claude            # remove saved credential
+orka whoami                              # show credential status for all providers
+orka models --provider claude            # list available models from provider
 ```
-main (branch kamu)
-  │
-  └── orka/session-<timestamp>        ← session branch
-       ├── orka/task-auth-schemas     ← per-task branch (builder-1)
-       ├── orka/task-auth-service     ← per-task branch (builder-2)
-       └── orka/task-api-routes       ← per-task branch (builder-2)
+
+### Project Setup
+```bash
+orka init                                # generate config from default preset
+orka init --profile ollama               # local-first preset (no cloud API needed)
+orka init --wizard                       # interactive setup wizard
+orka init --force                        # overwrite existing config
 ```
 
-Setelah semua task approved, Orka tanya: `Merge ke main? [Y/n]`
+### Git Conflict Resolution
+```bash
+orka fix                                 # resolve git conflicts using LLM
+orka fix --strategy ours                 # keep current branch version
+orka fix --strategy theirs               # keep incoming branch version
+```
 
-**Safety rules:**
-- Tidak pernah force push
-- Tidak pernah push ke remote tanpa konfirmasi
-- Merge conflict → pause + notifikasi, tidak auto-resolve diam-diam
+### Rules & Memory
+```bash
+orka rules show                          # show active project and global rules
+orka rules edit                          # open project rules in $EDITOR
+orka memory show                         # show memory entries
+orka memory add "always use pnpm"        # add a memory entry
+orka memory clear                        # clear all memory entries
+```
 
-## Dokumentasi
+### Plugins
+```bash
+orka plugin add my-plugin                # install plugin from npm
+orka plugin add ./local-plugin           # install local plugin
+orka plugin list                         # list installed plugins
+orka plugin remove my-plugin             # uninstall plugin
+```
+
+### MCP Server
+```bash
+orka mcp-server                          # start as MCP server (stdio transport)
+```
 
-- [Design Spec](docs/superpowers/specs/2026-03-11-orka-design.md) — arsitektur lengkap
-- [BRD](docs/superpowers/specs/2026-03-11-brd.md) — business requirements
-- [PRD](docs/superpowers/specs/2026-03-11-prd.md) — product requirements & user stories
-- [ERD](docs/superpowers/specs/2026-03-11-erd.md) — database schema
-- [Contributing](CONTRIBUTING.md) — setup development, commit rules, branching strategy repo
+## Git Flow
 
-## Roadmap
+Orka never touches your active branch directly:
 
-| Versi | Fitur |
-|-------|-------|
-| **v1.0** | Core orchestration, 4 roles, Claude + Ollama, TUI, git integration, rules, resume |
-| **v1.1** | OpenAI + Gemini, smart context management, memory auto-learning, `--dry-run` |
-| **v1.2** | Plugin system (custom roles, providers, hooks) |
-| **v2.0** | Desktop app (Electron/Tauri) |
-| **v3.0** | Web dashboard + managed cloud service |
+```
+main (your branch)
+  │
+  └── orka/session-<timestamp>           ← session branch (auto-created)
+       ├── task-1: auth types            ← builder-1 works here
+       ├── task-2: auth service          ← builder-2 works here
+       └── task-3: API routes            ← builder-2 works here
+```
+
+After all tasks are approved, Orka auto-commits to the session branch. You decide when to merge.
+
+**Safety guarantees:**
+- Never force pushes
+- Never pushes to remote without explicit confirmation (`push: false` by default)
+- Merge conflicts → session pauses and notifies you, never silently auto-resolves
+
+## Supported Providers
+
+| Provider | Models | Notes |
+|----------|--------|-------|
+| **Claude** | claude-sonnet-4, claude-haiku-4-5, ... | Best quality |
+| **OpenAI** | gpt-4o, gpt-4o-mini, o1, ... | |
+| **Gemini** | gemini-2.0-flash, gemini-1.5-pro, ... | |
+| **Ollama** | llama3, deepseek-coder-v2, qwen2.5-coder, ... | Free, runs locally |
+| **OpenRouter** | Any model via OpenRouter | |
+| **Zai / GLM** | glm-4, ... | |
+
+## MCP Integration
+
+Use Orka as an MCP tool inside Claude Desktop, Cursor, or any MCP-compatible editor:
+
+```json
+{
+  "mcpServers": {
+    "orka": {
+      "command": "orka",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
 
 ## Contributing
 
-Lihat [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orka-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Multi-agent orchestration CLI",
   "type": "module",
   "bin": {