zenctl 0.2.0

package/README.md

@@ -0,0 +1,134 @@
+# zenctl — OpenCode Zen distributed egress proxy (v2)
+
+A single compiled binary, `zenctl`, that spreads OpenCode Zen API traffic across
+a pool of egress nodes. Run one **coordinator** on a public host and any number
+of **nodes** on machines whose IPs you want to use for egress. Requests are
+routed by tier priority (your own node first, then others, then a direct
+fallback), so per-IP rate limits are spread across the pool.
+
+## Architecture
+
+```
+                       cloudflared (TLS, one hostname)
+                                  │
+OpenCode ──patch baseURL──▶ Coordinator (Bun, one port 9090)
+                                  │  • OpenAI API (/v1/chat/completions, /v1/models)
+                                  │  • Dashboard (GET /) + SSE logs (/api/logs/stream)
+                                  │  • Admin API (/api/admin/*)
+                                  │  • WebSocket for nodes (/ws)
+                                  ▼
+                    ┌─────────────┼─────────────┐
+                 Node tier 1   Node tier 2   Node tier 3
+                    │             │             │
+                    └─────────────┼─────────────┘
+                                  ▼
+                            opencode.ai/zen/v1
+                     (request egresses from a node's IP)
+```
+
+Everything runs on **one port** (Bun serves HTTP + WebSocket together). Nodes
+connect out over WebSocket, so they work behind NAT. There is no TUI and no
+separate proxy daemon — `zenctl node` is the only process a node machine runs.
+
+## Requirements
+
+- [Bun](https://bun.sh) ≥ 1.3
+- MongoDB (optional — the coordinator degrades to in-memory storage if absent)
+- `cloudflared` on the coordinator host for public TLS ingress (optional)
+
+## Install
+
+```bash
+# Via npm (requires Bun)
+npm install -g zenctl
+
+# Or run directly without installing:
+npx zenctl --help
+
+# Or via bun:
+bunx zenctl --help
+```
+
+## Quick start
+
+```bash
+# 1. On the coordinator host:
+zenctl coordinator --port 9090
+#    → prints a bootstrap admin key (ak_...) when running without MongoDB
+
+# 2. Mint a node key using the admin API (or `zenctl keys generate`):
+curl -X POST http://localhost:9090/api/admin/keys \
+  -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" \
+  -d '{"label":"my-laptop","type":"node"}'
+
+# 3. On each node machine:
+zenctl node --server ws://localhost:9090/ws --api-key nk_... --tier 1
+
+# 4. On the client machine, point OpenCode at the coordinator:
+zenctl patch --server https://ai.example.com
+```
+
+## Commands
+
+| Command | Purpose | Key flags |
+|---|---|---|
+| `zenctl coordinator` | Start the coordinator server | `--port`, `--config`, `--mongo-uri`, `--no-cloudflared` |
+| `zenctl node` | Start a node client | `--server` (required), `--api-key`, `--tier` (1-3), `--data-dir` |
+| `zenctl patch` | Point OpenCode's `baseURL` at the coordinator | `--server <url>`, `--restore`, `--show` |
+| `zenctl init` | Flag-driven setup (writes `~/.config/zenctl/config.json`) | `--role coordinator\|node`, `--server`, `--api-key`, `--tier`, `--port`, `--mongo-uri`, `--force` |
+| `zenctl keys generate` | Generate a node (`nk_*`) or admin (`ak_*`) key | `--type node\|admin`, `--label` |
+| `zenctl keys list` | List keys (prefix + label only, never the raw key) | |
+| `zenctl keys revoke` | Revoke a key by prefix | `--prefix` |
+
+Run any command with `--help` for full details. `zenctl --version` prints the
+version.
+
+## Admin API
+
+All `/api/admin/*` endpoints require an `Authorization: Bearer ak_*` admin key
+and are rate-limited to 10 requests/minute per IP.
+
+| Method & path | Purpose |
+|---|---|
+| `GET /api/admin/status` | Version, uptime, node count, rate-limited count, MongoDB status |
+| `GET /api/admin/nodes` | Connected nodes (id, name, tier, status, activeRequests, …) |
+| `GET /api/admin/keys` | List keys (prefix, label, type, createdAt, revoked) |
+| `POST /api/admin/keys` | Create a key `{ label, type }` — returns the raw key once |
+| `DELETE /api/admin/keys/:prefix` | Revoke a key (refuses the last active admin key) |
+
+Raw keys and hashes are never returned by any list endpoint. A freshly created
+key is the only place the raw value appears, exactly once.
+
+## Configuration
+
+Resolution order (later wins): built-in defaults → config file
+(`ZENCTL_CONFIG` path or `~/.config/zenctl/config.json`) → `ZENCTL_*` env vars.
+
+Env vars follow `ZENCTL_<SECTION>_<KEY>`, e.g.:
+
+| Env var | Overrides |
+|---|---|
+| `ZENCTL_COORDINATOR_PORT` | Coordinator listen port (default 9090) |
+| `ZENCTL_MONGODB_URI` | MongoDB connection string |
+| `ZENCTL_NODE_SERVER_URL` | Node's coordinator WebSocket URL |
+| `ZENCTL_NODE_API_KEY` | Node API key |
+| `ZENCTL_LOGGING_BUFFERSIZE` | In-memory log buffer size (default 1000) |
+
+Malformed values fall back to defaults; the loader never throws.
+
+## Deployment
+
+- **systemd:** copy [`scripts/opencode-zenctl.service`](./scripts/opencode-zenctl.service)
+  (coordinator) or [`scripts/opencode-zenctl-node.service`](./scripts/opencode-zenctl-node.service)
+  (node) to `/etc/systemd/system/`, then `systemctl enable --now`.
+- **cloudflared:** see [`scripts/cloudflared-config.yml`](./scripts/cloudflared-config.yml)
+  — a single ingress rule routes your hostname to `localhost:9090` (HTTP and
+  WebSocket share the port).
+
+## Tests
+
+```bash
+bun test            # full v2 suite
+bun run tsc --noEmit  # type check
+```
+

package/bin/zenctl.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// zenctl — Node shim that spawns the Bun runtime to execute the compiled bundle.
+// This allows `npx zenctl` to work on systems with Bun installed.
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const entry = join(__dirname, "..", "dist", "zenctl.js");
+
+// Try `bun` first, then `bun.exe` on Windows
+const candidates = process.platform === "win32" ? ["bun", "bun.exe"] : ["bun"];
+
+async function findBun() {
+  for (const name of candidates) {
+    try {
+      const { execSync } = await import("node:child_process");
+      execSync(name + " --version", { stdio: "ignore" });
+      return name;
+    } catch {
+      // not found, try next
+    }
+  }
+  return null;
+}
+
+const bun = await findBun();
+
+if (!bun) {
+  console.error("");
+  console.error("  zenctl requires Bun to run.");
+  console.error("  Install it:  https://bun.sh");
+  console.error("  Then try:    bunx zenctl");
+  console.error("");
+  process.exit(1);
+}
+
+const child = spawn(bun, ["run", entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});