@ratio-app/cli 0.1.1

package/dist/lib/relay/relay-client.d.ts

@@ -0,0 +1,91 @@
+import { RelayClientOptions, RelayEvent } from './types.js';
+import '../credentials/store.js';
+import '../credentials/clock.js';
+import '../credentials/refresher.js';
+import '../credentials/types.js';
+import '../auth/verbose-trace.js';
+
+/**
+ * WebSocket relay tunnel client.
+ *
+ * Responsibilities:
+ *  - Connect to the relay stream endpoint with `Authorization: Bearer`
+ *    at the HTTP handshake (the token never appears in the URL). The
+ *    server authenticates the upgrade by reading the `sessionId` query
+ *    parameter, so every connect URL carries `?sessionId=<id>`.
+ *  - Accept the server-issued stream URL, which may already carry the
+ *    canonical `?sessionId=` parameter; it must match the session the
+ *    client was constructed with, and no other query parameter is
+ *    allowed — the client owns the connect query string.
+ *  - Track the monotonic per-session sequence number; discard
+ *    duplicates delivered during a resume replay.
+ *  - Auto-reconnect on abnormal closes with exponential backoff
+ *    (capped) and multiplicative jitter, resuming from the last seen
+ *    sequence via the `resumeCursor` query parameter (sent alongside
+ *    `sessionId`).
+ *  - Surface a server-declared resume gap as a typed
+ *    RelayResumeGapError — recovery policy belongs to the caller.
+ *  - Deliver events through a pull-based AsyncIterable with a bounded
+ *    local buffer; a stalled consumer fails fast instead of growing
+ *    memory without limit.
+ *
+ * Uses the `ws` package (not the runtime's built-in WebSocket, which
+ * is only available as a stable global from Node 22 — this package
+ * supports Node 18+).
+ */
+
+/**
+ * Maximum number of undelivered events held for a slow consumer.
+ * Exceeding it rejects the consumer's next pull and closes the
+ * connection — the client never buffers without bound.
+ */
+declare const LOCAL_BUFFER_MAX = 1000;
+declare class RelayClient {
+    private readonly wsUrl;
+    private readonly options;
+    private readonly scheduler;
+    private readonly random;
+    private readonly trace;
+    private ws;
+    private lastSeq;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private readonly queue;
+    private readonly waiters;
+    /** First fatal error; once set, every consumer pull rejects with it. */
+    private failure;
+    /** Clean end of stream (normal close or caller-initiated close()). */
+    private ended;
+    private userClosed;
+    private started;
+    private pendingConnect;
+    constructor(options: RelayClientOptions);
+    /**
+     * 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.
+     */
+    connect(): Promise<void>;
+    /**
+     * 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(): AsyncIterable<RelayEvent>;
+    /**
+     * Graceful shutdown: cancels any pending reconnect, closes the
+     * socket with a normal-closure code, and completes the iterator.
+     */
+    close(): Promise<void>;
+    private openSocket;
+    private handleMessage;
+    private deliver;
+    private handleClose;
+    private scheduleReconnect;
+    private fail;
+    private endClean;
+    private nextEvent;
+}
+
+export { LOCAL_BUFFER_MAX, RelayClient };

package/dist/lib/relay/relay-client.js

@@ -0,0 +1,362 @@
+// src/lib/relay/relay-client.ts
+import WebSocket from "ws";
+
+// 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 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 });
+  }
+};
+
+// src/lib/relay/relay-client.ts
+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 });
+    });
+  }
+};
+export {
+  LOCAL_BUFFER_MAX,
+  RelayClient
+};
+//# sourceMappingURL=relay-client.js.map

