uplink-cli 0.1.38 → 0.1.39

package/cli/src/utils/launchDomainking.ts

@@ -0,0 +1,64 @@
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+function projectRoot(): string {
+  return join(__dirname, "../..");
+}
+
+function resolveTsx(): string {
+  const root = projectRoot();
+  try {
+    return require.resolve("tsx/dist/cli.cjs", { paths: [root] });
+  } catch {
+    try {
+      return require.resolve("tsx/cli", { paths: [root] });
+    } catch {
+      return "tsx";
+    }
+  }
+}
+
+/** Domainking stays its own package; we spawn it, we do not import it. */
+export function resolveDomainkingEntry(): string | null {
+  if (process.env.DOMAINKING_ENTRY && existsSync(process.env.DOMAINKING_ENTRY)) {
+    return process.env.DOMAINKING_ENTRY;
+  }
+  const candidates = [
+    join(homedir(), "domainking", "src", "index.tsx"),
+    join(projectRoot(), "..", "domainking", "src", "index.tsx"),
+    join(projectRoot(), "..", "..", "domainking", "src", "index.tsx"),
+  ];
+  return candidates.find((path) => existsSync(path)) ?? null;
+}
+
+export function launchDomainking(): string {
+  const entry = resolveDomainkingEntry();
+  if (!entry) {
+    return [
+      "Domain search TUI is not bundled with uplink-cli.",
+      "",
+      "Agent-friendly commands (no TUI needed):",
+      "  uplink domains list --json",
+      "  uplink domains check example.com --json",
+      "  uplink host domains add --id app_xxx --hostname example.com --json",
+      "  uplink host domains verify --id app_xxx --hostname example.com --json",
+      "",
+      "Optional: set DOMAINKING_ENTRY to a Domainking src/index.tsx for the search UI.",
+    ].join("\n");
+  }
+
+  const result = spawnSync(resolveTsx(), [entry], {
+    stdio: "inherit",
+    cwd: join(entry, "..", ".."),
+    env: process.env,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status && result.status !== 0) {
+    return "Domain search exited.";
+  }
+  return "Back from domain search. Attach a hostname with Domains › Attach to app.";
+}

package/docs/AGENTS.md

@@ -1,195 +1,161 @@
 # Agent Integration Guide
 
-For agents (Cursor/Claude/GPT/Windsurf) to use Uplink non-interactively.
+For agents (Cursor, Claude Code, Codex, Windsurf, and similar) to use Uplink **non-interactively**.
+
+Install: `npm install -g uplink-cli` or `npx uplink-cli …`  
+Package name: `uplink-cli` · Binary: `uplink`
 
 ## Auth
-- Use `AGENTCLOUD_TOKEN` (bearer). Avoid argv; prefer stdin:
+
+- Use `AGENTCLOUD_TOKEN` (bearer). Prefer stdin over argv:
   ```bash
-  echo "$TOKEN" | uplink --token-stdin ...
+  echo "$TOKEN" | uplink --token-stdin …
   ```
-- API base override: `--api-base https://api.uplink.spot` (or `AGENTCLOUD_API_BASE`).
+- API base: `--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` from the JSON — it is shown only once. Then:
+
+```bash
+export AGENTCLOUD_TOKEN='…'
 ```
-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)
+| Rule | Detail |
+|------|--------|
+| `--json` | stdout = JSON only; logs/errors go to stderr |
+| Exit `0` | success |
+| Exit `2` | usage / bad args |
+| Exit `10` | auth missing/invalid |
+| Exit `20` | network |
+| Exit `30` | server / unknown |
+
+Premium aliases may return `ALIAS_NOT_ENABLED` / `ALIAS_LIMIT_REACHED`.
+
+## Tunnels (share localhost)
+
+`tunnel create` **creates the API record and starts the local client** so the public URL works. Use `--api-only` only if you will start the client yourself.
+
 ```bash
-# Create tunnel (optional alias if enabled)
-echo "$TOKEN" | uplink --token-stdin --api-base https://api.uplink.spot \
+# Create + start client (optional alias if enabled)
+echo "$TOKEN" | uplink --token-stdin \
   tunnel create --port 3000 --alias myapp --json
 
-# List tunnels (includes connection status)
+# List (includes connected status)
 echo "$TOKEN" | uplink --token-stdin tunnel list --json
 
-# Set alias on tunnel
+# Alias on an existing 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
+# Stats / stop
 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
+echo "$TOKEN" | uplink --token-stdin tunnel stop --all --json
+```
+
+JSON create shape (representative):
+
+```json
+{
+  "tunnel": { "id": "tun_…", "url": "https://abc.x.uplink.spot", "token": "…", "status": "…" },
+  "alias": "myapp",
+  "aliasError": null,
+  "url": "https://myapp.uplink.spot",
+  "client": { "pid": 12345, "started": true }
+}
 ```
 
