uplink-cli 0.1.38 → 0.2.0

package/docs/MENU_STRUCTURE.md

@@ -1,337 +1,109 @@
 # Uplink CLI Menu Structure
 
-> Reference document for the interactive menu hierarchy.  
-> Last updated: January 2026
+> Interactive menu hierarchy for `uplink` / `uplink menu`.  
+> Last updated: August 2026
 
----
-
-## 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 |
+Agents should prefer non-interactive commands in [AGENTS.md](../AGENTS.md).
 
 ---
 
-## Complete Menu Hierarchy
+## Overview
 
-### Unauthenticated User
+The menu adapts by auth and role. Arrow keys + Enter (no numeric entry).
 
-```
-UPLINK
-● offline
+| State | Condition | Main options |
+|-------|-----------|--------------|
+| Guest | No / invalid token → guest access is created silently on menu open | Share, Check domain availability, Continue with email, About, Exit |
+| Verified user | Email-verified token | Share, Hosting, Domains, About, Exit |
+| Admin | `role: admin` | Same as user + Usage, System Status, Manage Tokens |
+| Offline | API unreachable | Connection details, About, Exit |
 
-Get Started
-  → Creates a user token via the API (`POST /v1/signup`)
-  → Optionally saves `AGENTCLOUD_TOKEN` into your shell rc file
-
-Exit
-```
+There is no separate "unauthenticated" menu: opening the menu without a usable token mints a guest token (1 active tunnel, 24-hour expiry) and shows the same Share menu everyone gets — including port scanning and tunnel management.
 
 ---
 
-### Authenticated User (Regular)
+## Guest
 
 ```
 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
 
+Share                     → same full Share menu as verified users (no Aliases)
+Check domain availability → Domainking TUI if bundled, else inline `domains check` (public DNS/RDAP)
+Continue with email       → preserve guest tunnel; unlock Hosting + Domains
+About
 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
+## Authenticated — Share
 
-Tunnel client running in background.
-Use "Stop Tunnel" to disconnect.
-```
-
-### Alias Created
-
-```
-✓ Alias created
+Creates tunnels **and** starts the local client (same as `uplink tunnel create`).
 
-→ 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
-
+Share
+├── Start tunnel     → scan ports / enter port → create + start client
+├── Stop tunnel      → kill local client + delete API record
+├── View tunnel stats
+├── Active tunnels   → connected tunnels table
+└── Aliases          → list / create permanent URLs (premium)
 ```
-❌ Permanent URLs are a premium feature
 
-Contact us on Discord at uplink.spot to upgrade your account.
-```
+Admins also get **Stop ALL Tunnel Clients** under Share.
 
-### Error: URL Limit Reached
-
-```
-❌ URL limit reached
-
-You've reached your URL limit. Contact us to increase it.
-```
+---
 
-### Error: URL Already Taken
+## Authenticated — Hosting
 
 ```
-❌ Alias "my-app" is already in use. Try a different name.
+Hosting
+├── Setup wizard     → analyze + create + deploy
+├── Deploy           → deploy to existing app
+├── List apps
+├── Analyze project
+├── Delete app
+└── (Apps subtree may show live apps + logs in the Ink TUI)
 ```
 
----
-
-## 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` |
-| `RELAY_HEALTH_URL` | Optional: show API/relay banner in menu | (unset) |
+CLI equivalents: `uplink host setup|deploy|list|status|logs|delete|analyze|preflight`.
 
 ---
 
-## 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:
+## Authenticated — Domains
 
 ```
-Admin (consolidated)
-├── Usage
-│   ├── All Tunnels
-│   └── All Databases
-├── System Status
-│   ├── View Status
-│   ├── Connected Tunnels
-│   └── Traffic Stats
-├── Manage Tokens
-│   ├── List / Create / Revoke
-└── Stop All Clients
+Domains
+├── My domains              → uplink domains list
+├── Connect registrar       → providers connect (token via env)
+├── Check availability      → domains check
+├── Attach to app           → host domains add
+├── Verify                  → host domains verify
+├── List attached           → host domains list
+├── Detach                  → host domains remove
+└── Search (optional TUI)   → Domainking if DOMAINKING_ENTRY / sibling repo exists
 ```
 
