Merge pull request #148 from ndycode/audit/current-structure-cleanup-20260425

Audit current structure cleanup

Author: ndycode

.github/workflows/ci.yml

@@ -53,8 +53,8 @@ jobs:
       - name: Build
         run: npm run build
 
-  audit-prod:
-    name: Production dependency audit
+  audit-ci:
+    name: Dependency audit
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -71,5 +71,5 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Audit production dependencies (high+)
-        run: npm run audit:prod
+      - name: Audit dependencies and dev allowlist
+        run: npm run audit:ci

AGENTS.md

@@ -1,7 +1,7 @@
 # PROJECT KNOWLEDGE BASE
 
-Generated: 2026-02-03
-Commit: 461ea2b
+Generated: 2026-04-25
+Source baseline: 3331324cb14d2b80dd8dfb424619870a88476706
 Branch: main
 
 ## OVERVIEW
@@ -10,7 +10,7 @@ OpenCode plugin: intercepts OpenAI SDK calls, routes through ChatGPT Codex backe
 ## STRUCTURE
 ```
 ./
-├── index.ts              # plugin entry (7-step fetch pipeline, tool registration)
+├── index.ts              # plugin entry (context wiring + 5-stage fetch pipeline)
 ├── lib/                  # core logic (see lib/AGENTS.md)
 ├── test/                 # vitest suites (see test/AGENTS.md)
 ├── scripts/              # install + build helpers
@@ -23,11 +23,12 @@ OpenCode plugin: intercepts OpenAI SDK calls, routes through ChatGPT Codex backe
 ## WHERE TO LOOK
 | Task | Location | Notes |
 | --- | --- | --- |
-| Plugin orchestration | `index.ts` | 7-step request pipeline, tool registration |
+| Plugin orchestration | `index.ts` | 5-stage request pipeline: URL rewrite, body transform, OAuth headers, SSE conversion, error handling |
+| Tool registry | `lib/tools/index.ts` + `lib/tools/codex-*.ts` | 21 registered `codex-*` tools |
 | OAuth flow + PKCE | `lib/auth/auth.ts` | token refresh, JWT decode |
 | OAuth callback server | `lib/auth/server.ts` | binds port 1455 |
 | Multi-account rotation | `lib/accounts.ts` | health scoring, cooldown, selection |
-| Account storage | `lib/storage.ts` | V3 format, per-project/global paths |
+| Account storage | `lib/storage.ts` + `lib/storage/` | V3 facade, per-project/global paths, keychain, import/export |
 | Request transformation | `lib/request/request-transformer.ts` | model normalization, prompt injection |
 | Headers + rate limits | `lib/request/fetch-helpers.ts` | Codex headers, error mapping |
 | SSE to JSON | `lib/request/response-handler.ts` | stream parsing |
@@ -37,13 +38,13 @@ OpenCode plugin: intercepts OpenAI SDK calls, routes through ChatGPT Codex backe
 | Graceful shutdown | `lib/shutdown.ts` | cleanup on process exit |
 | Health monitoring | `lib/health.ts` | account health status |
 | Circuit breaker | `lib/circuit-breaker.ts` | failure isolation |
-| Tests | `test/` | vitest globals, 80% coverage threshold |
+| Tests | `test/` | vitest globals, coverage threshold gate |
 
 ## CONVENTIONS
 - Source: root `index.ts` + `lib/`; `dist/` is generated output.
 - ESLint flat config: `no-explicit-any` enforced, unused args prefixed `_`.
 - Tests relax lint rules (see `eslint.config.js`).
-- Build emits `dist/lib/oauth-success.html` from the TypeScript source via `scripts/copy-oauth-success.js`.
+- Build cleans `dist/`, then emits `dist/lib/oauth-success.html` from the TypeScript source via `scripts/copy-oauth-success.js`.
 - ESM only (`"type": "module"`), Node >= 18.
 
 ## ANTI-PATTERNS (THIS PROJECT)
@@ -54,9 +55,11 @@ OpenCode plugin: intercepts OpenAI SDK calls, routes through ChatGPT Codex backe
 
 ## COMMANDS
 ```bash
-npm run build       # tsc + copy oauth-success.html
+npm run build       # clean dist + tsc + copy oauth-success.html
 npm run typecheck   # type checking only
 npm test            # vitest once
