Initial release: ReRouted 0.3.1

Author: gitcommit90

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+capture-out/
+*.log
+.DS_Store
+config.json
+.scratch/

AGENTS.md

@@ -0,0 +1,29 @@
+# ReRouted repository instructions
+
+## Non-negotiable definition of done
+
+Never describe a fix, feature, refactor, UI pass, documentation update, or other iteration as "done" until every item below is true:
+
+1. The relevant automated tests pass.
+2. The package version is bumped so the shipped app has a unique identity.
+3. The change is committed on a branch and pushed to `origin`.
+4. The branch is merged into `main` and the merged `main` is pushed.
+5. The Apple Silicon DMG is rebuilt from that exact merged `main` commit.
+6. The newest DMG is transferred to and installed on the host named `macair`.
+7. `/Applications/ReRouted.app` is launched on `macair` and its installed version is verified.
+8. The final report records the version, merged commit, DMG filename, DMG SHA-256, and MacBook Air verification.
+
+If any item is missing, say exactly what remains. Do not use "done" as shorthand for code-complete, tests-passing, committed, or pushed.
+
+Follow [docs/release-checklist.md](docs/release-checklist.md) for commands and ordering.
+
+## Repository basics
+
+- Target branch: `main`.
+- DMG target: Apple Silicon macOS (`arm64`).
+- Test command: `npm test`.
+- Package command: `npm run package:dmg` on macOS.
+- Preserve user data in `~/Library/Application Support/ReRouted` or the existing lowercase `rerouted` directory during app replacement.
+- Do not claim broad OpenAI API compatibility beyond the routes implemented in `src/lib/gateway.js`.
+- Same-provider OAuth accounts use automatic fill-first fallback. Explicit combos still control
+  cross-provider/model fallback and round-robin behavior.

README.md

