@ratio-app/cli 0.1.1

package/dist/lib/ratio-command.d.ts

@@ -0,0 +1,52 @@
+import { Command } from '@oclif/core';
+
+/**
+ * Base class for all Ratio CLI commands.
+ *
+ * Overrides catch() to intercept every error thrown from run(), render it
+ * per the Ratio CLI error-UX spec (typed hierarchy -> structured stderr/stdout,
+ * --verbose for stack traces, --json for machine-readable envelope), and then
+ * suppress oclif's own double-render by setting skipOclifErrorHandling on the
+ * re-thrown error.
+ *
+ * Path B: base-class override — no oclif.hooks wiring needed.
+ * oclif v4 does not expose a command_error hook; the reliable interception
+ * point is Command.catch(), which is called by Command._run() before the
+ * error bubbles up to oclif's global handle() function.
+ *
+ * Double-render prevention:
+ *   oclif's handle() checks err.skipOclifErrorHandling before printing.
+ *   After rendering we set skipOclifErrorHandling = true so oclif's
+ *   pretty-print is skipped. We also set err.oclif.exit = N so handle()
+ *   calls process.exit(N) with the correct code.
+ *
+ * Exit-code routing:
+ *   - exitCode === 0 (ComingSoonError): throw ExitError(0) so oclif calls
+ *     process.exit(0) cleanly. ExitError has code 'EEXIT' and is treated as
+ *     a clean exit — shouldPrint is false in handle().
+ *   - exitCode > 0: mark err.skipOclifErrorHandling = true and set
+ *     err.oclif = { exit: N }, then re-throw so handle() exits N.
+ *
+ * Verbose/json detection strategy:
+ *   We scan this.argv directly. this.argv is set by oclif's Command before
+ *   run() is called and always contains the raw argument list. This approach
+ *   works both for:
+ *   (a) post-parse errors (thrown after this.parse() succeeds) — argv has the
+ *       flags that were successfully recognised.
+ *   (b) pre-parse errors (thrown BY this.parse(), e.g. unknown flag) — argv
+ *       still contains --verbose / --json even though parse() threw.
+ *   Simple string scan is sufficient since --verbose and --json are boolean
+ *   flags with no value argument.
+ */
+declare abstract class RatioCommand extends Command {
+    private _getRenderFlags;
+    catch(err: Error & {
+        exitCode?: number;
+        oclif?: {
+            exit?: number;
+        };
+        skipOclifErrorHandling?: boolean;
+    }): Promise<never>;
+}
+
+export { RatioCommand };

package/dist/lib/ratio-command.js

@@ -0,0 +1,141 @@
+// src/lib/ratio-command.ts
+import { Command, Errors } from "@oclif/core";
+
+// 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 ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+function isRatioCLIError(err) {
+  return err instanceof RatioCLIError;
+}
+
+// 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;
+  }
+};
+export {
+  RatioCommand
+};
+//# sourceMappingURL=ratio-command.js.map

