opencode-anthropic-fix 0.0.16 → 0.0.18

package/.planning/CLI-ENHANCEMENTS.md

@@ -1,221 +0,0 @@
-# CLI Enhancements: Full Account Management
-
-**Status:** Complete
-**Created:** 2026-02-09
-**Completed:** 2026-02-09
-
----
-
-## Problem Statement
-
-The plugin CLI (`opencode-anthropic-auth`) can **manage** existing accounts (enable, disable, remove, switch, reset) but cannot **authenticate** new ones or re-authenticate broken ones. The only way to add an account is through `opencode auth login` → selecting "Claude Pro/Max" → browser OAuth flow inside the OpenCode TUI.
-
-This creates friction in several scenarios:
-
-1. **Disabled account recovery** — Account #1 was disabled due to a token refresh failure. To fix it, you'd have to `remove` it via CLI, then re-login via `opencode auth login`, which is the exact workflow we want to avoid.
-2. **No re-authentication** — There's no way to get fresh tokens for an existing broken account without deleting and re-adding it.
-3. **No proper logout** — The `remove` command just deletes local data without revoking tokens server-side.
-4. **Incomplete standalone tool** — The CLI should be a self-contained account management tool that doesn't depend on the OpenCode TUI for any operation.
-
-## Solution Overview
-
-Add four new commands to `cli.mjs` that give full account lifecycle management:
-
-| Command        | Alias | Description                                        |
-| -------------- | ----- | -------------------------------------------------- |
-| `login`        | `ln`  | Add a new account via browser OAuth flow           |
-| `logout <N>`   | `lo`  | Revoke tokens + remove a specific account          |
-| `logout --all` | —     | Revoke all tokens + clear all accounts             |
-| `reauth <N>`   | `ra`  | Re-authenticate an account with fresh OAuth tokens |
-| `refresh <N>`  | `rf`  | Attempt token refresh without browser (quick fix)  |
-
-### Architecture Change
-
-Extract the OAuth `authorize()` and `exchange()` functions from `index.mjs` into a new shared module `lib/oauth.mjs`, plus add a new `revoke()` function. Both `index.mjs` (plugin) and `cli.mjs` (standalone) import from this shared module.
-
-```
-lib/oauth.mjs (NEW)
-  ├── authorize(mode)          — Generate PKCE + build auth URL
-  ├── exchange(code, verifier) — Exchange auth code for tokens
-  └── revoke(refreshToken)     — Revoke a refresh token (best-effort)
-```
-
-## Design Decisions
-
-| Decision              | Choice               | Rationale                                                               |
-| --------------------- | -------------------- | ----------------------------------------------------------------------- |
-| Reauth matching       | Replace at index     | Simpler UX; user explicitly chooses which slot to replace               |
-| Logout behavior       | Revoke + remove      | Clean break; user can re-add via `login`                                |
-| Token refresh command | Yes, add `refresh`   | Quick fix for expired access tokens without browser round-trip          |
-| Browser opening       | Auto-open + show URL | Best UX: tries `open`/`xdg-open`/`start`, always prints URL as fallback |
-
-## Detailed Command Specifications
-
-### `login` (alias: `ln`)
-
-**Flow:**
-
-1. Call `authorize("max")` to get PKCE URL + verifier
-2. Auto-open the URL in the user's default browser
-3. Print the URL to terminal as fallback
-4. Prompt user to paste the authorization code (readline)
-5. Call `exchange(code, verifier)` to get tokens
-6. Deduplicate: check if an account with the same refresh token already exists
-7. Add the account to `anthropic-accounts.json`, save, print confirmation
-
-**Edge cases:**
-
-- If exchange fails, print error and exit with code 1
-- If max accounts (10) reached, print error
-- If duplicate refresh token, update existing account instead of adding
-
-### `logout <N>` (alias: `lo <N>`)
-
-**Flow:**
-
-1. Validate index N exists
-2. Attempt `revoke(account.refreshToken)` — best-effort, won't block on failure
-3. Remove the account from array (splice)
-4. Adjust `activeIndex` if needed (same logic as existing `remove` command)
-5. Save + print confirmation
-
-**Flags:**
-
-- `--force` — Skip confirmation prompt (same as `remove`)
-- `--all` — Logout all accounts
-
-### `logout --all`
-
-**Flow:**
-
-1. Iterate all accounts, attempt `revoke()` for each
-2. Write explicit empty storage `{ version: 1, accounts: [], activeIndex: 0 }`
-3. Print confirmation with count of revoked accounts
-
-**Important behavior:** empty storage is treated as authoritative by `AccountManager.load()`, so plugin instances stay logged out and do not re-bootstrap from fallback auth when the accounts file explicitly contains zero accounts.
-
-### `reauth <N>` (alias: `ra <N>`)
-
-**Flow:**
-
-1. Validate index N exists
-2. Run full OAuth flow (same as `login` steps 1-5)
-3. Replace the account at index N with the new tokens
-4. Preserve: `id`, `addedAt`, `stats`
-5. Reset: `enabled=true`, `consecutiveFailures=0`, `lastFailureTime=null`, `rateLimitResetTimes={}`
-6. Save + print confirmation
-
-**Key detail:** Replaces whatever's at index N with whatever the user logs in with, regardless of email matching.
-
-### `refresh <N>` (alias: `rf <N>`)
-
-**Flow:**
-
-1. Validate index N exists
-2. Call the existing `refreshAccessToken(account)` function
-3. If success: update account, re-enable if disabled, save + print new token expiry
-4. If failure: print error and suggest `reauth <N>` instead
-
-## Files Modified
-
-| File                | Change                                                               | Status |
-| ------------------- | -------------------------------------------------------------------- | ------ |
-| `lib/oauth.mjs`     | **NEW** — Extracted `authorize()`, `exchange()`, plus new `revoke()` | Done   |
-| `index.mjs`         | Replace inline OAuth functions with imports from `lib/oauth.mjs`     | Done   |
-| `cli.mjs`           | Add 5 new commands + browser opener utility                          | Done   |
-| `scripts/build.mjs` | No change needed — esbuild follows imports automatically             | N/A    |
-
-## Task List
-
-- [x] **Task 1:** Create `lib/oauth.mjs` — extract `authorize()` and `exchange()` from `index.mjs`, add `revoke()`
-- [x] **Task 2:** Update `index.mjs` — replace inline functions with imports from `lib/oauth.mjs`
-- [x] **Task 3:** Add `openBrowser()` utility to `cli.mjs`
-- [x] **Task 4:** Implement `cmdLogin` in `cli.mjs`
-- [x] **Task 5:** Implement `cmdLogout` and `cmdLogoutAll` in `cli.mjs`
-- [x] **Task 6:** Implement `cmdReauth` in `cli.mjs`
-- [x] **Task 7:** Implement `cmdRefresh` in `cli.mjs`
-- [x] **Task 8:** Wire new commands into `main()` dispatcher and update `cmdHelp()`
-- [x] **Task 9:** Build — passes (esbuild picks up `lib/oauth.mjs` automatically)
-- [x] **Task 10:** Tests — all 349 tests pass across 7 test files, zero failures
-- [x] **Task 11:** Lint — eslint passes cleanly
-- [x] **Task 12:** Live verification — `refresh 1` correctly fails (broken token), `refresh 2` succeeds (7h 59m expiry)
-- [x] **Task 13:** Update this document with completion status
-
-## Token Revocation Notes
-
-Anthropic's OAuth implementation may or may not support RFC 7009 token revocation at `POST /v1/oauth/revoke`. The `revoke()` function is implemented as best-effort:
-
-- Attempts `POST https://console.anthropic.com/v1/oauth/revoke` with `{ token: refreshToken, token_type_hint: "refresh_token", client_id: CLIENT_ID }`
-- Returns `true` if 2xx response, `false` otherwise
-- `logout` proceeds with local cleanup regardless of revocation result
-- No error is surfaced to the user if revocation fails — only a dim note
-
-## Immediate Use Case
-
-To fix the disabled account #1:
-
-```bash
-# Option A: Try a token refresh first (no browser)
-opencode-anthropic-auth refresh 1
-# Tested: correctly fails with "token refresh failed" and suggests reauth
-
-# Option B: If refresh fails, do a full re-auth
-opencode-anthropic-auth reauth 1
-
-# Option C: Full nuke and re-login
-opencode-anthropic-auth logout 1
-opencode-anthropic-auth login
-```
-
-**Verified:** `refresh 2` (healthy account) succeeds and reports "Token refreshed, expires in 7h 59m".
-
-## Updated Help Text (Preview)
-
-```
-Anthropic Multi-Account Auth CLI
-
-Usage:
-  opencode-anthropic-auth [command] [args]
-
-Commands:
-  list              Show all accounts with status (default)
-  status            Compact one-liner for scripts/prompts
-  login             Add a new account via browser OAuth flow
-  logout <N>        Revoke tokens and remove account N
-  logout --all      Revoke all tokens and clear all accounts
-  reauth <N>        Re-authenticate account N with fresh OAuth tokens
-  refresh <N>       Attempt token refresh (no browser needed)
-  switch <N>        Set account N as active
-  enable <N>        Enable a disabled account
-  disable <N>       Disable an account (skipped in rotation)
-  remove <N>        Remove an account permanently
-  reset <N|all>     Clear rate-limit / failure tracking
-  stats             Show per-account usage statistics
-  reset-stats [N|all] Reset usage statistics
-  strategy [name]   Show or change selection strategy
-  config            Show configuration and file paths
-  manage            Interactive account management menu
-  help              Show this help message
-```
-
-## Post-Review Remediations
-
-Following delegated code review, the following fixes were applied:
-
-1. **Logout-all semantics hardened**
-   - `cmdLogoutAll` now writes explicit empty account storage instead of deleting the accounts file.
-   - `AccountManager.load` now treats existing storage (including empty storage) as authoritative, preventing fallback re-bootstrap when users explicitly logout-all.
-
-2. **Windows browser launch fixed**
-   - `openBrowser` now uses `cmd /c start "" <url>` on Windows for correct URL handling.
-
-3. **Reauth state message bug fixed**
-   - `cmdReauth` now captures prior disabled state (`wasDisabled`) before mutation and correctly prints "re-enabled" message when applicable.
-
-4. **Login dedupe ordering corrected**
-   - `cmdLogin` now performs duplicate-token update path before applying max-account rejection, so existing accounts can still be refreshed when at capacity.
-
-5. **Unit test coverage expanded for new auth commands**
-   - Added direct CLI unit tests for `cmdLogin`, `cmdLogout` (single + `--all`), `cmdReauth`, and `cmdRefresh`.
-   - Added main routing tests for new aliases/paths: `ln`, `lo --all --force`, `ra`, and `rf`.
-   - Added help text assertions for new commands/examples.

