uplink-cli 0.1.26 → 0.1.28

package/docs/AGENTS.md

@@ -0,0 +1,139 @@
+# Agent Integration Guide
+
+For agents (Cursor/Claude/GPT/Windsurf) to use Uplink non-interactively.
+
+## Auth
+- Use `AGENTCLOUD_TOKEN` (bearer). Avoid argv; prefer stdin:
+  ```bash
+  echo "$TOKEN" | uplink --token-stdin ...
+  ```
+- API base override: `--api-base https://api.uplink.spot` (or `AGENTCLOUD_API_BASE`).
+
+## Signup (no auth required)
+```bash
+uplink signup --json
+uplink signup --label "cursor-agent" --expires-days 30 --json
+```
+JSON example:
+```json
+{
+  "id": "tok_xxx",
+  "token": "abc123...",
+  "tokenPrefix": "abc123",
+  "role": "user",
+  "userId": "user_xxx",
+  "label": "cursor-agent",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "expiresAt": "2025-01-31T00:00:00.000Z",
+  "message": "Token created successfully. Save this token securely..."
+}
+```
+Save `token`—shown only once.
+
+## Machine-mode contract
+- `--json` → stdout = JSON only; stderr = logs/errors.
+- Exit codes: 0 ok; 2 usage; 10 auth missing/invalid; 20 network; 30 server/unknown.
+- Premium alias gating: alias commands may return `ALIAS_NOT_ENABLED` / `ALIAS_LIMIT_REACHED`.
+
+## Core CLI flows (non-interactive)
+```bash
+# Create tunnel (optional alias if enabled)
+echo "$TOKEN" | uplink --token-stdin --api-base https://api.uplink.spot \
+  tunnel create --port 3000 --alias myapp --json
+
+# List tunnels (includes connection status)
+echo "$TOKEN" | uplink --token-stdin tunnel list --json
+
+# Set alias on tunnel
+echo "$TOKEN" | uplink --token-stdin tunnel alias-set --id tun_xxx --alias myapp --json
+
+# Delete alias from tunnel
+echo "$TOKEN" | uplink --token-stdin tunnel alias-delete --id tun_xxx --json
+
+# Stats
+echo "$TOKEN" | uplink --token-stdin tunnel stats --id tun_xxx --json
+
+# Stop/delete tunnel
+echo "$TOKEN" | uplink --token-stdin tunnel stop --id tun_xxx --json
+```
+
+### JSON shapes (representative)
+- Create: `{ "tunnel": { id, url?, token?, alias?, aliasUrl?, targetPort, status, connected?, createdAt }, "alias": "myapp"|null, "aliasError": "..."|null }`
+- List: `{ "tunnels": [ { id, url?, token?, alias?, aliasUrl?, targetPort, status, connected, createdAt } ], "count": n }`
+- Stats: alias tunnels include persisted totals + relay overlay; token-only tunnels show in-memory relay stats.
+
+**Note:** The `connected` field indicates whether the tunnel is actually connected to the relay server (verified via socket health check).
+
+## HTTP API Reference
+
+Auth: `Authorization: Bearer <AGENTCLOUD_TOKEN>`
+
+### Tunnels
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/v1/tunnels` | Create tunnel (body: `{ port, alias? }`) |
+| `GET` | `/v1/tunnels` | List user's tunnels (includes `connected` status) |
+| `GET` | `/v1/tunnels/{id}` | Get tunnel details |
+| `GET` | `/v1/tunnels/{id}/stats` | Get tunnel statistics |
+| `DELETE` | `/v1/tunnels/{id}` | Delete tunnel |
+| `POST` | `/v1/tunnels/{id}/alias` | Set alias on tunnel (body: `{ alias }`) |
+| `DELETE` | `/v1/tunnels/{id}/alias` | Remove alias from tunnel |
+
+### Port-Based Aliases (Premium)
+Aliases are now **port-based**: they persist across tunnel restarts and always point to the same port.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/v1/tunnels/aliases` | List all aliases for user |
+| `POST` | `/v1/tunnels/aliases` | Create alias for port (body: `{ alias, port }`) |
+| `PUT` | `/v1/tunnels/aliases/{alias}` | Reassign alias to different port (body: `{ port }`) |
+| `DELETE` | `/v1/tunnels/aliases/{alias}` | Delete alias |
+
+### Example: Create port-based alias
+```bash
+curl -X POST https://api.uplink.spot/v1/tunnels/aliases \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"alias": "myapp", "port": 3000}'
+```
+
+Response:
+```json
+{
+  "id": "alias_xxx",
+  "alias": "myapp",
+  "targetPort": 3000,
+  "url": "https://myapp.uplink.spot",
+  "createdAt": "2025-01-03T00:00:00.000Z"
+}
+```
+
+## Domains
+- Public tunnels: `https://<token>.x.uplink.spot`
+- Permanent URLs (aliases): `https://<alias>.uplink.spot`
+
+## Server Deployment (for self-hosted)
+
+### Deploy code changes
+```bash
+# On server (via SSH)
+cd /opt/agentcloud
+git pull origin master
+systemctl restart tunnel-relay
+systemctl restart backend-api  # if backend changed
+```
+
+### Services
+| Service | Command | Description |
+|---------|---------|-------------|
+| `tunnel-relay` | `systemctl status tunnel-relay` | WebSocket relay for tunnels |
+| `backend-api` | `systemctl status backend-api` | REST API server |
+
+### Relay health check
+The relay exposes internal endpoints (protected by `RELAY_INTERNAL_SECRET`):
+- `/internal/connected-tokens` - List connected tunnel tokens (with socket health verification)
+- `/internal/traffic-stats` - Traffic statistics by token/alias
+- `/health` - Basic health check
+
+## Optional JS helper
+Use `cli/src/agents/tunnels-client.ts` for the same retry/timeout behavior as the CLI.

