speqs 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2025 Speqs. All rights reserved.
+
+This software is the proprietary property of Speqs and is provided under the
+terms of the Speqs Terms of Service (https://speqs.io/terms). Unauthorized
+copying, modification, distribution, or use of this software, in whole or in
+part, is strictly prohibited without prior written consent from Speqs.

package/README.md

@@ -0,0 +1,68 @@
+# speqs
+
+CLI tool to expose your localhost to [Speqs](https://speqs.io) via Cloudflare tunnels for simulation testing.
+
+## Prerequisites
+
+[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) must be installed:
+
+- **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/)
+
+## Install
+
+### npm (all platforms)
+
+```bash
+npm install -g speqs
+```
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap speqs-io/tap
+brew install speqs
+```
+
+## Usage
+
+```bash
+speqs tunnel <port>
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-t, --token <token>` | Auth token (or set `SPEQS_TOKEN` env var, or enter interactively) |
+| `--api-url <url>` | Backend API URL (default: `https://api.speqs.io` or `SPEQS_API_URL` env var) |
+| `--version` | Show version |
+
+### Token Configuration
+
+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**.
+
+## Examples
+
+```bash
+# Expose port 3000
+speqs tunnel 3000
+
+# With explicit token
+speqs tunnel 3000 --token YOUR_TOKEN
+
+# Using environment variable
+SPEQS_TOKEN=YOUR_TOKEN speqs tunnel 8080
+```
+
+## License
+
+Copyright (c) 2025 Speqs. All rights reserved. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/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");
+program
+    .name("speqs")
+    .description("Speqs CLI tools")
+    .version(version);
+program
+    .command("tunnel")
+    .description("Expose your localhost to Speqs via a Cloudflare tunnel")
+    .argument("<port>", "Local port to tunnel (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())
+    .action(async (port, options) => {
+    const portNum = parseInt(port, 10);
+    if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+        console.error(`Invalid port: ${port}`);
+        process.exit(1);
+    }
+    const apiUrl = options.dev ? "http://localhost:8000" : options.apiUrl;
+    await runTunnel(portNum, options.token, apiUrl);
+});
+program.parse();

package/dist/tunnel.d.ts

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

package/dist/tunnel.js

@@ -0,0 +1,252 @@
+/**
+ * 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";
+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 });
+}
+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());
+        });
+    });
+}
+async function resolveToken(tokenArg, apiUrl) {
+    if (tokenArg)
+        return tokenArg;
+    const envToken = process.env.SPEQS_TOKEN;
+    if (envToken)
+        return envToken;
+    const config = loadConfig();
+    if (config.token) {
+        if (await verifyToken(config.token, apiUrl)) {
+            return config.token;
+        }
+        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");
+    }
+}
+// --- 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, token, 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 ${token}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            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);
+        },
+    };
+}
+// --- 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();
+    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, token, tunnelUrl, port);
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            process.exit(1);
+        shuttingDown = true;
+        console.log("\nShutting down...");
+        heartbeat.stop();
+        cfProcess.kill();
+        await deregisterTunnel(apiUrl, token);
+        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);
+            process.exit(0);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "speqs",
+  "version": "0.1.0",
+  "description": "The command-line interface for Speqs",
+  "type": "module",
+  "bin": {
+    "speqs": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "speqs",
+    "tunnel",
+    "localhost",
+    "testing"
+  ],
+  "author": "Speqs",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://speqs.io",
+  "bugs": {
+    "email": "support@speqs.io"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}