package/dist/lib/ratio-command.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/ratio-command.ts","../../src/lib/errors.ts","../../src/lib/render-error.ts"],"sourcesContent":["import { Command, Errors } from '@oclif/core';\nimport { renderError } from './render-error.js';\n\n/**\n * Base class for all Ratio CLI commands.\n *\n * Overrides catch() to intercept every error thrown from run(), render it\n * per the Ratio CLI error-UX spec (typed hierarchy -> structured stderr/stdout,\n * --verbose for stack traces, --json for machine-readable envelope), and then\n * suppress oclif's own double-render by setting skipOclifErrorHandling on the\n * re-thrown error.\n *\n * Path B: base-class override — no oclif.hooks wiring needed.\n * oclif v4 does not expose a command_error hook; the reliable interception\n * point is Command.catch(), which is called by Command._run() before the\n * error bubbles up to oclif's global handle() function.\n *\n * Double-render prevention:\n *   oclif's handle() checks err.skipOclifErrorHandling before printing.\n *   After rendering we set skipOclifErrorHandling = true so oclif's\n *   pretty-print is skipped. We also set err.oclif.exit = N so handle()\n *   calls process.exit(N) with the correct code.\n *\n * Exit-code routing:\n *   - exitCode === 0 (ComingSoonError): throw ExitError(0) so oclif calls\n *     process.exit(0) cleanly. ExitError has code 'EEXIT' and is treated as\n *     a clean exit — shouldPrint is false in handle().\n *   - exitCode > 0: mark err.skipOclifErrorHandling = true and set\n *     err.oclif = { exit: N }, then re-throw so handle() exits N.\n *\n * Verbose/json detection strategy:\n *   We scan this.argv directly. this.argv is set by oclif's Command before\n *   run() is called and always contains the raw argument list. This approach\n *   works both for:\n *   (a) post-parse errors (thrown after this.parse() succeeds) — argv has the\n *       flags that were successfully recognised.\n *   (b) pre-parse errors (thrown BY this.parse(), e.g. unknown flag) — argv\n *       still contains --verbose / --json even though parse() threw.\n *   Simple string scan is sufficient since --verbose and --json are boolean\n *   flags with no value argument.\n */\nexport abstract class RatioCommand extends Command {\n  private _getRenderFlags(): { verbose: boolean; json: boolean } {\n    const argv = this.argv as string[];\n    return {\n      verbose: argv.includes('--verbose'),\n      json: argv.includes('--json'),\n    };\n  }\n\n  override async catch(\n    err: Error & {\n      exitCode?: number;\n      oclif?: { exit?: number };\n      skipOclifErrorHandling?: boolean;\n    },\n  ): Promise<never> {\n    const { verbose, json } = this._getRenderFlags();\n\n    const output = renderError({ err, verbose, json });\n\n    // Write rendered output before any exit/throw\n    if (output.stdout) process.stdout.write(output.stdout);\n    if (output.stderr) process.stderr.write(output.stderr);\n\n    if (output.exitCode === 0) {\n      // ComingSoonError path — ExitError(0) causes oclif to call process.exit(0)\n      // cleanly. ExitError has code 'EEXIT'; handle() treats it as a clean exit\n      // (shouldPrint is false) so no additional output is written.\n      throw new Errors.ExitError(0);\n    }\n\n    // For non-zero exits: suppress oclif's pretty-print by marking the error,\n    // then route the correct exit code via oclif.exit so handle() calls process.exit(N).\n    err.skipOclifErrorHandling = true;\n    err.oclif = { exit: output.exitCode };\n    throw err;\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","import { isRatioCLIError, RatioCLIError, ValidationError } from './errors.js';\n\nexport interface RenderInput {\n  err: unknown;\n  verbose: boolean;\n  json: boolean;\n}\n\nexport interface RenderOutput {\n  /** Text to write to stdout. Empty string means nothing to write. */\n  stdout: string;\n  /** Text to write to stderr. Empty string means nothing to write. */\n  stderr: string;\n  exitCode: number;\n}\n\n/**\n * Detects whether an error originates from the oclif argument/flag parser.\n * oclif's CLIParseError subclasses (NonExistentFlagsError, RequiredArgsError,\n * etc.) all carry a `parse` property set by CLIParseErrorOptions. This is the\n * stable structural signal — more reliable than checking the class name string.\n */\nfunction isOclifParserError(err: unknown): err is Error & { parse: unknown } {\n  return (\n    err instanceof Error &&\n    'parse' in err &&\n    err.parse !== null &&\n    err.parse !== undefined\n  );\n}\n\n/**\n * Builds the JSON error envelope. Fields with undefined values are omitted\n * so the consumer never sees `\"hint\": null` or `\"docsUrl\": null`.\n */\nfunction buildErrorEnvelope(\n  code: string,\n  message: string,\n  hint?: string,\n  docsUrl?: string,\n): string {\n  const obj: Record<string, unknown> = { ok: false, code, message };\n  if (hint !== undefined) obj['hint'] = hint;\n  if (docsUrl !== undefined) obj['docsUrl'] = docsUrl;\n  return JSON.stringify(obj) + '\\n';\n}\n\n/**\n * Pure rendering function — no side effects, no process.exit, no I/O.\n * The caller (RatioCommand.catch) is responsible for writing output and exiting.\n *\n * Rendering rules (all branches):\n *\n * | Error shape          | --json | --verbose | stdout                         | stderr                           | exit |\n * |----------------------|--------|-----------|--------------------------------|----------------------------------|------|\n * | ComingSoonError      | false  | any       | err.message + '\\n'            | ''                               | 0    |\n * | ComingSoonError      | true   | any       | '{\"ok\":true,\"data\":null}\\n'   | ''                               | 0    |\n * | RatioCLIError >0     | false  | false     | ''                            | code: msg [+ hint] [+ docsUrl]  | N    |\n * | RatioCLIError >0     | false  | true      | ''                            | above + stack                    | N    |\n * | RatioCLIError >0     | true   | false     | JSON envelope                  | ''                               | N    |\n * | RatioCLIError >0     | true   | true      | JSON envelope                  | stack only                       | N    |\n * | oclif ParserError    | false  | any       | ''                            | VALIDATION_ERROR: msg [+stack]  | 8    |\n * | oclif ParserError    | true   | any       | JSON VALIDATION_ERROR envelope | stack if verbose                 | 8    |\n * | Plain Error / other  | false  | false     | ''                            | INTERNAL: msg\\n                 | 1    |\n * | Plain Error / other  | false  | true      | ''                            | INTERNAL: msg\\n + stack\\n       | 1    |\n * | Plain Error / other  | true   | any       | JSON INTERNAL envelope         | stack if verbose                 | 1    |\n */\nexport function renderError(input: RenderInput): RenderOutput {\n  const { err, verbose, json } = input;\n\n  // ── Branch 1: our own typed hierarchy ───────────────────────────────────\n  if (isRatioCLIError(err)) {\n    const ratioErr = err as RatioCLIError;\n\n    // exitCode === 0 → coming-soon: render on stdout, no stderr, exit 0\n    if (ratioErr.exitCode === 0) {\n      if (json) {\n        return {\n          stdout: JSON.stringify({ ok: true, data: null }) + '\\n',\n          stderr: '',\n          exitCode: 0,\n        };\n      }\n      return {\n        stdout: ratioErr.message + '\\n',\n        stderr: '',\n        exitCode: 0,\n      };\n    }\n\n    // exitCode > 0 → error render\n    let stderrLines = `${ratioErr.code}: ${ratioErr.message}\\n`;\n    if (ratioErr.hint !== undefined) stderrLines += `${ratioErr.hint}\\n`;\n    if (ratioErr.docsUrl !== undefined) stderrLines += `${ratioErr.docsUrl}\\n`;\n\n    if (json) {\n      return {\n        stdout: buildErrorEnvelope(ratioErr.code, ratioErr.message, ratioErr.hint, ratioErr.docsUrl),\n        stderr: verbose && ratioErr.stack ? ratioErr.stack + '\\n' : '',\n        exitCode: ratioErr.exitCode,\n      };\n    }\n\n    if (verbose && ratioErr.stack) {\n      stderrLines += ratioErr.stack + '\\n';\n    }\n\n    return { stdout: '', stderr: stderrLines, exitCode: ratioErr.exitCode };\n  }\n\n  // ── Branch 2: oclif parser error (unknown flag, missing required arg, etc.) ──\n  if (isOclifParserError(err)) {\n    const parserErr = err as Error & { parse: unknown };\n    const msg = parserErr.message || 'Unknown parse error';\n\n    // Strip oclif's \"Unexpected argument: --foo\" or similar prefix noise where\n    // possible, but keep the core message as-is since it's already human-readable.\n    const coercedErr = new ValidationError(msg);\n\n    let stderrText = `${coercedErr.code}: ${msg}\\n`;\n\n    if (json) {\n      return {\n        stdout: buildErrorEnvelope(coercedErr.code, msg),\n        stderr: verbose && parserErr.stack ? parserErr.stack + '\\n' : '',\n        exitCode: 8,\n      };\n    }\n\n    if (verbose && parserErr.stack) {\n      stderrText += parserErr.stack + '\\n';\n    }\n\n    return { stdout: '', stderr: stderrText, exitCode: 8 };\n  }\n\n  // ── Branch 3: plain Error or non-Error throw ─────────────────────────────\n  const message = err instanceof Error ? err.message : String(err);\n  const stack = err instanceof Error ? err.stack : undefined;\n  const stderrPrefix = `INTERNAL: ${message}\\n`;\n\n  if (json) {\n    return {\n      stdout: buildErrorEnvelope('INTERNAL', message),\n      stderr: verbose && stack ? stack + '\\n' : '',\n      exitCode: 1,\n    };\n  }\n\n  let stderrText = stderrPrefix;\n  if (verbose && stack) {\n    stderrText += stack + '\\n';\n  }\n\n  return { stdout: '', stderr: stderrText, exitCode: 1 };\n}\n"],"mappings":"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","names":["stderrText"]}

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

@@ -0,0 +1,7 @@
+export { LOCAL_BUFFER_MAX, RelayClient } from './relay-client.js';
+export { RelayClientOptions, RelayEvent, RelayRandom, RelayScheduler, ResumeCursor } from './types.js';
+import '../credentials/store.js';
+import '../credentials/clock.js';
+import '../credentials/refresher.js';
+import '../credentials/types.js';
+import '../auth/verbose-trace.js';

package/dist/lib/relay/index.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=index.js.map

package/dist/lib/relay/index.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":[]}