package/.planning/codebase/ARCHITECTURE.md

@@ -1,201 +0,0 @@
-# Architecture
-
-**Analysis Date:** 2026-02-07
-
-## Pattern Overview
-
-**Overall:** Plugin + CLI dual-entry-point architecture with shared library layer
-
-**Key Characteristics:**
-
-- OpenCode plugin providing OAuth-based multi-account Anthropic authentication
-- Standalone CLI binary for account management (shares storage layer with plugin)
-- Fetch interceptor pattern: the plugin wraps HTTP requests to Anthropic API, injecting OAuth tokens, transforming request/response bodies, and rotating accounts on failures
-- Stateful account management with disk persistence and in-memory health tracking
-- No framework — pure Node.js ESM modules with zero runtime dependencies beyond `@openauthjs/openauth`
-
-## Layers
-
-**Plugin Entry (`index.mjs`):**
-
-- Purpose: OpenCode plugin that intercepts Anthropic API calls with OAuth multi-account support
-- Location: `index.mjs`
-- Contains: OAuth authorize/exchange helpers, request/response transform functions, `AnthropicAuthPlugin` factory, token refresh logic, CLI-style interactive prompts for auth flow
-- Depends on: `lib/accounts.mjs`, `lib/config.mjs`, `lib/storage.mjs`, `lib/backoff.mjs`, `@openauthjs/openauth`
-- Used by: OpenCode runtime (loaded as plugin)
-
-**CLI Entry (`cli.mjs`):**
-
-- Purpose: Standalone CLI for managing accounts outside of the OpenCode TUI
-- Location: `cli.mjs`
-- Contains: All CLI commands (list, switch, enable, disable, remove, reset, stats, strategy, config, manage), formatting/color helpers, usage quota fetching
-- Depends on: `lib/storage.mjs`, `lib/config.mjs`
-- Used by: End users via `opencode-anthropic-auth` binary
-
-**Account Management (`lib/accounts.mjs`):**
-
-- Purpose: In-memory account pool with health scoring, rotation, and disk sync
-- Location: `lib/accounts.mjs`
-- Contains: `AccountManager` class — the core runtime coordinator for account selection, failure tracking, rate limit handling, and usage statistics
-- Depends on: `lib/storage.mjs`, `lib/rotation.mjs`, `lib/backoff.mjs`
-- Used by: `index.mjs`
-
-**Rotation Logic (`lib/rotation.mjs`):**
-
-- Purpose: Account selection algorithms and health/token tracking
-- Location: `lib/rotation.mjs`
-- Contains: `HealthScoreTracker` class, `TokenBucketTracker` class, `selectAccount()` function implementing sticky/round-robin/hybrid strategies
-- Depends on: `lib/config.mjs` (for defaults only)
-- Used by: `lib/accounts.mjs`
-
-**Backoff Logic (`lib/backoff.mjs`):**
-
-- Purpose: Error classification and retry backoff calculation
-- Location: `lib/backoff.mjs`
-- Contains: `isAccountSpecificError()`, `parseRateLimitReason()`, `calculateBackoffMs()`, `parseRetryAfterHeader()`
-- Depends on: Nothing
-- Used by: `index.mjs`, `lib/accounts.mjs`
-
-**Configuration (`lib/config.mjs`):**
-
-- Purpose: Config file loading, validation, and env var overrides
-- Location: `lib/config.mjs`
-- Contains: `loadConfig()`, `saveConfig()`, `DEFAULT_CONFIG`, `CLIENT_ID`, strategy validation, XDG-compliant path resolution
-- Depends on: Node.js builtins only
-- Used by: `index.mjs`, `cli.mjs`, `lib/accounts.mjs`, `lib/rotation.mjs`
-
-**Storage (`lib/storage.mjs`):**
-
-- Purpose: Atomic JSON file persistence for account data
-- Location: `lib/storage.mjs`
-- Contains: `loadAccounts()`, `saveAccounts()`, `clearAccounts()`, account validation/deduplication, `.gitignore` management
-- Depends on: `lib/config.mjs` (for config dir path)
-- Used by: `index.mjs`, `cli.mjs`, `lib/accounts.mjs`
-
-## Data Flow
-
-**API Request (Plugin fetch interceptor):**
-
-1. OpenCode calls `fetch(input, init)` on the plugin's custom fetch
-2. `transformRequestBody()` sanitizes system prompts and prefixes tool names with `mcp_`
-3. `transformRequestUrl()` adds `?beta=true` to `/v1/messages` endpoint
-4. `AccountManager.getCurrentAccount()` selects best account via strategy (sticky/round-robin/hybrid)
-5. If token expired, `refreshAccountTokenSingleFlight()` refreshes OAuth token (single-flight deduplication)
-6. `buildRequestHeaders()` sets Authorization bearer, anthropic-beta headers, removes x-api-key
-7. Actual `fetch()` to Anthropic API executes
-8. On account-specific error (429, 401, 400/403 with account language): mark account, try next account (up to N accounts)
-9. On service-wide error (529, 503, 500): return immediately (switching won't help)
-10. On success: `transformResponse()` wraps the SSE stream to strip `mcp_` prefix from tool names, extract token usage, and detect mid-stream account errors
-
-**Account Selection (per-request):**
-
-1. `AccountManager.syncActiveIndexFromDisk()` reconciles with CLI changes
-2. Build candidate list: enabled accounts, not in per-request exclusion set
-3. `selectAccount()` applies configured strategy:
-   - **sticky**: Stay on current account unless rate-limited/failed
-   - **round-robin**: Rotate cursor through available accounts
-   - **hybrid**: Score accounts by health (weighted ×2) + token bucket (weighted ×5) + freshness, with stickiness bonus (150 points) and switch threshold (100 points)
-4. Consume a token bucket token for the selected account
-5. Return selected `ManagedAccount`
-
-**OAuth Login Flow:**
-
-1. User triggers `opencode auth login` → plugin's `auth.methods[0].authorize()` runs
-2. If existing accounts: prompt menu (add/fresh/manage/cancel)
-3. Generate PKCE challenge via `@openauthjs/openauth`
-4. Build authorize URL for `claude.ai/oauth/authorize`
-5. User pastes authorization code
-6. `exchange()` POSTs to `console.anthropic.com/v1/oauth/token` for tokens
-7. `AccountManager.addAccount()` stores new credentials (deduplicates by refresh token)
-8. `AccountManager.saveToDisk()` persists to `~/.config/opencode/anthropic-accounts.json`
-
-**State Management:**
-
-- **In-memory (plugin process):** `AccountManager` with `HealthScoreTracker` and `TokenBucketTracker` — these are ephemeral, rebuilt on plugin load
-- **On-disk (shared):** `anthropic-accounts.json` stores account credentials, failure tracking, rate limit reset times, usage stats, and active index
-- **Sync mechanism:** Plugin reads `activeIndex` from disk before each request to pick up CLI changes; debounced writes (1s) persist plugin-side changes back
-- **Stats merge-on-save:** To handle concurrent instances, `saveToDisk()` reads disk values and applies in-memory deltas rather than overwriting
-
-## Key Abstractions
-
-**AccountManager (`lib/accounts.mjs`):**
-
-- Purpose: Central coordinator for multi-account state and request routing
-- Pattern: Singleton per plugin instance with private state (`#accounts`, `#healthTracker`, `#tokenTracker`)
-- Static factory: `AccountManager.load(config, authFallback)` bootstraps from disk + OpenCode auth
-- Key methods: `getCurrentAccount()`, `markRateLimited()`, `markSuccess()`, `markFailure()`, `recordUsage()`, `syncActiveIndexFromDisk()`
-
-**HealthScoreTracker (`lib/rotation.mjs`):**
-
-- Purpose: Track per-account health with passive time-based recovery
-- Pattern: In-memory score map with configurable initial/penalty/recovery values
-- Score range: 0–100, min_usable threshold (default 50) gates account selection
-
-**TokenBucketTracker (`lib/rotation.mjs`):**
-
-- Purpose: Rate-limit requests per account using token bucket algorithm
-- Pattern: Per-account bucket with configurable max tokens, regeneration rate
-- Default: 50 tokens, 6/minute regen
-
-**ManagedAccount (typedef in `lib/accounts.mjs`):**
-
-- Purpose: Runtime representation of an Anthropic OAuth account
-- Contains: id, index, email, refreshToken, access, expires, enabled, rateLimitResetTimes, consecutiveFailures, stats
-- Pattern: Mutable in-memory state with periodic disk sync
-
-## Entry Points
-
-**Plugin (`index.mjs` → `AnthropicAuthPlugin`):**
-
-- Location: `index.mjs`
-- Triggers: Loaded by OpenCode plugin system as ESM module
-- Responsibilities: Exports an async plugin factory function returning hooks for `experimental.chat.system.transform`, `auth.loader`, and `auth.methods`
-- Exported as: `export async function AnthropicAuthPlugin({ client })`
-
-**CLI (`cli.mjs` → `main()`):**
-
-- Location: `cli.mjs`
-- Triggers: Executed as `opencode-anthropic-auth [command]` via `~/.local/bin` symlink/copy
-- Responsibilities: Parse argv, route to command handlers, manage accounts via direct storage manipulation
-- Self-detection: Uses `import.meta.url === pathToFileURL(process.argv[1]).href` with symlink resolution
-
-**Build (`scripts/build.mjs`):**
-
-- Location: `scripts/build.mjs`
-- Triggers: `npm run build`
-- Responsibilities: Bundle `index.mjs` → `dist/opencode-anthropic-auth-plugin.js` and `cli.mjs` → `dist/opencode-anthropic-auth-cli.mjs` using esbuild (ESM, node20 target, all deps bundled except node: builtins)
-
-**Install (`scripts/install.mjs`):**
-
-- Location: `scripts/install.mjs`
-- Triggers: `npm run install:link` (dev) or `npm run install:copy` (production)
-- Responsibilities: Symlink or copy plugin to `~/.config/opencode/plugin/` and CLI to `~/.local/bin/`
-
-## Error Handling
-
-**Strategy:** Account-specific vs. service-wide error classification with automatic account rotation
-
-**Patterns:**
-
-- **Account-specific errors** (429, 401, 400/403 with account error body): Mark account with backoff, rotate to next account. Auth failures (401) invalidate cached token.
-- **Service-wide errors** (529, 503, 500): Return immediately to caller — switching accounts won't help.
-- **Token refresh failures**: Transient errors skip account for current request; terminal errors (400, 401, 403, `invalid_grant`) disable the account permanently.
-- **Mid-stream SSE errors**: Detected in response stream transformer. Account marked for next request (not retried mid-stream).
-- **Single-flight token refresh**: Concurrent requests to the same account share one in-flight refresh promise to prevent race conditions.
-- **Backoff calculation** (`lib/backoff.mjs`): Retry-After header takes precedence. Otherwise, reason-based: AUTH_FAILED=5s, RATE_LIMIT_EXCEEDED=30s, QUOTA_EXHAUSTED=escalating [1m, 5m, 30m, 2h].
-
-## Cross-Cutting Concerns
-
-**Logging:** Debug logging via `console.error("[opencode-anthropic-auth]", ...)` gated by `config.debug` flag (env: `OPENCODE_ANTHROPIC_DEBUG=1`). CLI uses direct `console.log` with ANSI color helpers.
-
-**Validation:** Config values are clamped to valid ranges in `lib/config.mjs` (`clampNumber()`). Account data is validated on load with type checks and fallbacks in `lib/storage.mjs` (`validateAccount()`). Duplicate refresh tokens are deduplicated.
-
-**Persistence:** All disk writes use atomic temp-file-and-rename pattern. Account storage uses `randomBytes(6).hex` temp names; config uses PID-based temp names. Files are written with `mode: 0o600` for security.
-
-**Configuration Precedence:** Config file (`~/.config/opencode/anthropic-auth.json`) → environment variable overrides (`OPENCODE_ANTHROPIC_STRATEGY`, `OPENCODE_ANTHROPIC_DEBUG`, `OPENCODE_ANTHROPIC_QUIET`).
-
-**Toast Notifications:** Plugin sends TUI toasts via `client.tui?.showToast()` for account usage, switching, and errors. Toasts are debounced per category and suppressible via quiet mode.
-
----
-
-_Architecture analysis: 2026-02-07_

package/.planning/codebase/CONCERNS.md

@@ -1,219 +0,0 @@
-# Codebase Concerns
-
-**Analysis Date:** 2026-02-07
-
-## Tech Debt
-
-**Duplicated Token Refresh Logic:**
-
-- Issue: Token refresh is implemented three separate times with different error handling
-- Files: `index.mjs` (lines 40-68 `exchange()`, lines 535-591 `refreshAccountToken()`), `cli.mjs` (lines 138-159 `refreshAccessToken()`)
-- Impact: Bug fixes or API changes must be applied in three places. `cli.mjs` version silently swallows errors (returns `null`), while `index.mjs` version throws with detailed error codes. Divergent behavior makes debugging harder.
-- Fix approach: Extract a shared `refreshToken()` function into `lib/auth.mjs` with consistent error handling. Both `index.mjs` and `cli.mjs` should import from the shared module.
-
-**Hardcoded User-Agent String:**
-
-- Issue: `user-agent` header is hardcoded as `"claude-cli/2.1.2 (external, cli)"` with a static version
-- Files: `index.mjs` (line 210)
-- Impact: Version never updates as the actual project version changes (currently `0.0.13` in `package.json`). Server-side analytics will show a stale version. The user-agent also impersonates a different product.
-- Fix approach: Read version from `package.json` or a generated constant at build time. Consider using the actual product name.
-
-**Hardcoded Beta Header Versions:**
-
-- Issue: Required beta header values `"oauth-2025-04-20"` and `"interleaved-thinking-2025-05-14"` are hardcoded inline
-- Files: `index.mjs` (line 205)
-- Impact: When Anthropic updates or removes beta flags, the change must be found inline rather than in a central configuration.
-- Fix approach: Move beta header values to constants in `lib/config.mjs` alongside `CLIENT_ID`.
-
-**Hardcoded OAuth URLs:**
-
-- Issue: URLs like `https://console.anthropic.com/v1/oauth/token`, `https://claude.ai/oauth/authorize`, and `https://api.anthropic.com/api/oauth/claude_cli/create_api_key` are scattered as string literals
-- Files: `index.mjs` (lines 21, 25, 42, 536, 1028), `cli.mjs` (lines 140, 168)
-- Impact: No way to override for testing or staging environments. URLs duplicated across files.
-- Fix approach: Centralize all API URLs as constants in `lib/config.mjs`.
-
-**No TypeScript — JSDoc Only:**
-
-- Issue: The entire codebase uses plain `.mjs` files with JSDoc type annotations instead of TypeScript
-- Files: All source files (`index.mjs`, `cli.mjs`, `lib/*.mjs`)
-- Impact: No compile-time type checking unless an editor provides it. `@ts-ignore` comments (3 instances in `index.mjs` lines 563-567) indicate type system friction. JSDoc types are more verbose and less expressive than TypeScript equivalents.
-- Fix approach: This is a conscious design choice (no build step for plugin, direct ESM). If migrating, use esbuild's existing TS support. Low priority unless type bugs emerge.
-
-**System Prompt Manipulation is Fragile:**
-
-- Issue: System prompt transform uses regex replacement `OpenCode → Claude Code` and `opencode → Claude` with a lookbehind `(?<!\/)` to preserve paths
-- Files: `index.mjs` (lines 233-239)
-- Impact: The regex may not handle all edge cases (e.g., `opencode` in URLs with query strings, or in code blocks). The prefix injection `"You are Claude Code, Anthropic's official CLI for Claude."` is concatenated by string position (`output.system[1]`), which assumes specific system prompt array structure.
-- Fix approach: Consider a more robust approach that doesn't depend on array index positions. Document the assumed system prompt structure.
-
-**`index.mjs` is a 1050-line Monolith:**
-
-- Issue: `index.mjs` contains OAuth helpers, request building, body transformation, SSE parsing, response wrapping, token refresh, the entire retry loop, and the plugin entry point — all in one file
-- Files: `index.mjs` (1050 lines)
-- Impact: Difficult to test individual pieces in isolation (integration test `index.test.mjs` must mock many dependencies). High cognitive load for maintainers.
-- Fix approach: Extract into focused modules: `lib/oauth.mjs` (authorize/exchange), `lib/request.mjs` (header building, body/URL transforms), `lib/sse.mjs` (stream parsing, usage extraction), `lib/retry.mjs` (fetch retry loop). Keep `index.mjs` as thin plugin wiring.
-
-## Known Bugs
-
-**Tool Name Prefix Regex May Match False Positives in SSE Stream:**
-
-- Symptoms: The response stream regex `/"name"\s*:\s*"mcp_([^"]+)"/g` strips `mcp_` from any JSON `"name"` field in the raw text stream, not just tool_use blocks
-- Files: `index.mjs` (line 489)
-- Trigger: An assistant response containing literal text like `"name": "mcp_something"` in a string field (e.g., in a code example within the response) would have `mcp_` incorrectly stripped
-- Workaround: Low probability in practice since the regex requires the exact JSON format. A proper fix would parse SSE events and only transform `tool_use` blocks.
-
-**Storage Version Migration Returns Null:**
-
-- Symptoms: If the storage file has a version other than `1`, `loadAccounts()` returns `null` — silently discarding all accounts
-- Files: `lib/storage.mjs` (lines 193-196)
-- Trigger: Future version migration — the comment says "Future: handle migrations here" but currently just returns null
-- Workaround: None currently needed (only version 1 exists), but this will cause data loss when version 2 is introduced unless migration is implemented first.
-
-## Security Considerations
-
-**Refresh Tokens Stored in Plaintext JSON:**
-
-- Risk: OAuth refresh tokens (long-lived credentials) are stored in `~/.config/opencode/anthropic-accounts.json` as plaintext JSON
-- Files: `lib/storage.mjs` (lines 230-251), `lib/config.mjs` (lines 253-268)
-- Current mitigation: File permissions set to `0o600` (owner-only read/write). `.gitignore` entry added automatically by `ensureGitignore()`. Storage path is in XDG config directory.
-- Recommendations: Consider using OS keychain (macOS Keychain, Linux Secret Service) for refresh tokens. At minimum, document the security model for users. The `0o600` permission is correctly applied.
-
-**Access Tokens Briefly Stored on Disk:**
-
-- Risk: Short-lived access tokens are persisted alongside refresh tokens in the accounts JSON file (via debounced save)
-- Files: `lib/accounts.mjs` (lines 474-479)
-- Current mitigation: Access tokens expire (typically 1 hour). File has `0o600` permissions.
-- Recommendations: Consider not persisting access tokens at all — they can always be re-derived from the refresh token. This reduces the window of exposure.
-
-**Silent Error Swallowing (17 Empty Catch Blocks):**
-
-- Risk: 17 empty `catch {}` blocks across the codebase silently swallow errors, potentially hiding security-relevant failures
-- Files: `index.mjs` (7 instances: lines 270, 292, 457, 557, 639, 738, 854), `cli.mjs` (3 instances: lines 156, 178, 1288), `lib/accounts.mjs` (line 435), `lib/backoff.mjs` (lines 57, 68), `lib/config.mjs` (lines 224, 242), `lib/storage.mjs` (lines 116, 246)
-- Current mitigation: Many are intentional (e.g., fallback to defaults on parse error, ignore cleanup errors). The `debugLog` function exists but is only used in the fetch retry loop.
-- Recommendations: Add `debugLog` calls to critical catch blocks (token refresh errors, storage write failures). At minimum, differentiate between "expected/safe" catches and "should-never-happen" catches with comments.
-
-**Client ID is Hardcoded and Public:**
-
-- Risk: The OAuth client ID `9d1c250a-e61b-44d9-88ed-5944d1962f5e` is hardcoded in source
-- Files: `lib/config.mjs` (line 71)
-- Current mitigation: OAuth client IDs are considered public (not secrets). PKCE flow provides security without a client secret.
-- Recommendations: No action needed — this is correct OAuth design.
-
-## Performance Bottlenecks
-
-**Disk I/O on Every Request (syncActiveIndexFromDisk):**
-
-- Problem: `syncActiveIndexFromDisk()` reads the entire accounts JSON file from disk at the start of every API request
-- Files: `lib/accounts.mjs` (lines 513-573), `index.mjs` (line 747)
-- Cause: Enables the CLI to change active account while the plugin is running. Reads `anthropic-accounts.json`, parses JSON, compares snapshots, potentially rebuilds the entire account list.
-- Improvement path: Use filesystem watcher (`fs.watch`) instead of polling on every request. Alternatively, add a TTL cache (e.g., only re-read if more than 5 seconds since last read). The current approach adds file I/O latency to every API call.
-
-**Debounced Save Creates Write Pressure:**
-
-- Problem: `requestSaveToDisk()` uses a 1-second debounce timer, but during rapid account switching (multiple 429s in quick succession), each `markRateLimited()` call resets the timer — meaning the write can be delayed indefinitely under sustained failures
-- Files: `lib/accounts.mjs` (lines 412-418)
-- Cause: Debounce resets on each call. Under heavy load with rapid account switches, state may be stale on disk for extended periods.
-- Improvement path: Add a maximum delay (e.g., save at most every 5 seconds regardless of debounce resets). Use a "leading + trailing" debounce pattern.
-
-**Full Account List Rebuild on Sync:**
-
-- Problem: When `syncActiveIndexFromDisk()` detects changes, it rebuilds the entire `#accounts` array and resets both `HealthScoreTracker` and `TokenBucketTracker`
-- Files: `lib/accounts.mjs` (lines 521-558)
-- Cause: Snapshot comparison uses string concatenation of all refresh tokens and enabled states. Any change triggers full rebuild.
-- Improvement path: Track individual account changes rather than full rebuild. Preserve health/token state for accounts that haven't changed.
-
-## Fragile Areas
-
-**SSE Stream Parser:**
-
-- Files: `index.mjs` (lines 406-499, `transformResponse()`)
-- Why fragile: The SSE parser manually splits on `\n\n` boundaries, handles chunk splitting across `reader.read()` calls, normalizes CRLF, and simultaneously strips tool name prefixes via regex, extracts usage stats, and detects mid-stream errors — all in a single `ReadableStream.pull()` callback.
-- Safe modification: Any changes to SSE parsing should be accompanied by tests that verify chunk-split scenarios (data split across multiple `reader.read()` calls). The existing tests in `index.test.mjs` cover this well (see "chunk-split mid-stream error" test).
-- Test coverage: Good — multiple SSE edge cases tested. But the regex-based tool name stripping (line 489) operates on raw text, not parsed JSON, making it sensitive to formatting changes.
-
-**Account Selection Retry Loop:**
-
-- Files: `index.mjs` (lines 723-930, the `for` loop inside `fetch()`)
-- Why fragile: 200+ line retry loop with nested async operations, multiple `continue` paths, error classification, token refresh with single-flight protection, toast debouncing, and account state mutations. Interleaves I/O (fetch, disk sync, toast) with state transitions.
-- Safe modification: Ensure any changes maintain the invariant that each account is tried at most once per request. The `maxAttempts = accountManager.getTotalAccountCount()` bound prevents infinite loops. Always test with 1, 2, and 3+ accounts.
-- Test coverage: Good — `index.test.mjs` has comprehensive tests for 429 retry, 401 auth failure, network errors, and mixed failures across accounts.
-
-**Plugin-CLI Shared State via Disk:**
-
-- Files: `lib/accounts.mjs` (`saveToDisk`, `syncActiveIndexFromDisk`), `lib/storage.mjs` (`saveAccounts`, `loadAccounts`)
-- Why fragile: The plugin (running inside OpenCode) and CLI (separate process) share state through `anthropic-accounts.json`. Both can read and write concurrently. The merge-on-save strategy in `saveToDisk()` (lines 427-506) attempts to handle this, but there's no file locking.
-- Safe modification: Always use atomic write (temp file + rename, already implemented). Test any changes with concurrent read/write scenarios. The stats delta merge system is particularly complex — changes need careful testing.
-- Test coverage: `lib/accounts.test.mjs` covers the AccountManager thoroughly. Storage atomicity is implemented but not stress-tested.
-
-## Scaling Limits
-
-**MAX_ACCOUNTS = 10:**
-
-- Current capacity: Hard limit of 10 accounts
-- Limit: `addAccount()` returns `null` when at capacity
-- Scaling path: The limit is defined in `lib/accounts.mjs` (line 35). Increasing it is trivial but would slow down the retry loop (which tries each account at most once per request) and make the disk sync snapshot comparison heavier.
-- Files: `lib/accounts.mjs` (line 35)
-
-**In-Memory Health/Token Trackers Not Persisted:**
-
-- Current capacity: Health scores and token bucket states exist only in memory
-- Limit: Plugin restart (OpenCode restart) resets all health scores to defaults. Recent rate-limit history from the health tracker is lost, potentially sending traffic to recently-failed accounts.
-- Scaling path: Persist tracker state alongside accounts, or at minimum, bootstrap health scores from `consecutiveFailures` and `lastFailureTime` on load.
-- Files: `lib/rotation.mjs` (classes `HealthScoreTracker`, `TokenBucketTracker`)
-
-## Dependencies at Risk
-
-**`@openauthjs/openauth` (^0.4.3):**
-
-- Risk: Only used for PKCE generation (`generatePKCE`). Small API surface but the package is pre-1.0 and could introduce breaking changes.
-- Impact: Auth flow breaks if PKCE generation API changes.
-- Migration plan: PKCE is a simple algorithm — could be replaced with a ~20 line implementation using `node:crypto`. Would eliminate the only production dependency.
-
-**`@opencode-ai/plugin` (devDependency, ^0.4.45):**
-
-- Risk: Defines the plugin interface (`Plugin` type). Pre-1.0, interface may change without notice.
-- Impact: Plugin won't load if the interface changes. This is a dev dependency (types only), so runtime impact is indirect.
-- Migration plan: No alternative — must track OpenCode's plugin interface. Pin version when stability is critical.
-
-## Missing Critical Features
-
-**No Automatic Account Recovery:**
-
-- Problem: When an account is disabled (e.g., due to repeated token refresh failures), it stays disabled forever until manually re-enabled via CLI
-- Blocks: Unattended long-running sessions. If a token refresh fails due to a transient network issue and triggers the disable path (400/401/403 status), the user must notice and manually run `opencode-anthropic-auth enable N`.
-- Files: `index.mjs` (lines 798-809, `shouldDisable` logic)
-- Fix approach: Add a periodic recovery check that attempts to refresh disabled accounts (e.g., every 30 minutes). Or add an `auto_disable: false` config option to prevent automatic disabling.
-
-**No Token Refresh Retry:**
-
-- Problem: Token refresh failures are treated as final — no retry with backoff. A single network hiccup during refresh disables or skips the account.
-- Blocks: Reliability in unstable network conditions.
-- Files: `index.mjs` (lines 785-816)
-- Fix approach: Add 1-2 retries with short backoff for token refresh before marking the account as failed.
-
-## Test Coverage Gaps
-
-**CLI Commands (`cli.mjs`) — Partial Coverage:**
-
-- What's not tested: `cmdList()` live usage quota fetching, `cmdManage()` interactive flows with actual account mutations, `cmdConfig()` output formatting, error paths in `cmdSwitch`/`cmdEnable`/`cmdDisable` when storage write fails
-- Files: `cli.mjs` (1301 lines), `cli.test.mjs` (1443 lines — tests exist but focus on unit functions and command routing, not integration)
-- Risk: CLI commands that mutate storage could have bugs in edge cases (e.g., removing the last account, disabling while active). The formatting/display functions are tested but the end-to-end command flows less so.
-- Priority: Medium — CLI is a secondary interface; the plugin's fetch interceptor is the critical path.
-
-**No Coverage Enforcement:**
-
-- What's not tested: No coverage thresholds or reports are configured
-- Files: `package.json` (no coverage script)
-- Risk: Coverage can silently degrade. Currently at 335 passing tests across 7 files, which is good, but there's no gate preventing regressions.
-- Priority: Low — test suite is healthy, but adding `vitest --coverage` to CI would formalize the baseline.
-
-**SSE Stream Edge Cases:**
-
-- What's not tested: Malformed SSE payloads (partially valid JSON), very large SSE events, streams with only `event:` lines and no `data:` lines, CRLF vs LF mixed in same stream
-- Files: `index.mjs` (lines 406-499)
-- Risk: Parsing bugs could cause token usage tracking to miss events or tool name stripping to fail silently
-- Priority: Low — existing tests cover the main paths including chunk splitting. The parser is defensive (catches JSON parse errors).
-
----
-
-_Concerns audit: 2026-02-07_