@sharnix/agent 1.0.6 → 1.0.8

package/README.md

@@ -2,47 +2,48 @@
 
 Instantly share your local app with anyone — no config, no port forwarding, no deployment.
 
-## First-time setup (one command)
+## Usage
 
 ```bash
-npx @sharnix/agent setup
+npx @sharnix/agent --port 3000
 ```
 
-This is all a new user needs to run. It will:
+That's it. If this is your first time on this machine, the CLI will handle setup automatically — no separate setup step needed.
+
+## First-time setup (automatic)
 
-1. Open your browser to relay.sharnix.com — sign in if you haven't already
-2. Click **"Authorize & create key"** — one click
-3. The CLI captures your API key automatically
-4. Writes the MCP config to Claude Desktop, Cursor, and Windsurf automatically (whichever are installed)
-5. Prints your key and tells you to restart your editor
+When no key is found, the CLI starts a one-time device flow:
 
-After that, your AI agent has full MCP access and you can start tunneling.
+1. Generates a short-lived auth URL and prints it in the terminal
+2. You (or your AI agent) open the URL in any browser — phone, laptop, doesn't matter
+3. Sign in and click **"Authorize"** — one click
+4. The CLI receives your key automatically via polling — nothing to copy or paste
+5. Key saved to `~/.sharnix/key.json` for all future runs
+6. Tunnel connects immediately
+
+**Every run after that is silent** — the CLI reads the saved key and connects with no prompts.
 
 ## Tunneling your app
 
 ```bash
+# Tunnel port 3000 (key read from ~/.sharnix/key.json or env)
 npx @sharnix/agent --port 3000
-```
 
-The API key is read from `SHARNIX_API_KEY` in your environment, or saved automatically by `setup`.
-
-```bash
-# Tunnel port 3000
+# Pass key explicitly
 SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
 
-# Tunnel and immediately print a share link (no dashboard needed)
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000 --share
-
 # With a label
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 8080 --label "staging"
+npx @sharnix/agent --port 8080 --label "staging"
 ```
 
-Save the key to your shell profile so you don't repeat it:
+## Key resolution order
 
-```bash
-# ~/.bashrc or ~/.zshrc
-export SHARNIX_API_KEY=shx_...
-```
+The CLI checks for a key in this order:
+
+1. `SHARNIX_API_KEY` environment variable
+2. `SHARNIX_KEY` environment variable
+3. `~/.sharnix/key.json` (saved automatically after first setup)
+4. Device flow (auto-started if none of the above exist)
 
 ## What it does
 
@@ -57,35 +58,22 @@ export SHARNIX_API_KEY=shx_...
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `setup` | — | First-time setup: creates API key and writes MCP config automatically |
 | `--port`, `-p` | `3000` | Local port to forward |
 | `--label`, `-l` | — | Human-readable label for this tunnel |
-| `--name` | `local-dev` | Agent name used on first-time setup |
-| `--share` | — | Create a read-only share link on connect and print the URL |
+| `--name` | `local-dev` | Agent name registered on first setup |
 | `--help`, `-h` | — | Show help |
 
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
-| `SHARNIX_API_KEY` | Your API key — set automatically by `setup`, or from Settings |
+| `SHARNIX_API_KEY` | API key — overrides saved key file |
+| `SHARNIX_KEY` | Alias for `SHARNIX_API_KEY` |
 | `SHARNIX_URL` | Override relay URL (default: `https://relay.sharnix.com`) |
 