-## Hosting flows (non-interactive)
-Use `--json` for machine-mode output. For interactive prompts, pass `--yes`.
+`connected` on `tunnel list` means the local client is attached to the relay.
+
+## Hosting
+
+Use `--json`. For prompts, pass `--yes`.
 
 ```bash
-# Full setup (analyze + init + create + deploy)
 echo "$TOKEN" | uplink --token-stdin host setup \
-  --path /path/to/app \
-  --name myapp \
-  --env-file /path/to/.env \
-  --wait-timeout 900 \
-  --wait-interval 5 \
-  --yes \
-  --json
-
-# Deploy only (Dockerfile-based app)
+  --path /path/to/app --name myapp --env-file /path/to/.env \
+  --wait-timeout 900 --wait-interval 5 --yes --json
+
 echo "$TOKEN" | uplink --token-stdin host deploy \
-  --path /path/to/app \
-  --name myapp \
-  --env-file /path/to/.env \
-  --wait \
-  --wait-timeout 900 \
-  --wait-interval 5 \
-  --json
-
-# Analyze project
-echo "$TOKEN" | uplink --token-stdin host analyze --path /path/to/app --json
+  --path /path/to/app --name myapp --wait --json
 
-# List hosted apps
+echo "$TOKEN" | uplink --token-stdin host analyze --path /path/to/app --json
+echo "$TOKEN" | uplink --token-stdin host preflight --path /path/to/app --json
 echo "$TOKEN" | uplink --token-stdin host list --json
-
-# Status + logs
 echo "$TOKEN" | uplink --token-stdin host status --id app_xxx --json
 echo "$TOKEN" | uplink --token-stdin host logs --id app_xxx --json
-
-# Delete app
 echo "$TOKEN" | uplink --token-stdin host delete --id app_xxx --yes --json
 ```
 
 Notes:
-- `host logs` returns `NOT_READY` until a deployment is running.
-- If builds stay `queued`, check builder/runner services and build logs on the server.
-- For Prisma apps, ensure the Dockerfile copies `prisma/schema.prisma` before `npm ci` and runs `npx prisma generate` before `npm run build`.
-- Use a `.uplinkignore` file to keep tarballs small. Typical entries include `node_modules`, `.next`, `dist`, `build`, `coverage`, `.turbo`, `.cache`, `.vercel`, `*.log`, and any local SQLite `.db` files.
-- `host list` (non-JSON) prints two lines per app: `- name (app_id)` and the URL on the next line.
-- `host delete` requires typing `DELETE` unless `--yes` is provided.
-- Hosting output modes: Next.js expects `output: "standalone"` for server builds. Vite and CRA are treated as static builds (dist/build).
-
-## Interactive menu notes
-- All selection lists use arrow keys + Enter (no numeric entry required).
-- Hosted app lists display the app URL alongside name and ID.
-
-### 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}'
-```
+- Next.js server hosting expects `output: "standalone"`. Vite/CRA → static `dist`/`build`.
+- Prefer a `.uplinkignore` (`node_modules`, `.next`, `dist`, `*.log`, local `.db`, …).
+- `host logs` may return `NOT_READY` until a deployment is running.
+- `host delete` requires `--yes` (or typing `DELETE` interactively).
 
-Response:
-```json
-{
-  "id": "alias_xxx",
-  "alias": "myapp",
-  "targetPort": 3000,
-  "url": "https://myapp.uplink.spot",
-  "createdAt": "2025-01-03T00:00:00.000Z"
-}
+## Custom domains
+
+Registrar inventory is CLI. Attach/verify is under `host domains`.  
+The bare `uplink domains` search TUI is **optional** and not bundled with npm — use the JSON commands below.
+
+```bash
+uplink domains providers connect godaddy --token-env GODADDY_PAT --json
+uplink domains providers connect cloudflare --token-env CF_API_TOKEN --json
+uplink domains providers connect hostinger --token-env HOSTINGER_API_TOKEN --json
+uplink domains providers connect namecheap --token-env NAMECHEAP_API_KEY --user-env NAMECHEAP_API_USER --json
+uplink domains providers list --json
+uplink domains providers disconnect godaddy --json
+
+uplink domains list --json
+uplink domains check example.com --json
+
+echo "$TOKEN" | uplink --token-stdin host domains add --id app_xxx --hostname example.com --json
+echo "$TOKEN" | uplink --token-stdin host domains verify --id app_xxx --hostname example.com --json
+echo "$TOKEN" | uplink --token-stdin host domains list --id app_xxx --json
+echo "$TOKEN" | uplink --token-stdin host domains remove --id app_xxx --hostname example.com --json
 ```
 
