speqs 0.1.2 → 0.3.0

package/README.md

@@ -12,6 +12,18 @@ CLI tool to expose your localhost to [Speqs](https://speqs.io) for simulation te
 
 ## Install
 
+### Quick install (recommended)
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/speqs-io/speqs-cli/main/install.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/speqs-io/speqs-cli/main/install.ps1 | iex
+```
+
 ### npm (all platforms)
 
 ```bash

package/dist/auth.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser-based authentication via the Speqs frontend plugin auth flow.
+ * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ */
+export declare function getAppUrl(): string;
+export declare function getSupabaseUrl(): string;
+export declare function getSupabaseAnonKey(): string;
+export declare function decodeJwtExp(token: string): number;
+export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+export declare function login(appUrl?: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;
+export declare function refreshTokens(refreshToken: string, supabaseUrl?: string, anonKey?: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;

package/dist/auth.js

@@ -0,0 +1,102 @@
+/**
+ * Browser-based authentication via the Speqs frontend plugin auth flow.
+ * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ */
+import * as crypto from "node:crypto";
+import { execFile } from "node:child_process";
+const POLL_INTERVAL = 2_000;
+const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes (matches server-side token TTL)
+const DEFAULT_APP_URL = "https://app.speqs.io";
+const DEFAULT_SUPABASE_URL = "https://hngymyxdyamokpbeakps.supabase.co";
+const DEFAULT_SUPABASE_ANON_KEY = "sb_publishable_JlS-HfwNyDqLNbrfbrkUlw_PSdZJdo2";
+export function getAppUrl() {
+    return process.env.SPEQS_APP_URL ?? DEFAULT_APP_URL;
+}
+export function getSupabaseUrl() {
+    return process.env.SPEQS_SUPABASE_URL ?? DEFAULT_SUPABASE_URL;
+}
+export function getSupabaseAnonKey() {
+    return process.env.SPEQS_SUPABASE_ANON_KEY ?? DEFAULT_SUPABASE_ANON_KEY;
+}
+// --- Browser open ---
+function openBrowser(url) {
+    if (process.platform === "win32") {
+        execFile("cmd", ["/c", "start", "", url]);
+    }
+    else if (process.platform === "darwin") {
+        execFile("open", [url]);
+    }
+    else {
+        execFile("xdg-open", [url]);
+    }
+}
+// --- JWT decode ---
+export function decodeJwtExp(token) {
+    try {
+        const payload = token.split(".")[1];
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString());
+        return decoded.exp;
+    }
+    catch {
+        return 0;
+    }
+}
+export function isTokenExpired(token, bufferSeconds = 300) {
+    const exp = decodeJwtExp(token);
+    if (!exp)
+        return true;
+    return Date.now() / 1000 >= exp - bufferSeconds;
+}
+// --- Login via browser polling ---
+export async function login(appUrl) {
+    const url = appUrl ?? getAppUrl();
+    const state = crypto.randomBytes(32).toString("hex");
+    const loginUrl = `${url}/auth/plugin?state=${state}`;
+    console.log("Opening browser to sign in...");
+    console.log(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
+    openBrowser(loginUrl);
+    console.log("Waiting for authentication...");
+    const deadline = Date.now() + LOGIN_TIMEOUT;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+        try {
+            const resp = await fetch(`${url}/api/plugin/auth/poll?state=${state}`, {
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (resp.status === 200) {
+                const data = await resp.json();
+                if (data.status === "complete" && data.access_token && data.refresh_token) {
+                    return { accessToken: data.access_token, refreshToken: data.refresh_token };
+                }
+            }
+            // 202 = pending, keep polling
+        }
+        catch {
+            // Network error, keep polling
+        }
+    }
+    throw new Error("Login timed out. Please try again.");
+}
+// --- Token refresh ---
+export async function refreshTokens(refreshToken, supabaseUrl, anonKey) {
+    const url = supabaseUrl ?? getSupabaseUrl();
+    const key = anonKey ?? getSupabaseAnonKey();
+    const resp = await fetch(`${url}/auth/v1/token?grant_type=refresh_token`, {
+        method: "POST",
+        headers: {
+            apikey: key,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`Token refresh failed (HTTP ${resp.status}): ${body}`);
+    }
+    const data = await resp.json();
+    if (!data.access_token || !data.refresh_token) {
+        throw new Error("Token refresh response missing required fields");
+    }
+    return { accessToken: data.access_token, refreshToken: data.refresh_token };
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Config persistence for ~/.speqs/config.json
+ */
+export interface SpeqsConfig {
+    access_token?: string;
+    refresh_token?: string;
+    token?: string;
+    [key: string]: string | undefined;
+}
+export declare function loadConfig(): SpeqsConfig;
+export declare function saveConfig(config: SpeqsConfig): void;

package/dist/config.js

@@ -0,0 +1,25 @@
+/**
+ * Config persistence for ~/.speqs/config.json
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const CONFIG_DIR = path.join(os.homedir(), ".speqs");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+        }
+    }
+    catch {
+        // Corrupted config — ignore
+    }
+    return {};
+}
+export function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const tmp = CONFIG_FILE + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, CONFIG_FILE);
+}

package/dist/index.js

@@ -1,13 +1,43 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
 import { program, Option } from "commander";
 import { runTunnel } from "./tunnel.js";
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
+import { login, getAppUrl } from "./auth.js";
+import { loadConfig, saveConfig } from "./config.js";
+import { upgrade } from "./upgrade.js";
+import pkg from "../package.json" with { type: "json" };
+const { version } = pkg;
 program
     .name("speqs")
     .description("Speqs CLI tools")
     .version(version);
+program
+    .command("login")
+    .description("Authenticate with Speqs via your browser")
+    .action(async () => {
+    try {
+        const tokens = await login(getAppUrl());
+        const config = loadConfig();
+        config.access_token = tokens.accessToken;
+        config.refresh_token = tokens.refreshToken;
+        saveConfig(config);
+        console.log("\nLogin successful!");
+    }
+    catch (e) {
+        console.error(`Login failed: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+program
+    .command("logout")
+    .description("Remove saved authentication credentials")
+    .action(() => {
+    const config = loadConfig();
+    delete config.access_token;
+    delete config.refresh_token;
+    delete config.token;
+    saveConfig(config);
+    console.log("Logged out.");
+});
 program
     .command("tunnel")
     .description("Expose your localhost to Speqs via a Cloudflare tunnel")
@@ -24,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/tunnel.js

@@ -2,33 +2,20 @@
  * Localhost tunnel CLI — wraps cloudflared and registers with Speqs backend.
  */
 import { spawn, execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import * as readline from "node:readline";
+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 = 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";
-const CONFIG_DIR = path.join(os.homedir(), ".speqs");
-const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-function loadConfig() {
-    try {
-        if (fs.existsSync(CONFIG_FILE)) {
-            return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
-        }
-    }
-    catch {
-        // Corrupted config — ignore
-    }
-    return {};
-}
-function saveConfig(config) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
-}
+const SPEQS_DIR = join(homedir(), ".speqs");
+const CLOUDFLARED_BIN = join(SPEQS_DIR, "bin", process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+// --- Token resolution ---
 async function verifyToken(token, apiUrl) {
     try {
         const resp = await fetch(`${apiUrl}${API_BASE}/tunnel/active`, {
@@ -49,61 +36,147 @@ function resolveApiUrl(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 tokenArg;
+        return { token: tokenArg, refresh: null };
+    // 2. Environment variable
     const envToken = process.env.SPEQS_TOKEN;
     if (envToken)
-        return 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 config.token;
+            return { token: config.token, refresh: null };
         }
         console.error("Saved token is invalid or expired.\n");
     }
-    // Interactive prompt
-    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;
-        }
-        console.error("Invalid token. Try again.\n");
-    }
+    // 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";
+function printBanner() {
+    console.log(`
+${ORANGE}${BOLD}   ███████╗██████╗ ███████╗ ██████╗ ███████╗
+   ██╔════╝██╔══██╗██╔════╝██╔═══██╗██╔════╝
+   ███████╗██████╔╝█████╗  ██║   ██║███████╗
+   ╚════██║██╔═══╝ ██╔══╝  ██║▄▄ ██║╚════██║
+   ███████║██║     ███████╗╚██████╔╝███████║
+   ╚══════╝╚═╝     ╚══════╝ ╚══▀▀═╝ ╚══════╝${RESET}
+
+   Tunnel active
+`);
 }
 // --- Cloudflared ---
-function checkCloudflared() {
+async function resolveCloudflaredBin() {
+    // 1. Prefer system-installed cloudflared
     try {
         execSync(process.platform === "win32" ? "where cloudflared" : "which cloudflared", { stdio: "ignore" });
+        return "cloudflared";
     }
     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/");
+        // 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 startCloudflared(port) {
+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(`Starting tunnel to localhost:${port}...`);
-        const proc = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
+        const proc = spawn(binPath, ["tunnel", "--url", `http://localhost:${port}`], {
             stdio: ["ignore", "pipe", "pipe"],
         });
         let tunnelUrl = null;
@@ -119,7 +192,7 @@ function startCloudflared(port) {
             if (match && !tunnelUrl) {
                 tunnelUrl = match[0];
                 clearTimeout(timeout);
-                console.log(`Tunnel active: ${tunnelUrl}`);
+                printBanner();
                 resolve({ process: proc, tunnelUrl });
             }
         });
@@ -149,7 +222,7 @@ async function registerTunnel(apiUrl, token, tunnelUrl, port) {
         });
         if (!resp.ok)
             throw new Error(`HTTP ${resp.status}`);
-        console.log("Registered with Speqs backend");
+        // Registration successful — banner already shown
     }
     catch (e) {
         console.error(`Warning: Failed to register tunnel: ${e}`);
@@ -171,7 +244,7 @@ async function deregisterTunnel(apiUrl, token) {
         console.error(`Warning: Failed to deregister tunnel: ${e}`);
     }
 }
-function startHeartbeat(apiUrl, token, onFatal) {
+function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal) {
     let consecutiveFailures = 0;
     let stopped = false;
     const interval = setInterval(async () => {
@@ -180,9 +253,30 @@ function startHeartbeat(apiUrl, token, onFatal) {
         try {
             const resp = await fetch(`${apiUrl}${API_BASE}/tunnel/heartbeat`, {
                 method: "POST",
-                headers: { Authorization: `Bearer ${token}` },
+                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;
@@ -205,47 +299,92 @@ function startHeartbeat(apiUrl, token, onFatal) {
         },
     };
 }
+/**
+ * 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 token = await resolveToken(tokenArg, apiUrl);
-    checkCloudflared();
+    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);
+        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, token, tunnelUrl, port);
+    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, token);
+        await deregisterTunnel(apiUrl, currentToken);
         process.exit(0);
     };
-    const heartbeat = startHeartbeat(apiUrl, token, async () => {
-        await deregisterTunnel(apiUrl, token);
-        cfProcess.kill();
-        process.exit(1);
-    });
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     console.log("\nPress Ctrl+C to disconnect.\n");
     cfProcess.on("exit", async () => {
         if (!shuttingDown) {
             heartbeat.stop();
-            await deregisterTunnel(apiUrl, token);
+            proactiveRefresh.stop();
+            await deregisterTunnel(apiUrl, currentToken);
             process.exit(0);
         }
     });

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 GITHUB_REPO = "speqs-io/speqs-cli";
+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(`https://api.github.com/repos/${GITHUB_REPO}/releases/latest`, { headers: { Accept: "application/vnd.github.v3+json" } });
+    if (!res.ok)
+        throw new Error(`Failed to fetch latest version: ${res.statusText}`);
+    const data = (await res.json());
+    return data.tag_name.replace(/^v/, "");
+}
+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 = `https://github.com/${GITHUB_REPO}/releases/download/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.1.2",
+  "version": "0.3.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"
   },