-## What setup writes automatically
-
-`npx @sharnix/agent setup` detects which editors are installed and writes the MCP config to:
-
-| Editor | Config file |
-|--------|-------------|
-| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
-| Cursor | `~/.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
-
-It merges into the existing config — it will never overwrite other MCP servers you have configured.
+## MCP config for AI editors
 
-The block it writes looks like this:
+To give your AI agent (Claude Desktop, Cursor, Windsurf) MCP access to Sharnix, add this to your editor's config file and restart:
 
 ```json
 {
@@ -101,11 +89,18 @@ The block it writes looks like this:
 }
 ```
 
+| Editor | Config file |
+|--------|-------------|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
 ## Creating share links
 
 Once the agent is running, create share links from:
 
-- **Terminal** — `npx @sharnix/agent --port 3000 --share` prints a URL immediately
 - **AI agent** — ask Claude/Cursor: *"share my app with the client"* via [`@sharnix/mcp-server`](https://www.npmjs.com/package/@sharnix/mcp-server)
 - **Dashboard** — [relay.sharnix.com/app](https://relay.sharnix.com/app)
 
@@ -113,11 +108,12 @@ Share links support permissions (`read-only`, `full`), expiry dates, email restr
 
 ## How it works
 
-1. `setup` creates an API key via browser auth and writes MCP config to your editors
-2. On first tunnel run, agent credentials (`agentId` + `secret`) are auto-provisioned via the API and saved to `~/.sharnix/agent.json`
-3. A stable tunnel ID is generated per working directory and saved to `~/.sharnix/tunnel-<hash>.json`
-4. The agent opens a WebSocket to the relay and registers the tunnel
-5. When a visitor opens a share link, the relay forwards their HTTP request over the WebSocket to your local app and streams the response back
+1. On first run with no key, the CLI starts a device flow: prints a one-time auth URL and polls for completion
+2. You open the URL in any browser, sign in, click Authorize — key is saved to `~/.sharnix/key.json` automatically
+3. Agent credentials (`agentId` + `secret`) are provisioned via the API and saved to `~/.sharnix/agent.json`
+4. A stable tunnel ID is generated per working directory and saved to `~/.sharnix/tunnel-<hash>.json`
+5. The agent opens a WebSocket to the relay and registers the tunnel
+6. When a visitor opens a share link, the relay forwards their HTTP request over the WebSocket to your local app and streams the response back
 
 ## License
 

package/index.js

@@ -10,7 +10,11 @@ const { randomBytes, createHash } = require('crypto');
 
 const RELAY_BASE = (process.env.SHARNIX_URL || 'https://relay.sharnix.com').replace(/\/$/, '');
 const WS_BASE = RELAY_BASE.replace(/^http/, 'ws');
-const API_KEY = process.env.SHARNIX_API_KEY || '';
+let API_KEY = process.env.SHARNIX_API_KEY || process.env.SHARNIX_KEY || '';
+
+// ── Config persistence (declared early so dispatch below can rely on it) ──────
+const CONFIG_DIR = path.join(os.homedir(), '.sharnix');
+if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
 
 // ── CLI args ──────────────────────────────────────────────────────────────────
 const args = process.argv.slice(2);
@@ -30,9 +34,10 @@ if (has('--help') || has('-h')) {
   sharnix — tunnel your local app through Sharnix
 
   Usage:
-    npx @sharnix/agent setup               First-time setup (no API key needed)
-    npx @sharnix/agent --port <port>       Tunnel a local port
-    SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
+    npx @sharnix/agent --port <port>            Tunnel a local port (auto-runs setup if no key)
+    npx @sharnix/agent --port <port> --share    Tunnel and print a share link on connect
+    npx @sharnix/agent setup                    Re-run setup explicitly (writes MCP config too)
+    npx @sharnix/agent setup --print-url        Print auth URL and exit (legacy non-blocking mode)
 
   Options:
     --port, -p <n>    Local port to forward (default: 3000)
@@ -42,21 +47,17 @@ if (has('--help') || has('-h')) {
     --help, -h        Show this message
 
   Environment:
-    SHARNIX_API_KEY   API key from relay.sharnix.com/app/settings
-    SHARNIX_URL       Override relay base URL
+    SHARNIX_API_KEY   API key (also: SHARNIX_KEY). If unset and ~/.sharnix/key.json
+                      doesn't exist, the CLI will start the device flow automatically.
+    SHARNIX_URL       Override relay base URL (default: https://relay.sharnix.com)
 `);
   process.exit(0);
 }
 
