opencode-anthropic-fix 0.0.16 → 0.0.18

package/.planning/codebase/CONVENTIONS.md

@@ -1,335 +0,0 @@
-# Coding Conventions
-
-**Analysis Date:** 2026-02-07
-
-## Language & Module System
-
-**Language:** Pure JavaScript (ES2025) — no TypeScript, no compilation for source files.
-**Module System:** ESM exclusively. All source files use `.mjs` extension.
-**Type Safety:** JSDoc annotations provide full type information without a compile step.
-
-## Naming Patterns
-
-**Files:**
-
-- Source files: `kebab-case.mjs` — e.g., `lib/storage.mjs`, `lib/backoff.mjs`
-- Test files: `kebab-case.test.mjs` — co-located next to source
-- Scripts: `kebab-case.mjs` in `scripts/` — e.g., `scripts/build.mjs`, `scripts/install.mjs`
-- Entry points: `index.mjs`, `cli.mjs` at project root
-
-**Functions:**
-
-- Use `camelCase` for all functions: `loadAccounts`, `calculateBackoffMs`, `parseRetryAfterHeader`
-- Factory/builder functions: `make*` prefix — `makeStoredAccount`, `makeClient`
-- Validation functions: `validate*` prefix — `validateAccount`, `validateConfig`, `validateStats`
-- Boolean-returning functions: `is*` prefix — `isAccountSpecificError`, `isUsable`
-- Getters: `get*` prefix — `getScore`, `getConfigDir`, `getStoragePath`, `getCurrentIndex`
-- Event recorders: `record*` prefix — `recordSuccess`, `recordRateLimit`, `recordFailure`
-
-**Variables:**
-
-- Use `camelCase`: `storagePath`, `configDir`, `activeIndex`
-- Constants: `UPPER_SNAKE_CASE` — `MAX_ACCOUNTS`, `RATE_LIMIT_KEY`, `CURRENT_VERSION`
-- Unused parameters: prefix with `_` — `_error`, `_response` (enforced by ESLint `argsIgnorePattern: "^_"`)
-
-**Classes:**
-
-- Use `PascalCase`: `AccountManager`, `HealthScoreTracker`, `TokenBucketTracker`
-- Private fields use `#` prefix (true private fields): `#accounts`, `#cursor`, `#config`, `#scores`
-- No underscore-prefixed "private" conventions — always use `#` for private state
-
-**Types (JSDoc):**
-
-- Use `PascalCase` for `@typedef` names: `ManagedAccount`, `AccountStorage`, `RateLimitReason`
-- String literal unions: `@typedef {'AUTH_FAILED' | 'QUOTA_EXHAUSTED' | 'RATE_LIMIT_EXCEEDED'} RateLimitReason`
-
-## Code Style
-
-**Formatting (Prettier):**
-
-- Config: `.prettierrc`
-- Print width: 120
-- Indent: 2 spaces (no tabs)
-- Semicolons: always
-- Quotes: double quotes (`"`)
-- Trailing commas: all (including function parameters)
-- Bracket spacing: true
-- Arrow parens: always
-
-**Linting (ESLint):**
-
-- Config: `eslint.config.mjs` (flat config format)
-- Base: `@eslint/js` recommended
-- ECMAScript: 2025
-- Key rules:
-  - `prefer-const`: error — always use `const` unless reassignment needed
-  - `no-var`: error — never use `var`
-  - `eqeqeq: smart` — use `===` except allow `== null` for null/undefined checks
-  - `no-console: off` — this is a CLI tool, console output is expected
-  - `no-constant-condition: { checkLoops: false }` — `while (true)` is intentional
-  - `no-unused-vars: warn` with `argsIgnorePattern: "^_"` and `varsIgnorePattern: "^_"`
-- Globals: Node.js + Web API globals declared explicitly (no `node: true` environment)
-
-**Pre-commit (Husky + lint-staged):**
-
-- Config: `package.json` under `lint-staged`
-- `.mjs` files: `prettier --write` then `eslint --fix`
-- `.json`, `.md` files: `prettier --write`
-- Pre-push hook: runs `npm test`
-
-## Import Organization
-
-**Order:**
-
-1. External packages — `import { createClient } from "@openauthjs/openauth/client"`
-2. Node built-ins — `import { promises as fs } from "node:fs"`, `import { join } from "node:path"`
-3. Local modules — `import { loadAccounts } from "./lib/storage.mjs"`
-
-**Rules:**
-
-- Always use `node:` prefix for Node.js built-in modules
-- Always include `.mjs` extension in relative imports
-- Named exports only — no default exports anywhere in the codebase
-- Destructured imports preferred: `import { loadAccounts, saveAccounts } from "./storage.mjs"`
-
-**Path Aliases:**
-
-- None configured. All imports use relative paths.
-
-## JSDoc Type System
-
-**Every function gets JSDoc:**
-
-```javascript
-/**
- * Parse the Retry-After header from a response.
- * Supports both seconds (integer) and HTTP-date formats.
- * @param {Response} response
- * @returns {number | null} Retry-after duration in milliseconds, or null
- */
-export function parseRetryAfterHeader(response) {
-```
-
-**Type definitions at the top of files using `@typedef`:**
-
-```javascript
-/**
- * @typedef {object} ManagedAccount
- * @property {string} id
- * @property {number} index
- * @property {string} [email]
- * @property {string} refreshToken
- * @property {boolean} enabled
- * @property {AccountStats} stats
- */
-```
-
-**Cross-file type imports:**
-
-```javascript
-/**
- * @typedef {import('./config.mjs').AnthropicAuthConfig} AnthropicAuthConfig
- * @typedef {import('./storage.mjs').AccountMetadata} AccountMetadata
- */
-```
-
-**Inline JSDoc casts for type narrowing:**
-
-```javascript
-const code = /** @type {NodeJS.ErrnoException} */ (error).code;
-const hs = /** @type {Record<string, unknown>} */ (raw.health_score);
-```
-
-**Private class field annotations:**
-
-```javascript
-/** @type {ManagedAccount[]} */
-#accounts = [];
-/** @type {Map<string, StatsDelta>} */
-#statsDeltas = new Map();
-```
-
-## Error Handling
-
-**Pattern 1: Silent catch for non-critical operations**
-Used when failure should not disrupt the main flow:
-
-```javascript
-try {
-  await fs.unlink(tempPath);
-} catch {
-  // Ignore cleanup errors
-}
-```
-
-**Pattern 2: Error code discrimination for fs operations**
-
-```javascript
-try {
-  const content = await fs.readFile(storagePath, "utf-8");
-  // ...process
-} catch (error) {
-  const code = /** @type {NodeJS.ErrnoException} */ (error).code;
-  if (code === "ENOENT") return null;
-  return null;
-}
-```
-
-**Pattern 3: Graceful degradation — return defaults on failure**
-Config loading, account loading, etc. return defaults or null rather than throwing:
-
-```javascript
-export function loadConfig() {
-  try {
-    // ...try to read and parse
-  } catch {
-    return { ...DEFAULT_CONFIG };
-  }
-}
-```
-
-**Pattern 4: Propagate errors for critical paths**
-Storage save errors are thrown after cleanup, so callers know the save failed:
-
-```javascript
-try {
-  await fs.writeFile(tempPath, content, { encoding: "utf-8", mode: 0o600 });
-  await fs.rename(tempPath, storagePath);
-} catch (error) {
-  try {
-    await fs.unlink(tempPath);
-  } catch {
-    /* ignore */
-  }
-  throw error;
-}
-```
-
-**General rule:** Never crash the plugin. If something fails, log/ignore and continue. The plugin is middleware for a CLI tool — availability beats correctness for non-critical paths.
-
-## File I/O Patterns
-
-**Atomic writes (temp file + rename):**
-All data persistence uses this pattern to prevent corruption on crash:
-
-```javascript
-const tempPath = `${storagePath}.${randomBytes(6).toString("hex")}.tmp`;
-await fs.writeFile(tempPath, content, { encoding: "utf-8", mode: 0o600 });
-await fs.rename(tempPath, storagePath);
-```
-
-See `lib/storage.mjs` `saveAccounts()`.
-
-**File permissions:**
-Sensitive files (accounts with tokens) are written with `mode: 0o600` (owner read/write only).
-
-**Debounced persistence:**
-`AccountManager` in `lib/accounts.mjs` uses a 1-second debounce (`#saveTimeout`) to coalesce rapid state changes into a single disk write.
-
-**Merge-on-save:**
-Before writing, `AccountManager._persistNow()` re-reads the current disk state and merges in-memory deltas. This supports multiple CLI/plugin instances running concurrently without data loss.
-
-## Code Organization
-
-**Section comments:**
-Major logical sections are separated with comment blocks:
-
-```javascript
-// ---------------------------------------------------------------------------
-// Color helpers — zero dependencies, respects NO_COLOR / TTY
-// ---------------------------------------------------------------------------
-```
-
-**Module structure pattern:**
-
-1. Imports
-2. JSDoc `@typedef` declarations
-3. Constants (`const UPPER_SNAKE = ...`)
-4. Internal/private helper functions
-5. Exported functions/classes
-6. Main entry point (in entry files like `cli.mjs`)
-
-**Export pattern:**
-
-- Named exports only: `export function ...`, `export class ...`, `export const ...`
-- No barrel files — each module exports its own public API
-- No default exports
-
-## CLI Patterns
-
-**Command functions return exit codes:**
-
-```javascript
-async function cmdList(storage) {
-  // ...
-  return 0; // success
-}
-```
-
-**Color helpers respect `NO_COLOR` and TTY:**
-
-```javascript
-let USE_COLOR = !process.env.NO_COLOR && process.stdout.isTTY !== false;
-const ansi = (code, text) => (USE_COLOR ? `\x1b[${code}m${text}\x1b[0m` : text);
-const c = {
-  bold: (t) => ansi("1", t),
-  dim: (t) => ansi("2", t),
-  green: (t) => ansi("32", t),
-  // ...
-};
-```
-
-**Interactive prompts:**
-Use `node:readline/promises` with `createInterface({ input: stdin, output: stdout })`.
-
-## Validation Patterns
-
-**Config validation with clamping:**
-Invalid or out-of-range values are clamped to valid ranges, never rejected:
-
-```javascript
-function clampNumber(value, min, max, fallback) {
-  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
-  return Math.max(min, Math.min(max, value));
-}
-```
-
-See `lib/config.mjs` `validateConfig()`.
-
-**Account validation with field-level sanitization:**
-Each field is individually validated and defaulted. Invalid accounts (no refreshToken) return null and are filtered out:
-
-```javascript
-if (typeof acc.refreshToken !== "string" || !acc.refreshToken.trim()) return null;
-```
-
-See `lib/storage.mjs` `validateAccount()`.
-
-**Deduplication:**
-Accounts are deduplicated by `refreshToken` — the one with the latest `lastUsed` timestamp wins. See `lib/storage.mjs` `deduplicateByRefreshToken()`.
-
-## Null Handling
-
-**Use `== null` for null/undefined checks** (enabled by `eqeqeq: smart`):
-
-```javascript
-if (body == null) {
-  return { errorType, message, text };
-}
-```
-
-**Nullable fields use `| null` in JSDoc, not `undefined`:**
-
-```javascript
-/** @property {number | null} lastFailureTime */
-```
-
-**Optional fields use `[bracket]` notation in JSDoc:**
-
-```javascript
-/** @property {string} [email] */
-```
-
----
-
-_Convention analysis: 2026-02-07_

package/.planning/codebase/INTEGRATIONS.md

@@ -1,215 +0,0 @@
-# External Integrations
-
-**Analysis Date:** 2026-02-07
-
-## APIs & External Services
-
-**Anthropic OAuth (Primary Integration):**
-
-- **Purpose:** OAuth 2.0 authentication for Claude Pro/Max subscriptions and API key creation
-- **SDK/Client:** Native `fetch()` — no SDK wrapper
-- **Auth:** OAuth 2.0 with PKCE (Authorization Code flow)
-- **Client ID:** `9d1c250a-e61b-44d9-88ed-5944d1962f5e` (hardcoded in `lib/config.mjs:71`)
-- **PKCE Library:** `@openauthjs/openauth/pkce` — `generatePKCE()` function
-
-**Anthropic OAuth Endpoints (used in `index.mjs` and `cli.mjs`):**
-
-| Endpoint                                                        | Method        | Purpose                               | Used In                                        |
-| --------------------------------------------------------------- | ------------- | ------------------------------------- | ---------------------------------------------- |
-| `https://claude.ai/oauth/authorize`                             | GET (browser) | OAuth authorization (Max plan)        | `index.mjs:21`                                 |
-| `https://console.anthropic.com/oauth/authorize`                 | GET (browser) | OAuth authorization (Console/API key) | `index.mjs:21`                                 |
-| `https://console.anthropic.com/v1/oauth/token`                  | POST          | Token exchange & refresh              | `index.mjs:42`, `index.mjs:536`, `cli.mjs:140` |
-| `https://api.anthropic.com/api/oauth/claude_cli/create_api_key` | POST          | Create API key from OAuth token       | `index.mjs:1028`                               |
-| `https://api.anthropic.com/api/oauth/usage`                     | GET           | Fetch per-account usage quotas        | `cli.mjs:168`                                  |
-
-**Anthropic Messages API (Proxied):**
-
-- **Purpose:** The plugin intercepts and transforms requests to the Anthropic Messages API
-- **Endpoint:** `/v1/messages` — detected via URL pathname matching
-- **Transforms applied:**
-  - Adds `?beta=true` query parameter (`index.mjs:296`)
-  - Sets `Authorization: Bearer {access_token}` header
-  - Adds `anthropic-beta: oauth-2025-04-20,interleaved-thinking-2025-05-14` header
-  - Sets `user-agent: claude-cli/2.1.2 (external, cli)`
-  - Removes `x-api-key` header
-  - Prefixes tool names with `mcp_` in request body
-  - Strips `mcp_` prefix from tool names in response stream
-  - Rewrites `OpenCode` → `Claude Code` and `opencode` → `Claude` in system prompts
-
-**OAuth Flow Parameters:**
-
-- Redirect URI: `https://console.anthropic.com/oauth/code/callback`
-- Scopes: `org:create_api_key user:profile user:inference`
-- PKCE: S256 challenge method
-- Grant types: `authorization_code` (initial), `refresh_token` (renewal)
-
-## Data Storage
-
-**Databases:**
-
-- None — All storage is local filesystem JSON files
-
-**File Storage (Local):**
-
-- `~/.config/opencode/anthropic-accounts.json` — Multi-account OAuth token storage
-  - Written by: `lib/storage.mjs` (`saveAccounts()`)
-  - Read by: `lib/storage.mjs` (`loadAccounts()`)
-  - Format: JSON with version, accounts array, activeIndex
-  - Security: File mode `0o600` (owner read/write only)
-  - Write strategy: Atomic (temp file + rename via `randomBytes(6)` suffix)
-  - Auto-deduplication by refresh token on load
-  - Auto `.gitignore` maintained in config directory
-
-- `~/.config/opencode/anthropic-auth.json` — Plugin configuration
-  - Written by: `lib/config.mjs` (`saveConfig()`)
-  - Read by: `lib/config.mjs` (`loadConfig()`)
-  - Format: JSON with strategy, health scores, token bucket settings
-  - Security: File mode `0o600`
-  - Write strategy: Atomic (temp file + rename via PID suffix)
-
-**Caching:**
-
-- In-memory only — Health scores (`HealthScoreTracker`), token buckets (`TokenBucketTracker`), and stats deltas (`Map<string, StatsDelta>`) are held in memory during the process lifetime
-- No external cache service
-
-## Authentication & Identity
-
-**Auth Provider:** Anthropic OAuth 2.0 (custom implementation)
-
-**Implementation:**
-
-- PKCE Authorization Code flow for initial login
-- Refresh token rotation for session maintenance
-- Multi-account support (up to 10 accounts, `MAX_ACCOUNTS` in `lib/accounts.mjs:35`)
-- Single-flight refresh protection (prevents concurrent refresh races in `index.mjs:659`)
-- Automatic account switching on auth failure, rate limit, or quota exhaustion
-
-**Token Lifecycle:**
-
-1. User visits authorization URL in browser
-2. User pastes authorization code back to CLI
-3. Plugin exchanges code for access + refresh tokens
-4. Access token used for API requests (short-lived)
-5. Refresh token used to obtain new access tokens when expired
-6. Plugin persists tokens to `anthropic-accounts.json`
-7. Also syncs primary account to OpenCode's `auth.json` for compatibility
-
-**Account Selection Strategies (configurable in `lib/rotation.mjs`):**
-
-- `sticky` — Stay on current account until it fails (default)
-- `round-robin` — Rotate through accounts on every request
-- `hybrid` — Score-based selection using health scores + token buckets + freshness
-
-## OpenCode Plugin SDK Integration
-
-**SDK:** `@opencode-ai/plugin` ^0.4.45 (via `@opencode-ai/sdk` 0.4.19)
-
-**Plugin hooks used:**
-
-- `auth.loader(getAuth, provider)` — Custom auth loader that intercepts fetch requests
-- `auth.methods[]` — Three auth methods (OAuth Max, OAuth Console/API Key, Manual API Key)
-- `experimental.chat.system.transform` — Prepends Claude Code identity to system prompts
-
-**SDK Client API used:**
-
-- `client.auth.set()` — Persist OAuth tokens to OpenCode's auth store (`index.mjs:580`)
-- `client.tui?.showToast()` — Display notifications in OpenCode TUI (`index.mjs:638`)
-
-## Monitoring & Observability
-
-**Error Tracking:**
-
-- None — No external error tracking service
-
-**Logs:**
-
-- Debug logging to `stderr` via `console.error()` when `config.debug` is enabled
-- Prefix: `[opencode-anthropic-auth]`
-- Controlled by: `OPENCODE_ANTHROPIC_DEBUG=1` env var or `debug: true` in config file
-
-**TUI Toasts:**
-
-- Account usage notifications (which account is active)
-- Account switch notifications (when switching due to rate limit/failure)
-- Error toasts (disabled accounts, auth failures)
-- Configurable: `toasts.quiet` suppresses non-error toasts, `toasts.debounce_seconds` rate-limits toast frequency
-
-## CI/CD & Deployment
-
-**Hosting:**
-
-- npm registry (`opencode-anthropic-auth` package, currently v0.0.13)
-- Self-installed to user machine (not a hosted service)
-
-**CI Pipeline:**
-
-- GitHub Actions: `.github/workflows/publish.yml`
-- Trigger: Manual (`workflow_dispatch`) with optional version bump type
-- Steps: Checkout → Node.js 24 → `npm install` → `npm publish --access public`
-- Auth: `NPM_TOKEN` secret
-
-**Publishing Flow:**
-
-1. Run `bun script/publish.ts [patch|minor|major]` locally
-2. Bumps version in `package.json`, commits, pushes
-3. Triggers GitHub Actions workflow via `gh workflow run`
-4. CI publishes to npm
-
-## Environment Configuration
-
-**Required env vars:**
-
-- None required for runtime (config file is optional, defaults are sane)
-
-**Optional env vars (runtime):**
-
-- `OPENCODE_ANTHROPIC_STRATEGY` — Override account selection strategy
-- `OPENCODE_ANTHROPIC_DEBUG` — Toggle debug logging
-- `OPENCODE_ANTHROPIC_QUIET` — Suppress non-error toasts
-- `XDG_CONFIG_HOME` — Override config/storage directory base
-- `NO_COLOR` — Disable ANSI colors in CLI output
-
-**CI/CD env vars:**
-
-- `NPM_TOKEN` — npm authentication for publishing (GitHub Actions secret)
-- `NODE_AUTH_TOKEN` — Mapped from `NPM_TOKEN` in workflow
-
-**Secrets location:**
-
-- OAuth tokens stored in `~/.config/opencode/anthropic-accounts.json` (file mode 0o600)
-- `.gitignore` auto-maintained in config directory to prevent accidental commits
-- No secrets in repository
-
-## Webhooks & Callbacks
-
-**Incoming:**
-
-- OAuth callback URL: `https://console.anthropic.com/oauth/code/callback` (handled by Anthropic's servers; user pastes the returned code manually)
-
-**Outgoing:**
-
-- None
-
-## SSE Stream Processing
-
-**The plugin processes Server-Sent Events (SSE) streams from the Anthropic API:**
-
-- Strips `mcp_` prefix from tool names in response stream (`index.mjs:489`)
-- Extracts token usage from `message_start` and `message_delta` events (`index.mjs:317-341`)
-- Detects mid-stream account errors for proactive switching (`index.mjs:368-392`)
-- Implemented via `ReadableStream` wrapping of response body (`index.mjs:465-492`)
-
-## Rate Limit & Backoff System
-
-**The plugin implements sophisticated rate limit handling across accounts:**
-
-- Categorizes errors: `AUTH_FAILED`, `QUOTA_EXHAUSTED`, `RATE_LIMIT_EXCEEDED` (`lib/backoff.mjs`)
-- Respects `Retry-After` headers (both seconds and HTTP-date formats)
-- Escalating backoffs for quota exhaustion: 1m → 5m → 30m → 2h
-- Fixed backoffs: Auth failure 5s, Rate limit 30s
-- Health scoring with passive recovery (configurable in `lib/rotation.mjs`)
-- Token bucket for request gating (`lib/rotation.mjs`)
-
----
-
-_Integration audit: 2026-02-07_