stoat.run 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# stoat.run
+
+Share your localhost in one command.
+
+## Install
+
+```bash
+npm i -g stoat.run
+pnpm add -g stoat.run
+yarn global add stoat.run
+bun add -g stoat.run
+```
+
+## Usage
+
+```bash
+stoat http 3000
+stoat status
+```
+
+## Environment
+
+- `STOAT_CONTROL_PLANE_URL` (default: `https://cp.discova.us`)

package/dist/bin.cjs

@@ -0,0 +1,754 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/bin.ts
+var import_commander = require("commander");
+
+// src/tunnel.ts
+var import_ws = __toESM(require("ws"), 1);
+
+// src/protocol.ts
+var MIN_FRAME_SIZE = 8;
+function encodeFrame(type, streamId, payload, flags = 0) {
+  const header = Buffer.alloc(MIN_FRAME_SIZE);
+  header.writeUInt8(type, 0);
+  header.writeUInt8(flags, 1);
+  header.writeUInt16BE(streamId, 2);
+  header.writeUInt32BE(payload.length, 4);
+  return Buffer.concat([header, payload]);
+}
+function decodeFrame(buf) {
+  if (buf.length < MIN_FRAME_SIZE) {
+    throw new Error(`Frame too short: ${buf.length} bytes (minimum ${MIN_FRAME_SIZE})`);
+  }
+  const type = buf.readUInt8(0);
+  const flags = buf.readUInt8(1);
+  const streamId = buf.readUInt16BE(2);
+  const payloadLength = buf.readUInt32BE(4);
+  const payload = buf.subarray(MIN_FRAME_SIZE, MIN_FRAME_SIZE + payloadLength);
+  return { type, flags, streamId, payload };
+}
+function encodeJsonPayload(data) {
+  return Buffer.from(JSON.stringify(data), "utf-8");
+}
+function decodeJsonPayload(payload) {
+  return JSON.parse(payload.toString("utf-8"));
+}
+
+// src/heartbeat.ts
+var PING_INTERVAL_MS = 25e3;
+var MAX_MISSED = 2;
+var HeartbeatManager = class {
+  timer = null;
+  missedPongs = 0;
+  lastPingSentAt = 0;
+  ws = null;
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  start(ws) {
+    this.ws = ws;
+    this.missedPongs = 0;
+    this.timer = setInterval(() => {
+      this.sendPing();
+    }, PING_INTERVAL_MS);
+  }
+  stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.ws = null;
+  }
+  receivedPong(payload) {
+    this.missedPongs = 0;
+    const sentAt = Number(payload.readBigInt64BE(0));
+    const latency = Date.now() - sentAt;
+    this.opts.onLatency?.(latency);
+    void sentAt;
+    void this.lastPingSentAt;
+  }
+  sendPing() {
+    if (!this.ws) return;
+    this.missedPongs += 1;
+    if (this.missedPongs > MAX_MISSED) {
+      this.opts.onDisconnect();
+      return;
+    }
+    const ts = BigInt(Date.now());
+    const payload = Buffer.alloc(8);
+    payload.writeBigInt64BE(ts, 0);
+    this.lastPingSentAt = Date.now();
+    const frame = encodeFrame(6 /* PING */, 0, payload);
+    try {
+      this.ws.send(frame);
+    } catch {
+    }
+  }
+};
+
+// src/local-proxy.ts
+var import_undici = require("undici");
+var import_stream = require("stream");
+var CHUNK_SIZE = 1024 * 1024;
+var LocalProxy = class {
+  port;
+  ws;
+  onRequest;
+  constructor(opts) {
+    this.port = opts.localPort;
+    this.ws = opts.ws;
+    this.onRequest = opts.onRequest;
+  }
+  async handleStream(streamId, meta, requestBody) {
+    const startMs = Date.now();
+    const url = `http://localhost:${this.port}${meta.url}`;
+    try {
+      const headers = {};
+      for (const [k, v] of Object.entries(meta.headers)) {
+        headers[k] = Array.isArray(v) ? v.join(", ") : v;
+      }
+      const { statusCode, headers: resHeaders, body } = await (0, import_undici.request)(url, {
+        method: meta.method,
+        headers,
+        body: requestBody,
+        bodyTimeout: 3e4,
+        headersTimeout: 1e4
+      });
+      const initPayload = {
+        statusCode,
+        headers: resHeaders
+      };
+      this.ws.send(
+        encodeFrame(5 /* RESPONSE_INIT */, streamId, encodeJsonPayload(initPayload))
+      );
+      if (body instanceof import_stream.Readable) {
+        for await (const chunk of body) {
+          const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          for (let offset = 0; offset < buf.length; offset += CHUNK_SIZE) {
+            const slice = buf.subarray(offset, offset + CHUNK_SIZE);
+            this.ws.send(encodeFrame(2 /* STREAM_DATA */, streamId, slice));
+          }
+        }
+      }
+      this.ws.send(encodeFrame(3 /* STREAM_END */, streamId, Buffer.alloc(0)));
+      const elapsedMs = Date.now() - startMs;
+      this.onRequest?.(meta.method, meta.url, statusCode, elapsedMs);
+    } catch (err) {
+      const isConnectionRefused = err instanceof Error && (err.message.includes("ECONNREFUSED") || err.message.includes("connect"));
+      const rstPayload = {
+        code: isConnectionRefused ? 502 : 500,
+        reason: isConnectionRefused ? "Local server not responding" : "Internal proxy error"
+      };
+      try {
+        this.ws.send(
+          encodeFrame(4 /* STREAM_RST */, streamId, encodeJsonPayload(rstPayload))
+        );
+      } catch {
+      }
+      const elapsedMs = Date.now() - startMs;
+      this.onRequest?.(meta.method, meta.url, rstPayload.code, elapsedMs);
+    }
+  }
+};
+
+// src/display.ts
+var import_node_process = __toESM(require("process"), 1);
+function info(message) {
+  import_node_process.default.stdout.write(`  ${message}
+`);
+}
+function ok(message) {
+  import_node_process.default.stdout.write(`  \u2713 ${message}
+`);
+}
+function warn(message) {
+  import_node_process.default.stdout.write(`  ! ${message}
+`);
+}
+function printBanner(publicUrl, localPort, slug, expiresAt) {
+  const expiresDate = new Date(expiresAt);
+  const nowMs = Date.now();
+  const diffMs = expiresDate.getTime() - nowMs;
+  const diffHours = Math.floor(diffMs / (1e3 * 60 * 60));
+  const diffMins = Math.floor(diffMs % (1e3 * 60 * 60) / (1e3 * 60));
+  const expiresStr = diffHours > 0 ? `in ${diffHours} hours` : `in ${diffMins} minutes`;
+  import_node_process.default.stdout.write("\n  \u{1F43E} Stoat.run v0.1.0\n\n");
+  info(`\u279C Public URL: ${publicUrl}`);
+  info(`\u279C Local: http://localhost:${localPort}`);
+  info(`\u279C Slug: ${slug}`);
+  info(`\u279C Expires: ${expiresStr}`);
+  info("\u279C Viewers: 0");
+  import_node_process.default.stdout.write(
+    "\n  Shortcuts: [L]ink  [C]opy  [P]ause  [R]econnect  [Q]uit\n\n"
+  );
+}
+function printRequest(method, path, status, ms) {
+  info(`\u2190 ${method} ${path} ${status} ${ms}ms`);
+}
+function updateViewerCount(count) {
+  info(`\u279C Viewers: ${count}`);
+}
+function printReconnecting() {
+  warn("Reconnecting...");
+}
+function printReconnected() {
+  ok("Reconnected");
+}
+function printError(msg) {
+  import_node_process.default.stderr.write(`  \u2717 ${msg}
+`);
+}
+
+// src/tunnel.ts
+var VERSION = "0.1.0";
+function rawDataToBuffer(data) {
+  if (Buffer.isBuffer(data)) {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return Buffer.concat(data);
+  }
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(data);
+  }
+  throw new TypeError("Unsupported websocket message payload type");
+}
+var TunnelClient = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.heartbeat = new HeartbeatManager({
+      onDisconnect: () => {
+        printReconnecting();
+        void this.reconnect();
+      },
+      onLatency: (ms) => {
+        process.stdout.write(`  Heartbeat latency: ${ms} ms
+`);
+      }
+    });
+  }
+  ws = null;
+  heartbeat;
+  proxy = null;
+  reconnectAttempt = 0;
+  reconnectTimer = null;
+  stopped = false;
+  paused = false;
+  pendingStreams = /* @__PURE__ */ new Map();
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new import_ws.default(this.opts.edgeUrl, {
+        perMessageDeflate: false
+      });
+      this.ws = ws;
+      ws.on("open", () => {
+        const authPayload = {
+          slug: this.opts.slug,
+          token: this.opts.token,
+          version: VERSION
+        };
+        ws.send(encodeFrame(8 /* AUTH */, 0, encodeJsonPayload(authPayload)));
+      });
+      ws.on("message", (data) => {
+        const buf = rawDataToBuffer(data);
+        let frame;
+        try {
+          frame = decodeFrame(buf);
+        } catch {
+          return;
+        }
+        if (frame.type === 9 /* AUTH_OK */) {
+          const info2 = decodeJsonPayload(frame.payload);
+          this.reconnectAttempt = 0;
+          this.proxy = new LocalProxy({
+            localPort: this.opts.localPort,
+            ws,
+            onRequest: (method, path, status, ms) => {
+              printRequest(method, path, status, ms);
+            }
+          });
+          this.heartbeat.start(ws);
+          ws.removeAllListeners("message");
+          ws.on("message", (d) => {
+            void this.handleFrame(rawDataToBuffer(d));
+          });
+          this.opts.onAuthOk?.(info2);
+          resolve(info2);
+        } else if (frame.type === 10 /* AUTH_ERR */) {
+          const err = decodeJsonPayload(frame.payload);
+          ws.close();
+          reject(new Error(`Auth failed: ${err.message}`));
+        }
+      });
+      ws.on("error", (err) => {
+        reject(err);
+      });
+      ws.on("close", () => {
+        this.heartbeat.stop();
+        if (!this.stopped && !this.paused) {
+          printReconnecting();
+          void this.reconnect();
+        }
+        this.opts.onDisconnect?.();
+      });
+    });
+  }
+  async handleFrame(buf) {
+    let frame;
+    try {
+      frame = decodeFrame(buf);
+    } catch {
+      return;
+    }
+    switch (frame.type) {
+      case 1 /* STREAM_OPEN */: {
+        const meta = decodeJsonPayload(frame.payload);
+        this.pendingStreams.set(frame.streamId, { meta, chunks: [] });
+        break;
+      }
+      case 2 /* STREAM_DATA */: {
+        const pending = this.pendingStreams.get(frame.streamId);
+        if (pending) {
+          pending.chunks.push(Buffer.from(frame.payload));
+        }
+        break;
+      }
+      case 3 /* STREAM_END */: {
+        const pending = this.pendingStreams.get(frame.streamId);
+        if (pending) {
+          this.pendingStreams.delete(frame.streamId);
+          const body = pending.chunks.length > 0 ? Buffer.concat(pending.chunks) : void 0;
+          void this.proxy?.handleStream(frame.streamId, pending.meta, body);
+        }
+        break;
+      }
+      case 4 /* STREAM_RST */: {
+        this.pendingStreams.delete(frame.streamId);
+        break;
+      }
+      case 7 /* PONG */: {
+        this.heartbeat.receivedPong(frame.payload);
+        break;
+      }
+      case 6 /* PING */: {
+        this.ws?.send(encodeFrame(7 /* PONG */, 0, frame.payload));
+        break;
+      }
+      case 11 /* VIEWER_COUNT */: {
+        const { count } = decodeJsonPayload(frame.payload);
+        updateViewerCount(count);
+        this.opts.onViewerCount?.(count);
+        break;
+      }
+      case 12 /* GO_AWAY */: {
+        const payload = decodeJsonPayload(frame.payload);
+        this.opts.onGoAway?.(payload);
+        if (payload.reason === "session_expired") {
+          printError("Session expired. Tunnel closed.");
+          this.stop();
+          process.exit(0);
+        }
+        break;
+      }
+    }
+  }
+  async reconnect() {
+    if (this.stopped || this.paused) return;
+    this.heartbeat.stop();
+    this.ws?.terminate();
+    const backoffMs = Math.min(
+      1e3 * Math.pow(2, this.reconnectAttempt),
+      3e4
+    );
+    this.reconnectAttempt++;
+    await new Promise((res) => {
+      this.reconnectTimer = setTimeout(res, backoffMs);
+    });
+    if (this.stopped || this.paused) return;
+    try {
+      await this.connect();
+      printReconnected();
+    } catch (err) {
+      printError(`Reconnect failed: ${err instanceof Error ? err.message : String(err)}`);
+      void this.reconnect();
+    }
+  }
+  sendGoAway(reason) {
+    if (this.ws?.readyState === import_ws.default.OPEN) {
+      this.ws.send(
+        encodeFrame(12 /* GO_AWAY */, 0, encodeJsonPayload({ reason }))
+      );
+    }
+  }
+  pause() {
+    if (this.stopped || this.paused) return;
+    this.paused = true;
+    this.heartbeat.stop();
+    this.pendingStreams.clear();
+    this.sendGoAway("user_paused");
+    this.ws?.close();
+  }
+  resume() {
+    if (this.stopped || !this.paused) return;
+    this.paused = false;
+    void this.reconnect();
+  }
+  stop() {
+    this.stopped = true;
+    this.heartbeat.stop();
+    this.pendingStreams.clear();
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+    }
+    this.ws?.close();
+  }
+};
+
+// src/session.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var import_os = require("os");
+var STOAT_DIR = (0, import_path.join)((0, import_os.homedir)(), ".stoat");
+var STATE_FILE = (0, import_path.join)(STOAT_DIR, "p.json");
+function saveSession(session) {
+  (0, import_fs.mkdirSync)(STOAT_DIR, { recursive: true });
+  (0, import_fs.writeFileSync)(STATE_FILE, JSON.stringify(session, null, 2));
+}
+function loadSession() {
+  try {
+    return JSON.parse((0, import_fs.readFileSync)(STATE_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function clearSession() {
+  try {
+    (0, import_fs.unlinkSync)(STATE_FILE);
+  } catch {
+  }
+}
+
+// src/interactive.ts
+var import_child_process = require("child_process");
+var InteractiveMode = class {
+  opts;
+  paused = false;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  start() {
+    if (!process.stdin.isTTY) return;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (key) => {
+      const ch = key.toUpperCase();
+      switch (ch) {
+        case "L":
+          process.stdout.write(`  ${this.opts.publicUrl}
+`);
+          break;
+        case "C":
+          this.copyToClipboard(this.opts.publicUrl);
+          break;
+        case "P":
+          this.togglePause();
+          break;
+        case "R":
+          void this.opts.tunnel.reconnect();
+          break;
+        case "Q":
+        case "":
+          this.opts.onQuit();
+          break;
+      }
+    });
+  }
+  stop() {
+    if (!process.stdin.isTTY) return;
+    try {
+      process.stdin.setRawMode(false);
+    } catch {
+    }
+    process.stdin.pause();
+  }
+  copyToClipboard(text) {
+    const platform = process.platform;
+    const run = (cmd, args = []) => {
+      const result = (0, import_child_process.spawnSync)(cmd, args, {
+        input: text,
+        stdio: ["pipe", "ignore", "ignore"]
+      });
+      return result.status === 0;
+    };
+    const commandExists = (cmd) => {
+      const result = (0, import_child_process.spawnSync)("sh", ["-c", `command -v ${cmd}`], {
+        stdio: "ignore"
+      });
+      return result.status === 0;
+    };
+    if (platform === "darwin" && commandExists("pbcopy") && run("pbcopy")) {
+      process.stdout.write("  \u2713 Copied to clipboard\n");
+      return;
+    }
+    if (platform === "linux") {
+      const isWayland = Boolean(process.env["WAYLAND_DISPLAY"]) || process.env["XDG_SESSION_TYPE"] === "wayland";
+      if (isWayland && commandExists("wl-copy") && run("wl-copy")) {
+        process.stdout.write("  \u2713 Copied to clipboard\n");
+        return;
+      }
+      if (commandExists("xclip") && run("xclip", ["-selection", "clipboard"])) {
+        process.stdout.write("  \u2713 Copied to clipboard\n");
+        return;
+      }
+      if (commandExists("xsel") && run("xsel", ["--clipboard", "--input"])) {
+        process.stdout.write("  \u2713 Copied to clipboard\n");
+        return;
+      }
+      if (commandExists("termux-clipboard-set") && run("termux-clipboard-set")) {
+        process.stdout.write("  \u2713 Copied to clipboard\n");
+        return;
+      }
+    }
+    if (platform === "win32" && (commandExists("clip.exe") && run("clip.exe") || commandExists("powershell.exe") && (0, import_child_process.spawnSync)(
+      "powershell.exe",
+      ["-NoProfile", "-Command", "Set-Clipboard -Value ([Console]::In.ReadToEnd())"],
+      { input: text, stdio: ["pipe", "ignore", "ignore"] }
+    ).status === 0)) {
+      process.stdout.write("  \u2713 Copied to clipboard\n");
+      return;
+    }
+    printError(
+      "Could not copy to clipboard (install wl-clipboard, xclip, or xsel on Linux)"
+    );
+  }
+  togglePause() {
+    this.paused = !this.paused;
+    if (this.paused) {
+      this.opts.tunnel.pause();
+      process.stdout.write("  ! Tunnel paused\n");
+    } else {
+      this.opts.tunnel.resume();
+      process.stdout.write("  ! Resuming tunnel...\n");
+    }
+  }
+};
+
+// src/commands/http.ts
+var CONTROL_PLANE_URL = process.env["STOAT_CONTROL_PLANE_URL"] ?? "https://cp.discova.us";
+async function httpCommand(port, options) {
+  const localPort = parseInt(port, 10);
+  if (isNaN(localPort) || localPort < 1 || localPort > 65535) {
+    printError(`Invalid port: ${port}`);
+    process.exit(1);
+  }
+  let basicAuth = null;
+  if (options.auth) {
+    const parts = options.auth.split(":");
+    if (parts.length < 2) {
+      printError("--auth must be in format user:pass");
+      process.exit(1);
+    }
+    basicAuth = { user: parts[0], pass: parts.slice(1).join(":") };
+  }
+  const expiresIn = options.expiry ? parseInt(options.expiry, 10) : 86400;
+  let sessionResp;
+  try {
+    const res = await fetch(`${CONTROL_PLANE_URL}/sessions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        localPort,
+        desiredSlug: options.slug ?? null,
+        basicAuth,
+        expiresIn
+      })
+    });
+    if (!res.ok) {
+      const body = await res.json();
+      printError(`Control plane error: ${body.error ?? res.statusText}`);
+      process.exit(1);
+    }
+    sessionResp = await res.json();
+  } catch (err) {
+    printError(
+      `Cannot reach control plane at ${CONTROL_PLANE_URL}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+  const { slug, token, expiresAt } = sessionResp;
+  const edgeUrl = sessionResp.edgeUrl.trim();
+  const publicUrl = sessionResp.publicUrl.replace(/\s+/g, "");
+  saveSession({
+    slug,
+    token,
+    localPort,
+    publicUrl,
+    edgeUrl,
+    expiresAt,
+    pid: process.pid,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const tunnel = new TunnelClient({
+    edgeUrl,
+    slug,
+    token,
+    localPort,
+    onAuthOk: (info2) => {
+      printBanner(publicUrl, localPort, info2.slug, info2.expiresAt);
+    },
+    onGoAway: (payload) => {
+      if (payload.reason === "session_expired") {
+        clearSession();
+      }
+    }
+  });
+  const interactive = new InteractiveMode({
+    publicUrl,
+    tunnel,
+    onQuit: () => {
+      process.stdout.write("  \u{1F43E} Goodbye\n");
+      tunnel.sendGoAway("user_quit");
+      tunnel.stop();
+      clearSession();
+      interactive.stop();
+      process.exit(0);
+    }
+  });
+  process.on("SIGINT", () => {
+    process.stdout.write("  \u{1F43E} Goodbye\n");
+    tunnel.sendGoAway("user_quit");
+    tunnel.stop();
+    clearSession();
+    interactive.stop();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    tunnel.sendGoAway("server_shutdown");
+    tunnel.stop();
+    clearSession();
+    process.exit(0);
+  });
+  process.stdout.write("  Connecting tunnel...\n");
+  try {
+    await tunnel.connect();
+    process.stdout.write("  \u2713 Tunnel connected\n");
+    interactive.start();
+  } catch (err) {
+    process.stdout.write("  \u2717 Tunnel connection failed\n");
+    printError(
+      `Failed to connect: ${err instanceof Error ? err.message : String(err)}`
+    );
+    clearSession();
+    process.exit(1);
+  }
+}
+
+// src/commands/status.ts
+var CONTROL_PLANE_URL2 = process.env["STOAT_CONTROL_PLANE_URL"] ?? "https://cp.discova.us";
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function statusCommand() {
+  const session = loadSession();
+  if (!session) {
+    process.stdout.write("No active tunnel.\n");
+    return;
+  }
+  const localProcessAlive = isProcessAlive(session.pid);
+  let controlPlaneActive = false;
+  let controlPlaneError = null;
+  let expiresAt = session.expiresAt;
+  try {
+    const url = new URL(
+      `${CONTROL_PLANE_URL2}/sessions/${encodeURIComponent(session.slug)}`
+    );
+    url.searchParams.set("token", session.token);
+    const res = await fetch(url);
+    if (res.ok) {
+      const body = await res.json();
+      controlPlaneActive = body.active;
+      expiresAt = body.expiresAt;
+    } else {
+      controlPlaneError = `${res.status} ${res.statusText}`;
+    }
+  } catch (err) {
+    controlPlaneError = err instanceof Error ? err.message : String(err);
+  }
+  const now = Date.now();
+  const expiryMs = new Date(expiresAt).getTime();
+  const expired = Number.isFinite(expiryMs) ? expiryMs <= now : false;
+  const overallStatus = localProcessAlive && controlPlaneActive && !expired ? "online" : "offline";
+  process.stdout.write("Stoat.run Tunnel Status\n");
+  process.stdout.write("====================\n");
+  process.stdout.write(`Slug:             ${session.slug}
+`);
+  process.stdout.write(`Public URL:       ${session.publicUrl}
+`);
+  process.stdout.write(`Local Port:       ${session.localPort}
+`);
+  process.stdout.write(`CLI PID:          ${session.pid}
+`);
+  process.stdout.write(
+    `CLI Process:      ${localProcessAlive ? "running" : "not running"}
+`
+  );
+  process.stdout.write(
+    `Control Plane:    ${controlPlaneActive ? "active" : "inactive"}
+`
+  );
+  process.stdout.write(`Expires At:       ${expiresAt}
+`);
+  process.stdout.write(`Overall Status:   ${overallStatus}
+`);
+  if (controlPlaneError) {
+    process.stdout.write(`Control Plane Err: ${controlPlaneError}
+`);
+  }
+}
+
+// src/bin.ts
+var program = new import_commander.Command();
+program.name("stoat").description("Share your localhost in one command").version("0.1.0");
+program.command("http").description("Expose a local HTTP server").argument("<port>", "local port to expose").option("--slug <slug>", "request a specific slug").option("--auth <user:pass>", "require basic auth for public access").option("--expiry <seconds>", "session expiry in seconds").action(
+  async (port, options) => {
+    await httpCommand(port, {
+      slug: options.slug,
+      auth: options.auth,
+      expiry: options.expiry
+    });
+  }
+);
+program.command("status").description("Show the current tunnel status").action(async () => {
+  await statusCommand();
+});
+void program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "stoat.run",
+  "version": "0.1.0",
+  "description": "Share your localhost in one command",
+  "license": "MIT",
+  "author": "sic-em",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sic-em/stoat.run.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/sic-em/stoat.run/tree/main/packages/cli",
+  "bugs": {
+    "url": "https://github.com/sic-em/stoat.run/issues"
+  },
+  "keywords": [
+    "tunnel",
+    "localhost",
+    "cli",
+    "proxy",
+    "websocket"
+  ],
+  "bin": {
+    "stoat": "dist/bin.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "node --test dist/protocol.test.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "undici": "^7.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  }
+}