-// ── Setup command (device-flow bootstrap, no API key required) ────────────────
+// ── Dispatch ──────────────────────────────────────────────────────────────────
 if (args[0] === 'setup') {
-  runSetup().catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
+  runSetup(has('--print-url')).catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
 } else {
-  if (!API_KEY) {
-    console.error('\n  Error: SHARNIX_API_KEY is not set.');
-    console.error('  Run:  npx @sharnix/agent setup\n');
-    process.exit(1);
-  }
   if (isNaN(port) || port < 1 || port > 65535) {
     console.error(`\n  Error: invalid port "${get('--port') || get('-p')}"\n`);
     process.exit(1);
@@ -65,10 +66,7 @@ if (args[0] === 'setup') {
 }
 
 
-// ── Config persistence ────────────────────────────────────────────────────────
-const CONFIG_DIR = path.join(os.homedir(), '.sharnix');
-if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
-
+// ── Config persistence helpers ────────────────────────────────────────────────
 function loadJson(file) {
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
 }
@@ -262,61 +260,116 @@ process.on('SIGINT', () => {
   process.exit(0);
 });
 
-// ── Tunnel main ───────────────────────────────────────────────────────────────
-function main() {
-  console.log(`\n  Sharnix Agent  →  localhost:${port}\n`);
-  bootstrap()
-    .then((c) => { creds = c; connect(); })
-    .catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
+// ── Key resolution + headless detection ──────────────────────────────────────
+function resolveApiKey() {
+  if (API_KEY) return API_KEY;
+  for (const name of ['key.json', 'sharnix-key.json']) {
+    const data = loadJson(path.join(CONFIG_DIR, name));
+    if (data?.apiKey) return data.apiKey;
+  }
+  return null;
 }
 
-// ── Setup: device-flow bootstrap ─────────────────────────────────────────────
-async function runSetup() {
-  const { execSync, spawn } = require('child_process');
-
-  console.log('\n  Sharnix Setup\n');
+function isHeadlessEnv() {
+  if (!process.stdout.isTTY) return true;
+  if (process.env.SSH_CLIENT || process.env.SSH_TTY || process.env.SSH_CONNECTION) return true;
+  if (process.env.CI) return true;
+  if (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return true;
+  return false;
+}
 
-  // Start device flow
-  process.stdout.write('  Starting setup…');
+// Device-flow bootstrap — returns the API key without writing MCP config.
+// Shared by both auto-bootstrap (main path) and the explicit `setup` command.
+async function obtainKeyViaDeviceFlow() {
   const r = await fetch(`${RELAY_BASE}/api/v1/setup-cli`, { method: 'POST' });
-  if (!r.ok) throw new Error('Could not reach relay.sharnix.com. Check your internet connection.');
+  if (!r.ok) throw new Error(`Could not reach ${RELAY_BASE}. Check your connection.`);
   const { code, authUrl } = await r.json();
-  process.stdout.write(' done\n\n');
 
-  console.log('  Opening your browser to authorize…');
-  console.log(`  URL: ${authUrl}\n`);
+  const headless = isHeadlessEnv();
 
-  // Open browser cross-platform
-  try {
-    const cmd = process.platform === 'win32' ? 'start' :
-                process.platform === 'darwin' ? 'open' : 'xdg-open';
-    if (process.platform === 'win32') {
-      spawn('cmd', ['/c', 'start', '', authUrl], { detached: true, stdio: 'ignore' });
-    } else {
-      spawn(cmd, [authUrl], { detached: true, stdio: 'ignore' });
-    }
-  } catch {}
+  console.log('\n  ──────────────────────────────────────────────────────────');
+  console.log('  No Sharnix key found — let\'s set one up. (10-second flow.)');
+  console.log('  ──────────────────────────────────────────────────────────\n');
+  console.log('  Open this URL in any browser to authorize (your phone works fine):\n');
+  console.log(`    ${authUrl}\n`);
+
+  if (!headless) {
+    try {
+      const { spawn } = require('child_process');
+      if (process.platform === 'win32') {
+        spawn('cmd', ['/c', 'start', '', authUrl], { detached: true, stdio: 'ignore' });
+      } else {
+        const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+        spawn(cmd, [authUrl], { detached: true, stdio: 'ignore' });
+      }
+    } catch {}
+  }
 
-  // Poll until authorized
-  process.stdout.write('  Waiting for browser authorization');
-  let apiKey = null;
+  process.stdout.write('  Waiting for authorization');
   const deadline = Date.now() + 10 * 60 * 1000;
   while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, 2000));
+    await new Promise((r) => setTimeout(r, 3000));
     process.stdout.write('.');
     const poll = await fetch(`${RELAY_BASE}/api/v1/setup-cli/${code}`);
     if (!poll.ok) { process.stdout.write('\n'); throw new Error('Setup session expired.'); }
     const data = await poll.json();
-    if (data.done) { apiKey = data.key; break; }
+    if (data.done) { process.stdout.write(' ✓\n'); return data.key; }
   }
   process.stdout.write('\n');
-  if (!apiKey) throw new Error('Setup timed out. Run npx @sharnix/agent setup again.');
+  throw new Error('Setup timed out after 10 minutes.');
+}
 
-  console.log('\n  API key received!\n');
+function saveKeyToDisk(apiKey) {
+  saveJson(path.join(CONFIG_DIR, 'key.json'), { apiKey, createdAt: new Date().toISOString() });
+}
 
-  // Save key to ~/.sharnix/config.json
-  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  saveJson(path.join(CONFIG_DIR, 'sharnix-key.json'), { apiKey, createdAt: new Date().toISOString() });
+// ── Tunnel main ───────────────────────────────────────────────────────────────
+async function main() {
+  console.log(`\n  Sharnix Agent  →  localhost:${port}`);
+
+  // Resolve a key, or trigger device flow inline if none.
+  API_KEY = resolveApiKey();
+  if (!API_KEY) {
+    try {
+      API_KEY = await obtainKeyViaDeviceFlow();
+      saveKeyToDisk(API_KEY);
+      console.log(`  ✓ Key saved to ${path.join(CONFIG_DIR, 'key.json')}\n`);
+    } catch (err) {
+      console.error(`\n  Error: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+
+  try {
+    creds = await bootstrap();
+    connect();
+  } catch (err) {
+    console.error(`\n  Error: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+// ── Setup: explicit `setup` subcommand — bootstrap + MCP config write ────────
+async function runSetup(printUrlOnly = false) {
+  console.log('\n  Sharnix Setup\n');
+
+  if (printUrlOnly) {
+    // Legacy non-blocking mode — start device flow, print URL, exit.
+    process.stdout.write('  Starting setup…');
+    const r = await fetch(`${RELAY_BASE}/api/v1/setup-cli`, { method: 'POST' });
+    if (!r.ok) throw new Error('Could not reach relay.sharnix.com. Check your internet connection.');
+    const { authUrl } = await r.json();
+    process.stdout.write(' done\n\n');
+    console.log('  Authorization URL (open this in your browser):\n');
+    console.log(`  ${authUrl}\n`);
+    console.log('  After authorizing, just run the tunnel — the CLI will read the saved key:');
+    console.log('    npx @sharnix/agent --port 3000\n');
+    process.exit(0);
+  }
+
+  const apiKey = await obtainKeyViaDeviceFlow();
+  console.log('\n  API key received!\n');
+  saveKeyToDisk(apiKey);
 
   // Detect and write MCP configs
   const mcpBlock = {

package/package.json

@@ -1,27 +1,17 @@
 {
   "name": "@sharnix/agent",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Tunnel your local app through Sharnix — share previews with one command",
-  "keywords": [
-    "tunnel",
-    "preview",
-    "sharing",
-    "localhost",
-    "sharnix"
-  ],
+  "keywords": ["tunnel", "preview", "sharing", "localhost", "sharnix"],
   "homepage": "https://relay.sharnix.com",
   "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
+  "engines": { "node": ">=18" },
   "main": "./index.js",
   "bin": {
-    "sharnix-agent": "./index.js",
-    "sharnix": "./index.js"
+    "sharnix-agent": "index.js",
+    "sharnix": "index.js"
   },
-  "files": [
-    "index.js"
-  ],
+  "files": ["index.js"],
   "dependencies": {
     "ws": "^8.18.0"
   }