-This would reduce top-level clutter for admin users while maintaining all functionality.
+Bare `uplink domains` opens the search TUI when available; otherwise it prints agent-friendly command hints.
 
 ---
 
-## Implementation Reference (Maintainers)
-
-This section is a **single source of truth** for how the interactive menu is implemented and how it should evolve. It intentionally stays high-level and avoids security-sensitive details.
-
-### Goals
-- **Deterministic**: UI output is a function of state (no hidden UI state).
-- **Maintainable**: Separate **rendering**, **input/events**, and **side-effects** (API calls, spawning clients).
-- **Safe defaults**: Avoid leaking secrets; avoid printing raw tokens except in the explicit signup/token-creation flows.
-
-### Proposed refactor shape (Textual-inspired, Node/TS)
-
-Current `cli/src/subcommands/menu.ts` mixes rendering + input handling + actions in one file. The refactor splits into a tiny internal “menu framework”:
-
-- `cli/src/subcommands/menu/state.ts`
-  - Exports `MenuState`, `MenuRole`, `MenuAuthStatus`
-  - Single state object drives all rendering
-- `cli/src/subcommands/menu/events.ts`
-  - Exports `MenuEvent` (key presses, navigation, action results)
-- `cli/src/subcommands/menu/reducer.ts`
-  - Pure reducer: `(state, event) => { state, effect? }`
-- `cli/src/subcommands/menu/effects.ts`
-  - Side-effects runner (API calls, spawn/kill tunnel clients)
-  - Dispatches `MenuEvent` results back into the reducer
-- `cli/src/subcommands/menu/render.ts`
-  - `render(state): string[]` (or a single string) composing widget renderers
-- `cli/src/subcommands/menu/widgets.ts`
-  - Small, testable “views”: header, breadcrumbs, menu list, message area, footer, active tunnel panel
-- `cli/src/subcommands/menu/menu-tree.ts`
-  - Build `MenuChoice[]` based on auth status + role (unauth/user/admin)
+## Admin extras
 
-Existing primitives continue to be reused:
-- `cli/src/subcommands/menu/colors.ts` (palette)
-- `cli/src/subcommands/menu/io.ts` (prompt/clear/raw-mode helpers)
-- `cli/src/subcommands/menu/inline-select.ts` (arrow-key selector)
-- `cli/src/subcommands/menu/requests.ts` (unauthenticated API requests)
+- **Usage** — cross-user tunnels / databases visibility  
+- **System Status** — API health + stats (+ smoke where configured)  
+- **Manage Tokens** — create / list / revoke  
 
-### Migration order (keep behavior stable)
-1. Remove duplicate palette + selector from `menu.ts` and use `menu/colors.ts`, `menu/io.ts`, `menu/inline-select.ts`.
-2. Extract a pure `render(state)` and keep current behavior.
-3. Introduce `MenuState` and move mutable globals into state.
-4. Introduce `MenuEvent` + reducer loop (keypress → event → state update → render).
-5. Move actions (API/spawn) into `effects.ts` and keep render side-effect free.
+CLI: `uplink admin status|tunnels|databases|tokens …`
 
 ---
 
-## Related Documentation
+## Environment
 
-- [AGENTS.md](./AGENTS.md) - Programmatic CLI usage for AI agents
-- [README.md](./README.md) - Public docs index
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `AGENTCLOUD_TOKEN` | Auth bearer | — |
+| `AGENTCLOUD_API_BASE` | API host | `https://api.uplink.spot` |
+| `TUNNEL_CTRL` | Relay | `tunnel.uplink.spot:7071` |
+| `TUNNEL_DOMAIN` | Tunnel DNS suffix | `x.uplink.spot` |
+| `DOMAINKING_ENTRY` | Optional search TUI entry | — |

package/docs/PRODUCT.md

