@rerouter/helper 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# @rerouter/helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect coding agents (Claude, Codex, Cursor, opencode, Continue) to Rerouter in seconds.
+
+One command to configure your favorite AI coding tool to use Rerouter as the LLM gateway — with automatic backup, preview-first, and zero API keys written to disk.
+
+## Install
+
+```bash
+npx @rerouter/helper
+```
+
+Or install globally:
+
+```bash
+npm install -g @rerouter/helper
+rerouter-helper
+```
+
+## Quick start
+
+Set your Rerouter API key (get one from the Rerouter dashboard → API Keys):
+
+```bash
+# POSIX (bash/zsh)
+export REROUTER_API_KEY=sk-rr-...
+
+# PowerShell
+$env:REROUTER_API_KEY = "sk-rr-..."
+```
+
+Run the interactive wizard:
+
+```bash
+npx @rerouter/helper
+```
+
+Or configure directly:
+
+```bash
+npx @rerouter/helper configure --target claude --model anthropic/claude-sonnet-4 --write
+```
+
+## Commands
+
+| Command | Description |
+|--------|-------------|
+| `npx @rerouter/helper` | Interactive wizard |
+| `npx @rerouter/helper models [--search X]` | List models from catalog (auth required) |
+| `npx @rerouter/helper configure --target T --model ID [--small-model ID] [--port N] [--write [--yes]]` | Configure a target |
+| `npx @rerouter/helper check-key` | Key info without inference/billing |
+| `npx @rerouter/helper targets` | List configuration targets |
+| `npx @rerouter/helper bridge [--port N] [--host H]` | Local Responses API bridge (Codex) → Rerouter |
+
+## Supported targets
+
+| Target | Type | What it does |
+|--------|------|-------------|
+| `claude` | Automatic | Merges `~/.claude/settings.json` with env vars |
+| `codex` | Automatic | Writes `~/.codex/config.toml` for local bridge |
+| `opencode` | Automatic | Merges `~/.config/opencode/opencode.json` |
+| `omp` | Automatic | Writes `~/.omp/agent/models.yml` |
+| `continue` | Automatic | Writes `~/.continue/config.yaml` + `.env` placeholder |
+| `openai` | Snippet | Prints shell env exports |
+| `anthropic` | Snippet | Prints shell env exports |
+| `cursor` | Guide | Step-by-step UI instructions |
+| `vscode` | Guide | Step-by-step UI instructions |
+| `cline` | Guide | Step-by-step UI instructions |
+| `roo` | Guide | Step-by-step UI instructions |
+
+## Codex (Responses API bridge)
+
+Codex CLI speaks the Responses API (`POST /v1/responses`). Rerouter speaks Chat Completions. Run the local bridge to translate:
+
+```bash
+# Terminal 1: start bridge
+npx @rerouter/helper bridge
+
+# Terminal 2: configure Codex
+npx @rerouter/helper configure --target codex --model your-model --write
+```
+
+The bridge runs on `127.0.0.1:8787` by default. Codex reads `env_key` from `REROUTER_API_KEY`.
+
+## Safety
+
+- **Preview first.** Without `--write`, every command is read-only.
+- **Timestamp backup.** Any existing config is backed up before writing.
+- **Key never written.** Your API key is only read from `REROUTER_API_KEY` env — never printed, never written to any file.
+- **Ambiguous configs → manual merge.** If a config file is broken or ambiguous, the helper stops and shows you what to add manually.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `REROUTER_API_KEY` | Your Rerouter API key (`sk-rr-...`). Required for `models`, `configure`, `check-key`. |
+| `REROUTER_BASE_URL` | Override base URL (default: `https://api.rerouter.id`). |
+
+## Examples
+
+```bash
+# List all models
+npx @rerouter/helper models
+
+# Search for Claude models
+npx @rerouter/helper models --search claude
+
+# Configure Claude with a small/fast model for background tasks
+npx @rerouter/helper configure --target claude --model anthropic/claude-sonnet-4 --small-model anthropic/claude-haiku-4 --write
+
+# Preview Cursor setup (no changes)
+npx @rerouter/helper configure --target cursor --model openai/gpt-5
+
+# Get shell exports for any OpenAI-compatible tool
+npx @rerouter/helper configure --target openai --model openai/gpt-5
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@rerouter/helper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Connect coding agents (Claude, Codex, Cursor, opencode, Continue) to Rerouter in seconds",
+  "type": "module",
+  "bin": {
+    "rerouter-helper": "src/cli.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test src/*.test.js"
+  },
+  "dependencies": {
+    "yaml": "^2.6.1"
+  },
+  "license": "MIT",
+  "keywords": [
+    "rerouter",
+    "llm",
+    "gateway",
+    "claude",
+    "codex",
+    "cursor",
+    "opencode",
+    "continue",
+    "ai",
+    "coding-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import readline from "node:readline/promises";
+import { keyInfo, listModels } from "./lib/api.js";
+import { DEFAULT_BRIDGE_PORT, startBridge } from "./lib/bridge-server.js";
+import { MissingKeyError, apiKey, baseUrl } from "./lib/env.js";
+import {
+  ALL_TARGETS,
+  AUTOMATIC_TARGETS,
+  GUIDE_TARGETS,
+  SNIPPET_TARGETS,
+  applyPlan,
+  guide,
+  pickSmallModel,
+  planTarget,
+  snippet,
+} from "./lib/targets.js";
+
+const VERSION = "0.1.0";
+
+const HELP = `Rerouter helper — connect coding agents to Rerouter.
+
+Usage:
+  npx @rerouter/helper                       Interactive wizard
+  npx @rerouter/helper models [--search X]   List models from catalog (auth)
+  npx @rerouter/helper configure --target T --model ID [--small-model ID] [--port N] [--write [--yes]]
+  npx @rerouter/helper check-key             Key info without inference/billing
+  npx @rerouter/helper targets               List configuration targets
+  npx @rerouter/helper bridge [--port N] [--host H]
+                                             Local Responses API bridge (Codex) → Rerouter
+  npx @rerouter/helper --version | --help
+
+Automatic targets (config file merge):  ${AUTOMATIC_TARGETS.join(", ")}
+Shell snippet targets:                  ${SNIPPET_TARGETS.join(", ")}
+UI guide targets:                       ${GUIDE_TARGETS.join(", ")}
+
+Env:
+  REROUTER_API_KEY    Rerouter key (sk-rr-...). Never printed or written to any file.
+  REROUTER_BASE_URL   Override base URL (default: https://api.rerouter.id).
+`;
+
+function fail(err) {
+  console.error(`error: ${err.message}`);
+  process.exitCode = 1;
+}
+
+async function cmdModels(values) {
+  const models = await listModels();
+  const needle = values.search?.toLowerCase();
+  const rows = models
+    .map((m) => String(m?.id ?? ""))
+    .filter(Boolean)
+    .filter((id) => !needle || id.toLowerCase().includes(needle))
+    .sort();
+  if (!rows.length) {
+    console.log(needle ? `No models match "${values.search}".` : "Catalog is empty.");
+    return;
+  }
+  for (const id of rows) console.log(id);
+  console.log(`\n${rows.length} models.`);
+}
+
+async function cmdCheckKey() {
+  const info = await keyInfo();
+  const lines = [
+    `key:        ${info.prefix ?? "????"}…`,
+    `status:     ${info.status ?? "unknown"}`,
+  ];
+  if (info.name) lines.push(`name:       ${info.name}`);
+  if (info.expires_at) lines.push(`expires:    ${info.expires_at}`);
+  if (Array.isArray(info.model_scope) && info.model_scope.length) {
+    lines.push(`model scope: ${info.model_scope.join(", ")}`);
+  } else {
+    lines.push("model scope: (all models)");
+  }
+  if (typeof info.has_balance === "boolean") lines.push(`balance:     ${info.has_balance ? "ok" : "empty"}`);
+  if (info.rate_limits) lines.push(`rate limit: ${JSON.stringify(info.rate_limits)}`);
+  console.log(lines.join("\n"));
+}
+
+function cmdTargets() {
+  console.log("Automatic targets (helper merges config file + backup):");
+  for (const t of AUTOMATIC_TARGETS) console.log(`  ${t}`);
+  console.log("\nShell snippet targets (printed, no files changed):");
+  for (const t of SNIPPET_TARGETS) console.log(`  ${t}`);
+  console.log("\nUI guide targets (manual steps in IDE):");
+  for (const t of GUIDE_TARGETS) console.log(`  ${t}`);
+}
+
+async function confirm(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} [y/N] `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+async function cmdConfigure(values) {
+  const target = values.target;
+  if (!target || !ALL_TARGETS.includes(target)) {
+    throw new Error(`--target is required and must be one of: ${ALL_TARGETS.join(", ")}`);
+  }
+  const opts = { baseUrl: baseUrl(), model: values.model, smallModel: values["small-model"], port: parsePort(values.port) };
+
+  if (GUIDE_TARGETS.includes(target)) {
+    console.log(guide(target, opts));
+    return;
+  }
+  if (SNIPPET_TARGETS.includes(target)) {
+    console.log(snippet(target, opts));
+    return;
+  }
+
+  // Automatic target: fill small-model from catalog if key available.
+  if (target === "claude" && !opts.smallModel && apiKey()) {
+    try {
+      opts.smallModel = pickSmallModel(await listModels(), opts.model);
+    } catch {
+      /* catalog failed → fallback to main model */
+    }
+  }
+  const plan = planTarget(target, opts);
+  const content = await plan.build();
+
+  console.log(`# ${plan.description}`);
+  console.log(`# file: ${plan.file}\n`);
+  console.log(content);
+  for (const note of plan.notes ?? []) console.log(`# ${note}`);
+
+  if (!values.write) {
+    console.log("\nPreview only. Add --write to write (with automatic backup).");
+    return;
+  }
+  if (!values.yes) {
+    const ok = await confirm(`Write changes to ${plan.file}?`);
+    if (!ok) {
+      console.log("Cancelled — no files changed.");
+      return;
+    }
+  }
+  const results = await applyPlan(plan, content);
+  for (const r of results) {
+    console.log(`\nwritten: ${r.file}`);
+    if (r.backupPath) console.log(`backup:  ${r.backupPath}`);
+  }
+}
+
+function parsePort(value) {
+  if (value == null) return undefined;
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`--port invalid: "${value}" (must be an integer 1-65535)`);
+  }
+  return port;
+}
+
+async function cmdBridge(values) {
+  const port = parsePort(values.port) ?? DEFAULT_BRIDGE_PORT;
+  const host = values.host?.trim() || "127.0.0.1";
+  if (host !== "127.0.0.1" && host !== "localhost" && host !== "::1") {
+    throw new Error(`--host "${host}" rejected — bridge must be loopback only (127.0.0.1).`);
+  }
+  const key = apiKey();
+  const bridge = await startBridge({ host, port, baseUrl: baseUrl(), apiKey: key });
+
+  console.log(`Responses API bridge active: ${bridge.url}`);
+  console.log(`Upstream gateway:            ${baseUrl()}`);
+  if (!key) {
+    console.log("\nNote: REROUTER_API_KEY not set — clients must send their own Authorization.");
+  }
+  console.log("\nConnect Codex (one-time):");
+  console.log(`  npx @rerouter/helper configure --target codex --model <ID>${port !== DEFAULT_BRIDGE_PORT ? ` --port ${port}` : ""} --write`);
+  console.log("\nPress Ctrl+C to stop.");
+
+  await new Promise((resolve) => {
+    const stop = () => {
+      void bridge.close().then(resolve, resolve);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}
+
+async function wizard() {
+  console.log(`Rerouter helper v${VERSION} — base URL: ${baseUrl()}`);
+  if (!apiKey()) {
+    console.log("\nNote: REROUTER_API_KEY not set (model listing disabled).\n");
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log("\nSelect target:");
+    ALL_TARGETS.forEach((t, i) => console.log(`  ${i + 1}. ${t}`));
+    const pick = await rl.question(`\nTarget [1-${ALL_TARGETS.length}]: `);
+    const target = ALL_TARGETS[Number(pick.trim()) - 1];
+    if (!target) throw new Error("invalid selection");
+
+    let model;
+    if (apiKey()) {
+      try {
+        const models = (await listModels()).map((m) => String(m?.id ?? "")).filter(Boolean);
+        if (models.length) {
+          console.log(`\nAvailable models (first 10): ${models.slice(0, 10).join(", ")}${models.length > 10 ? ` … (+${models.length - 10})` : ""}`);
+        }
+      } catch {
+        /* ignore — manual input */
+      }
+    }
+    model = (await rl.question("Model ID: ")).trim();
+    if (!model) throw new Error("model is required");
+
+    const values = { target, model, write: true, yes: false };
+    rl.close();
+    await cmdConfigure(values);
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      search: { type: "string" },
+      target: { type: "string" },
+      model: { type: "string" },
+      "small-model": { type: "string" },
+      port: { type: "string" },
+      host: { type: "string" },
+      write: { type: "boolean", default: false },
+      yes: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+    },
+  });
+
+  const command = positionals[0];
+  if (values.help) return console.log(HELP);
+  if (values.version) return console.log(VERSION);
+
+  switch (command) {
+    case undefined:
+      return wizard();
+    case "models":
+      return cmdModels(values);
+    case "configure":
+      return cmdConfigure(values);
+    case "check-key":
+      return cmdCheckKey();
+    case "targets":
+      return cmdTargets();
+    case "bridge":
+      return cmdBridge(values);
+    default:
+      throw new Error(`unknown command: "${command}". Run with --help.`);
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof MissingKeyError) {
+    fail(err);
+    return;
+  }
+  fail(err);
+});

