speqs 0.2.0 → 0.4.0

package/README.md

@@ -2,15 +2,19 @@
 
 CLI tool to expose your localhost to [Speqs](https://speqs.io) for simulation testing.
 
-## Prerequisites
+## Install
 
-[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) must be installed:
+### Quick install (recommended)
 
-- **macOS**: `brew install cloudflare/cloudflare/cloudflared`
-- **Debian/Ubuntu**: `sudo apt install cloudflared`
-- **Windows**: `scoop install cloudflared` or [download](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
+**macOS / Linux:**
+```bash
+curl -fsSL https://speqs.io/install.sh | sh
+```
 
-## Install
+**Windows (PowerShell):**
+```powershell
+irm https://speqs.io/install.ps1 | iex
+```
 
 ### npm (all platforms)
 
@@ -28,7 +32,7 @@ brew install speqs
 ## Usage
 
 ```bash
-speqs tunnel <port>
+speqs connect <port>
 ```
 
 ### Options
@@ -45,22 +49,19 @@ The CLI resolves your auth token in this order:
 
 1. `--token` CLI argument
 2. `SPEQS_TOKEN` environment variable
-3. Saved token in `~/.speqs/config.json`
-4. Interactive prompt (token is saved for future use)
-
-Find your token in the Speqs app under **Settings**.
+3. Saved token from `speqs login` (stored in `~/.speqs/config.json`)
 
 ## Examples
 
 ```bash
 # Expose port 3000
-speqs tunnel 3000
+speqs connect 3000
 
 # With explicit token
-speqs tunnel 3000 --token YOUR_TOKEN
+speqs connect 3000 --token YOUR_TOKEN
 
 # Using environment variable
-SPEQS_TOKEN=YOUR_TOKEN speqs tunnel 8080
+SPEQS_TOKEN=YOUR_TOKEN speqs connect 8080
 ```
 
 ## License

package/dist/{tunnel.d.ts → connect.d.ts}

@@ -1,4 +1,4 @@
 /**
- * Localhost tunnel CLI — wraps cloudflared and registers with Speqs backend.
+ * Localhost connect CLI — wraps cloudflared and registers with Speqs backend.
  */
 export declare function runTunnel(port: number, tokenArg?: string, apiUrlArg?: string): Promise<void>;

package/dist/connect.js

@@ -0,0 +1,573 @@
+/**
+ * Localhost connect CLI — wraps cloudflared and registers with Speqs backend.
+ */
+import { spawn, execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, chmodSync, writeFileSync } from "node:fs";
+import { loadConfig, saveConfig } from "./config.js";
+import { refreshTokens, isTokenExpired, decodeJwtExp } from "./auth.js";
+const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+const HEARTBEAT_INTERVAL = 10_000;
+const MAX_HEARTBEAT_FAILURES = 3;
+const CLOUDFLARED_STARTUP_TIMEOUT = 30_000;
+const DEFAULT_API_URL = "https://api.speqs.io";
+const API_BASE = "/api/v1";
+const SPEQS_DIR = join(homedir(), ".speqs");
+const CLOUDFLARED_BIN = join(SPEQS_DIR, "bin", process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+// --- Simulation card rendering ---
+const CARD_WIDTH = 64;
+function statusColor(status) {
+    switch (status) {
+        case "running": return "\x1b[32m";
+        case "pending": return "\x1b[33m";
+        case "completed": return "\x1b[32m";
+        case "failed": return "\x1b[31m";
+        default: return "\x1b[2m";
+    }
+}
+function sentimentColor(sentiment) {
+    switch (sentiment) {
+        case "Excited":
+        case "Satisfied": return GREEN;
+        case "Frustrated":
+        case "Unsure": return RED;
+        default: return DIM; // Neutral
+    }
+}
+function padVisible(str, len) {
+    const visible = str.replace(/\x1b\[[0-9;]*m/g, "").length;
+    return visible >= len ? str : str + " ".repeat(len - visible);
+}
+function truncate(str, maxLen) {
+    return str.length > maxLen ? str.slice(0, maxLen - 1) + "…" : str;
+}
+function row(content, inner) {
+    return `\x1b[2m│\x1b[0m  ${padVisible(content, inner)}\x1b[2m│\x1b[0m`;
+}
+function renderCard(sim) {
+    const inner = CARD_WIDTH - 4;
+    const name = truncate(sim.tester_name ?? sim.instance_name ?? sim.tester_id.slice(0, 8), inner - 2);
+    // Top border with name
+    const nameSegment = `─ ${name} `;
+    const topPad = CARD_WIDTH - 2 - nameSegment.length;
+    const top = `\x1b[2m┌\x1b[0m${ORANGE}${BOLD}${nameSegment}${RESET}\x1b[2m${"─".repeat(Math.max(0, topPad))}┐\x1b[0m`;
+    const li = sim.last_interaction;
+    const lines = [top];
+    // Status badge: ● Status (N steps) — right-aligned
+    const titleStatus = sim.status.charAt(0).toUpperCase() + sim.status.slice(1);
+    const steps = `${sim.interaction_count} step${sim.interaction_count !== 1 ? "s" : ""}`;
+    const badge = `${statusColor(sim.status)}●${RESET} ${titleStatus} ${DIM}(${steps})${RESET}`;
+    const badgePlain = `● ${titleStatus} (${steps})`;
+    if (li) {
+        // Frame name (bold) + status badge right-aligned
+        if (li.current_frame_name) {
+            const frameStr = truncate(li.current_frame_name, inner - badgePlain.length - 2);
+            const gap = inner - frameStr.length - badgePlain.length;
+            lines.push(row(`${BOLD}${frameStr}${RESET}${" ".repeat(Math.max(1, gap))}${badge}`, inner));
+        }
+        else {
+            const pad = inner - badgePlain.length;
+            lines.push(row(`${" ".repeat(Math.max(0, pad))}${badge}`, inner));
+        }
+        // Comment (dim, italic quotes — up to 3 lines)
+        if (li.comment) {
+            const maxChars = inner - 3;
+            const words = li.comment.split(" ");
+            const commentLines = [];
+            let current = "";
+            for (const word of words) {
+                const next = current ? `${current} ${word}` : word;
+                if (next.length > maxChars && current) {
+                    commentLines.push(current);
+                    current = word;
+                }
+                else {
+                    current = next;
+                }
+                if (commentLines.length === 3)
+                    break;
+            }
+            if (current && commentLines.length < 3)
+                commentLines.push(current);
+            if (commentLines.length > 0) {
+                commentLines[0] = `"${commentLines[0]}`;
+                const lastIdx = commentLines.length - 1;
+                commentLines[lastIdx] = `${commentLines[lastIdx]}"`;
+            }
+            for (const cl of commentLines) {
+                lines.push(row(`${DIM}${truncate(cl, inner)}${RESET}`, inner));
+            }
+        }
+        // Action rows — one per action, action_type in cyan
+        for (const action of li.actions) {
+            if (!action.action_type)
+                continue;
+            const label = action.element_label
+                ? ` ${truncate(action.element_label, inner - action.action_type.length - 2)}`
+                : "";
+            lines.push(row(`${CYAN}${action.action_type}${RESET}${label}`, inner));
+        }
+        // Sentiment badge
+        if (li.sentiment) {
+            const sc = sentimentColor(li.sentiment);
+            lines.push(row(`${sc}${li.sentiment}${RESET}`, inner));
+        }
+    }
+    else {
+        // No interaction — just show status badge
+        const pad = inner - badgePlain.length;
+        lines.push(row(`${" ".repeat(Math.max(0, pad))}${badge}`, inner));
+    }
+    // Bottom border
+    lines.push(`\x1b[2m└${"─".repeat(CARD_WIDTH - 2)}┘\x1b[0m`);
+    return lines;
+}
+function renderAllCards(simulations) {
+    if (simulations.length === 0)
+        return [];
+    const lines = [];
+    const ts = new Date().toLocaleTimeString("en-GB", { hour12: false });
+    const study = simulations[0]?.study_name;
+    lines.push(`\x1b[2m${study ? `${study} · ` : ""}Updated ${ts}\x1b[0m`);
+    lines.push("");
+    for (const sim of simulations) {
+        lines.push(...renderCard(sim));
+        lines.push("");
+    }
+    return lines;
+}
+let cardLineCount = 0;
+function clearCards() {
+    if (cardLineCount > 0) {
+        process.stdout.write(`\x1b[${cardLineCount}A`);
+        for (let i = 0; i < cardLineCount; i++) {
+            process.stdout.write("\x1b[2K\n");
+        }
+        process.stdout.write(`\x1b[${cardLineCount}A`);
+    }
+}
+function renderSimulationCards(simulations) {
+    clearCards();
+    const lines = renderAllCards(simulations);
+    cardLineCount = lines.length;
+    if (lines.length > 0) {
+        process.stdout.write(lines.join("\n") + "\n");
+    }
+}
+// --- Local storage for completed simulations ---
+const SIMULATIONS_DIR = join(SPEQS_DIR, "simulations");
+const storedTesterIds = new Set();
+function storeCompletedSimulation(sim) {
+    if (storedTesterIds.has(sim.tester_id))
+        return;
+    storedTesterIds.add(sim.tester_id);
+    mkdirSync(SIMULATIONS_DIR, { recursive: true });
+    const logFile = join(SIMULATIONS_DIR, "history.jsonl");
+    const entry = {
+        tester_id: sim.tester_id,
+        instance_name: sim.instance_name,
+        status: sim.status,
+        study_name: sim.study_name,
+        interaction_count: sim.interaction_count,
+        last_interaction: sim.last_interaction,
+        completed_at: new Date().toISOString(),
+    };
+    writeFileSync(logFile, JSON.stringify(entry) + "\n", { flag: "a" });
+}
+// --- Token resolution ---
+async function verifyToken(token, apiUrl) {
+    try {
+        const resp = await fetch(`${apiUrl}${API_BASE}/connect/active`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        // 404 = valid token, no connection (expected). 401/403 = bad token.
+        return resp.status !== 401 && resp.status !== 403;
+    }
+    catch {
+        // Network error — can't verify, assume ok
+        console.error("Warning: Could not verify token (network error). Proceeding anyway.");
+        return true;
+    }
+}
+function resolveApiUrl(apiUrlArg) {
+    if (apiUrlArg)
+        return apiUrlArg;
+    return process.env.SPEQS_API_URL ?? DEFAULT_API_URL;
+}
+/**
+ * Resolve an access token, refreshing if needed.
+ * Returns both the token and a mutable holder for runtime refresh.
+ */
+async function resolveToken(tokenArg, apiUrl) {
+    // 1. Explicit token argument
+    if (tokenArg)
+        return { token: tokenArg, refresh: null };
+    // 2. Environment variable
+    const envToken = process.env.SPEQS_TOKEN;
+    if (envToken)
+        return { token: envToken, refresh: null };
+    // 3. Saved config with refresh token
+    const config = loadConfig();
+    if (config.access_token && config.refresh_token) {
+        let accessToken = config.access_token;
+        // Refresh if expired or close to expiry
+        if (isTokenExpired(accessToken)) {
+            try {
+                const tokens = await refreshTokens(config.refresh_token);
+                accessToken = tokens.accessToken;
+                config.access_token = tokens.accessToken;
+                config.refresh_token = tokens.refreshToken;
+                saveConfig(config);
+            }
+            catch {
+                console.error('Session expired. Run "speqs login" to re-authenticate.');
+                process.exit(1);
+            }
+        }
+        if (await verifyToken(accessToken, apiUrl)) {
+            // Return with refresh capability for long-running tunnel
+            const doRefresh = async () => {
+                const cfg = loadConfig();
+                if (!cfg.refresh_token)
+                    throw new Error("No refresh token");
+                const tokens = await refreshTokens(cfg.refresh_token);
+                cfg.access_token = tokens.accessToken;
+                cfg.refresh_token = tokens.refreshToken;
+                saveConfig(cfg);
+                return tokens.accessToken;
+            };
+            return { token: accessToken, refresh: doRefresh };
+        }
+        console.error('Saved token is invalid. Run "speqs login" to re-authenticate.');
+        process.exit(1);
+    }
+    // 4. Legacy saved token (no refresh token)
+    if (config.token) {
+        if (await verifyToken(config.token, apiUrl)) {
+            return { token: config.token, refresh: null };
+        }
+        console.error('Saved token is invalid. Run "speqs login" to re-authenticate.');
+        process.exit(1);
+    }
+    // 5. No valid token found — direct user to login
+    console.error('No valid token found. Run "speqs login" to authenticate.');
+    process.exit(1);
+}
+// --- Branding ---
+const RESET = "\x1b[0m";
+const ORANGE = "\x1b[38;2;212;117;78m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+function printBanner() {
+    console.log(`
+${ORANGE}${BOLD}   ███████╗██████╗ ███████╗ ██████╗ ███████╗
+   ██╔════╝██╔══██╗██╔════╝██╔═══██╗██╔════╝
+   ███████╗██████╔╝█████╗  ██║   ██║███████╗
+   ╚════██║██╔═══╝ ██╔══╝  ██║▄▄ ██║╚════██║
+   ███████║██║     ███████╗╚██████╔╝███████║
+   ╚══════╝╚═╝     ╚══════╝ ╚══▀▀═╝ ╚══════╝${RESET}
+
+   Connected
+`);
+}
+// --- Cloudflared ---
+async function resolveCloudflaredBin() {
+    // 1. Prefer system-installed cloudflared
+    try {
+        execSync(process.platform === "win32" ? "where cloudflared" : "which cloudflared", { stdio: "ignore" });
+        return "cloudflared";
+    }
+    catch {
+        // Not on PATH
+    }
+    // 2. Check ~/.speqs/bin/cloudflared
+    if (existsSync(CLOUDFLARED_BIN))
+        return CLOUDFLARED_BIN;
+    // 3. Download from Cloudflare releases
+    console.log("cloudflared not found. Installing...");
+    const url = getCloudflaredDownloadUrl();
+    if (!url) {
+        printManualInstallInstructions();
+        process.exit(1);
+    }
+    try {
+        const binDir = join(SPEQS_DIR, "bin");
+        mkdirSync(binDir, { recursive: true, mode: 0o755 });
+        if (url.endsWith(".tgz")) {
+            execSync(`curl -fsSL "${url}" | tar xz -C "${binDir}" cloudflared`, { stdio: "ignore" });
+        }
+        else {
+            const resp = await fetch(url);
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            writeFileSync(CLOUDFLARED_BIN, Buffer.from(await resp.arrayBuffer()));
+        }
+        chmodSync(CLOUDFLARED_BIN, 0o755);
+        return CLOUDFLARED_BIN;
+    }
+    catch (e) {
+        console.error(`Failed to install cloudflared: ${e instanceof Error ? e.message : e}\n`);
+        printManualInstallInstructions();
+        process.exit(1);
+    }
+}
+function getCloudflaredDownloadUrl() {
+    const base = "https://github.com/cloudflare/cloudflared/releases/latest/download";
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "darwin" && arch === "arm64")
+        return `${base}/cloudflared-darwin-arm64.tgz`;
+    if (platform === "darwin" && arch === "x64")
+        return `${base}/cloudflared-darwin-amd64.tgz`;
+    if (platform === "linux" && arch === "x64")
+        return `${base}/cloudflared-linux-amd64`;
+    if (platform === "linux" && arch === "arm64")
+        return `${base}/cloudflared-linux-arm64`;
+    if (platform === "win32" && arch === "x64")
+        return `${base}/cloudflared-windows-amd64.exe`;
+    return null;
+}
+function printManualInstallInstructions() {
+    console.error("You can install it manually:\n" +
+        "  brew install cloudflare/cloudflare/cloudflared   # macOS\n" +
+        "  sudo apt install cloudflared                     # Debian/Ubuntu\n" +
+        "\n  Or: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/");
+}
+function startCloudflared(port, binPath) {
+    return new Promise((resolve, reject) => {
+        console.log(`Connecting to localhost:${port}...`);
+        const proc = spawn(binPath, ["tunnel", "--url", `http://localhost:${port}`], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let tunnelUrl = null;
+        const timeout = setTimeout(() => {
+            if (!tunnelUrl) {
+                proc.kill();
+                reject(new Error("Failed to get tunnel URL within timeout."));
+            }
+        }, CLOUDFLARED_STARTUP_TIMEOUT);
+        proc.stderr?.on("data", (data) => {
+            const line = data.toString("utf-8");
+            const match = line.match(TUNNEL_URL_PATTERN);
+            if (match && !tunnelUrl) {
+                tunnelUrl = match[0];
+                clearTimeout(timeout);
+                printBanner();
+                resolve({ process: proc, tunnelUrl });
+            }
+        });
+        proc.on("exit", (code) => {
+            clearTimeout(timeout);
+            if (!tunnelUrl) {
+                reject(new Error("cloudflared exited unexpectedly."));
+            }
+        });
+        proc.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+// --- API calls ---
+async function registerTunnel(apiUrl, token, tunnelUrl, port) {
+    try {
+        const resp = await fetch(`${apiUrl}${API_BASE}/connect`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ tunnel_url: tunnelUrl, local_port: port }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}`);
+        // Registration successful — banner already shown
+    }
+    catch (e) {
+        console.error(`Warning: Failed to register connection: ${e}`);
+        console.error("Connection is still active — you can retry manually.");
+    }
+}
+async function deregisterTunnel(apiUrl, token) {
+    try {
+        const resp = await fetch(`${apiUrl}${API_BASE}/connect`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(2_000),
+        });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}`);
+        console.log("Disconnected");
+    }
+    catch (e) {
+        console.error(`Warning: Failed to deregister connection: ${e}`);
+    }
+}
+function processHeartbeatResponse(resp) {
+    resp.json().then((data) => {
+        const sims = data.simulations ?? [];
+        renderSimulationCards(sims);
+        // Store completed simulations locally
+        for (const sim of sims) {
+            if (sim.status === "completed" || sim.status === "failed" || sim.status === "cancelled") {
+                storeCompletedSimulation(sim);
+            }
+        }
+    }).catch(() => {
+        // Non-fatal: response parsing failed, silently continue
+    });
+}
+function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal) {
+    let consecutiveFailures = 0;
+    let stopped = false;
+    const interval = setInterval(async () => {
+        if (stopped)
+            return;
+        try {
+            const resp = await fetch(`${apiUrl}${API_BASE}/connect/heartbeat`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${getToken()}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            // If 401 and we can refresh, try once
+            if (resp.status === 401 && doRefresh) {
+                try {
+                    const newToken = await doRefresh();
+                    onTokenRefreshed(newToken);
+                    console.log("Token refreshed.");
+                    // Retry heartbeat with new token
+                    const retry = await fetch(`${apiUrl}${API_BASE}/connect/heartbeat`, {
+                        method: "POST",
+                        headers: { Authorization: `Bearer ${newToken}` },
+                        signal: AbortSignal.timeout(10_000),
+                    });
+                    if (!retry.ok)
+                        throw new Error(`HTTP ${retry.status}`);
+                    consecutiveFailures = 0;
+                    processHeartbeatResponse(retry);
+                    return;
+                }
+                catch (refreshErr) {
+                    console.error(`Token refresh failed: ${refreshErr}`);
+                }
+            }
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            consecutiveFailures = 0;
+            processHeartbeatResponse(resp);
+        }
+        catch (e) {
+            consecutiveFailures++;
+            console.error(`Heartbeat failed (${consecutiveFailures}/${MAX_HEARTBEAT_FAILURES}): ${e}`);
+            if (consecutiveFailures >= MAX_HEARTBEAT_FAILURES) {
+                console.error("Lost connection to Speqs backend. Shutting down.");
+                stopped = true;
+                clearInterval(interval);
+                onFatal();
+            }
+        }
+    }, HEARTBEAT_INTERVAL);
+    return {
+        stop: () => {
+            stopped = true;
+            clearInterval(interval);
+        },
+    };
+}
+/**
+ * Schedule a proactive token refresh before the JWT expires.
+ * Refreshes 10 minutes before expiry.
+ */
+function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed) {
+    if (!doRefresh)
+        return { stop: () => { } };
+    const exp = decodeJwtExp(token);
+    if (!exp)
+        return { stop: () => { } };
+    const refreshAt = (exp - 600) * 1000; // 10 min before expiry
+    const delay = refreshAt - Date.now();
+    if (delay <= 0)
+        return { stop: () => { } };
+    const timer = setTimeout(async () => {
+        try {
+            const newToken = await doRefresh();
+            onTokenRefreshed(newToken);
+            console.log("Token proactively refreshed.");
+            // Schedule next refresh for the new token
+            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed);
+        }
+        catch (e) {
+            console.error(`Proactive token refresh failed: ${e}`);
+        }
+    }, delay);
+    return { stop: () => clearTimeout(timer) };
+}
+// --- Main ---
+export async function runTunnel(port, tokenArg, apiUrlArg) {
+    const apiUrl = resolveApiUrl(apiUrlArg);
+    if (apiUrl !== DEFAULT_API_URL) {
+        console.log(`Using API: ${apiUrl}`);
+    }
+    const resolved = await resolveToken(tokenArg, apiUrl);
+    let currentToken = resolved.token;
+    const onTokenRefreshed = (newToken) => {
+        currentToken = newToken;
+    };
+    // Serialize refresh calls to prevent concurrent use of single-use refresh tokens
+    let refreshInFlight = null;
+    const serializedRefresh = resolved.refresh
+        ? async () => {
+            if (refreshInFlight)
+                return refreshInFlight;
+            refreshInFlight = resolved.refresh().finally(() => { refreshInFlight = null; });
+            return refreshInFlight;
+        }
+        : null;
+    const cloudflaredPath = await resolveCloudflaredBin();
+    let cfResult;
+    try {
+        cfResult = await startCloudflared(port, cloudflaredPath);
+    }
+    catch (e) {
+        console.error(`Failed to start cloudflared: ${e}`);
+        process.exit(1);
+    }
+    const { process: cfProcess, tunnelUrl } = cfResult;
+    await registerTunnel(apiUrl, currentToken, tunnelUrl, port);
+    let shuttingDown = false;
+    const heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
+        await deregisterTunnel(apiUrl, currentToken);
+        cfProcess.kill();
+        process.exit(1);
+    });
+    const proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed);
+    const shutdown = async () => {
+        if (shuttingDown)
+            process.exit(1);
+        shuttingDown = true;
+        console.log("\nShutting down...");
+        heartbeat.stop();
+        proactiveRefresh.stop();
+        cfProcess.kill();
+        await deregisterTunnel(apiUrl, currentToken);
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    console.log("\nPress Ctrl+C to disconnect.\n");
+    cfProcess.on("exit", async () => {
+        if (!shuttingDown) {
+            heartbeat.stop();
+            proactiveRefresh.stop();
+            await deregisterTunnel(apiUrl, currentToken);
+            process.exit(0);
+        }
+    });
+}

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
 import { program, Option } from "commander";
-import { runTunnel } from "./tunnel.js";
+import { runTunnel } from "./connect.js";
 import { login, getAppUrl } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
+import { upgrade } from "./upgrade.js";
+import pkg from "../package.json" with { type: "json" };
+const { version } = pkg;
 program
     .name("speqs")
     .description("Speqs CLI tools")
@@ -39,9 +39,9 @@ program
     console.log("Logged out.");
 });
 program