+npm run test:coverage # vitest coverage
+npm run audit:ci    # prod audit + dev allowlist
 npm run test:watch  # vitest watch mode
 npm run lint        # eslint
 ```
@@ -82,7 +85,7 @@ Skills to load when delegating tasks in this codebase.
 |-------|---------------|
 | `typescript-senior` | Strict mode, template literal types (`QuotaKey`), discriminated unions (`TokenResult`), Zod inference |
 | `node-backend` | ESM-first, `node:crypto`, Buffer API, async patterns |
-| `testing-js` | Vitest with 80% coverage threshold, `vi.mock`, `vi.useFakeTimers` |
+| `testing-js` | Vitest coverage gates, `vi.mock`, `vi.useFakeTimers` |
 | `mcp-builder` | Uses `@opencode-ai/plugin/tool` pattern for tool registration |
 
 ### Domain-Specific Skills (load when touching these areas)

CONTRIBUTING.md

@@ -188,7 +188,7 @@ Contract tests in `test/contracts/` pin external API response shapes (OAuth toke
 **Never commit real tokens, real account ids, real organization ids, real JWT payloads, or any PII in fixtures.** The fixtures live in version control; treat them as public.
 
 ### Debug OAuth flow locally
-Set `CODEX_DEBUG_AUTH=1` in your shell before running. See `docs/development/AUTH_FLOW.md` (if present) for protocol details.
+Set `CODEX_DEBUG_AUTH=1` in your shell before running. See `docs/development/ARCHITECTURE.md#oauth-flow` for protocol details.
 
 ### Testing the OS-keychain backend
 

config/minimal-opencode.json

@@ -5,7 +5,8 @@
   "provider": {
     "openai": {
       "options": {
-        "store": false
+        "store": false,
+        "include": ["reasoning.encrypted_content"]
       }
     }
   },

docs/DOCUMENTATION.md

@@ -14,18 +14,27 @@ This file describes how docs are organized in this repository.
 
 ```text
 docs/
-  index.md                     # documentation landing page
-  README.md                    # docs portal / navigation
-  getting-started.md           # install + first-run guide
-  configuration.md             # full config reference
-  troubleshooting.md           # operational debugging guide
-  privacy.md                   # data handling notes
-  development/
-    ARCHITECTURE.md            # technical design
-    CONFIG_FLOW.md             # config resolution internals
-    CONFIG_FIELDS.md           # config field semantics
-    TESTING.md                 # testing strategy and commands
-    TUI_PARITY_CHECKLIST.md    # auth dashboard UI parity checks
+├── _config.yml                 # docs site config
+├── DOCUMENTATION.md            # this repository documentation map
+├── README.md                   # docs portal / navigation
+├── index.md                    # documentation landing page
+├── getting-started.md          # install + first-run guide
+├── configuration.md            # full config reference
+├── troubleshooting.md          # operational debugging guide
+├── faq.md                      # short common answers
+├── privacy.md                  # data handling notes
+├── OPENCODE_PR_PROPOSAL.md     # upstream OpenCode proposal notes
+├── development/
+│   ├── ARCHITECTURE.md         # technical design and current module/docs layout
+│   ├── CONFIG_FIELDS.md        # config field semantics
+│   ├── CONFIG_FLOW.md          # config resolution internals
+│   ├── TESTING.md              # testing strategy and commands
+│   └── TUI_PARITY_CHECKLIST.md # auth dashboard UI parity checks
+└── audits/
+    ├── INDEX.md
+    ├── 01-executive-summary.md ... 16-verdict.md
+    ├── _findings/              # T01 through T16 detailed findings
+    └── _meta/                  # audit rubric, ledger, environment, verification
 ```
 
 ## config/ (copy-paste templates)

docs/audits/01-executive-summary.md

@@ -1,90 +1,22 @@
-> **Audit SHA**: d92a8eedad906fcda94cd45f9b75a6244fd9ef51 | **Generated**: 2026-04-17T09:28:39Z | **Task**: T18 Synthesis | **Source**: docs/audits/_meta/findings-ledger.csv
+> Audit source: 3331324cb14d2b80dd8dfb424619870a88476706 | Generated: 2026-04-25T12:45:33+08:00 | Scope: current-structure refresh
 
-# 01 — Executive Summary
+# Executive Summary
 
-**Repository**: `oc-codex-multi-auth` — OpenCode plugin intercepting OpenAI SDK calls and routing through a ChatGPT Codex OAuth backend with multi-account rotation. Version: `v6.0.0` (per `CHANGELOG.md`). Languages: TypeScript (strict), ESM-only Node ≥ 18.
+The audit corpus has been regenerated against the current codebase. The old audit line anchors for the pre-split tool monolith and storage monolith are no longer valid. Current structure evidence:
 