@@ -0,0 +1,64 @@
+# Uplink
+
+**Software for agents** — share localhost, host apps, and attach domains from the terminal. No dashboard required.
+
+Website: [uplink.spot](https://uplink.spot) · CLI: [`uplink-cli`](https://www.npmjs.com/package/uplink-cli) · Agents: [AGENTS.md](../AGENTS.md)
+
+## What it is
+
+Three surfaces, one CLI (`uplink`):
+
+1. **Share** — expose `localhost:<port>` as HTTPS (`https://<token>.x.uplink.spot`).
+2. **Hosting** — deploy a project to `https://<app_id>.host.uplink.spot` (email-verified accounts).
+3. **Domains** — check availability, list registrar inventory, attach a hostname to a hosted app.
+
+Humans use `uplink` (keyboard menu). Agents use subcommands with `--json` and `--token-stdin`.
+
+## Accounts
+
+| Kind | How you get it | Can do | Cannot do |
+|------|----------------|--------|-----------|
+| **Guest** | Automatic on `tunnel create` or menu open | 1 tunnel (24h), public `domains check` | Hosting, databases, aliases, custom domains |
+| **Verified** | `uplink login --email` then OTP | Guest plus hosting / DBs / registrars | Plan-gated extras (aliases, custom domains) |
+| **Admin** | Operator token in the control plane | Everything + Usage / System Status / Manage Tokens | — |
+
+Guest → verified **merges**: the existing tunnel stays; credentials land in `~/.uplink/credentials` (mode 600). Gate error for locked features: `ACCOUNT_VERIFICATION_REQUIRED`.
+
+## URLs
+
+| Kind | Format |
+|------|--------|
+| Tunnel | `https://<token>.x.uplink.spot` |
+| Alias (plan) | `https://<alias>.uplink.spot` |
+| Hosted app | `https://<app_id>.host.uplink.spot` |
+| Custom domain | hostname attached + verified on an app |
+
+Reserved alias labels include `www`, `api`, `x`, `host`, `docs`, `status`.
+
+## Architecture (high level)
+
+```
+localhost  --tunnel client-->  relay (*.x.uplink.spot)
+                               control plane API (api.uplink.spot)
+hosted app --container------>  runner + router (*.host.uplink.spot)
+Caddy terminates TLS (Cloudflare DNS-01 wildcards).
+```
+
+The CLI repo is public. The control plane, builder, runner, router, and relay live in a private runtime repo.
+
+## Hosting behavior
+
+Free apps **sleep after 30 minutes idle**. A request wakes them (first hit is slower). See [HOSTING.md](./HOSTING.md).
+
+## vs a typical tunnel SaaS
+
+| | Uplink | Typical tunnel dashboard |
+|--|--------|--------------------------|
+| Signup to share localhost | Guest token, no email | Account + browser |
+| Agent install | `npx uplink-cli` + `--json` | Scraping a UI |
+| Hosting | Same CLI | Separate product |
+| Custom domains | Attach to a hosted app | Often a paid add-on |
+
+## License
+
+CLI: MIT. Runtime: private.

package/docs/README.md

@@ -3,19 +3,23 @@
 ## Quick Start
 
 ```bash
-# Install
-npm install -g uplink-cli
-
-# Launch interactive menu
-uplink menu
+# 0.2.0 (guest login, public domain check) — GitHub tag until npm org auth lands
+npm install -g github:firstprinciplecode/uplink#v0.2.0
+uplink menu          # interactive
+uplink --help        # commands
 ```
 
 ## Documentation
 
-- **[AGENTS.md](./AGENTS.md)** - Programmatic CLI usage for AI agents and automation
-- **[MENU_STRUCTURE.md](./MENU_STRUCTURE.md)** - Interactive menu reference
+- **[AGENTS.md](../AGENTS.md)** (also mirrored here) — programmatic CLI for AI agents
+- **[PRODUCT.md](./PRODUCT.md)** — what Uplink is, account types, URLs
+- **[HOSTING.md](./HOSTING.md)** — deploy, quotas, sleep/wake
+- **[MENU_STRUCTURE.md](./MENU_STRUCTURE.md)** — interactive menu reference
+- **[CHANGELOG.md](../CHANGELOG.md)** — releases
 
 ## Links
 
 - Website: [uplink.spot](https://uplink.spot)
+- npm: [uplink-cli](https://www.npmjs.com/package/uplink-cli) (0.1.39 until 0.2.0 publishes)
+- Source: [github.com/firstprinciplecode/uplink](https://github.com/firstprinciplecode/uplink)
 - API: `https://api.uplink.spot`

package/package.json

@@ -1,23 +1,21 @@
 {
   "name": "uplink-cli",
-  "version": "0.1.38",
-  "description": "Expose localhost to the internet in seconds. Interactive terminal UI, permanent custom domains, zero config. A modern ngrok alternative.",
+  "version": "0.2.0",
+  "description": "Software for agents — share localhost, host apps, and attach domains from the terminal. JSON-first CLI for Cursor, Claude, Codex, and Windsurf.",
   "keywords": [
+    "ai-agents",
+    "agents",
+    "cursor",
+    "claude-code",
     "tunnel",
     "localhost",
-    "ngrok",
-    "ngrok-alternative",
-    "expose",
+    "hosting",
     "cli",
     "dev-tools",
-    "webhook",
     "public-url",
-    "port-forwarding",
-    "reverse-proxy",
-    "tunneling",
-    "local-development",
     "https-tunnel",
-    "custom-domain"
+    "custom-domain",
+    "agent-cli"
   ],
   "homepage": "https://uplink.spot",
   "repository": {
@@ -38,45 +36,33 @@
   "files": [
     "cli/",
     "scripts/tunnel/client-improved.js",
+    "scripts/tunnel/client.js",
     "README.md",
-    "assets/",
+    "LICENSE",
+    "AGENTS.md",
     "docs/README.md",
     "docs/AGENTS.md",
-    "docs/MENU_STRUCTURE.md"
+    "docs/MENU_STRUCTURE.md",
+    "docs/HOSTING.md",
+    "docs/PRODUCT.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "dev:relay": "node scripts/tunnel/relay.js",
-    "dev:stub": "PORT=4100 AGENTCLOUD_TOKEN_DEV=dev-token node scripts/dev/stub-control-plane.js",
     "dev:cli": "tsx cli/src/index.ts",
-    "smoke:tunnel": "bash scripts/tunnel-smoke.sh",
-    "smoke:db": "bash scripts/db-api-smoke.sh",
-    "smoke:all": "bash scripts/smoke-all.sh",
-    "test:features": "bash scripts/test-new-features.sh",
-    "test:comprehensive": "bash scripts/test-comprehensive.sh"
+    "pack:check": "npm pack --dry-run"
   },
   "dependencies": {
-    "@sendgrid/mail": "^8.1.6",
-    "better-sqlite3": "^11.10.0",
-    "body-parser": "^1.20.3",
     "commander": "^12.1.0",
-    "compression": "^1.7.4",
-    "dotenv": "^16.6.1",
-    "express": "^4.19.2",
-    "express-rate-limit": "^8.2.1",
-    "helmet": "^8.1.0",
+    "ink": "^6.8.0",
+    "ink-text-input": "^6.0.0",
     "node-fetch": "^2.7.0",
-    "pg": "^8.12.0",
-    "pino": "^10.1.0",
-    "pino-pretty": "^13.1.3",
-    "tsx": "^4.21.0",
-    "zod": "^4.2.1"
+    "react": "^19.2.8",
+    "tsx": "^4.21.0"
   },
   "devDependencies": {
-    "@types/compression": "^1.7.5",
-    "@types/express": "^4.17.21",
-    "@types/express-rate-limit": "^5.1.3",
     "@types/node": "^22.7.4",
     "@types/node-fetch": "^2.6.11",
+    "@types/react": "^19.2.18",
     "typescript": "^5.6.2"
   }
 }