package/docs/MENU_STRUCTURE.md

@@ -0,0 +1,292 @@
+# Uplink CLI Menu Structure
+
+> Reference document for the interactive menu hierarchy.  
+> Last updated: January 2025
+
+---
+
+## Overview
+
+The Uplink CLI (`uplink menu`) provides an interactive terminal interface for managing tunnels, databases, and system administration. The menu adapts based on authentication status and user role.
+
+---
+
+## Menu States
+
+| State | Condition | Available Options |
+|-------|-----------|-------------------|
+| Unauthenticated | No `AGENTCLOUD_TOKEN` or invalid token | Get Started, Exit |
+| User | Valid token with `role: user` | Tunnels, Exit |
+| Admin | Valid token with `role: admin` | Tunnels, Usage (all tunnels/dbs), System Status, Manage Tokens, Stop All, Exit |
+
+---
+
+## Complete Menu Hierarchy
+
+### Unauthenticated User
+
+```
+UPLINK
+● offline
+
+Get Started
+  → Opens browser to uplink.spot
+  → Displays instructions to create account and get API token
+
+Exit
+```
+
+---
+
+### Authenticated User (Regular)
+
+```
+UPLINK
+● connected
+├─ Active   2 tunnels
+
+Manage Tunnels
+├── Start Tunnel
+│   └── [Port Selection]
+│       ├── Port 3000                    → Creates tunnel & starts client
+│       ├── Port 8080                    → Creates tunnel & starts client
+│       ├── Enter custom port            → Prompt → Creates tunnel
+│       └── ← Back
+│
+├── Stop Tunnel
+│   └── [Running Tunnels Selection]
+│       ├── Port 3000 (abc123...)        → Stops tunnel client
+│       ├── Port 8080 (def456...)        → Stops tunnel client
+│       ├── Stop all tunnels             → Stops all clients
+│       └── ← Back
+│
+├── View Tunnel Stats
+│   └── [Running Tunnel Selection]
+│       ├── abc123...  Port 3000
+│       └── ← Back
+│       
+│       → Displays:
+│         - Permanent URL (if set)
+│         - Connection status (verified via relay)
+│         - Total stats (requests, bytes in/out)
+│         - Current run stats
+│
+└── Active Tunnels
+    └── Displays table (only shows tunnels connected to relay):
+        Token          Port   Status       Permanent URL
+        ────────────────────────────────────────────────
+        abc123...      3000   connected    myapp.uplink.spot
+        def456...      8080   connected    -
+
+Manage Aliases (Premium)
+├── My Aliases
+│   └── Displays table:
+│       Alias            Port    Status
+│       ────────────────────────────────
+│       myapp            3000    active
+│       api              8080    inactive
+│       
+│       (active = tunnel running on that port)
+│
+├── Create Alias
+│   └── [Port Selection]
+│       ├── Port 3000 (tunnel running)   → Prompt alias name
+│       ├── Enter custom port            → Prompt port → Prompt alias
+│       └── ← Back
+│       
+│       → Creates permanent URL at {alias}.uplink.spot
+│       → Alias is port-based (persists across tunnel restarts)
+│
+├── Reassign Alias
+│   └── [Alias Selection]
+│       ├── myapp → Port 3000
+│       └── ← Back
+│       
+│       → Select new port for alias
+│
+└── Delete Alias
+    └── [Alias Selection]
+        ├── myapp
+        └── ← Back
+        
+        → Removes permanent URL
+
+Exit
+```
+
+> **Note:** 
+> - Database features are admin-only. Regular users do not see database options.
+> - Aliases are port-based: they persist even when tunnels restart. The same alias always points to the same port.
+> - "Active Tunnels" verifies connection status with the relay server (not just local processes).
+
+---
+
+### Admin User (Additional Sections)
+
+```
+Usage (admin-only)
+├── List All Tunnels
+│   └── Shows all tunnels across all users
+│
+└── List All Databases
+    └── Shows all databases across all users
+
+System Status
+├── View Status
+│   └── Displays:
+│       - API health
+│       - Relay status (online/offline)
+│       - Connected tunnels count
+│       - Active databases count
+│
+├── View Connected Tunnels
+│   └── Displays table:
+│       Token          Client IP        Port   Uptime     Connected At
+│       ─────────────────────────────────────────────────────────────
+│       abc123...      192.168.1.5      3000   2h 15m     2024-12-31T10:00:00
+│
+└── View Traffic Stats
+    └── Displays table:
+        Alias                    Requests   In         Out        Sts  Last Seen
+        ─────────────────────────────────────────────────────────────────────────
+        chat                     1,234      45.2 MB    12.8 MB    200  2024-12-31...
+
+Manage Tokens
+├── List Tokens
+│   └── Displays table:
+│       ID           Prefix        Role     Label                   Created
+│       ──────────────────────────────────────────────────────────────────────
+│       tok_abc...   sk-abc...     admin    Production              2024-12-01...
+│
+├── Create Token
+│   ├── Prompt: "Role (admin/user, default user):"
+│   ├── Prompt: "Label (optional):"
+│   ├── Prompt: "Expires in days (optional):"
+│   └── Displays created token (save immediately!)
+│
+└── Revoke Token
+    ├── Prompt: "Token ID to revoke:"
+    └── Confirms revocation
+
+⚠️ Stop All Tunnel Clients
+└── Emergency kill switch for all local tunnel processes
+```
+
+---
+
+## Result Displays
+
+### Tunnel Created Successfully
+
+```
+✓ Tunnel created and client started
+
+→ Public URL    https://abc123.x.uplink.spot
+→ Token         abc123
+→ Local port    3000
+
+Tunnel client running in background.
+Use "Stop Tunnel" to disconnect.
+```
+
+### Alias Created
+
+```
+✓ Alias created
+
+→ Alias     my-app
+→ Port      3000
+→ URL       https://my-app.uplink.spot
+
+Your tunnel will now be accessible at this permanent URL.
+Alias is port-based - it will persist across tunnel restarts.
+```
+
+### Error: Premium Feature Required
+
+```
+❌ Permanent URLs are a premium feature
+
+Contact us on Discord at uplink.spot to upgrade your account.
+```
+
+### Error: URL Limit Reached
+
+```
+❌ URL limit reached
+
+You've reached your URL limit. Contact us to increase it.
+```
+
+### Error: URL Already Taken
+
+```
+❌ Alias "my-app" is already in use. Try a different name.
+```
+
+---
+
+## Navigation Controls
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate menu items |
+| `Enter` | Select item |
+| `←` | Go back to parent menu |
+| `Ctrl+C` | Exit immediately |
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTCLOUD_TOKEN` | API authentication token | (required) |
+| `AGENTCLOUD_API_BASE` | API base URL | `https://api.uplink.spot` |
+| `TUNNEL_CTRL` | Tunnel relay control endpoint | `tunnel.uplink.spot:7071` |
+| `TUNNEL_DOMAIN` | Tunnel URL domain | `x.uplink.spot` |
+
+---
+
+## Design Decisions
+
+### Current Structure Rationale
+
+**Regular users** see a focused menu:
+- All tunnel operations in one place ("Manage Tunnels")
+- "My Tunnels" listing included in the same menu
+- No database options (admin feature only)
+
+**Admin users** get additional sections:
+- "Usage" for cross-user visibility (all tunnels, all databases)
+- "System Status" for monitoring
+- "Manage Tokens" for access control
+- Emergency kill switch
+
+### Future Improvements
+
+Consider consolidating admin sections:
+
+```
+Admin (consolidated)
+├── Usage
+│   ├── All Tunnels
+│   └── All Databases
+├── System Status
+│   ├── View Status
+│   ├── Connected Tunnels
+│   └── Traffic Stats
+├── Manage Tokens
+│   ├── List / Create / Revoke
+└── Stop All Clients
+```
+
+This would reduce top-level clutter for admin users while maintaining all functionality.
+
+---
+
+## Related Documentation
+
+- [AGENTS.md](./AGENTS.md) - Programmatic CLI usage for AI agents
+- [QUICKSTART.md](./guides/QUICKSTART.md) - Getting started guide
+- [TUNNEL_SETUP.md](./guides/TUNNEL_SETUP.md) - Tunnel configuration