package/dist/lib/relay/relay-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/relay/relay-client.ts","../../../src/lib/errors.ts"],"sourcesContent":["/**\n * WebSocket relay tunnel client.\n *\n * Responsibilities:\n *  - Connect to the relay stream endpoint with `Authorization: Bearer`\n *    at the HTTP handshake (the token never appears in the URL). The\n *    server authenticates the upgrade by reading the `sessionId` query\n *    parameter, so every connect URL carries `?sessionId=<id>`.\n *  - Accept the server-issued stream URL, which may already carry the\n *    canonical `?sessionId=` parameter; it must match the session the\n *    client was constructed with, and no other query parameter is\n *    allowed — the client owns the connect query string.\n *  - Track the monotonic per-session sequence number; discard\n *    duplicates delivered during a resume replay.\n *  - Auto-reconnect on abnormal closes with exponential backoff\n *    (capped) and multiplicative jitter, resuming from the last seen\n *    sequence via the `resumeCursor` query parameter (sent alongside\n *    `sessionId`).\n *  - Surface a server-declared resume gap as a typed\n *    RelayResumeGapError — recovery policy belongs to the caller.\n *  - Deliver events through a pull-based AsyncIterable with a bounded\n *    local buffer; a stalled consumer fails fast instead of growing\n *    memory without limit.\n *\n * Uses the `ws` package (not the runtime's built-in WebSocket, which\n * is only available as a stable global from Node 22 — this package\n * supports Node 18+).\n */\n\nimport WebSocket from 'ws';\nimport {\n  RelayConnectError,\n  RelayResumeGapError,\n  ValidationError,\n} from '../errors.js';\nimport type {\n  RelayClientOptions,\n  RelayEvent,\n  RelayRandom,\n  RelayScheduler,\n  ResumeCursor,\n} from './types.js';\n\n/**\n * Maximum number of undelivered events held for a slow consumer.\n * Exceeding it rejects the consumer's next pull and closes the\n * connection — the client never buffers without bound.\n */\nexport const LOCAL_BUFFER_MAX = 1000;\n\n/** Base backoff unit; attempt n waits min(2^n * 100, 30_000) ms. */\nconst BACKOFF_BASE_MS = 100;\n/** Backoff ceiling: 30_000 ms (30 seconds). */\nconst BACKOFF_CAP_MS = 30_000;\n\n/** Close code the server uses to reject an unauthenticated socket. */\nconst CLOSE_CODE_AUTH_REJECTED = 4401;\n/** Normal-closure code — clean shutdown, never reconnected. */\nconst CLOSE_CODE_NORMAL = 1000;\n\nconst defaultScheduler: RelayScheduler = (fn, ms) => {\n  const handle = setTimeout(fn, ms);\n  return { cancel: () => clearTimeout(handle) };\n};\n\ninterface Waiter {\n  resolve: (result: IteratorResult<RelayEvent>) => void;\n  reject: (err: Error) => void;\n}\n\nexport class RelayClient {\n  private readonly wsUrl: string;\n  private readonly options: RelayClientOptions;\n  private readonly scheduler: RelayScheduler;\n  private readonly random: RelayRandom;\n  private readonly trace: (msg: string) => void;\n\n  private ws: WebSocket | null = null;\n  private lastSeq: ResumeCursor = -1;\n  private reconnectAttempt = 0;\n  private reconnectTimer: { cancel: () => void } | null = null;\n\n  private readonly queue: RelayEvent[] = [];\n  private readonly waiters: Waiter[] = [];\n  /** First fatal error; once set, every consumer pull rejects with it. */\n  private failure: Error | null = null;\n  /** Clean end of stream (normal close or caller-initiated close()). */\n  private ended = false;\n  private userClosed = false;\n  private started = false;\n\n  private pendingConnect: {\n    resolve: () => void;\n    reject: (err: Error) => void;\n  } | null = null;\n\n  constructor(options: RelayClientOptions) {\n    if (options.wsUrl === '') {\n      throw new ValidationError('Relay stream URL must not be empty.');\n    }\n    if (options.sessionId === '') {\n      throw new ValidationError('Relay session id must not be empty.');\n    }\n    let parsed: URL;\n    try {\n      parsed = new URL(options.wsUrl);\n    } catch {\n      throw new ValidationError(\n        'Relay stream URL is not a valid URL.',\n        'The server returned a malformed stream endpoint — retry creating the session.',\n      );\n    }\n    for (const [name, value] of parsed.searchParams.entries()) {\n      if (name === 'sessionId') {\n        if (value !== options.sessionId) {\n          throw new ValidationError(\n            'Relay stream URL carries a session id that does not match the created session.',\n            'The server and client disagree on the session — retry creating the session.',\n          );\n        }\n        continue;\n      }\n      throw new ValidationError(\n        'Relay stream URL must not carry query parameters other than the session id.',\n        'The client builds the connection query string itself.',\n      );\n    }\n    this.options = options;\n    // Canonical base: origin + path only. The connect query string\n    // (sessionId, and resumeCursor on resume) is built per attempt.\n    this.wsUrl = `${parsed.origin}${parsed.pathname}`;\n    this.scheduler = options.scheduler ?? defaultScheduler;\n    this.random = options.random ?? Math.random;\n    this.trace = options.tracer ?? (() => {});\n  }\n\n  /**\n   * Opens the first connection. Resolves when the socket is open;\n   * rejects with a typed error on authentication rejection or when the\n   * stream fails before ever becoming established. May only be called\n   * once per client instance.\n   */\n  async connect(): Promise<void> {\n    if (this.started) {\n      throw new ValidationError('connect() may only be called once.');\n    }\n    this.started = true;\n    await new Promise<void>((resolve, reject) => {\n      this.pendingConnect = { resolve, reject };\n      void this.openSocket();\n    });\n  }\n\n  /**\n   * Pull-based event stream. Single-consumer: the iterator shares the\n   * client's internal queue. Ends when close() is called or the server\n   * closes cleanly; rejects with a typed error on fatal conditions.\n   */\n  events(): AsyncIterable<RelayEvent> {\n    return {\n      [Symbol.asyncIterator]: () => ({\n        next: () => this.nextEvent(),\n        return: async (): Promise<IteratorResult<RelayEvent>> => {\n          await this.close();\n          return { done: true, value: undefined };\n        },\n      }),\n    };\n  }\n\n  /**\n   * Graceful shutdown: cancels any pending reconnect, closes the\n   * socket with a normal-closure code, and completes the iterator.\n   */\n  async close(): Promise<void> {\n    this.userClosed = true;\n    if (this.reconnectTimer !== null) {\n      this.reconnectTimer.cancel();\n      this.reconnectTimer = null;\n    }\n    const ws = this.ws;\n    if (ws === null || ws.readyState === WebSocket.CLOSED) {\n      this.endClean();\n      return;\n    }\n    await new Promise<void>((resolve) => {\n      ws.once('close', () => resolve());\n      ws.close(CLOSE_CODE_NORMAL);\n    });\n  }\n\n  // ── internal state machine ────────────────────────────────────────\n\n  private async openSocket(): Promise<void> {\n    let token: string;\n    try {\n      token = await this.options.credentialStore.getValidAccessToken(\n        this.options.profileName,\n      );\n    } catch (err) {\n      // Credential-store failures are already typed; surface as fatal.\n      this.fail(err instanceof Error ? err : new RelayConnectError(\n        'Could not obtain an access token for the relay connection.',\n      ));\n      return;\n    }\n\n    // The server authenticates the upgrade via the sessionId query\n    // parameter — every connect carries it; a resume adds the cursor.\n    const query = new URLSearchParams({ sessionId: this.options.sessionId });\n    if (this.lastSeq !== -1) {\n      query.set('resumeCursor', String(this.lastSeq));\n    }\n    const url = `${this.wsUrl}?${query.toString()}`;\n\n    this.trace(\n      `relay connect: session=${this.options.sessionId} cursor=${this.lastSeq}`,\n    );\n\n    const ws = new WebSocket(url, {\n      headers: { Authorization: `Bearer ${token}` },\n    });\n    this.ws = ws;\n\n    ws.on('open', () => {\n      this.reconnectAttempt = 0;\n      this.trace('relay connected');\n      if (this.pendingConnect !== null) {\n        this.pendingConnect.resolve();\n        this.pendingConnect = null;\n      }\n    });\n    ws.on('message', (data) => {\n      this.handleMessage(String(data));\n    });\n    ws.on('error', (err) => {\n      // The matching 'close' event drives the state machine; this\n      // listener only prevents an unhandled-error crash.\n      this.trace(`relay socket error: ${err.message}`);\n    });\n    ws.on('close', (code) => {\n      this.handleClose(code);\n    });\n  }\n\n  private handleMessage(raw: string): void {\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      this.trace('relay frame dropped: not valid JSON');\n      return;\n    }\n    if (typeof parsed !== 'object' || parsed === null) {\n      this.trace('relay frame dropped: not an object');\n      return;\n    }\n    const frame = parsed as Record<string, unknown>;\n\n    if (frame['kind'] === 'control') {\n      if (frame['type'] === 'resume-gap') {\n        this.trace('relay resume gap reported by server');\n        this.fail(\n          new RelayResumeGapError(\n            'The server could not replay all missed events: the resume cursor is older than the replay window.',\n          ),\n        );\n        return;\n      }\n      this.trace('relay control frame ignored: unknown type');\n      return;\n    }\n\n    if (frame['kind'] === 'webhook' && typeof frame['seq'] === 'number') {\n      const seq = frame['seq'];\n      if (seq <= this.lastSeq) {\n        // Duplicate delivered during a resume replay — discard.\n        return;\n      }\n      this.lastSeq = seq;\n      this.deliver({\n        kind: 'webhook',\n        seq,\n        timestamp:\n          typeof frame['timestamp'] === 'number'\n            ? new Date(frame['timestamp']).toISOString()\n            : '',\n        payload: frame['event'],\n      });\n      return;\n    }\n\n    this.trace('relay frame dropped: unrecognized envelope');\n  }\n\n  private deliver(event: RelayEvent): void {\n    const waiter = this.waiters.shift();\n    if (waiter !== undefined) {\n      waiter.resolve({ done: false, value: event });\n      return;\n    }\n    if (this.queue.length >= LOCAL_BUFFER_MAX) {\n      this.trace('relay local buffer overflow — closing connection');\n      this.fail(\n        new RelayConnectError(\n          'Local buffer overflow — consumer stalled',\n          'Slow down the consumer or reduce upstream event rate.',\n        ),\n      );\n      return;\n    }\n    this.queue.push(event);\n  }\n\n  private handleClose(code: number): void {\n    this.ws = null;\n\n    if (this.failure !== null) {\n      // Already failed (resume gap, overflow, auth) — nothing to do.\n      return;\n    }\n\n    if (this.userClosed || code === CLOSE_CODE_NORMAL) {\n      this.trace(`relay closed cleanly (code ${code})`);\n      this.endClean();\n      return;\n    }\n\n    if (code === CLOSE_CODE_AUTH_REJECTED) {\n      this.trace('relay rejected the connection: authentication failed');\n      this.fail(\n        new RelayConnectError(\n          'The relay rejected the connection: authentication failed (close code 4401).',\n          \"Run 'ratio auth login' and retry.\",\n        ),\n      );\n      return;\n    }\n\n    this.scheduleReconnect(code);\n  }\n\n  private scheduleReconnect(closeCode: number): void {\n    this.reconnectAttempt += 1;\n    const base = Math.min(\n      2 ** this.reconnectAttempt * BACKOFF_BASE_MS,\n      BACKOFF_CAP_MS,\n    );\n    // Multiplicative jitter in [0.75, 1.25] avoids reconnect stampedes.\n    const delay = base * (0.75 + this.random() * 0.5);\n    this.trace(\n      `relay reconnect attempt ${this.reconnectAttempt} in ${Math.round(delay)}ms (close code ${closeCode})`,\n    );\n    this.reconnectTimer = this.scheduler(() => {\n      this.reconnectTimer = null;\n      void this.openSocket();\n    }, delay);\n  }\n\n  private fail(err: Error): void {\n    if (this.failure !== null) {\n      return;\n    }\n    this.failure = err;\n    // A failed stream must never reconnect — drop any pending timer.\n    if (this.reconnectTimer !== null) {\n      this.reconnectTimer.cancel();\n      this.reconnectTimer = null;\n    }\n    if (this.pendingConnect !== null) {\n      this.pendingConnect.reject(err);\n      this.pendingConnect = null;\n    }\n    let waiter = this.waiters.shift();\n    while (waiter !== undefined) {\n      waiter.reject(err);\n      waiter = this.waiters.shift();\n    }\n    const ws = this.ws;\n    if (ws !== null && ws.readyState !== WebSocket.CLOSED) {\n      ws.close(CLOSE_CODE_NORMAL);\n    }\n  }\n\n  private endClean(): void {\n    if (this.ended) {\n      return;\n    }\n    this.ended = true;\n    if (this.pendingConnect !== null) {\n      // Closed before ever opening — the stream never established.\n      this.pendingConnect.reject(\n        new RelayConnectError(\n          'The relay connection closed before it was established.',\n        ),\n      );\n      this.pendingConnect = null;\n    }\n    let waiter = this.waiters.shift();\n    while (waiter !== undefined) {\n      waiter.resolve({ done: true, value: undefined });\n      waiter = this.waiters.shift();\n    }\n  }\n\n  private nextEvent(): Promise<IteratorResult<RelayEvent>> {\n    if (this.failure !== null) {\n      return Promise.reject(this.failure);\n    }\n    const queued = this.queue.shift();\n    if (queued !== undefined) {\n      return Promise.resolve({ done: false, value: queued });\n    }\n    if (this.ended) {\n      return Promise.resolve({ done: true, value: undefined });\n    }\n    return new Promise<IteratorResult<RelayEvent>>((resolve, reject) => {\n      this.waiters.push({ resolve, reject });\n    });\n  }\n}\n","/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n"],"mappings":"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","names":[]}

package/dist/lib/relay/types.d.ts

@@ -0,0 +1,71 @@
+import { CredentialStore } from '../credentials/store.js';
+import { VerboseTracer } from '../auth/verbose-trace.js';
+import '../credentials/clock.js';
+import '../credentials/refresher.js';
+import '../credentials/types.js';
+
+/**
+ * Public types for the relay tunnel client.
+ *
+ * The relay client maintains a persistent WebSocket to the platform's
+ * dev-session relay endpoint and surfaces inbound events to the caller
+ * as an AsyncIterable. All timing (reconnect backoff) and randomness
+ * (jitter) sources are injectable so tests run fully deterministic.
+ */
+
+/**
+ * The last sequence number successfully received, used to resume a
+ * dropped connection without event loss. `-1` means "never received"
+ * (cold connect — no resume cursor is sent).
+ */
+type ResumeCursor = number;
+/**
+ * Event surfaced to consumers, mapped from the server's wire frame
+ * (wire `event` → `payload`, epoch-ms `timestamp` → ISO string).
+ * `kind` is the envelope discriminator ("webhook" today; the envelope
+ * reserves room for future kinds without a wire break). `seq` is
+ * monotonic per session.
+ */
+interface RelayEvent {
+    kind: 'webhook' | 'control';
+    seq: number;
+    timestamp: string;
+    payload: unknown;
+}
+/**
+ * Injected timer seam. Returns a handle whose `cancel()` prevents the
+ * callback from firing. Defaults to `setTimeout`/`clearTimeout`.
+ */
+type RelayScheduler = (fn: () => void, ms: number) => {
+    cancel: () => void;
+};
+/** Injected randomness seam for backoff jitter. Defaults to `Math.random`. */
+type RelayRandom = () => number;
+interface RelayClientOptions {
+    /**
+     * Dev-session identifier the stream belongs to. Sent as the
+     * `sessionId` query parameter on every connect — the server
+     * authenticates the WebSocket upgrade with it.
+     */
+    readonly sessionId: string;
+    /**
+     * Full WSS endpoint for the session stream, e.g.
+     * "wss://relay.example.com/dev/relay". The server-issued form may
+     * carry `?sessionId=<id>`; it must match `sessionId` above. Any
+     * other query parameter is rejected — the client builds the connect
+     * query string (`sessionId`, plus `resumeCursor` on resume) itself.
+     */
+    readonly wsUrl: string;
+    /** Credential store used to obtain a valid Bearer access token. */
+    readonly credentialStore: CredentialStore;
+    /** Optional profile forwarded to the credential store. */
+    readonly profileName?: string;
+    /** Timer seam for reconnect scheduling (tests inject a fake). */
+    readonly scheduler?: RelayScheduler;
+    /** Randomness seam for backoff jitter (tests inject a constant). */
+    readonly random?: RelayRandom;
+    /** Verbose diagnostics sink. Never receives secret material. */
+    readonly tracer?: VerboseTracer;
+}
+
+export type { RelayClientOptions, RelayEvent, RelayRandom, RelayScheduler, ResumeCursor };

package/dist/lib/relay/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/lib/relay/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/lib/render-error.d.ts

@@ -0,0 +1,35 @@
+interface RenderInput {
+    err: unknown;
+    verbose: boolean;
+    json: boolean;
+}
+interface RenderOutput {
+    /** Text to write to stdout. Empty string means nothing to write. */
+    stdout: string;
+    /** Text to write to stderr. Empty string means nothing to write. */
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Pure rendering function — no side effects, no process.exit, no I/O.
+ * The caller (RatioCommand.catch) is responsible for writing output and exiting.
+ *
+ * Rendering rules (all branches):
+ *
+ * | Error shape          | --json | --verbose | stdout                         | stderr                           | exit |
+ * |----------------------|--------|-----------|--------------------------------|----------------------------------|------|
+ * | ComingSoonError      | false  | any       | err.message + '\n'            | ''                               | 0    |
+ * | ComingSoonError      | true   | any       | '{"ok":true,"data":null}\n'   | ''                               | 0    |
+ * | RatioCLIError >0     | false  | false     | ''                            | code: msg [+ hint] [+ docsUrl]  | N    |
+ * | RatioCLIError >0     | false  | true      | ''                            | above + stack                    | N    |
+ * | RatioCLIError >0     | true   | false     | JSON envelope                  | ''                               | N    |
+ * | RatioCLIError >0     | true   | true      | JSON envelope                  | stack only                       | N    |
+ * | oclif ParserError    | false  | any       | ''                            | VALIDATION_ERROR: msg [+stack]  | 8    |
+ * | oclif ParserError    | true   | any       | JSON VALIDATION_ERROR envelope | stack if verbose                 | 8    |
+ * | Plain Error / other  | false  | false     | ''                            | INTERNAL: msg\n                 | 1    |
+ * | Plain Error / other  | false  | true      | ''                            | INTERNAL: msg\n + stack\n       | 1    |
+ * | Plain Error / other  | true   | any       | JSON INTERNAL envelope         | stack if verbose                 | 1    |
+ */
+declare function renderError(input: RenderInput): RenderOutput;
+
+export { type RenderInput, type RenderOutput, renderError };