colana 1.0.0-beta.9 → 1.0.0-beta.91

package/README.md

@@ -11,7 +11,6 @@
 <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>
@@ -33,65 +32,47 @@ The dashboard opens in your browser at `http://localhost:9876`. On first run, a
 
 ## 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 |
+| Provider | Auth | Resume |
+|----------|------|--------|
+| **Claude Code** | Anthropic subscription or API key | Yes |
+| **Codex CLI** | OpenAI API key | Yes |
+| **Gemini CLI** | Free Google account (no API key needed) | Yes |
+| **Copilot CLI** | GitHub Copilot subscription | Yes |
+| **Aider** | LLM API key (OpenAI, Anthropic, etc.) | Yes |
+| **OpenClaw** | User-configured model keys | — |
 
-You need at least one provider installed. **Gemini CLI** is recommended for quick start — works with any Google account, no API key needed.
+You need at least one provider installed. **Gemini CLI** is recommended for quick start — works with any Google account, no API key needed. The setup wizard detects and installs missing providers automatically.
 
 ## 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
+- **Interactive terminals** — full terminal emulation for all 6 providers
+- **Real-time streaming** — instant terminal output, 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
+- **Pop-out windows** — focus on one agent or drag it to a second monitor
+- **Safe Parallel Mode** — automatic 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
+- **Session history** — search across all projects by title, project, or conversation content
+- **Git checkpoints** — auto-capture state 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
+- **Always-on companion** — header strip, notification dropdown, and slide-in panel
+- **Chat and terminal modes** — stream responses or use the full terminal
+- **Proactive notifications** — alerts with category icons and deep links
+- **Integration Hub** — connect 17 tools (GitHub, Google Workspace, Slack, Notion, and more)
+- **Model switching** — change the 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)
+- **Command palette** — `Ctrl+K` fuzzy search
+- **Task templates** — save and reuse common prompts
 - **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
+- **Cost tracking** — per-project token and cost tracking
+- **Context Sync** — automatic multi-agent project context sharing
 
 ## Pricing
 
@@ -99,221 +80,68 @@ You need at least one provider installed. **Gemini CLI** is recommended for quic
 |---|---|---|
 | **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 |
+| **All 6 providers** | Yes | Yes |
 
-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.
+No trial. No expiry. Free tier is the full product — only concurrent session count is gated.
 