-## Domains
-- Public tunnels: `https://<token>.x.uplink.spot`
-- Permanent URLs (aliases): `https://<alias>.uplink.spot`
+Do not treat RDAP “available” as buyable unless `domains check` says `buyable: true`. Purchase is not wired yet.
 
-## Server Deployment (for self-hosted)
-Control plane + hosting runtime live in the private repo `uplink-hosting-runtime`.
+## Databases (optional)
 
-### Deploy code changes
 ```bash
-# On server (via SSH)
-cd /opt/uplink-hosting-runtime
-git pull origin main
-systemctl restart backend-api
-systemctl restart tunnel-relay
-systemctl restart uplink-builder uplink-runner uplink-router  # if hosting runtime changed
+echo "$TOKEN" | uplink --token-stdin db create --name mydb --project myproj --json
+echo "$TOKEN" | uplink --token-stdin db list --json
+echo "$TOKEN" | uplink --token-stdin db info --id db_xxx --json
+echo "$TOKEN" | uplink --token-stdin db delete --id db_xxx --yes --json
 ```
 
-### Services
-| Service | Command | Description |
-|---------|---------|-------------|
-| `backend-api` | `systemctl status backend-api` | REST API server |
-| `tunnel-relay` | `systemctl status tunnel-relay` | WebSocket relay for tunnels |
-| `uplink-builder` | `systemctl status uplink-builder` | Builds Docker images |
-| `uplink-runner` | `systemctl status uplink-runner` | Runs containers |
-| `uplink-router` | `systemctl status uplink-router` | Routes host domains |
-
-### 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.
+## Failure modes agents should expect
+
+| Symptom | Likely cause |
+|---------|----------------|
+| URL 502 / not connected | Local process on `--port` not running, or client died — re-run `tunnel create` or check `tunnel list` |
+| Auth errors | Missing/invalid `AGENTCLOUD_TOKEN`; use `--token-stdin` |
+| `ALIAS_NOT_ENABLED` | Account does not have permanent aliases |
+| Domain search TUI missing | Expected on npm — use `domains list` / `check` / `host domains *` |
+| Hosting stuck `queued` | Edge builder/runner issue — check `host status` / `host logs` |
+
+## Interactive menu
+
+Humans: `uplink` or `uplink menu` (Share · Hosting · Domains).  
+Agents should prefer the non-interactive commands above.
+
+## URLs
+
+- Ephemeral tunnels: `https://<token>.x.uplink.spot`
+- Aliases: `https://<alias>.uplink.spot`
+
+## More
+
+- Menu map: `docs/MENU_STRUCTURE.md`
+- Website: https://uplink.spot
+- npm: https://www.npmjs.com/package/uplink-cli