-**Audit effort**: 16 task audits (T01–T16) producing 10,841 lines across `docs/audits/_findings/`. Verification layer T17 extracted 320 findings; after Layer-2 citation check and Layer-3 dedup/severity reclassification, **149 unique PASSED findings** survive: 1 CRITICAL, 15 HIGH, 40 MEDIUM, 93 LOW. See `_meta/verification-report.md`, `_meta/dedup-report.md`, `_meta/severity-reclassifications.md` for the trail.
+- `index.ts`: 3694 lines, plugin context wiring and request pipeline.
+- `lib/tools/`: 21 per-tool `codex-*` modules wired by `createToolRegistry`.
+- `lib/storage.ts`: 79-line facade over focused `lib/storage/*` modules.
+- `lib/accounts.ts`: 366-line orchestrator over focused `lib/accounts/*` modules.
+- Tests: 83 Vitest files, including extracted-tool, chaos, property, contract, and doc-parity suites.
 
----
+Current severity posture after this refresh:
 
-## Maturity assessment
+| Severity | Current active | Notes |
+| --- | ---: | --- |
+| Critical | 0 | No active Critical finding remains. |
+| High | 0 | Former High items for inline tools, storage monolith, remove confirmation, export overwrite, and minimal config drift are resolved or superseded. |
+| Medium | 4 | Remaining items are maintainability or hardening work, mainly large request modules and release/process polish. |
+| Low | 5 | Backlog items are docs hygiene, coverage granularity, and developer-experience polish. |
 