@@ -0,0 +1,195 @@
+<div align="center">
+  <img src="./resources/brandMark@2x.png" width="64" height="64" alt="ReRouted logo" />
+  <h1>ReRouted</h1>
+  <p><strong>Stop rewiring your AI tools every time an account hits quota.</strong></p>
+  <p>
+    A macOS menu-bar router that puts your connected accounts, models,
+    API keys, and fallback routes behind one local chat-completions endpoint.
+  </p>
+  <p>
+    <a href="https://rerouted.dev">Website</a> |
+    <a href="https://github.com/gitcommit90/rerouted/releases/latest">Download</a> |
+    <a href="#quick-start">Quick start</a> |
+    <a href="./docs/architecture.md">Architecture</a>
+  </p>
+  <p>
+    <a href="https://github.com/gitcommit90/rerouted/releases/latest"><img alt="GitHub release" src="https://img.shields.io/github/v/release/gitcommit90/rerouted?color=ef5b2a&label=release" /></a>
+    <img alt="macOS Apple Silicon" src="https://img.shields.io/badge/macOS-Apple%20Silicon-1b1d18?logo=apple&logoColor=white" />
+    <img alt="Local first" src="https://img.shields.io/badge/gateway-local--first-247454" />
+  </p>
+</div>
+
+<p align="center">
+  <img src="./docs/images/status.png" width="400" alt="ReRouted status panel" />
+  <img src="./docs/images/route-editor.png" width="400" alt="ReRouted route editor" />
+</p>
+
+## One URL. The routing decision lives somewhere sane.
+
+Your editor should not need to know which account still has quota, which provider is having a bad morning, or which model you want to try next.
+
+ReRouted gives compatible chat-completions clients the same local contract:
+
+```text
+Base URL   http://127.0.0.1:4949/v1
+API key    rr-your-generated-key
+Model      coding
+```
+
+`coding` is a route you own. Put your preferred model first, another account second, and a backup provider third. When an upstream rate-limits, times out, or returns a retryable failure before output begins, ReRouted advances through the route without changing the URL or model name your client uses.
+
+The promise is deliberately focused: ReRouted exposes model discovery and OpenAI-style chat completions. It is a routing layer, not a clone of every OpenAI API.
+
+## Why ReRouted exists
+
+| Without ReRouted | With ReRouted |
+| --- | --- |
+| Provider URLs and credentials are repeated across tools | One localhost URL and one generated gateway key |
+| A model name hard-codes a provider or account | A named route describes intent: `coding`, `fast`, `review` |
+| Quota means stopping to edit settings | The next route member is attempted automatically |
+| Multiple OAuth accounts are managed by hand | OAuth accounts share a provider pool and fall through in order |
+| Requests and failures are scattered | Activity, quota, token counts, and logs live in the menu bar |
+
+No hosted control plane. No account with ReRouted. No Dock icon. The gateway and panel run together on your Mac.
+
+## How it works
+
+```text
+ editor / agent / script
+          |
+          | POST /v1/chat/completions
+          | model: "coding"
+          v
+  127.0.0.1:4949/v1
+          |
+          v
+     ReRouted route
+       1. primary model
+       2. second account
+       3. backup provider
+          |
+          v
+ normalized OpenAI-style response
+```
+
+Routes support two strategies:
+
+- **Fallback:** try members in the order you chose.
+- **Round robin:** rotate the starting member on each request, then retain fallback through the rest.
+
+Timeouts and retryable `408`, `429`, and `5xx` responses can advance the route. Streaming failures are inspected before output begins; once client-visible output has started, ReRouted does not replay the request behind the client's back.
+
+## What connects
+
+- **OAuth accounts:** ChatGPT, Claude, Antigravity, and xAI.
+- **API-key presets:** OpenRouter, NVIDIA NIM, Cloudflare, and GLM Coding.
+- **Custom upstreams:** any service that exposes the OpenAI chat-completions shape ReRouted expects.
+- **Local credential discovery:** supported credentials already stored in known files or the macOS Keychain can be imported instead of re-entered.
+- **Multiple accounts:** connect more than one account for the same provider and use shared or account-specific model routes.
+
+OAuth accounts and keyed providers can live in the same route. ReRouted handles request translation and normalizes supported upstream responses back into the shape your client expects.
+
+ReRouted is an independent project and is not affiliated with or endorsed by any upstream provider.
+
+## Quick start
+
+### 1. Install
+
+[Download ReRouted 0.3.1 for Apple Silicon](https://github.com/gitcommit90/rerouted/releases/download/v0.3.1/ReRouted-0.3.1-arm64.dmg), open the DMG, and drag ReRouted to Applications.
+
+The macOS release is Developer ID signed, notarized by Apple, and stapled for a normal Gatekeeper launch.
+
+After the first install, ReRouted checks stable releases in the background. You can also use **Settings → Software updates** at any time; new versions download inside the app and install on restart.
+
+### 2. Connect what you already use
+
+Import a detected credential, complete an OAuth flow, or add an API key. ReRouted keeps OAuth accounts and keyed providers side by side.
+
+### 3. Create a route
+
+Name it for the job rather than the vendor:
+
+```text
+coding
+  1. preferred account and model
+  2. second account
+  3. backup provider
+```
+
+### 4. Test the route, then point your client at localhost
+
+Use a direct request to verify the gateway and route:
+
+```bash
+curl http://127.0.0.1:4949/v1/chat/completions \
+  -H "Authorization: Bearer rr-your-generated-key" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"coding","messages":[{"role":"user","content":"Say hello in three words."}]}'
+```
+
+Then enter the same base URL, gateway key, and route name in a configurable client that supports OpenAI-style chat completions. Setting names vary by client. Switch providers, accounts, models, and route order inside ReRouted; leave the client configuration alone.
+
+## The menu-bar control plane
+
+- **Status:** gateway health, endpoint, latest route, and recent traffic.
+- **Accounts:** OAuth sessions, imported credentials, API keys, and model availability.
+- **Routes:** named fallback or round-robin model groups with explicit ordering controls.
+- **Activity:** requests, failures, token counts, route choices, and account usage.
+- **Quota:** provider-specific subscription windows where supported.
+- **Settings:** gateway keys, localhost or network binding, login launch, security controls, and signed software updates.
+
+The gateway continues running when the panel is hidden. Quitting ReRouted stops both.
+
+## API surface
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /` | Same unauthenticated local health response as `/health` |
+| `GET /health` | Local gateway health and listening port |
+| `GET /v1/models` | Enabled direct models and named routes |
+| `POST /v1/chat/completions` | Streaming or non-streaming routed completions |
+
+Requests require a generated bearer key except for `/` and `/health`. ReRouted currently targets clients that use OpenAI-style chat completions; embeddings, images, audio, and the rest of the OpenAI platform API are outside its scope.
+
+## Local-first, with the boundaries stated plainly
+
+- The gateway binds to `127.0.0.1` by default.
+- Configuration, credentials, request metadata, usage, and logs are stored locally.
+- Prompt bodies are not intentionally persisted.
+- Local config and usage files are written with restrictive permissions where supported.
+- Provider credentials are not encrypted at rest.
+- Requests and the credentials needed to authorize them are sent to the upstream services you choose.
+- Enabling network access binds the gateway to `0.0.0.0`; only do that on a network you trust.
+
+## Build from source
+
+Requires Node.js 22.12 or newer. Packaging requires macOS and produces an Apple Silicon DMG.
+
+```bash
+git clone https://github.com/gitcommit90/rerouted.git
+cd rerouted
+npm ci
+npm test
+npm start
+```
+
+Package the macOS app and DMG:
+
+```bash
+npm run package:dmg
+```
+
+The implementation is intentionally small: Electron, Node's built-in HTTP server, and a vanilla HTML/CSS/JavaScript renderer. See [the architecture document](./docs/architecture.md) for the runtime, routing, persistence, and packaging details.
+
+Questions and bug reports are welcome in [GitHub Issues](https://github.com/gitcommit90/rerouted/issues).
+
+## Current release
+
+ReRouted `0.3.1` ships for Apple Silicon macOS with a Developer ID signature, stapled Apple notarization tickets, and in-app updates backed by stable GitHub Releases. The public API is intentionally limited to health, model discovery, and chat completions; a published third-party client compatibility matrix is still forthcoming.
+
+ReRouted is released by [Public Bytes](https://publicbytes.org), a nonprofit building practical technology for public good.
+
+## Thanks
+
+- Thanks to [9Router](https://github.com/decolua/9router) and its contributors for pushing local multi-provider routing forward.
+- Thanks to [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) and its contributors for advancing local provider connectivity and the ecosystem around it.

docs/architecture.md

@@ -0,0 +1,152 @@
+# ReRouted architecture
+
+This document describes the implementation in this repository today. It is the code map for maintainers, not a future-product proposal.
+
+## Runtime shape
+
+ReRouted is one Electron process with three jobs:
+
+1. Own the macOS menu-bar icon and panel window.
+2. Run the local HTTP gateway.
+3. Persist provider, route, usage, and diagnostic state.
+
+There is no separate daemon. Closing or hiding the panel does not stop the gateway; quitting ReRouted does.
+
+```text
+OpenAI-compatible client
+        |
+        | Bearer rr-... + /v1/chat/completions
+        v
+src/lib/gateway.js
+        |
+        | resolve model/combo
+        v
+src/lib/router.js
+        |
+        | select provider + translate request
+        v
+src/lib/providers/*  --->  upstream provider API
+        |
+        | normalize response/SSE
+        v
+OpenAI-compatible response
+```
+
+## Main process and panel
+
+`src/main.js` owns the single-instance lock, tray, frameless panel window, login-item preference, IPC handlers, store, usage store, router, and gateway lifecycle.
+
+The panel is a local file loaded from `src/renderer/index.html`. `src/preload.js` exposes an IPC bridge to `src/renderer/app.js`; context isolation is enabled and renderer Node integration is disabled. The BrowserWindow sandbox is currently disabled.
+
+The renderer is vanilla HTML, CSS, and JavaScript. It renders onboarding and the Status, Accounts, Routes, Activity, and Settings pages from state returned by the main process.
+
+## Gateway contract
+
+`src/lib/gateway.js` uses Node's built-in HTTP server.
+
+| Route | Auth | Behavior |
+| --- | --- | --- |
+| `GET /` | None | Same process health response as `/health` |
+| `GET /health` | None | App name and current listening port |
+| `GET /v1/models` | Bearer key | Enabled provider models plus named route IDs |
+| `POST /v1/chat/completions` | Bearer key | Streaming or non-streaming routed completion |
+
+The default bind is `127.0.0.1:4949`. Settings can switch the host to `0.0.0.0` for LAN or Tailscale access. CORS is currently `*`, so the bearer key is the gateway's access boundary when network binding is enabled.
+
+## Model IDs and routes
+
+Provider model IDs are generated by `src/lib/providers/index.js`. A direct model resolves to one enabled provider/model pair.
+
+A route is a persisted virtual model with members shaped like:
+
+```json
+{
+  "providerId": "prov_...",
+  "model": "upstream-model-id"
+}
+```
+
+The router supports:
+
+- `fallback`: members are attempted in their configured order.
+- `round-robin`: each request rotates the starting member, then retains fallback behavior through the remaining members.
+
+Timeouts, `408`, `429`, and `5xx` responses are retryable. The per-member timeout defaults to 60 seconds. A route stops when a member returns a non-retryable failure; a single direct model stops after its only member.
+
+OAuth providers add an account-pool layer beneath model routing. Accounts receive the lowest available alias (`oauth1`, `oauth2`, ...), and both shared ids (`chatgpt/gpt-5.4`) and account-specific ids (`chatgpt/oauth2/gpt-5.4`) can continue through sibling accounts. Quota failures create an account-wide lock using provider reset hints when available; authentication and transient failures use shorter model-scoped cooldowns. Early streaming quota events are inspected before the client stream starts so fallback can still occur. Selection, failure, fallback, locked-account skips, and terminal exhaustion are written as structured logs.
+
+## Provider adapters
+
+`src/lib/providers/index.js` selects an adapter by provider type.
+
+- `openai-compat.js` handles OpenAI-shaped keyed services.
+- `chatgpt.js` translates chat-completion requests to the ChatGPT Codex Responses surface and normalizes Responses SSE.
+- `claude.js` translates OpenAI messages and tools to Anthropic Messages, applies the current OAuth client contract, and converts JSON/SSE back to OpenAI shapes.
+- `antigravity.js` translates Gemini-style upstream requests and SSE.
+- `xai.js` uses an OpenAI-compatible chat surface with xAI OAuth credentials.
+
+OAuth access-token refreshes are persisted back to the provider record when an adapter returns updated tokens.
+
+## OAuth and credential discovery
+
+`src/lib/oauth.js` implements PKCE browser flows and loopback callbacks. Some providers require the user to paste a callback URL or code into the panel.
+
+`src/lib/detect.js` performs read-only discovery of supported provider credentials already stored in known local files or the macOS Keychain.
+
+Selected credentials are copied into ReRouted's config. ReRouted does not continue reading the original source on each request.
+
+## Persistence
+
+Electron's `userData` directory contains:
+
+| File | Contents |
+| --- | --- |
+| `config.json` | Providers, credentials, models, routes, gateway keys, bind settings, onboarding state, admin password hash |
+| `usage.json` | Up to 20,000 recent request metadata rows and token counts |
+| `rerouted.log` | Gateway, OAuth, and operational diagnostics |
+
+The Quota page probes subscription windows directly for ChatGPT/Codex, Claude, and Antigravity. Probe failures remain isolated per account and do not disable chat routing.
+
+Config and usage writes use a temporary file followed by rename. The files are written with mode `0600`; parent directories are created with mode `0700` where supported.
+
+The admin password is scrypt-hashed. Provider credentials and gateway keys are not encrypted at rest.
+
+## Packaging
+
+`scripts/package-mac-dmg.js` must run on macOS. It:
+
+1. Packages Electron for `darwin/arm64`.
+2. Adds the tray resources and menu-bar-only bundle settings.
+3. Applies hardened-runtime Electron signing with a Developer ID identity when available.
+4. For release builds, notarizes and staples the app.
+5. For release builds, creates an updater ZIP from the stapled app and verifies the extracted bundle.
+6. Creates and signs a compressed UDZO DMG with an Applications shortcut.
+7. For release builds, notarizes and staples the DMG.
+
+The output name is derived from `package.json`:
+
+```text
+dist/ReRouted-<version>-arm64.dmg
+dist/ReRouted-<version>-mac-arm64.zip
+```
+
+Official release builds require `REROUTED_NOTARY_PROFILE` and fail if Developer ID signing or notarization is unavailable. See [signing.md](signing.md).
+
+Packaged builds use Electron's native macOS updater and the public stable GitHub Release feed. Checks run shortly after launch and every six hours, with a manual control in Settings. The native updater downloads the post-stapling ZIP, verifies the replacement application through macOS code signing, and installs it on restart. Draft and prerelease GitHub releases are not update channels.
+
+## Tests and current gaps
+
+`tests/gateway.test.js` covers password hashing, config persistence, bearer auth, model listing, streaming and non-streaming completion paths, fallback, round-robin ordering, timeouts, OAuth request behavior, token refresh, format translation, SSE decoding, multiple gateway keys, disabled models, and usage aggregation.
+
+Important gaps to keep visible:
+
+- No automated renderer or end-to-end Electron tests.
+- No macOS packaging test in CI.
+- No request-body size limit or gateway rate limit.
+- No automated release publication or CI-hosted signing/notarization.
+- No commit SHA embedded in the app bundle.
+- No compatibility matrix for third-party OpenAI clients.
+
+## Maintenance rules
+
+Read [docs/release-checklist.md](release-checklist.md) before changing the app. A merged commit is only one stage of a ReRouted iteration; the DMG and MacBook Air installation are part of the deliverable.