@ratio-app/cli 0.1.1

package/dist/commands/dev/listen.js

@@ -0,0 +1,1187 @@
+// src/commands/dev/listen.ts
+import { Flags as Flags2 } from "@oclif/core";
+import { z as z2 } from "zod";
+
+// src/lib/auth/config.ts
+var DEFAULT_SERVER_URL = "https://gkx.ratio.win";
+function resolveServerUrl(opts) {
+  const env = opts?.env ?? process.env;
+  if (typeof env["RATIO_SERVER_URL"] === "string" && env["RATIO_SERVER_URL"].length > 0) {
+    return env["RATIO_SERVER_URL"];
+  }
+  if (typeof opts?.credentials?.server === "string" && opts.credentials.server.length > 0) {
+    return opts.credentials.server;
+  }
+  return DEFAULT_SERVER_URL;
+}
+
+// src/lib/credentials/clock.ts
+var SystemClock = class {
+  now() {
+    return Date.now();
+  }
+};
+
+// src/lib/credentials/path.ts
+import os from "os";
+import path from "path";
+function snapshotPathEnv() {
+  const snapshot = {};
+  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
+  if (xdgConfigHome !== void 0) {
+    snapshot.XDG_CONFIG_HOME = xdgConfigHome;
+  }
+  const appData = process.env["APPDATA"];
+  if (appData !== void 0) {
+    snapshot.APPDATA = appData;
+  }
+  return snapshot;
+}
+function defaultCredentialsPath(platform, homedir, env) {
+  const resolvedPlatform = platform ?? process.platform;
+  const resolvedHome = homedir ?? os.homedir();
+  const resolvedEnv = env ?? snapshotPathEnv();
+  if (resolvedPlatform === "win32") {
+    const appData = resolvedEnv.APPDATA;
+    const base2 = appData !== void 0 && appData !== "" ? appData : path.win32.join(resolvedHome, "AppData", "Roaming");
+    return path.win32.join(base2, "ratio", "credentials");
+  }
+  const xdgConfigHome = resolvedEnv.XDG_CONFIG_HOME;
+  const base = typeof xdgConfigHome === "string" && xdgConfigHome !== "" ? xdgConfigHome : path.posix.join(resolvedHome, ".config");
+  return path.posix.join(base, "ratio", "credentials");
+}
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var NotLoggedInError = class extends RatioCLIError {
+  constructor(message, hint = "Run 'ratio auth login' to sign in.") {
+    super({ code: "NOT_LOGGED_IN", exitCode: 3, message, hint });
+  }
+};
+var TokenExpiredError = class extends RatioCLIError {
+  constructor(message, hint = "Run 'ratio auth login' to refresh your session.") {
+    super({ code: "TOKEN_EXPIRED", exitCode: 3, message, hint });
+  }
+};
+var RelayConnectError = class extends RatioCLIError {
+  constructor(message, hint = "Verify the tunnel URL and that the auth-server is reachable.") {
+    super({ code: "RELAY_CONNECT", exitCode: 6, message, hint });
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+var RelayResumeGapError = class extends RatioCLIError {
+  constructor(message, hint = "Reconnect from the current cursor; older events are outside the buffer window.") {
+    super({ code: "RELAY_RESUME_GAP", exitCode: 9, message, hint });
+  }
+};
+function isRatioCLIError(err) {
+  return err instanceof RatioCLIError;
+}
+
+// src/lib/credentials/refresher.ts
+var NotImplementedRefresher = class {
+  async refresh(refreshToken) {
+    void refreshToken;
+    throw new NotLoggedInError(
+      "Token refresh is not available yet in this CLI version."
+    );
+  }
+};
+
+// src/lib/credentials/store.ts
+import crypto from "crypto";
+import fs from "fs";
+import { dirname } from "path";
+
+// src/lib/credentials/schema.ts
+import { z } from "zod";
+var identitySchema = z.object({
+  developerId: z.string(),
+  email: z.string(),
+  // Token-derived fields captured at login. Optional (additive) so files
+  // written before these fields existed still validate as version 1.
+  merchantId: z.string().optional(),
+  scopes: z.array(z.string()).optional()
+}).strict();
+var profileSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresAt: z.string().datetime({ offset: true }),
+  identity: identitySchema,
+  obtainedAt: z.string().datetime({ offset: true })
+}).strict();
+var developerSessionSchema = z.object({
+  jwt: z.string(),
+  developerId: z.string(),
+  email: z.string(),
+  expiresAt: z.string().datetime({ offset: true }),
+  obtainedAt: z.string().datetime({ offset: true })
+}).strict();
+var credentialsSchema = z.object({
+  version: z.literal(1),
+  server: z.string(),
+  clientId: z.string(),
+  profiles: z.record(z.string(), profileSchema),
+  // Optional cached developer session. Additive so files written before
+  // this field existed still validate as version 1.
+  developer: developerSessionSchema.optional()
+}).strict();
+function parseCredentials(input) {
+  if (typeof input === "object" && input !== null && "version" in input) {
+    const version = input.version;
+    if (version !== 1) {
+      const label = typeof version === "number" ? String(version) : "unknown";
+      throw new ValidationError(
+        `credentials file version ${label} is unsupported by this CLI \u2014 upgrade the CLI or sign in again`
+      );
+    }
+  }
+  const result = credentialsSchema.safeParse(input);
+  if (!result.success) {
+    throw new ValidationError(
+      "credentials file schema mismatch \u2014 expected v1 shape"
+    );
+  }
+  return result.data;
+}
+
+// src/lib/credentials/store.ts
+var REFRESH_WINDOW_MS = 3e5;
+var ENV_TOKEN_VAR = "RATIO_API_TOKEN";
+var ENV_DEVELOPER_TOKEN_VAR = "RATIO_DEVELOPER_TOKEN";
+function hasErrnoCode(err, code) {
+  return err instanceof Error && err.code === code;
+}
+var FileCredentialStore = class {
+  filePath;
+  clock;
+  refresher;
+  envReader;
+  platform;
+  constructor(opts) {
+    this.filePath = opts?.filePath ?? defaultCredentialsPath();
+    this.clock = opts?.clock ?? new SystemClock();
+    this.refresher = opts?.refresher ?? new NotImplementedRefresher();
+    this.envReader = opts?.envReader ?? (() => process.env);
+    this.platform = opts?.platform ?? process.platform;
+  }
+  async load() {
+    this.reapplyFileModeIfDrifted();
+    let raw;
+    try {
+      raw = fs.readFileSync(this.filePath, "utf8");
+    } catch (err) {
+      if (hasErrnoCode(err, "ENOENT")) {
+        throw new NotLoggedInError("You are not signed in.");
+      }
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new ValidationError(
+        'credentials file is not valid JSON \u2014 run "ratio auth login" to reset'
+      );
+    }
+    return parseCredentials(parsed);
+  }
+  async save(creds) {
+    const dir = dirname(this.filePath);
+    fs.mkdirSync(dir, { recursive: true, mode: 448 });
+    if (this.platform !== "win32") {
+      fs.chmodSync(dir, 448);
+    }
+    const tmpPath = `${this.filePath}.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`;
+    try {
+      fs.writeFileSync(tmpPath, JSON.stringify(creds, null, 2), {
+        mode: 384
+      });
+      fs.renameSync(tmpPath, this.filePath);
+    } catch (err) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+      }
+      throw err;
+    }
+    if (this.platform !== "win32") {
+      fs.chmodSync(this.filePath, 384);
+    }
+  }
+  async clear() {
+    try {
+      fs.unlinkSync(this.filePath);
+    } catch (err) {
+      if (hasErrnoCode(err, "ENOENT")) {
+        return;
+      }
+      throw err;
+    }
+  }
+  async getValidAccessToken(profileName) {
+    const envToken = this.envReader()[ENV_TOKEN_VAR];
+    if (typeof envToken === "string" && envToken.length > 0) {
+      return envToken;
+    }
+    const creds = await this.load();
+    const name = profileName ?? "default";
+    const profile = creds.profiles[name];
+    if (profile === void 0) {
+      throw new NotLoggedInError("You are not signed in.");
+    }
+    const msUntilExpiry = new Date(profile.expiresAt).getTime() - this.clock.now();
+    if (msUntilExpiry < REFRESH_WINDOW_MS) {
+      return this.refreshAndPersist(creds, name, profile);
+    }
+    return profile.accessToken;
+  }
+  async getValidDeveloperToken() {
+    const envToken = this.envReader()[ENV_DEVELOPER_TOKEN_VAR];
+    if (typeof envToken === "string" && envToken.length > 0) {
+      return envToken;
+    }
+    let creds;
+    try {
+      creds = await this.load();
+    } catch (err) {
+      if (err instanceof NotLoggedInError) {
+        throw new NotLoggedInError("Developer signin required.");
+      }
+      throw err;
+    }
+    const session = creds.developer;
+    if (session === void 0) {
+      throw new NotLoggedInError("Developer signin required.");
+    }
+    const msUntilExpiry = new Date(session.expiresAt).getTime() - this.clock.now();
+    if (msUntilExpiry < REFRESH_WINDOW_MS) {
+      throw new NotLoggedInError("Developer signin required.");
+    }
+    return session.jwt;
+  }
+  async saveDeveloperSession(session) {
+    let creds;
+    try {
+      creds = await this.load();
+    } catch (err) {
+      if (err instanceof NotLoggedInError) {
+        creds = { version: 1, server: "", clientId: "", profiles: {} };
+      } else {
+        throw err;
+      }
+    }
+    const updated = {
+      ...creds,
+      developer: session
+    };
+    await this.save(updated);
+  }
+  /**
+   * Exchange the profile's refresh token for a fresh token set, merge it
+   * into the loaded credentials (preserving every other profile), persist
+   * atomically, and return the new access token. A refresher failure is
+   * wrapped in TokenExpiredError; the underlying message is deliberately
+   * discarded so a secret can never leak through the error surface.
+   */
+  async refreshAndPersist(creds, name, profile) {
+    let refreshed;
+    try {
+      refreshed = await this.refresher.refresh(profile.refreshToken);
+    } catch {
+      throw new TokenExpiredError(
+        "Your session has expired and could not be refreshed."
+      );
+    }
+    const updated = {
+      ...creds,
+      profiles: {
+        ...creds.profiles,
+        [name]: {
+          ...profile,
+          accessToken: refreshed.accessToken,
+          refreshToken: refreshed.refreshToken,
+          expiresAt: refreshed.expiresAt
+        }
+      }
+    };
+    await this.save(updated);
+    return refreshed.accessToken;
+  }
+  /**
+   * POSIX-only startup permission check: if the file exists with a mode
+   * other than 0600, re-apply 0600 and emit a warning to stderr. Never
+   * runs on Windows (stat modes there do not map to POSIX bits and chmod
+   * must not be called). Missing file is NOT an error here — load()
+   * reports it as NotLoggedInError.
+   */
+  reapplyFileModeIfDrifted() {
+    if (this.platform === "win32") {
+      return;
+    }
+    let stat;
+    try {
+      stat = fs.statSync(this.filePath);
+    } catch (err) {
+      if (hasErrnoCode(err, "ENOENT")) {
+        return;
+      }
+      throw err;
+    }
+    const mode = stat.mode & 511;
+    if (mode !== 384) {
+      fs.chmodSync(this.filePath, 384);
+      process.stderr.write(
+        `[warn] credentials file permissions were 0o${mode.toString(8)}; corrected to 0600.
+`
+      );
+    }
+  }
+};
+
+// src/lib/ratio-command.ts
+import { Command, Errors } from "@oclif/core";
+
+// src/lib/render-error.ts
+function isOclifParserError(err) {
+  return err instanceof Error && "parse" in err && err.parse !== null && err.parse !== void 0;
+}
+function buildErrorEnvelope(code, message, hint, docsUrl) {
+  const obj = { ok: false, code, message };
+  if (hint !== void 0) obj["hint"] = hint;
+  if (docsUrl !== void 0) obj["docsUrl"] = docsUrl;
+  return JSON.stringify(obj) + "\n";
+}
+function renderError(input) {
+  const { err, verbose, json } = input;
+  if (isRatioCLIError(err)) {
+    const ratioErr = err;
+    if (ratioErr.exitCode === 0) {
+      if (json) {
+        return {
+          stdout: JSON.stringify({ ok: true, data: null }) + "\n",
+          stderr: "",
+          exitCode: 0
+        };
+      }
+      return {
+        stdout: ratioErr.message + "\n",
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    let stderrLines = `${ratioErr.code}: ${ratioErr.message}
+`;
+    if (ratioErr.hint !== void 0) stderrLines += `${ratioErr.hint}
+`;
+    if (ratioErr.docsUrl !== void 0) stderrLines += `${ratioErr.docsUrl}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(ratioErr.code, ratioErr.message, ratioErr.hint, ratioErr.docsUrl),
+        stderr: verbose && ratioErr.stack ? ratioErr.stack + "\n" : "",
+        exitCode: ratioErr.exitCode
+      };
+    }
+    if (verbose && ratioErr.stack) {
+      stderrLines += ratioErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrLines, exitCode: ratioErr.exitCode };
+  }
+  if (isOclifParserError(err)) {
+    const parserErr = err;
+    const msg = parserErr.message || "Unknown parse error";
+    const coercedErr = new ValidationError(msg);
+    let stderrText2 = `${coercedErr.code}: ${msg}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(coercedErr.code, msg),
+        stderr: verbose && parserErr.stack ? parserErr.stack + "\n" : "",
+        exitCode: 8
+      };
+    }
+    if (verbose && parserErr.stack) {
+      stderrText2 += parserErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrText2, exitCode: 8 };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const stack = err instanceof Error ? err.stack : void 0;
+  const stderrPrefix = `INTERNAL: ${message}
+`;
+  if (json) {
+    return {
+      stdout: buildErrorEnvelope("INTERNAL", message),
+      stderr: verbose && stack ? stack + "\n" : "",
+      exitCode: 1
+    };
+  }
+  let stderrText = stderrPrefix;
+  if (verbose && stack) {
+    stderrText += stack + "\n";
+  }
+  return { stdout: "", stderr: stderrText, exitCode: 1 };
+}
+
+// src/lib/ratio-command.ts
+var RatioCommand = class extends Command {
+  _getRenderFlags() {
+    const argv = this.argv;
+    return {
+      verbose: argv.includes("--verbose"),
+      json: argv.includes("--json")
+    };
+  }
+  async catch(err) {
+    const { verbose, json } = this._getRenderFlags();
+    const output = renderError({ err, verbose, json });
+    if (output.stdout) process.stdout.write(output.stdout);
+    if (output.stderr) process.stderr.write(output.stderr);
+    if (output.exitCode === 0) {
+      throw new Errors.ExitError(0);
+    }
+    err.skipOclifErrorHandling = true;
+    err.oclif = { exit: output.exitCode };
+    throw err;
+  }
+};
+
+// src/lib/relay/relay-client.ts
+import WebSocket from "ws";
+var LOCAL_BUFFER_MAX = 1e3;
+var BACKOFF_BASE_MS = 100;
+var BACKOFF_CAP_MS = 3e4;
+var CLOSE_CODE_AUTH_REJECTED = 4401;
+var CLOSE_CODE_NORMAL = 1e3;
+var defaultScheduler = (fn, ms) => {
+  const handle = setTimeout(fn, ms);
+  return { cancel: () => clearTimeout(handle) };
+};
+var RelayClient = class {
+  wsUrl;
+  options;
+  scheduler;
+  random;
+  trace;
+  ws = null;
+  lastSeq = -1;
+  reconnectAttempt = 0;
+  reconnectTimer = null;
+  queue = [];
+  waiters = [];
+  /** First fatal error; once set, every consumer pull rejects with it. */
+  failure = null;
+  /** Clean end of stream (normal close or caller-initiated close()). */
+  ended = false;
+  userClosed = false;
+  started = false;
+  pendingConnect = null;
+  constructor(options) {
+    if (options.wsUrl === "") {
+      throw new ValidationError("Relay stream URL must not be empty.");
+    }
+    if (options.sessionId === "") {
+      throw new ValidationError("Relay session id must not be empty.");
+    }
+    let parsed;
+    try {
+      parsed = new URL(options.wsUrl);
+    } catch {
+      throw new ValidationError(
+        "Relay stream URL is not a valid URL.",
+        "The server returned a malformed stream endpoint \u2014 retry creating the session."
+      );
+    }
+    for (const [name, value] of parsed.searchParams.entries()) {
+      if (name === "sessionId") {
+        if (value !== options.sessionId) {
+          throw new ValidationError(
+            "Relay stream URL carries a session id that does not match the created session.",
+            "The server and client disagree on the session \u2014 retry creating the session."
+          );
+        }
+        continue;
+      }
+      throw new ValidationError(
+        "Relay stream URL must not carry query parameters other than the session id.",
+        "The client builds the connection query string itself."
+      );
+    }
+    this.options = options;
+    this.wsUrl = `${parsed.origin}${parsed.pathname}`;
+    this.scheduler = options.scheduler ?? defaultScheduler;
+    this.random = options.random ?? Math.random;
+    this.trace = options.tracer ?? (() => {
+    });
+  }
+  /**
+   * Opens the first connection. Resolves when the socket is open;
+   * rejects with a typed error on authentication rejection or when the
+   * stream fails before ever becoming established. May only be called
+   * once per client instance.
+   */
+  async connect() {
+    if (this.started) {
+      throw new ValidationError("connect() may only be called once.");
+    }
+    this.started = true;
+    await new Promise((resolve, reject) => {
+      this.pendingConnect = { resolve, reject };
+      void this.openSocket();
+    });
+  }
+  /**
+   * Pull-based event stream. Single-consumer: the iterator shares the
+   * client's internal queue. Ends when close() is called or the server
+   * closes cleanly; rejects with a typed error on fatal conditions.
+   */
+  events() {
+    return {
+      [Symbol.asyncIterator]: () => ({
+        next: () => this.nextEvent(),
+        return: async () => {
+          await this.close();
+          return { done: true, value: void 0 };
+        }
+      })
+    };
+  }
+  /**
+   * Graceful shutdown: cancels any pending reconnect, closes the
+   * socket with a normal-closure code, and completes the iterator.
+   */
+  async close() {
+    this.userClosed = true;
+    if (this.reconnectTimer !== null) {
+      this.reconnectTimer.cancel();
+      this.reconnectTimer = null;
+    }
+    const ws = this.ws;
+    if (ws === null || ws.readyState === WebSocket.CLOSED) {
+      this.endClean();
+      return;
+    }
+    await new Promise((resolve) => {
+      ws.once("close", () => resolve());
+      ws.close(CLOSE_CODE_NORMAL);
+    });
+  }
+  // ── internal state machine ────────────────────────────────────────
+  async openSocket() {
+    let token;
+    try {
+      token = await this.options.credentialStore.getValidAccessToken(
+        this.options.profileName
+      );
+    } catch (err) {
+      this.fail(err instanceof Error ? err : new RelayConnectError(
+        "Could not obtain an access token for the relay connection."
+      ));
+      return;
+    }
+    const query = new URLSearchParams({ sessionId: this.options.sessionId });
+    if (this.lastSeq !== -1) {
+      query.set("resumeCursor", String(this.lastSeq));
+    }
+    const url = `${this.wsUrl}?${query.toString()}`;
+    this.trace(
+      `relay connect: session=${this.options.sessionId} cursor=${this.lastSeq}`
+    );
+    const ws = new WebSocket(url, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    this.ws = ws;
+    ws.on("open", () => {
+      this.reconnectAttempt = 0;
+      this.trace("relay connected");
+      if (this.pendingConnect !== null) {
+        this.pendingConnect.resolve();
+        this.pendingConnect = null;
+      }
+    });
+    ws.on("message", (data) => {
+      this.handleMessage(String(data));
+    });
+    ws.on("error", (err) => {
+      this.trace(`relay socket error: ${err.message}`);
+    });
+    ws.on("close", (code) => {
+      this.handleClose(code);
+    });
+  }
+  handleMessage(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      this.trace("relay frame dropped: not valid JSON");
+      return;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      this.trace("relay frame dropped: not an object");
+      return;
+    }
+    const frame = parsed;
+    if (frame["kind"] === "control") {
+      if (frame["type"] === "resume-gap") {
+        this.trace("relay resume gap reported by server");
+        this.fail(
+          new RelayResumeGapError(
+            "The server could not replay all missed events: the resume cursor is older than the replay window."
+          )
+        );
+        return;
+      }
+      this.trace("relay control frame ignored: unknown type");
+      return;
+    }
+    if (frame["kind"] === "webhook" && typeof frame["seq"] === "number") {
+      const seq = frame["seq"];
+      if (seq <= this.lastSeq) {
+        return;
+      }
+      this.lastSeq = seq;
+      this.deliver({
+        kind: "webhook",
+        seq,
+        timestamp: typeof frame["timestamp"] === "number" ? new Date(frame["timestamp"]).toISOString() : "",
+        payload: frame["event"]
+      });
+      return;
+    }
+    this.trace("relay frame dropped: unrecognized envelope");
+  }
+  deliver(event) {
+    const waiter = this.waiters.shift();
+    if (waiter !== void 0) {
+      waiter.resolve({ done: false, value: event });
+      return;
+    }
+    if (this.queue.length >= LOCAL_BUFFER_MAX) {
+      this.trace("relay local buffer overflow \u2014 closing connection");
+      this.fail(
+        new RelayConnectError(
+          "Local buffer overflow \u2014 consumer stalled",
+          "Slow down the consumer or reduce upstream event rate."
+        )
+      );
+      return;
+    }
+    this.queue.push(event);
+  }
+  handleClose(code) {
+    this.ws = null;
+    if (this.failure !== null) {
+      return;
+    }
+    if (this.userClosed || code === CLOSE_CODE_NORMAL) {
+      this.trace(`relay closed cleanly (code ${code})`);
+      this.endClean();
+      return;
+    }
+    if (code === CLOSE_CODE_AUTH_REJECTED) {
+      this.trace("relay rejected the connection: authentication failed");
+      this.fail(
+        new RelayConnectError(
+          "The relay rejected the connection: authentication failed (close code 4401).",
+          "Run 'ratio auth login' and retry."
+        )
+      );
+      return;
+    }
+    this.scheduleReconnect(code);
+  }
+  scheduleReconnect(closeCode) {
+    this.reconnectAttempt += 1;
+    const base = Math.min(
+      2 ** this.reconnectAttempt * BACKOFF_BASE_MS,
+      BACKOFF_CAP_MS
+    );
+    const delay = base * (0.75 + this.random() * 0.5);
+    this.trace(
+      `relay reconnect attempt ${this.reconnectAttempt} in ${Math.round(delay)}ms (close code ${closeCode})`
+    );
+    this.reconnectTimer = this.scheduler(() => {
+      this.reconnectTimer = null;
+      void this.openSocket();
+    }, delay);
+  }
+  fail(err) {
+    if (this.failure !== null) {
+      return;
+    }
+    this.failure = err;
+    if (this.reconnectTimer !== null) {
+      this.reconnectTimer.cancel();
+      this.reconnectTimer = null;
+    }
+    if (this.pendingConnect !== null) {
+      this.pendingConnect.reject(err);
+      this.pendingConnect = null;
+    }
+    let waiter = this.waiters.shift();
+    while (waiter !== void 0) {
+      waiter.reject(err);
+      waiter = this.waiters.shift();
+    }
+    const ws = this.ws;
+    if (ws !== null && ws.readyState !== WebSocket.CLOSED) {
+      ws.close(CLOSE_CODE_NORMAL);
+    }
+  }
+  endClean() {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    if (this.pendingConnect !== null) {
+      this.pendingConnect.reject(
+        new RelayConnectError(
+          "The relay connection closed before it was established."
+        )
+      );
+      this.pendingConnect = null;
+    }
+    let waiter = this.waiters.shift();
+    while (waiter !== void 0) {
+      waiter.resolve({ done: true, value: void 0 });
+      waiter = this.waiters.shift();
+    }
+  }
+  nextEvent() {
+    if (this.failure !== null) {
+      return Promise.reject(this.failure);
+    }
+    const queued = this.queue.shift();
+    if (queued !== void 0) {
+      return Promise.resolve({ done: false, value: queued });
+    }
+    if (this.ended) {
+      return Promise.resolve({ done: true, value: void 0 });
+    }
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
+    });
+  }
+};
+
+// src/lib/verbose-flag.ts
+import { Flags } from "@oclif/core";
+var verboseFlag = {
+  verbose: Flags.boolean({
+    description: "Show diagnostic detail: HTTP status/timing lines for auth requests (stderr) and stack traces for internal errors."
+  })
+};
+var jsonFlag = {
+  json: Flags.boolean({
+    description: "Emit machine-readable JSON on stdout."
+  })
+};
+
+// src/commands/dev/listen.ts
+var TARGET_PROBE_TIMEOUT_MS = 2e3;
+var FORWARD_TIMEOUT_MS = 1e4;
+var FORWARD_MAX_INFLIGHT = 32;
+var SHUTDOWN_DRAIN_MS = 5e3;
+var SIGNAL_FORCE_EXIT_WINDOW_MS = 2e3;
+var FORWARD_ERR_PREFIX = "err:";
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "::1"
+]);
+var FORWARD_TO_HINT = "Use a local address with an explicit port, e.g. --forward-to localhost:3000/webhooks.";
+var devSessionSchema = z2.object({
+  sessionId: z2.string().min(1),
+  wsUrl: z2.string().min(1),
+  expiresAt: z2.string()
+});
+function parseForwardTarget(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    throw new ValidationError("--forward-to must not be empty.", FORWARD_TO_HINT);
+  }
+  let candidate = trimmed;
+  const hasScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(candidate);
+  if (!hasScheme && candidate.startsWith("::1")) {
+    candidate = `[::1]${candidate.slice("::1".length)}`;
+  }
+  if (!hasScheme) {
+    candidate = `http://${candidate}`;
+  }
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new ValidationError(
+      `--forward-to is not a valid URL: ${raw}`,
+      FORWARD_TO_HINT
+    );
+  }
+  if (url.protocol === "https:") {
+    throw new ValidationError(
+      "--forward-to does not support https targets; local forwarding uses plain http.",
+      FORWARD_TO_HINT
+    );
+  }
+  if (url.protocol !== "http:") {
+    throw new ValidationError(
+      `--forward-to has an unsupported scheme: ${url.protocol}//`,
+      FORWARD_TO_HINT
+    );
+  }
+  const hostname = url.hostname.replace(/^\[/, "").replace(/\]$/, "");
+  if (!LOOPBACK_HOSTS.has(hostname)) {
+    throw new ValidationError(
+      `--forward-to host must be local; got: ${hostname}`,
+      FORWARD_TO_HINT
+    );
+  }
+  if (url.port === "") {
+    throw new ValidationError(
+      "--forward-to must include an explicit port.",
+      FORWARD_TO_HINT
+    );
+  }
+  return url;
+}
+function parseEventsFilter(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const topics = raw.split(",").map((token) => token.trim()).filter((token) => token !== "");
+  if (topics.length === 0) {
+    throw new ValidationError(
+      "--events was provided but contains no topics.",
+      "Pass a comma-separated list, e.g. --events=orders.created,orders.updated."
+    );
+  }
+  return new Set(topics);
+}
+function extractTopic(payload) {
+  if (typeof payload !== "object" || payload === null) {
+    return void 0;
+  }
+  const topic = payload.topic;
+  return typeof topic === "string" ? topic : void 0;
+}
+function formatEventLine(mode, seq, timestamp, topic, status) {
+  if (mode === "json") {
+    return JSON.stringify({
+      seq,
+      t: timestamp,
+      topic: topic ?? null,
+      "forward-status": status
+    }) + "\n";
+  }
+  return `seq=${seq} t=${timestamp} topic=${topic ?? "-"} forward-status=${status}
+`;
+}
+function shortReason(cause, aborted) {
+  if (aborted) {
+    return "timeout";
+  }
+  if (cause instanceof Error) {
+    const code = cause.cause?.code;
+    if (typeof code === "string" && code.length > 0) {
+      return code.toLowerCase();
+    }
+  }
+  return "network";
+}
+async function createDevSession(serverUrl, token, appId) {
+  const base = serverUrl.replace(/\/+$/, "");
+  let response;
+  try {
+    response = await fetch(`${base}/dev/sessions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ appId })
+    });
+  } catch {
+    throw new RelayConnectError("Could not reach the dev-session endpoint.");
+  }
+  if (response.status === 400) {
+    throw new ValidationError(
+      "The server rejected the dev-session request.",
+      "You may have too many active dev sessions; wait for one to expire and retry."
+    );
+  }
+  if (!response.ok) {
+    throw new RelayConnectError(
+      `Failed to create dev session (status: ${response.status})`
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new RelayConnectError("Dev-session response was not the expected shape.");
+  }
+  const parsed = devSessionSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new RelayConnectError("Dev-session response was not the expected shape.");
+  }
+  return parsed.data;
+}
+async function drainPending(pending, capMs) {
+  if (pending.size === 0) {
+    return;
+  }
+  let capTimer;
+  const cap = new Promise((resolve) => {
+    capTimer = setTimeout(resolve, capMs);
+  });
+  try {
+    await Promise.race([Promise.all([...pending]), cap]);
+  } finally {
+    if (capTimer !== void 0) {
+      clearTimeout(capTimer);
+    }
+  }
+}
+var DevListen = class _DevListen extends RatioCommand {
+  static description = "Stream webhook events from your dev session and forward them to a local HTTP server.";
+  static examples = [
+    "<%= config.bin %> dev listen --forward-to localhost:3000/webhooks --app-id=4f9d2c31-8a6b-4f2e-9c1d-3e5a7b9d0f12",
+    "<%= config.bin %> dev listen --forward-to http://127.0.0.1:3000/webhooks --events=orders.created,orders.updated --app-id=4f9d2c31-8a6b-4f2e-9c1d-3e5a7b9d0f12",
+    "<%= config.bin %> dev listen --forward-to localhost:3000/webhooks --json",
+    "<%= config.bin %> dev listen --forward-to localhost:3000/webhooks --app-id=4f9d2c31-8a6b-4f2e-9c1d-3e5a7b9d0f12 --verbose"
+  ];
+  static flags = {
+    ...verboseFlag,
+    ...jsonFlag,
+    "forward-to": Flags2.string({
+      description: "Local URL to forward events to (localhost only, explicit port required), e.g. localhost:3000/webhooks.",
+      required: true
+    }),
+    events: Flags2.string({
+      description: "Comma-separated event topics to forward (default: all)."
+    }),
+    "app-id": Flags2.string({
+      description: "App id whose dev session to open (UUID). Required.",
+      required: true
+    })
+  };
+  // ── Seams: overridable in tests; defaults hit the real process. ──────────
+  writeOut = (chunk) => {
+    process.stdout.write(chunk);
+  };
+  writeErr = (chunk) => {
+    process.stderr.write(chunk);
+  };
+  signalSource = process;
+  hardExit = (code) => {
+    process.exit(code);
+  };
+  makeRelayClient = (options) => new RelayClient(options);
+  async run() {
+    const { flags } = await this.parse(_DevListen);
+    const jsonMode = flags.json === true;
+    const verbose = flags.verbose === true;
+    const trace = (message) => {
+      if (verbose) {
+        this.writeErr(`${message}
+`);
+      }
+    };
+    const target = parseForwardTarget(flags["forward-to"]);
+    const targetUrl = target.toString();
+    const topicFilter = parseEventsFilter(flags.events);
+    const appId = flags["app-id"];
+    if (appId === "") {
+      throw new ValidationError(
+        "A dev listen session requires an --app-id.",
+        "Pass --app-id=<uuid>."
+      );
+    }
+    const store = new FileCredentialStore();
+    const token = await store.getValidAccessToken();
+    const serverUrl = resolveServerUrl();
+    const session = await createDevSession(serverUrl, token, appId);
+    trace(`session created: ${session.sessionId} (expires ${session.expiresAt})`);
+    await this.probeTarget(targetUrl, trace);
+    const clientOptions = {
+      sessionId: session.sessionId,
+      wsUrl: session.wsUrl,
+      credentialStore: store,
+      ...verbose ? { tracer: (message) => this.writeErr(`${message}
+`) } : {}
+    };
+    const client = this.makeRelayClient(clientOptions);
+    const emitEventLine = (seq, timestamp, topic, status) => {
+      if (jsonMode) {
+        this.writeOut(formatEventLine("json", seq, timestamp, topic, status));
+        return;
+      }
+      this.writeErr(formatEventLine("kv", seq, timestamp, topic, status));
+    };
+    let inFlight = 0;
+    const slotWaiters = [];
+    const pending = /* @__PURE__ */ new Set();
+    const releaseSlot = () => {
+      const wake = slotWaiters.shift();
+      if (wake !== void 0) {
+        wake();
+      }
+    };
+    let shuttingDown = false;
+    let firstSignalAt = 0;
+    const onSignal = () => {
+      if (shuttingDown) {
+        if (Date.now() - firstSignalAt <= SIGNAL_FORCE_EXIT_WINDOW_MS) {
+          this.hardExit(130);
+        }
+        return;
+      }
+      shuttingDown = true;
+      firstSignalAt = Date.now();
+      this.writeErr(
+        "shutting down: closing the event stream and draining in-flight forwards\n"
+      );
+      void client.close();
+    };
+    this.signalSource.on("SIGINT", onSignal);
+    this.signalSource.on("SIGTERM", onSignal);
+    try {
+      await client.connect();
+      this.writeErr(
+        `listening: forwarding webhook events to ${targetUrl}
+`
+      );
+      try {
+        for await (const event of client.events()) {
+          if (event.kind !== "webhook") {
+            emitEventLine(event.seq, event.timestamp, void 0, "dropped:control");
+            continue;
+          }
+          const topic = extractTopic(event.payload);
+          if (topicFilter !== void 0 && (topic === void 0 || !topicFilter.has(topic))) {
+            emitEventLine(event.seq, event.timestamp, topic, "filtered");
+            continue;
+          }
+          if (inFlight >= FORWARD_MAX_INFLIGHT) {
+            trace("forward capacity reached; waiting for a slot");
+            await new Promise((resolve) => {
+              slotWaiters.push(resolve);
+            });
+          }
+          inFlight += 1;
+          const task = this.forwardOnce(targetUrl, event.payload).then((status) => {
+            emitEventLine(event.seq, event.timestamp, topic, status);
+          }).finally(() => {
+            inFlight -= 1;
+            pending.delete(task);
+            releaseSlot();
+          });
+          pending.add(task);
+        }
+      } catch (streamErr) {
+        if (streamErr instanceof RelayResumeGapError) {
+          throw streamErr;
+        }
+        if (streamErr instanceof RelayConnectError && /4401|auth/i.test(streamErr.message)) {
+          throw new RelayConnectError(
+            streamErr.message,
+            "Your session token was rejected. Run 'ratio auth login' to sign in again."
+          );
+        }
+        throw streamErr;
+      }
+      await drainPending(pending, SHUTDOWN_DRAIN_MS);
+    } finally {
+      this.signalSource.removeListener("SIGINT", onSignal);
+      this.signalSource.removeListener("SIGTERM", onSignal);
+      await client.close().catch(() => void 0);
+    }
+  }
+  /**
+   * Best-effort reachability probe of the forward target. Never throws and
+   * never blocks the session: a dead target only produces a warning, because
+   * the user may start their local server after this command boots.
+   */
+  async probeTarget(targetUrl, trace) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TARGET_PROBE_TIMEOUT_MS);
+    try {
+      const response = await fetch(targetUrl, {
+        method: "HEAD",
+        signal: controller.signal
+      });
+      trace(`target probe: responded with status ${response.status}`);
+    } catch {
+      this.writeErr(
+        `warning: target ${targetUrl} is not responding yet; events will still be forwarded once your server is up
+`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * POST one event body to the local target. Resolves to a status token —
+   * `ok:<status>` or `err:<reason>` — and NEVER rejects: a failed forward
+   * is logged and dropped so the stream keeps flowing.
+   */
+  async forwardOnce(targetUrl, payload) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FORWARD_TIMEOUT_MS);
+    try {
+      const response = await fetch(targetUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload ?? null),
+        signal: controller.signal
+      });
+      await response.arrayBuffer().catch(() => void 0);
+      if (response.ok) {
+        return `ok:${response.status}`;
+      }
+      return `${FORWARD_ERR_PREFIX}http-${response.status}`;
+    } catch (cause) {
+      return `${FORWARD_ERR_PREFIX}${shortReason(cause, controller.signal.aborted)}`;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+export {
+  FORWARD_MAX_INFLIGHT,
+  FORWARD_TIMEOUT_MS,
+  SHUTDOWN_DRAIN_MS,
+  SIGNAL_FORCE_EXIT_WINDOW_MS,
+  TARGET_PROBE_TIMEOUT_MS,
+  DevListen as default,
+  extractTopic,
+  formatEventLine,
+  parseEventsFilter,
+  parseForwardTarget
+};
+//# sourceMappingURL=listen.js.map