-**Overall**: **mid-to-late maturity for a single-maintainer plugin**, early for commercial/enterprise use.
-
-- The codebase shows TypeScript-senior hygiene: strict mode, `noImplicitAny`, discriminated unions, Zod schema source-of-truth in `lib/schemas.ts`. Anti-pattern surface in production code is near-zero (`no-explicit-any` enforced; `as any` banned).
-- Package hygiene is deliberate: aggressive dependency overrides, per-project + global storage, `files:` allowlist, `.npmignore` present.
-- Documentation and public-policy surface exist: `README.md`, `CHANGELOG.md`, `SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, issue templates, `docs/` with architecture/getting-started/configuration/faq/privacy/troubleshooting.
-- Test coverage claims 80% at the line level (`vitest.config.ts`). 60+ test files exist covering the common auth + rotation + storage paths.
-
-**Counter-signals**:
-- No CI runs typecheck, lint, test, audit, or build on pull requests (`pr-quality.yml` is markdown-only) — HIGH `290`.
-- Two advertised features (`lib/audit.ts`, `lib/auth-rate-limit.ts`) are 100% dead production code (HIGH `302`, `303`).
-- 5975-line `index.ts` and 1296-line `lib/storage.ts` block safe incremental change.
-- One package in the credential path (`@openauthjs/openauth@0.4.3`) ships without a declared license.
-
----
-
-## Biggest strengths
-
-- **Strict TypeScript + schema source-of-truth**. Zod schemas drive `lib/types.ts` and most boundary parsing; discriminated unions (e.g., `TokenResult`) are a first-class pattern. Type-safety findings ([§05-medium.md](05-medium.md)) are *polish*, not *risk*.
-- **Zero `as any`, zero `@ts-ignore`, zero `@ts-expect-error`** in production code.
-- **Dependency discipline**: aggressive overrides block known-bad transitives (ledger id `276`); Node engines constrained; ESM-only.
-- **SECURITY.md present with triage channel** (LOW `295` only asks for a dedicated email).
-- **Prompt-template ETag caching** (`lib/prompts/codex.ts`) is a model of cache-correctness: SWR + If-None-Match + bundled fallback.
-- **Proactive-refresh + refresh-queue** is well-structured — the defects in it are persistence races (HIGH `14`), not architectural mistakes.
-
----
-
-## Biggest risks
-
-1. **Credential handling has five latent defects** that are defensible-in-depth but one accident away from CRITICAL (plaintext persistence, unsigned cross-process injection, credential resurrection on merge, unverified JWT identity, silent token loss on refresh). See [§09-security-trust.md](09-security-trust.md).
-2. **One active CRITICAL race** in `lib/accounts.ts:728-733` (auth-failure counter across org-variant accounts). See [§03-critical-issues.md](03-critical-issues.md).
-3. **Silent-failure chains** across storage, recovery, and logger — swallowed errors, `warn`-level on session-breaking conditions, unbounded log files. See [§05-medium.md](05-medium.md), [§09-security-trust.md](09-security-trust.md).
-4. **Two monolithic modules** (`index.ts`, `lib/storage.ts`) prevent safe incremental change and concentrate blast radius. See [§04-high-priority.md](04-high-priority.md), [§07-refactoring-plan.md](07-refactoring-plan.md).
-5. **Dead code shipping as if live** — `lib/audit.ts` and `lib/auth-rate-limit.ts`. See [§04-high-priority.md](04-high-priority.md).
-6. **No CI validation on PRs** — regressions reach main; coverage, type, and lint signals are maintainer-local only. See [§11-dx-cli-docs.md](11-dx-cli-docs.md).
-7. **Destructive defaults** — `importAccounts(backupMode:"none")`, `exportAccounts(force:true)`, `codex-remove` without confirmation. See [§06-low-priority.md](06-low-priority.md) and [§12-quick-wins.md](12-quick-wins.md).
-8. **Storage-format forward-compat gap** — V4+ is silently discarded; V2 has no migrator. See [§04-high-priority.md](04-high-priority.md).
-9. **Testing**: documented 80% coverage masks zero direct tests for `lib/accounts/rate-limits.ts`, no fault-injection despite a 537-line "chaos" file, and no contract tests for external API shapes. See [§10-testing-gaps.md](10-testing-gaps.md).
-10. **Supply chain**: `@openauthjs/openauth@0.4.3` ships with no declared license. See [§04-high-priority.md](04-high-priority.md), [§09-security-trust.md](09-security-trust.md).
-
----
-
-## Top 5 priorities (next 3-5 days)
-
-1. **Ship the CRITICAL fix** — per-refresh-token promise chain in `lib/accounts.ts:728-733` + paired test (§10 #1, §03 entry). Effort: Short.
-2. **Flush debounced save on shutdown** — RC-10 closes a correlated defect class. Effort: Short. See [§07-refactoring-plan.md](07-refactoring-plan.md).
-3. **Turn on CI (typecheck/lint/test/build) on PRs** — F9 unblocks everything else. Effort: Short. See [§11-dx-cli-docs.md](11-dx-cli-docs.md).
-4. **Swap destructive defaults** — `importAccounts(backupMode:"timestamped")`, `exportAccounts(force:false)`, `codex-remove(confirm:true)`. Effort: Quick. See [§12-quick-wins.md](12-quick-wins.md).
-5. **Decide `lib/audit.ts` + `lib/auth-rate-limit.ts`** via a single RFC — either wire in (F1/F10) or retire (RC-5). Effort: Short. See [§07-refactoring-plan.md](07-refactoring-plan.md), [§08-feature-recommendations.md](08-feature-recommendations.md).
-
-The full 20-item prioritised list lives in [§14-top20.md](14-top20.md); adversarial verification outcomes in [`_meta/oracle-review.md`](_meta/oracle-review.md). For calendar sequencing see [§13-phased-roadmap.md](13-phased-roadmap.md).
-
----
-
-## Per-chapter anchor pointers
-
-Every domain chapter contributes to this summary:
-
-- **[§02-system-map.md](02-system-map.md)** — architecture + trust boundaries backing the "biggest risks" list.
-- **[§03-critical-issues.md](03-critical-issues.md)** — the single CRITICAL race.
-- **[§04-high-priority.md](04-high-priority.md)** — 15 HIGHs spanning security, reliability, storage, CLI, CI.
-- **[§05-medium.md](05-medium.md)** — 40 MEDIUMs including the silent-failure cluster.
-- **[§06-low-priority.md](06-low-priority.md)** — 93 LOW items as a batched backlog.
-- **[§07-refactoring-plan.md](07-refactoring-plan.md)** — RC-1..RC-10 unblocking the HIGH/MEDIUM backlog.
-- **[§08-feature-recommendations.md](08-feature-recommendations.md)** — 10 user-pain-anchored features.
-- **[§09-security-trust.md](09-security-trust.md)** — credential lifecycle + hardening steps.
-- **[§10-testing-gaps.md](10-testing-gaps.md)** — race-window + contract + property tests to add.
-- **[§11-dx-cli-docs.md](11-dx-cli-docs.md)** — OSS-readiness scorecard.
-- **[§12-quick-wins.md](12-quick-wins.md)** — 20 ≤ 2-hour changes, high ROI.
-- **[§13-phased-roadmap.md](13-phased-roadmap.md)** — four phases with rollback posture.
-- **[§14-top20.md](14-top20.md)** — final ranked action list.
-- **[§15-file-by-file.md](15-file-by-file.md)** — disposition per module.
-- **[§16-verdict.md](16-verdict.md)** — scorecard + ship/don't-ship.
-
----
-
-## Bottom line
-
-The project is **structurally healthy** — mature TS/Node posture, explicit schemas, decent docs — but **operationally exposed** through one active race, destructive defaults, dead-code promises in privacy features, and no CI gating. The remediation cost is modest: **Phase 1 (safety + CI) is 3-5 days for a single maintainer**, after which the HIGH backlog halves and every subsequent change lands under test + type + lint protection.
+This PR also adds current-structure parity tests so future stale audit claims fail locally.