-    .command("tunnel")
+    .command("connect")
     .description("Expose your localhost to Speqs via a Cloudflare tunnel")
-    .argument("<port>", "Local port to tunnel (e.g. 3000)")
+    .argument("<port>", "Local port to connect (e.g. 3000)")
     .option("-t, --token <token>", "Auth token (or set SPEQS_TOKEN, or save via interactive prompt)")
     .option("--api-url <url>", "Backend API URL (default: SPEQS_API_URL or https://api.speqs.io)")
     .addOption(new Option("--dev", "Use local dev API (http://localhost:8000)").hideHelp())
@@ -54,4 +54,11 @@ program
     const apiUrl = options.dev ? "http://localhost:8000" : options.apiUrl;
     await runTunnel(portNum, options.token, apiUrl);
 });
+program
+    .command("upgrade")
+    .description("Update speqs to the latest version")
+    .option("--version <version>", "Install a specific version")
+    .action(async (options) => {
+    await upgrade(version, options.version);
+});
 program.parse();

package/dist/upgrade.d.ts

@@ -0,0 +1 @@
+export declare function upgrade(currentVersion: string, targetVersion?: string): Promise<void>;

package/dist/upgrade.js

@@ -0,0 +1,94 @@
+import { createWriteStream, renameSync, unlinkSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+const BASE_URL = "https://speqs.io";
+function getPlatformTarget() {
+    const platform = process.platform;
+    const arch = process.arch;
+    const targets = {
+        darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
+        linux: { arm64: "linux-arm64", x64: "linux-x64" },
+        win32: { x64: "windows-x64" },
+    };
+    const target = targets[platform]?.[arch];
+    if (!target) {
+        throw new Error(`Unsupported platform: ${platform}-${arch}`);
+    }
+    return target;
+}
+async function getLatestVersion() {
+    const res = await fetch(`${BASE_URL}/api/releases/latest`);
+    if (!res.ok)
+        throw new Error(`Failed to fetch latest version: ${res.statusText}`);
+    const data = (await res.json());
+    return data.version;
+}
+export async function upgrade(currentVersion, targetVersion) {
+    if (targetVersion && !/^\d+\.\d+\.\d+/.test(targetVersion)) {
+        throw new Error(`Invalid version format: ${targetVersion}`);
+    }
+    const latest = targetVersion || (await getLatestVersion());
+    if (latest === currentVersion) {
+        console.log(`Already up to date (v${currentVersion}).`);
+        return;
+    }
+    console.log(`Updating speqs v${currentVersion} → v${latest}...`);
+    const target = getPlatformTarget();
+    const ext = process.platform === "win32" ? ".exe" : "";
+    const assetName = `speqs-${target}${ext}`;
+    const url = `${BASE_URL}/api/releases/v${latest}/${assetName}`;
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok) {
+        throw new Error(`Download failed: ${res.statusText} (${url})`);
+    }
+    if (!res.body) {
+        throw new Error(`Download failed: empty response body (${url})`);
+    }
+    const execPath = process.execPath;
+    // Use same directory as the binary to avoid cross-device rename issues
+    const tmpPath = join(dirname(execPath), `.speqs-upgrade-${Date.now()}${ext}`);
+    const fileStream = createWriteStream(tmpPath);
+    try {
+        await pipeline(Readable.fromWeb(res.body), fileStream);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch { }
+        throw err;
+    }
+    if (process.platform === "win32") {
+        const oldPath = execPath + ".old";
+        try {
+            unlinkSync(oldPath);
+        }
+        catch { }
+        renameSync(execPath, oldPath);
+        try {
+            renameSync(tmpPath, execPath);
+            try {
+                unlinkSync(oldPath);
+            }
+            catch { }
+        }
+        catch (err) {
+            // Restore original binary on failure
+            try {
+                renameSync(oldPath, execPath);
+            }
+            catch { }
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch { }
+            throw err;
+        }
+    }
+    else {
+        chmodSync(tmpPath, 0o755);
+        renameSync(tmpPath, execPath);
+    }
+    console.log(`Updated to v${latest}.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speqs",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The command-line interface for Speqs",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:binary": "bun build --compile src/index.ts --outfile speqs",
     "dev": "tsc --watch",
     "prepublishOnly": "npm run build"
   },
@@ -21,7 +22,7 @@
   ],
   "keywords": [
     "speqs",
-    "tunnel",
+    "connect",
     "localhost",
     "testing"
   ],

package/dist/tunnel.js

@@ -1,343 +0,0 @@
-/**
- * Localhost tunnel CLI — wraps cloudflared and registers with Speqs backend.
- */
-import { spawn, execSync } from "node:child_process";
-import * as readline from "node:readline";
-import { loadConfig, saveConfig } from "./config.js";
-import { refreshTokens, isTokenExpired, decodeJwtExp } from "./auth.js";
-const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
-const HEARTBEAT_INTERVAL = 30_000;
-const MAX_HEARTBEAT_FAILURES = 3;
-const CLOUDFLARED_STARTUP_TIMEOUT = 30_000;
-const DEFAULT_API_URL = "https://api.speqs.io";
-const API_BASE = "/api/v1";
-// --- Token resolution ---
-async function verifyToken(token, apiUrl) {
-    try {
-        const resp = await fetch(`${apiUrl}${API_BASE}/tunnel/active`, {
-            headers: { Authorization: `Bearer ${token}` },
-            signal: AbortSignal.timeout(10_000),
-        });
-        // 404 = valid token, no tunnel (expected). 401/403 = bad token.
-        return resp.status !== 401 && resp.status !== 403;
-    }
-    catch {
-        // Network error — can't verify, assume ok
-        console.error("Warning: Could not verify token (network error). Proceeding anyway.");
-        return true;
-    }
-}
-function resolveApiUrl(apiUrlArg) {
-    if (apiUrlArg)
-        return apiUrlArg;
-    return process.env.SPEQS_API_URL ?? DEFAULT_API_URL;
-}
-function prompt(question) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.trim());
-        });
-    });
-}
-/**
- * Resolve an access token, refreshing if needed.
- * Returns both the token and a mutable holder for runtime refresh.
- */
-async function resolveToken(tokenArg, apiUrl) {
-    // 1. Explicit token argument
-    if (tokenArg)
-        return { token: tokenArg, refresh: null };
-    // 2. Environment variable
-    const envToken = process.env.SPEQS_TOKEN;
-    if (envToken)
-        return { token: envToken, refresh: null };
-    // 3. Saved config with refresh token
-    const config = loadConfig();
-    if (config.access_token && config.refresh_token) {
-        let accessToken = config.access_token;
-        // Refresh if expired or close to expiry
-        if (isTokenExpired(accessToken)) {
-            try {
-                console.log("Refreshing access token...");
-                const tokens = await refreshTokens(config.refresh_token);
-                accessToken = tokens.accessToken;
-                config.access_token = tokens.accessToken;
-                config.refresh_token = tokens.refreshToken;
-                saveConfig(config);
-            }
-            catch (e) {
-                console.error(`Token refresh failed: ${e instanceof Error ? e.message : e}`);
-                console.error('Run "speqs login" to re-authenticate.\n');
-            }
-        }
-        if (await verifyToken(accessToken, apiUrl)) {
-            // Return with refresh capability for long-running tunnel
-            const doRefresh = async () => {
-                const cfg = loadConfig();
-                if (!cfg.refresh_token)
-                    throw new Error("No refresh token");
-                const tokens = await refreshTokens(cfg.refresh_token);
-                cfg.access_token = tokens.accessToken;
-                cfg.refresh_token = tokens.refreshToken;
-                saveConfig(cfg);
-                return tokens.accessToken;
-            };
-            return { token: accessToken, refresh: doRefresh };
-        }
-        console.error('Saved token is invalid. Run "speqs login" to re-authenticate.\n');
-    }
-    // 4. Legacy saved token (no refresh token)
-    if (config.token) {
-        if (await verifyToken(config.token, apiUrl)) {
-            return { token: config.token, refresh: null };
-        }
-        console.error("Saved token is invalid or expired.\n");
-    }
-    // 5. Interactive prompt (legacy fallback)
-    console.log('Tip: Run "speqs login" for browser-based authentication with auto-refresh.\n');
-    console.log("You can find your token in the simulation view.\n");
-    while (true) {
-        const token = await prompt("Paste your token: ");
-        if (!token) {
-            console.log("No token provided, exiting.");
-            process.exit(1);
-        }
-        if (await verifyToken(token, apiUrl)) {
-            config.token = token;
-            saveConfig(config);
-            return { token, refresh: null };
-        }
-        console.error("Invalid token. Try again.\n");
-    }
-}
-// --- Cloudflared ---
-function checkCloudflared() {
-    try {
-        execSync(process.platform === "win32" ? "where cloudflared" : "which cloudflared", { stdio: "ignore" });
-    }
-    catch {
-        console.error("Missing dependency. Install it:\n" +
-            "  brew install cloudflare/cloudflare/cloudflared   # macOS\n" +
-            "  sudo apt install cloudflared                     # Debian/Ubuntu\n" +
-            "\n  Or: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/");
-        process.exit(1);
-    }
-}
-function startCloudflared(port) {
-    return new Promise((resolve, reject) => {
-        console.log(`Starting tunnel to localhost:${port}...`);
-        const proc = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        let tunnelUrl = null;
-        const timeout = setTimeout(() => {
-            if (!tunnelUrl) {
-                proc.kill();
-                reject(new Error("Failed to get tunnel URL within timeout."));
-            }
-        }, CLOUDFLARED_STARTUP_TIMEOUT);
-        proc.stderr?.on("data", (data) => {
-            const line = data.toString("utf-8");
-            const match = line.match(TUNNEL_URL_PATTERN);
-            if (match && !tunnelUrl) {
-                tunnelUrl = match[0];
-                clearTimeout(timeout);
-                console.log(`Tunnel active: ${tunnelUrl}`);
-                resolve({ process: proc, tunnelUrl });
-            }
-        });
-        proc.on("exit", (code) => {
-            clearTimeout(timeout);
-            if (!tunnelUrl) {
-                reject(new Error("cloudflared exited unexpectedly."));
-            }
-        });
-        proc.on("error", (err) => {
-            clearTimeout(timeout);
-            reject(err);
-        });
-    });
-}
-// --- API calls ---
-async function registerTunnel(apiUrl, token, tunnelUrl, port) {
-    try {
-        const resp = await fetch(`${apiUrl}${API_BASE}/tunnel`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ tunnel_url: tunnelUrl, local_port: port }),
-            signal: AbortSignal.timeout(10_000),
-        });
-        if (!resp.ok)
-            throw new Error(`HTTP ${resp.status}`);
-        console.log("Registered with Speqs backend");
-    }
-    catch (e) {
-        console.error(`Warning: Failed to register tunnel: ${e}`);
-        console.error("Tunnel is still active — you can retry manually.");
-    }
-}
-async function deregisterTunnel(apiUrl, token) {
-    try {
-        const resp = await fetch(`${apiUrl}${API_BASE}/tunnel`, {
-            method: "DELETE",
-            headers: { Authorization: `Bearer ${token}` },
-            signal: AbortSignal.timeout(2_000),
-        });
-        if (!resp.ok)
-            throw new Error(`HTTP ${resp.status}`);
-        console.log("Tunnel deregistered");
-    }
-    catch (e) {
-        console.error(`Warning: Failed to deregister tunnel: ${e}`);
-    }
-}
-function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal) {
-    let consecutiveFailures = 0;
-    let stopped = false;
-    const interval = setInterval(async () => {
-        if (stopped)
-            return;
-        try {
-            const resp = await fetch(`${apiUrl}${API_BASE}/tunnel/heartbeat`, {
-                method: "POST",
-                headers: { Authorization: `Bearer ${getToken()}` },
-                signal: AbortSignal.timeout(10_000),
-            });
-            // If 401 and we can refresh, try once
-            if (resp.status === 401 && doRefresh) {
-                try {
-                    const newToken = await doRefresh();
-                    onTokenRefreshed(newToken);
-                    console.log("Token refreshed.");
-                    // Retry heartbeat with new token
-                    const retry = await fetch(`${apiUrl}${API_BASE}/tunnel/heartbeat`, {
-                        method: "POST",
-                        headers: { Authorization: `Bearer ${newToken}` },
-                        signal: AbortSignal.timeout(10_000),
-                    });
-                    if (!retry.ok)
-                        throw new Error(`HTTP ${retry.status}`);
-                    consecutiveFailures = 0;
-                    return;
-                }
-                catch (refreshErr) {
-                    console.error(`Token refresh failed: ${refreshErr}`);
-                }
-            }
-            if (!resp.ok)
-                throw new Error(`HTTP ${resp.status}`);
-            consecutiveFailures = 0;
-        }
-        catch (e) {
-            consecutiveFailures++;
-            console.error(`Heartbeat failed (${consecutiveFailures}/${MAX_HEARTBEAT_FAILURES}): ${e}`);
-            if (consecutiveFailures >= MAX_HEARTBEAT_FAILURES) {
-                console.error("Lost connection to Speqs backend. Shutting down.");
-                stopped = true;
-                clearInterval(interval);
-                onFatal();
-            }
-        }
-    }, HEARTBEAT_INTERVAL);
-    return {
-        stop: () => {
-            stopped = true;
-            clearInterval(interval);
-        },
-    };
-}
-/**
- * Schedule a proactive token refresh before the JWT expires.
- * Refreshes 10 minutes before expiry.
- */
-function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed) {
-    if (!doRefresh)
-        return { stop: () => { } };
-    const exp = decodeJwtExp(token);
-    if (!exp)
-        return { stop: () => { } };
-    const refreshAt = (exp - 600) * 1000; // 10 min before expiry
-    const delay = refreshAt - Date.now();
-    if (delay <= 0)
-        return { stop: () => { } };
-    const timer = setTimeout(async () => {
-        try {
-            const newToken = await doRefresh();
-            onTokenRefreshed(newToken);
-            console.log("Token proactively refreshed.");
-            // Schedule next refresh for the new token
-            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed);
-        }
-        catch (e) {
-            console.error(`Proactive token refresh failed: ${e}`);
-        }
-    }, delay);
-    return { stop: () => clearTimeout(timer) };
-}
-// --- Main ---
-export async function runTunnel(port, tokenArg, apiUrlArg) {
-    const apiUrl = resolveApiUrl(apiUrlArg);
-    if (apiUrl !== DEFAULT_API_URL) {
-        console.log(`Using API: ${apiUrl}`);
-    }
-    const resolved = await resolveToken(tokenArg, apiUrl);
-    let currentToken = resolved.token;
-    const onTokenRefreshed = (newToken) => {
-        currentToken = newToken;
-    };
-    // Serialize refresh calls to prevent concurrent use of single-use refresh tokens
-    let refreshInFlight = null;
-    const serializedRefresh = resolved.refresh
-        ? async () => {
-            if (refreshInFlight)
-                return refreshInFlight;
-            refreshInFlight = resolved.refresh().finally(() => { refreshInFlight = null; });
-            return refreshInFlight;
-        }
-        : null;
-    checkCloudflared();
-    let cfResult;
-    try {
-        cfResult = await startCloudflared(port);
-    }
-    catch (e) {
-        console.error(`Failed to start cloudflared: ${e}`);
-        process.exit(1);
-    }
-    const { process: cfProcess, tunnelUrl } = cfResult;
-    await registerTunnel(apiUrl, currentToken, tunnelUrl, port);
-    let shuttingDown = false;
-    const heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
-        await deregisterTunnel(apiUrl, currentToken);
-        cfProcess.kill();
-        process.exit(1);
-    });
-    const proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed);
-    const shutdown = async () => {
-        if (shuttingDown)
-            process.exit(1);
-        shuttingDown = true;
-        console.log("\nShutting down...");
-        heartbeat.stop();
-        proactiveRefresh.stop();
-        cfProcess.kill();
-        await deregisterTunnel(apiUrl, currentToken);
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-    console.log("\nPress Ctrl+C to disconnect.\n");
-    cfProcess.on("exit", async () => {
-        if (!shuttingDown) {
-            heartbeat.stop();
-            proactiveRefresh.stop();
-            await deregisterTunnel(apiUrl, currentToken);
-            process.exit(0);
-        }
-    });
-}