-Payments handled by [Polar.sh](https://polar.sh) (Merchant of Record — tax, subscriptions, refunds).
+Payments handled by [Polar.sh](https://polar.sh) (Merchant of Record).
 
 ## 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) |
+- **Node.js** 18.0.0 or later
+- **OS:** Linux, macOS, or Windows (WSL2 recommended)
+- **Browser:** Chrome or Edge (desktop)
 
-## CLI Reference
+## CLI
 
 ```bash
-colana                   # Start the dashboard (auto-detects free port from 9876)
+colana                   # Start the dashboard
 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
+colana doctor            # Check system health
+colana service install   # Auto-start on login
 ```
 
-See [docs/CLI.md](docs/CLI.md) for the full CLI reference.
-
 ## Keyboard Shortcuts
 
 | Shortcut | Action |
 |----------|--------|
-| `Ctrl+K` | Open command palette |
+| `Ctrl+K` | 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
-```
+| `` Ctrl+` `` | Personal Agent panel |
+| `F11` | Fullscreen |
 
 ## 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.
+No. Install only the ones you use. Gemini CLI works with just a Google account.
 
 **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.
+No. Everything runs locally on your machine. Your code never leaves your filesystem.
 
 **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.
+Yes. Free tier is the full product with no expiry. The only limit is 2 concurrent sessions.
 
 **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).
+Sessions are persisted and auto-resume on restart.
 
 **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.
+Yes, via WSL2 (recommended). Native Windows is also supported.
 
 **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.
+co:lana checks for updates automatically and shows an in-app banner, or run `npm update -g colana`.
 
 **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
+Locally in the `data/` directory — database, encrypted API keys, and logs.
 
 ## 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)
+- **Email** — [support@colana.ai](mailto:support@colana.ai)
+- **Security** — [security@colana.ai](mailto:security@colana.ai)
 
 ## License
 
-Proprietary. See [LICENSE](LICENSE) for terms. Commercial use requires an active license — see [colana.ai/pricing](https://colana.ai/pricing).
+Proprietary. See [LICENSE](LICENSE) for terms.
 
 Copyright (c) 2025-2026 Colana. All rights reserved.

package/bin/admin.js

@@ -156,12 +156,14 @@ async function createKey(flags) {
     console.error(`\n  ${icons.fail} ${c.error}ERROR: --name is required.${c.reset}\n`);
     console.error('  Usage: colana admin create-key --name "Sarah" --type staff [--email x] [--expires 2026-12-31]\n');
     process.exit(1);
+    return;
   }
 
   const validTypes = ['admin', 'staff', 'beta'];
   if (!validTypes.includes(type)) {
     console.error(`\n  ${icons.fail} ${c.error}ERROR: Invalid type "${type}". Must be one of: ${validTypes.join(', ')}${c.reset}\n`);
     process.exit(1);
+    return;
   }
 
   // Prefer server API (avoids sql.js in-memory DB conflict)
@@ -174,6 +176,7 @@ async function createKey(flags) {
     } catch (err) {
       console.error(`\n  ${icons.fail} ${c.error}${err.message}${c.reset} ${c.muted}(via server)${c.reset}\n`);
       process.exit(1);
+      return;
     }
   } else {
     // Fallback: direct DB access (only safe when server is NOT running)
@@ -184,9 +187,16 @@ async function createKey(flags) {
     } catch (err) {
       console.error(`\n  ${icons.fail} ${c.error}${err.message}${c.reset}\n`);
       process.exit(1);
+      return;
     }
   }
 
+  if (!result || !result.name) {
+    console.error(`\n  ${icons.fail} ${c.error}Key generation returned an unexpected response.${c.reset}\n`);
+    process.exit(1);
+    return; // Guard for test environments where process.exit is mocked
+  }
+
   console.log('');
   console.log(`  ${icons.pass} Key generated successfully!`);
   console.log(`  ${c.muted}${'─'.repeat(40)}${c.reset}`);
@@ -219,6 +229,7 @@ async function listKeysCmd(flags) {
     } catch (err) {
       console.error(`\n  ${icons.fail} ${c.error}${err.message}${c.reset} ${c.muted}(via server)${c.reset}\n`);
       process.exit(1);
+      return;
     }
   } else {
     await ensureDb();
@@ -226,7 +237,7 @@ async function listKeysCmd(flags) {
     result = listKeys(filters);
   }
 
-  if (!result.keys.length) {
+  if (!result || !result.keys || !result.keys.length) {
     console.log('\n  No keys found.\n');
     return;
   }
@@ -257,6 +268,7 @@ async function revokeKeyCmd(positional) {
     console.error(`\n  ${icons.fail} ${c.error}ERROR: Key ID is required.${c.reset}\n`);
     console.error('  Usage: colana admin revoke-key <id>\n');
     process.exit(1);
+    return;
   }
 
   // Prefer server API
@@ -269,6 +281,7 @@ async function revokeKeyCmd(positional) {
     } catch (err) {
       console.error(`\n  ${icons.fail} ${c.error}${err.message}${c.reset} ${c.muted}(via server)${c.reset}\n`);
       process.exit(1);
+      return;
     }
   } else {
     await ensureDb();
@@ -279,6 +292,7 @@ async function revokeKeyCmd(positional) {
     } catch (err) {
       console.error(`\n  ${icons.fail} ${c.error}${err.message}${c.reset}\n`);
       process.exit(1);
+      return;
     }
   }
 }
@@ -375,7 +389,11 @@ async function main() {
       console.error(`  ${icons.fail} Unknown command: ${c.value}${command}${c.reset}`);
       console.error(`  ${c.muted}Run "colana admin help" for usage.${c.reset}`);
       process.exit(1);
+      return;
   }
 }
 
-main();
+main().catch((err) => {
+  console.error(`  ${icons.fail} ${c.error}${err.message || err}${c.reset}`);
+  process.exit(1);
+});