package/src/lib/api.js

@@ -0,0 +1,35 @@
+import { baseUrl, requireApiKey } from "./env.js";
+
+async function fetchJson(path, { timeoutMs = 15_000 } = {}) {
+  const key = requireApiKey();
+  const res = await fetch(`${baseUrl()}${path}`, {
+    headers: { authorization: `Bearer ${key}`, accept: "application/json" },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    /* leave null — handled below */
+  }
+  if (!res.ok) {
+    const message =
+      (body && typeof body.error === "string" && body.error) ||
+      body?.error?.message ||
+      `HTTP ${res.status}`;
+    throw new Error(`${path} failed: ${message}`);
+  }
+  return body;
+}
+
+/** GET /v1/models — catalog remains auth (decision #1). */
+export async function listModels() {
+  const body = await fetchJson("/v1/models");
+  return Array.isArray(body?.data) ? body.data : [];
+}
+
+/** GET /v1/key/info — zero-inference, no billing. */
+export async function keyInfo() {
+  return fetchJson("/v1/key/info");
+}

package/src/lib/bridge-server.js

@@ -0,0 +1,217 @@
+import http from "node:http";
+import {
+  ResponsesBridgeError,
+  chatJsonToResponse,
+  responsesToChatRequest,
+  wrapResponsesStream,
+} from "./responses-bridge.js";
+
+/**
+ * Local Responses API → Chat Completions bridge.
+ *
+ * Codex CLI only speaks the Responses API (`POST /v1/responses`); the
+ * Rerouter gateway speaks Chat Completions. This bridge runs on localhost,
+ * translates both ways, and forwards auth as-is — billing, failover, and
+ * rate limiting stay at the gateway. No state, no local billing.
+ */
+
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+
+export const DEFAULT_BRIDGE_PORT = 8787;
+
+function sendJson(res, status, body, headers = {}) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(payload),
+    ...headers,
+  });
+  res.end(payload);
+}
+
+function sendError(res, status, message, type = "invalid_request_error", code = null) {
+  sendJson(res, status, { error: { type, message, code, param: null } });
+}
+
+async function readBody(req, limit = MAX_BODY_BYTES) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) throw new ResponsesBridgeError(413, "Body too large (>32MB).");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function resolveAuth(req, fallbackKey) {
+  const header = req.headers.authorization;
+  if (typeof header === "string" && header.trim()) return header;
+  if (fallbackKey) return `Bearer ${fallbackKey}`;
+  return null;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.host] default 127.0.0.1 — bridge must NOT be exposed.
+ * @param {number} [opts.port]
+ * @param {string} opts.baseUrl gateway base URL (no trailing slash)
+ * @param {string} [opts.apiKey] fallback if the client does not send Authorization
+ * @param {typeof fetch} [opts.fetchImpl] for testing
+ */
+export async function startBridge({ host = "127.0.0.1", port = DEFAULT_BRIDGE_PORT, baseUrl, apiKey, fetchImpl = fetch }) {
+  if (!baseUrl) throw new Error("startBridge: baseUrl is required.");
+  const chatUrl = `${baseUrl}/v1/chat/completions`;
+  const modelsUrl = `${baseUrl}/v1/models`;
+
+  const server = http.createServer((req, res) => {
+    void handle(req, res).catch((err) => {
+      if (res.headersSent) {
+        res.end();
+        return;
+      }
+      if (err instanceof ResponsesBridgeError) {
+        sendError(res, err.status, err.message, err.type);
+      } else {
+        sendError(res, 500, `bridge internal error: ${err?.message ?? err}`, "server_error");
+      }
+    });
+  });
+
+  async function handle(req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+
+    if (req.method === "GET" && (path === "/health" || path === "/")) {
+      sendJson(res, 200, { ok: true, bridge: "rerouter-responses", upstream: baseUrl });
+      return;
+    }
+
+    if (req.method === "GET" && path === "/v1/models") {
+      const auth = resolveAuth(req, apiKey);
+      if (!auth) {
+        sendError(res, 401, "Missing bearer token (set REROUTER_API_KEY or Authorization header).", "authentication_error");
+        return;
+      }
+      const upstream = await fetchImpl(modelsUrl, { headers: { authorization: auth } });
+      const text = await upstream.text();
+      res.writeHead(upstream.status, { "content-type": upstream.headers.get("content-type") ?? "application/json" });
+      res.end(text);
+      return;
+    }
+
+    if (req.method === "POST" && (path === "/v1/responses" || path === "/responses")) {
+      await handleResponses(req, res);
+      return;
+    }
+
+    sendError(res, 404, `Unknown endpoint: ${req.method} ${path}`);
+  }
+
+  async function handleResponses(req, res) {
+    const auth = resolveAuth(req, apiKey);
+    if (!auth) {
+      sendError(res, 401, "Missing bearer token (set REROUTER_API_KEY or Authorization header).", "authentication_error");
+      return;
+    }
+
+    let body;
+    try {
+      body = JSON.parse(await readBody(req));
+    } catch (err) {
+      if (err instanceof ResponsesBridgeError) throw err;
+      throw new ResponsesBridgeError(400, "Body is not valid JSON.");
+    }
+
+    const { request, customToolNames } = responsesToChatRequest(body);
+    const wantsStream = request.stream === true;
+
+    let upstream;
+    try {
+      upstream = await fetchImpl(chatUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: wantsStream ? "text/event-stream" : "application/json",
+          authorization: auth,
+        },
+        body: JSON.stringify(request),
+      });
+    } catch (err) {
+      sendError(res, 502, `Gateway unreachable: ${err?.message ?? err}`, "api_error", "upstream_unreachable");
+      return;
+    }
+
+    if (!upstream.ok) {
+      // Forward the gateway error message (billing/rate-limit/etc.) as clearly as possible.
+      const text = await upstream.text();
+      let message = text.slice(0, 500);
+      try {
+        const parsed = JSON.parse(text);
+        message = parsed?.error?.message ?? (typeof parsed?.error === "string" ? parsed.error : null) ?? parsed?.message ?? message;
+      } catch {
+        /* body is not JSON */
+      }
+      sendError(res, upstream.status, `Upstream ${upstream.status}: ${message}`, "api_error", "upstream_error");
+      return;
+    }
+
+    if (!wantsStream) {
+      let chat;
+      try {
+        chat = await upstream.json();
+      } catch {
+        sendError(res, 502, "Gateway response is not valid JSON.", "api_error", "invalid_upstream_response");
+        return;
+      }
+      sendJson(res, 200, chatJsonToResponse(chat, { requestedModel: request.model, customToolNames }));
+      return;
+    }
+
+    if (!upstream.body) {
+      sendError(res, 502, "Gateway stream response has no body.", "api_error", "invalid_upstream_response");
+      return;
+    }
+
+    res.writeHead(200, {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "x-accel-buffering": "no",
+    });
+
+    const stream = wrapResponsesStream(upstream.body, { requestedModel: request.model, customToolNames });
+    const reader = stream.getReader();
+    let closed = false;
+    req.on("close", () => {
+      closed = true;
+      void reader.cancel().catch(() => {});
+    });
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done || closed) break;
+        if (!res.write(value)) {
+          await new Promise((resolve) => res.once("drain", resolve));
+        }
+      }
+    } finally {
+      res.end();
+    }
+  }
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  const boundPort = typeof address === "object" && address ? address.port : port;
+
+  return {
+    server,
+    host,
+    port: boundPort,
+    url: `http://${host}:${boundPort}/v1`,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  };
+}