colana 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2025-2026 Colana. All rights reserved.
+
+This software is proprietary and confidential.
+
+The use, reproduction, modification, or distribution of this software
+is governed by the terms available at https://colana.ai/terms.
+
+Commercial use requires an active license. See https://colana.ai/pricing
+for licensing options.
+
+For licensing inquiries, contact hello@colana.ai.

package/README.md

@@ -0,0 +1,319 @@
+<p align="center">
+  <img src="public/icons/icon.svg" width="80" height="80" alt="co:lana">
+</p>
+
+<h1 align="center">co:lana</h1>
+<p align="center"><strong>Agent-First. Multiplied.</strong></p>
+<p align="center">
+  A multi-agent command center for orchestrating AI coding agents across projects simultaneously.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/colana"><img src="https://img.shields.io/npm/v/colana.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/colana"><img src="https://img.shields.io/npm/dm/colana.svg" alt="npm downloads"></a>
+  <a href="https://github.com/colana-ai/colana/actions"><img src="https://img.shields.io/github/actions/workflow/status/colana-ai/colana/ci.yml?branch=main" alt="CI"></a>
+  <img src="https://img.shields.io/node/v/colana.svg" alt="Node.js version">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-proprietary-blue.svg" alt="License"></a>
+</p>
+
+---
+
+Run Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Aider, and OpenClaw side-by-side. Monitor output, manage sessions, track costs, and review diffs — all from a single browser tab.
+
+<!-- Screenshot placeholder: add a screenshot or GIF of the dashboard here -->
+
+## Quick Start
+
+```bash
+npm install -g colana    # Install globally
+colana                   # Start the dashboard
+```
+
+The dashboard opens in your browser at `http://localhost:9876`. On first run, a setup wizard walks you through installing and authenticating your preferred AI agents.
+
+## Supported Providers
+
+| Provider | Install Command | Auth | Resume |
+|----------|----------------|------|--------|
+| **Claude Code** | `npm i -g @anthropic-ai/claude-code` | Anthropic subscription or API key | Yes |
+| **Codex CLI** | `npm i -g @openai/codex` | OpenAI API key | Yes |
+| **Gemini CLI** | `npm i -g @google/gemini-cli` | Free Google account (no API key needed) | Yes |
+| **Copilot CLI** | Standalone binary or `gh extension install github/gh-copilot` | GitHub Copilot subscription | Yes |
+| **Aider** | `pipx install aider-chat` | LLM API key (OpenAI, Anthropic, etc.) | Yes |
+| **OpenClaw** | `npm i -g openclaw` | User-configured model keys | No |
+
+You need at least one provider installed. **Gemini CLI** is recommended for quick start — works with any Google account, no API key needed.
+
+## Features
+
+### Agent Orchestration
+- **Multi-provider dashboard** — run and observe agents across different projects from one screen
+- **Interactive PTY terminals** — full pseudo-terminal emulation for all 6 providers
+- **Real-time streaming** — terminal-speed output via WebSocket, no polling
+- **Split-pane view** — monitor multiple agents side-by-side
+- **Pop-out and maximize** — focus on one agent or drag it to a second monitor
+- **Safe Parallel Mode** — automatic git worktree isolation when multiple agents work on the same project
+
+### Session Management
+- **Universal resume** — resume sessions for all providers with native support
+- **Session history** — search across all projects by task title, project name, or conversation content
+- **Git checkpoints** — auto-capture git HEAD on session start, one-click restore, per-file accept/reject
+- **Git diff preview** — review file changes with "Open in Editor" integration
+- **Session export** — export session logs and conversation history
+- **Auto-resume** — automatically resume interrupted sessions on server restart
+
+### Personal Agent
+- **3-layer companion UI** — header strip with status, notification dropdown, slide-in panel
+- **Chat mode** — stream responses via OpenClaw's HTTP API with markdown rendering and syntax highlighting
+- **Terminal mode** — full xterm.js PTY session for power users
+- **Proactive notifications** — server-side detection of agent alerts with category icons
+- **Integration Hub** — connect 17 MCP tools (GitHub, Google Workspace, Slack, Notion, and more)
+- **Model configuration** — view and switch the Personal Agent's AI model from Settings
+
+### Productivity
+- **Command palette** — `Ctrl+K` fuzzy search with arrow navigation
+- **Task templates** — save and reuse common prompts (12 starter templates included)
+- **Clipboard snippets** — quick-access code snippets with search
+- **Cost tracking** — per-project token and cost tracking from CLI-reported data
+- **Context Sync** — automatic multi-agent project context sharing via AGENTS.md
+
+### Setup & Admin
+- **First-run wizard** — 6-step guided setup (scan, select, install, authenticate, done)
+- **Inline authentication** — Claude OAuth, API key inputs, GitHub device-code flow — no terminal needed
+- **Admin panel** — user stats, version/OS breakdown, analytics dashboard
+- **Admin CLI** — `colana admin` for key management and diagnostics
+- **System service** — auto-start on login via `colana service install`
+- **Auto-updates** — automatic update detection with in-app install
+
+### Enterprise Quality
+- **4-tier rate limiting** — general, agent, sensitive, and admin tiers
+- **Input validation** — Zod schemas on all POST endpoints
+- **AES-256-GCM encryption** — for stored API keys and tokens
+- **Structured logging** — JSONL server logs with daily rotation
+- **PWA support** — installable as a standalone desktop app
+- **Free tier** — full product, 2 concurrent sessions, no trial, no expiry
+
+## Pricing
+
+| | Free | Pro |
+|---|---|---|
+| **Price** | $0 forever | $9/mo or $79/yr |
+| **Concurrent sessions** | 2 | Unlimited |
+| **All 6 providers** | Yes | Yes |
+| **All features** | Yes | Yes |
+| **Updates** | Stable channel | Stable + beta channel |
+
+No trial. No expiry. Free tier is the full product — only concurrent session count is gated. Upgrade when you naturally need 3+ agents running simultaneously.
+
+Payments handled by [Polar.sh](https://polar.sh) (Merchant of Record — tax, subscriptions, refunds).
+
+## System Requirements
+
+| Requirement | Minimum |
+|-------------|---------|
+| **Node.js** | 18.0.0 or later |
+| **OS** | Linux, macOS, or Windows (WSL2 recommended) |
+| **CPU** | x64 or ARM64 |
+| **RAM** | ~100 MB per concurrent agent |
+| **Disk** | ~50 MB installed + runtime data |
+| **Browser** | Chrome or Edge (desktop) |
+
+## CLI Reference
+
+```bash
+colana                   # Start the dashboard (auto-detects free port from 9876)
+colana --version         # Show version
+colana --help            # Show help
+colana doctor            # Run diagnostic checks
+colana doctor --verbose  # Detailed diagnostics with provider paths
+
+colana admin create-key --name "User" --type pro --email user@example.com
+colana admin list-keys [--type <type>] [--status <active|revoked>] [--format table|csv|json]
+colana admin revoke-key --name "User"
+colana admin key-info --name "User"
+colana admin update-key --name "User" [--expires <date>] [--max-machines <n>]
+colana admin staff-keys
+
+colana service install   # Auto-start on login (systemd / LaunchAgent / Registry)
+colana service uninstall
+colana service status
+colana service logs
+```
+
+See [docs/CLI.md](docs/CLI.md) for the full CLI reference.
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+K` | Open command palette |
+| `Ctrl+B` | Toggle sidebar |
+| `` Ctrl+` `` | Toggle Personal Agent panel |
+| `1`–`9` | Select active agent by index |
+| `F11` | Maximize current agent |
+| `Esc` | Exit maximize / close modal |
+
+## Environment Variables
+
+All optional. Defaults work for local use.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `START_PORT` | `9876` | First port to scan |
+| `DATA_DIR` | `./data` | SQLite database + logs directory |
+| `ENCRYPTION_KEY` | auto-generated | AES-256-GCM key for stored secrets |
+| `BIND_ADDRESS` | `127.0.0.1` | Server bind address |
+| `PTY_BUFFER_SIZE` | `262144` | PTY ring buffer in bytes (256 KB) |
+| `SHUTDOWN_TIMEOUT_MS` | `10000` | Graceful shutdown timeout |
+| `FREE_MAX_SESSIONS` | `2` | Free tier concurrent session limit |
+| `LOG_RETENTION_DAYS` | `0` | Log retention in days (0 = keep all) |
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all 30+ configuration options.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Backend** | Node.js + Express + WebSocket (ws) |
+| **Database** | SQLite via sql.js (WASM — zero native compilation) |
+| **Terminal** | node-pty for PTY emulation |
+| **Frontend** | Vanilla HTML / CSS / JS (no build step) |
+| **Validation** | Zod (schema validation on all inputs) |
+| **Rate Limiting** | express-rate-limit (4-tier) |
+| **Encryption** | AES-256-GCM for stored secrets |
+| **Testing** | Vitest (unit) + Playwright (E2E) |
+| **Licensing** | Polar.sh (Merchant of Record) |
+| **Distribution** | npm (global package with prebuilt binaries) |
+
+## Project Structure
+
+```
+colana/
+├── bin/
+│   ├── colana.js              # CLI entry point + first-run wizard + doctor
+│   └── admin.js               # Admin CLI (key management, diagnostics)
+├── server/
+│   ├── index.js               # Express + WebSocket server entry
+│   ├── config.js              # Provider definitions (6 providers), Polar.sh config
+│   ├── db.js                  # SQLite schema + migration system
+│   ├── agent-manager.js       # Agent spawn/stop (headless JSON mode)
+│   ├── pty-manager.js         # PTY terminal management + idle cleanup
+│   ├── session-store.js       # Session CRUD + log persistence
+│   ├── project-store.js       # Project CRUD
+│   ├── settings-store.js      # Settings + API key encryption
+│   ├── template-store.js      # Task template CRUD
+│   ├── snippet-store.js       # Clipboard snippet CRUD
+│   ├── license.js             # Polar.sh license validation + cache
+│   ├── key-manager.js         # SQLite-stored license key CRUD
+│   ├── admin.js               # Admin panel API routes
+│   ├── analytics.js           # Anonymous product analytics
+│   ├── validation.js          # Zod schemas + validation middleware
+│   ├── logger.js              # Structured JSONL logging + rotation
+│   ├── context-sync.js        # Multi-agent context sharing (AGENTS.md)
+│   ├── worktree-manager.js    # Safe Parallel Mode (git worktree isolation)
+│   ├── integration-hub.js     # MCP integration catalog + config
+│   ├── openclaw-config.js     # OpenClaw config reader/writer
+│   ├── updater.js             # Auto-update checker (npm registry)
+│   ├── port-finder.js         # Auto-detect free port
+│   ├── platform.js            # Cross-platform utilities
+│   ├── service-manager.js     # System service (systemd, LaunchAgent, Registry)
+│   └── ...routes.js           # 15+ route modules (sessions, projects, agents, etc.)
+├── public/
+│   ├── index.html             # Main dashboard SPA
+│   ├── admin.html             # Admin panel
+│   ├── wizard.html            # Onboarding wizard
+│   ├── agent.html             # Pop-out agent window
+│   ├── agent-split.html       # Split-pane agent view
+│   ├── styles.css             # Dark theme styling
+│   ├── app.js                 # Dashboard logic
+│   ├── manifest.json          # PWA manifest
+│   ├── service-worker.js      # PWA service worker
+│   └── vendor/                # Local vendor libs (marked, highlight.js)
+├── scripts/
+│   ├── build.js               # Build pipeline (esbuild + bytenode + obfuscator)
+│   ├── prebuild.js            # Compile node-pty for current platform
+│   └── release.sh             # Release automation
+├── .github/workflows/
+│   ├── ci.yml                 # CI: cross-platform test matrix
+│   └── release.yml            # Release: prebuild + npm publish
+├── test/
+│   ├── server/                # Vitest unit tests (90+ files)
+│   └── e2e/                   # Playwright E2E tests
+├── docs/                      # Documentation
+│   ├── CLI.md                 # CLI reference
+│   ├── PROVIDERS.md           # Provider setup guides
+│   ├── CONFIGURATION.md       # Configuration reference
+│   ├── TROUBLESHOOTING.md     # FAQ and common issues
+│   └── API.md                 # REST + WebSocket API reference
+└── data/                      # Created at runtime
+    ├── dashboard.db           # SQLite database
+    ├── encryption.key         # Auto-generated encryption key
+    ├── backups/               # Daily database backups
+    ├── logs/                  # Server + agent JSONL logs
+    └── worktrees/             # Safe Parallel Mode worktrees
+```
+
+## Development
+
+```bash
+git clone https://github.com/colana-ai/colana.git
+cd colana
+npm install
+
+npm run dev          # Start dev server (port 9877, auto-reload)
+npm test             # Run unit tests (Vitest)
+npm run test:e2e     # Run E2E tests (Playwright)
+npm run test:all     # Run both unit and E2E tests
+npm run build        # Build dist/ for npm publish
+npm run release      # Test + build + publish + tag
+```
+
+## FAQ
+
+**Do I need API keys for all providers?**
+No. Install only the providers you use. Gemini CLI works with just a Google account — no API key needed. Free tier gives you 2 concurrent sessions with any combination of providers.
+
+**Does co:lana send my code anywhere?**
+No. co:lana runs entirely on your machine. It orchestrates CLI tools that run locally. Your code stays on your filesystem. The only external calls are license validation (Polar.sh) and the CLI providers' own API connections.
+
+**Can I use co:lana without paying?**
+Yes. The Free tier is the full product with no trial or expiry. The only limit is 2 concurrent sessions. You can run one agent at a time indefinitely.
+
+**What happens if the server crashes?**
+Sessions are persisted to SQLite. On restart, co:lana detects interrupted sessions and offers to resume them automatically (auto-resume is on by default).
+
+**Does it work on Windows?**
+Yes, via WSL2 (recommended). Native Windows support is available but WSL2 provides the most reliable experience for node-pty and CLI tools.
+
+**Can multiple users share one instance?**
+co:lana is designed for single-user local use. It binds to `127.0.0.1` by default. For multi-user setups, each user runs their own instance.
+
+**How do I update?**
+co:lana checks for updates automatically and shows an in-app banner. Click "Install" to update, or run `npm update -g colana` manually.
+
+**Where is my data stored?**
+In the `data/` directory (configurable via `DATA_DIR`): SQLite database, encrypted API keys, server logs, and database backups.
+
+## Documentation
+
+- [CLI Reference](docs/CLI.md) — all commands, flags, and options
+- [Provider Setup](docs/PROVIDERS.md) — per-provider installation and authentication
+- [Configuration](docs/CONFIGURATION.md) — environment variables and settings
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common issues and fixes
+- [API Reference](docs/API.md) — REST endpoints and WebSocket protocol
+- [Security Policy](SECURITY.md) — vulnerability reporting
+- [Support](SUPPORT.md) — how to get help
+
+## Support
+
+- **Bug reports** — [GitHub Issues](https://github.com/colana-ai/colana/issues/new?template=bug_report.yml)
+- **Feature requests** — [GitHub Issues](https://github.com/colana-ai/colana/issues/new?template=feature_request.yml)
+- **Security** — [security@colana.ai](mailto:security@colana.ai) (see [SECURITY.md](SECURITY.md))
+- **Licensing** — [support@colana.ai](mailto:support@colana.ai) or [Polar.sh dashboard](https://polar.sh)
+- **Website** — [colana.ai](https://colana.ai)
+
+## License
+
+Proprietary. See [LICENSE](LICENSE) for terms. Commercial use requires an active license — see [colana.ai/pricing](https://colana.ai/pricing).
+
+Copyright (c) 2025-2026 Colana. All rights reserved.