@konstantdotcloud/boombox 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# @konstantdotcloud/boombox
+
+CLI and MCP bridge for a tenant's Boombox VM.
+
+Boombox Cloud lives at <https://boombox.konstant.cloud>. Each tenant VM is served at `https://boombox-<tenant>.exe.xyz`. The CLI stores your tenant identity, talks to the VM, and exposes the Gary cassette runtime to Claude Desktop, Claude Code, Cursor, OpenClaw, or any MCP client.
+
+## Install
+
+```bash
+curl -fsSL https://boombox.konstant.cloud/install/boombox.sh | sh
+```
+
+The installer installs `@konstantdotcloud/boombox` and then tells you to run `boombox login`.
+
+## Quickstart
+
+```bash
+boombox login       # browser sign-in via boombox.konstant.cloud; writes ~/.boombox/config.toml
+boombox whoami      # verifies tenant, user, VM URL, and key expiry
+boombox admin       # opens the VM admin UI through a short-lived cloud grant
+boombox run bd_pre_meeting_brief --input meeting_uid=sample --input organizer=user@example.com --input attendees='["user@example.com"]' --input start_time=2026-06-02T15:00:00Z --input summary=Sample
+```
+
+For MCP clients, add `boombox serve --mcp` after `boombox login` succeeds.
+
+## Commands
+
+| Command | What it does |
+|-|-|
+| `boombox login [--tenant <tenant_id>]` | Browser sign-in through `boombox.konstant.cloud`; writes tenant id, VM URL, API key, and expiry to `~/.boombox/config.toml`. |
+| `boombox whoami` | Calls the VM identity endpoint and prints tenant id, user id, VM URL, key expiry, and days remaining. |
+| `boombox admin` | Requests a short-lived admin grant from Boombox Cloud and opens the tenant VM admin UI. |
+| `boombox run <cassette_name> [--input key=value ...] [--no-tail] [--json]` | Manually triggers a cassette through `/gateway/rack/run`, prompts for required missing inputs, then polls to a terminal state unless `--no-tail` is set. |
+| `boombox cassettes list` | Lists active cassettes available to the tenant. |
+| `boombox cassettes show <id> [--draft]` | Prints a cassette YAML projection. |
+| `boombox runs list [--cassette=X] [--since=24h] [--actor=Y] [--status=completed] [--limit=20]` | Lists recent runs with run id, cassette, actor, status, duration, and start time. |
+| `boombox runs show <run_id>` | Shows one run: spec hash, inputs, step trace, delivery receipts, error summary, and replay ref. |
+| `boombox logs tail [--cassette=X]` | Tails run/step events from the VM SSE stream. |
+| `boombox artifacts open <artifact_id>` | Opens `<vm_url>/artifact/<artifact_id>` in the system browser. |
+| `boombox keys list` | Lists tenant API keys visible to the current API key authority. |
+| `boombox capabilities list [--kind=recipe\|tool\|artifact_template\|prompt_template] [--status=available\|missing]` | Lists registered tenant capabilities. |
+| `boombox status` | Checks VM health, `/v2/api/info`, and the run-event stream. |
+| `boombox doctor` | Checks config, VM reachability, API-key validity, and MCP boot. |
+| `boombox init` | Manual config fallback for provisioned credentials. Most users should prefer `boombox login`. |
+| `boombox enroll` | Browser enrollment flow that can write config from a provisioning payload. |
+| `boombox serve [--mcp] [--http] [--port <port>]` | Starts stdio MCP and/or the local HTTP proxy. MCP clients should use `--mcp`. |
+| `boombox reload` | Sends SIGHUP to a running local `boombox serve`. |
+| `boombox restart` | Stops and respawns local `boombox serve`. |
+| `boombox stop` | Stops a running local `boombox serve`. |
+| `boombox upgrade` | Self-update through npm. |
+
+## Config file
+
+`~/.boombox/config.toml`:
+
+```toml
+[konstant]
+tenant_id = "example"
+api_key = "kn_example_***"
+gateway_url = "https://boombox.konstant.cloud/v2"
+
+[runtime]
+default_kind = "vm"
+vm_url = "https://boombox-example.exe.xyz"
+
+[boombox]
+http_port = 8787
+mcp_enabled = true
+
+[admin]
+```
+
+`runtime.vm_url` is the preferred target. If it is present, CLI commands talk to the tenant VM. `gateway_url` remains the shared cloud fallback and login/onboarding origin.
+
+The file is created with mode `600`. Override the location with `BOOMBOX_HOME=/some/dir` (config lives at `$BOOMBOX_HOME/config.toml`).
+
+## MCP client setup
+
+### Claude Desktop / Claude Code / Cursor / OpenClaw
+
+```json
+{
+  "mcpServers": {
+    "boombox": {
+      "command": "boombox",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
+```
+
+After saving, restart your client. The default MCP profile exposes the chat-parity tools: `ask_gary`, `list_threads`, `clear_thread`, `artifact_fetch`, and `gary_status`. Advanced/operator profiles can expose rack, prompt, cassette, and admin verbs when explicitly enabled.
+
+## Ops route contracts
+
+The ops CLI uses direct HTTP service routes with `Authorization: Bearer <tenant_api_key>`; it does not speak MCP wire format.
+
+| CLI command | Primary route contract |
+|-|-|
+| `whoami` | `GET /v2/api/me`. |
+| `status` | `GET /health`, `GET /v2/api/info`, `GET /admin/runs/stream` (fallback: `/api/admin/runs/stream`). |
+| `runs list` | `GET /api/admin/runs` with `cassette`, `since`, `actor`, `status`, `limit`; fallback: `GET /api/admin/cassettes/runs`. |
+| `runs show` | `GET /api/admin/runs/:run_id`; fallback: `GET /api/admin/cassettes/runs/:run_id/replay`. |
+| `logs tail` | `GET /admin/runs/stream` SSE; fallback: `GET /api/admin/runs/stream`. |
+| `run` | `GET /api/admin/cassettes/:id` for required input metadata, `POST /gateway/rack/run` to trigger, then `GET /api/admin/runs/:run_id` or replay fallback to poll. |
+| `cassettes list` | `GET /api/admin/cassettes`; the VM route currently defaults unknown status filters to `active`. |
+| `cassettes show` | `GET /api/admin/cassettes/:id/yaml?draft=true`; falls back to `GET /api/admin/cassettes/:id` if YAML is not wired. |
+| `keys list` | `GET /api/admin/keys`. |
+| `capabilities list` | `GET /api/admin/capabilities`. |
+
+## Local HTTP server
+
+When `boombox serve --http` is running, your browser hits Hono on `localhost:8787`:
+
+- `GET http://localhost:8787/` → the bundled Boombox UI when `packages/boombox/ui/dist` exists.
+- `GET http://localhost:8787/api/...` → proxied to the configured VM/cloud gateway with `Authorization: Bearer <api_key>` injected. The browser never sees your API key.
+- `GET http://localhost:8787/gateway/...` → rewritten to `/api/gateway/...` upstream.
+- `GET http://localhost:8787/healthz` → 200 if config loaded.
+
+If `ui/dist/` is missing, `/` and SPA routes return `503 ui_not_built`; `/healthz` and `/api/*` still work. Run `cd packages/boombox/ui && npm run build` to populate `ui/dist/`.
+
+CORS is locked to `localhost`/`127.0.0.1` origins.
+
+## Troubleshooting
+
+- **`boombox doctor` says "config not found"** — run `boombox login`; use `boombox init` only when Konstant gave you raw VM credentials.
+- **`whoami` returns 401/403** — the API key is invalid, expired, or lacks authority. Run `boombox login` to refresh it.
+- **`gateway: unreachable`** — verify `runtime.vm_url` in `~/.boombox/config.toml`; the expected VM domain is `https://boombox-<tenant>.exe.xyz`.
+- **Run stays queued** — the VM may not have an Inngest/worker dispatcher wired for that cassette. Check `boombox runs show <run_id>` and the VM admin run trace.
+- **Port 8787 already in use** — pass `--port 9000` to `boombox serve --http`, or set `http_port` in config.
+- **MCP boot test fails** — make sure your Node version is `>= 20`.
+
+## Privacy & data
+
+The CLI stores config and API keys locally; it does not store run output, telemetry, or tenant data on disk. Runtime data, replay packets, artifacts, and events live in the tenant VM/Mongo path configured for that tenant. LLM calls route through the tenant's configured provider path.
+
+## Versioning
+
+`0.1.0` — V1 ships with the default MCP tools plus CLI commands for login, VM status, cassette runs, run inspection, artifacts, keys, capabilities, admin, and lifecycle control. Run `boombox upgrade` to pull updates.
+
+## License
+
+UNLICENSED — internal Konstant package.