package/docs/OPEN_SOURCE_CLI.md

@@ -0,0 +1,71 @@
+# Uplink CLI – Public Release Prep
+
+This doc captures the steps to make the CLI fully public/open while keeping the core backend/relay private.
+
+## Scope
+- **Public repo**: `uplink-cli` (new). Contents: `cli/`, `scripts/tunnel/` (clients only), `docs/`, `README.md`, `LICENSE`, `package.json`, `package-lock.json`.
+- **Private repo**: `uplink-core` (current repo or a new private one). Contents: `backend/`, infra scripts, deploy configs, database migrations, relay/server configs, secrets.
+
+## Rationale
+- Users and agents can install/audit/contribute to the CLI.
+- Business logic, billing, and infra stay closed; avoids self-hosting churn and preserves premium features (permanent URLs, aliases).
+
+## What to Publish in `uplink-cli`
+- `cli/` (all commands).
+- `scripts/tunnel/client-improved.js` and `scripts/tunnel/client.js` (tunnel client only).
+- `docs/` (keep `MENU_STRUCTURE.md`, `AGENTS.md`, any usage guides).
+- `README.md` rewritten for CLI-only usage.
+- `LICENSE` (MIT is fine).
+- `package.json`, `package-lock.json`.
+
+## What **Not** to Publish
+- `backend/`, database migrations, infra/relay configs, deploy scripts.
+- Any tokens/keys/configs.
+- Server-side test scripts that hit prod (`scripts/*` that are API smoke tests). Keep only client-side tunnel test if desired.
+
+## Repo Split Steps
+1) Create new repo `uplink-cli` (public).
+2) Copy in:
+   - `cli/`
+   - `scripts/tunnel/client-improved.js` (and `client.js` if still needed)
+   - `docs/`
+   - `README.md` (rewrite for CLI usage)
+   - `LICENSE`
+   - `package.json`, `package-lock.json`
+3) Prune `package.json`:
+   - Remove backend deps.
+   - Keep only CLI deps (`commander`, `node-fetch`, `tsx`, etc.).
+   - Set `"files"` to include `cli/`, `scripts/tunnel/`, `docs/`, `README.md`, `LICENSE`.
+   - Verify `"bin": { "uplink": "./cli/bin/uplink.js" }`.
+4) Add a minimal `.npmignore` (or rely on `"files"`):
+   - Exclude tests not meant for users.
+5) Update `README.md` (CLI-focused):
+   - Install: `npm install -g uplink-cli`
+   - Auth: set `AGENTCLOUD_TOKEN`
+   - Quick start: `uplink tunnel create --port 3000` and `uplink menu`
+   - Machine/agent mode: `--json`, `--token-stdin`, `--api-base`.
+   - Link to `docs/MENU_STRUCTURE.md` and `docs/AGENTS.md`.
+6) Audit for secrets/tokens (ensure none in docs/logs).
+7) Tag and publish from the new repo:
+   - `npm version patch`
+   - `npm publish`
+   - `git push --tags`
+
+## Current Repo (`uplink-core`, private)
+- Keep `backend/`, infra, deployment scripts, smoke tests that touch prod.
+- Keep `scripts/tunnel-smoke.sh`, `scripts/db-api-smoke.sh`, etc. here only.
+- Optionally keep CLI here for internal dev, but treat `uplink-cli` as the public source of truth (mirror changes back as needed).
+
+## Optional Hardening Before Public
+- Ensure CLI defaults point to production `api.uplink.spot` and `tunnel.uplink.spot:7071`.
+- Verify `--api-base` override works for staging.
+- Confirm `uplink tunnel create --json` surfaces `url` and `alias` correctly.
+- Keep premium gating server-side (alias limits, etc.).
+
+## Release Checklist (CLI)
+- [ ] `npm install && npm test` (CLI scope)
+- [ ] `npm version patch`
+- [ ] `npm publish`
+- [ ] `git push origin main --tags`
+- [ ] Manual sanity: `npm install -g uplink-cli` in a clean shell, run `uplink --version`, `uplink tunnel create --port 3000 --json` (with valid token)
+