refactor: add package subpath exports

[ndycode]

Summary

• add explicit supported package subpath exports for auth, storage, config, request, and cli
• add narrow barrel entrypoints for supported subpaths instead of forcing consumers onto the broad root barrel
• extend the public API contract test to cover the supported exports surface

Validation

• npm run typecheck
• npm run lint -- package.json lib/auth/index.ts lib/request/index.ts lib/codex-cli/index.ts test/public-api-contract.test.ts (ESLint ignores package.json, no TypeScript lint errors)
• npm run test -- test/public-api-contract.test.ts
• npm run build
• node --input-type=module -e "const root = await import('codex-multi-auth'); const auth = await import('codex-multi-auth/auth'); const storage = await import('codex-multi-auth/storage'); const config = await import('codex-multi-auth/config'); const request = await import('codex-multi-auth/request'); const cli = await import('codex-multi-auth/cli'); console.log(JSON.stringify({ rootPlugin: typeof root.OpenAIOAuthPlugin, authExchange: typeof auth.exchangeAuthorizationCode, storageLoad: typeof storage.loadAccounts, configLoad: typeof config.loadPluginConfig, requestHeaders: typeof request.createCodexHeaders, cliState: typeof cli.loadCodexCliState }));"

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this PR adds five explicit package subpath exports (auth, storage, config, request, cli) with narrow barrel entrypoints, replacing the need for consumers to rely on the broad root barrel. it also extends the public API contract test to snapshot the full exports map and validate barrel alignment.

highlights:

• lib/request/index.ts correctly excludes response-handler.ts and stream-failover.ts (SSE internals), and the contract test explicitly asserts their absence — clean follow-through on the prior review concern
• lib/auth/index.ts is narrow by design — only auth.ts, leaving browser.ts, server.ts, token-utils.ts as implementation details
• package.json exports map has correct types-first condition ordering for all five subpaths; ESM-only shape is consistent with "type": "module"
• docs and documentation integrity test are kept in sync

one gap worth closing: the codex-multi-auth/cli barrel (lib/codex-cli/index.ts) promotes all four CLI modules — including observability.ts and sync.ts (account sync coordination, concurrency-sensitive) — to Tier A semver-stable surface. the contract test only pins cli.loadCodexCliState; no positive assertions guard observability.ts/sync.ts/writer.ts exports, and there are no negative guards either. this is asymmetric with the request barrel test pattern and leaves those exports silently unprotected against future renames.

Confidence Score: 4/5

• safe to merge with one minor contract test gap in the cli barrel worth addressing before treating those exports as fully locked
• prior concern about SSE internals in the request barrel is fully resolved — correct exclusions in place with negative-assertion test guards. the overall structure is solid: exports map ordering is correct, auth barrel is intentionally narrow, docs are in sync. score is 4 rather than 5 because the cli barrel test only pins one of four exposed files' exports, leaving observability.ts, sync.ts, and writer.ts semver-stable but contractually unguarded
• test/public-api-contract.test.ts (lines 87–102): cli barrel contract coverage gap

Important Files Changed

Filename	Overview
lib/request/index.ts	narrow barrel correctly excludes response-handler.ts and stream-failover.ts; exposes failure-policy, fetch-helpers, rate-limit-backoff, and request-transformer
lib/auth/index.ts	single-line barrel, re-exports auth.ts only; browser.ts, server.ts, token-utils.ts correctly left out as implementation details
lib/codex-cli/index.ts	exports all four CLI modules including sync.ts (concurrency-sensitive account sync) and observability.ts; contract test only pins loadCodexCliState, leaving the other three files' exports unguarded
package.json	exports map added with correct types-first condition ordering for all five subpaths plus ./package.json passthrough; ESM-only (no require condition), consistent with "type": "module"
test/public-api-contract.test.ts	adds snapshot test for exports map and barrel alignment test; request barrel correctly has negative assertions for SSE internals; cli barrel test only asserts one export from state.ts, leaving observability/sync/writer unpinned

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph consumers["consumer import paths"]
        R[codex-multi-auth]
        A[codex-multi-auth/auth]
        S[codex-multi-auth/storage]
        C[codex-multi-auth/config]
        RQ[codex-multi-auth/request]
        CL[codex-multi-auth/cli]
    end

    subgraph barrels["barrel entrypoints (dist/)"]
        RI[dist/index.js]
        AI[dist/lib/auth/index.js]
        SI[dist/lib/storage.js]
        CI[dist/lib/config.js]
        RQI[dist/lib/request/index.js]
        CLI[dist/lib/codex-cli/index.js]
    end

    subgraph modules["source modules"]
        AM[auth/auth.ts]
        SM[storage.ts]
        CM[config.ts]
        FP[request/failure-policy.ts]
        FH[request/fetch-helpers.ts]
        RLB[request/rate-limit-backoff.ts]
        RT[request/request-transformer.ts]
        RH[request/response-handler.ts ❌ excluded]
        SF[request/stream-failover.ts ❌ excluded]
        OB[codex-cli/observability.ts]
        ST[codex-cli/state.ts]
        SY[codex-cli/sync.ts]
        WR[codex-cli/writer.ts]
    end

    R --> RI
    A --> AI
    S --> SI
    C --> CI
    RQ --> RQI
    CL --> CLI

    AI --> AM
    SI --> SM
    CI --> CM
    RQI --> FP
    RQI --> FH
    RQI --> RLB
    RQI --> RT
    CLI --> OB
    CLI --> ST
    CLI --> SY
    CLI --> WR

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: test/public-api-contract.test.ts
Line: 87-102

Comment:
**cli barrel contract test only pins one export**

the `request` barrel test (lines 99–100) follows a clean pattern: positive assertions for what's meant to be public, plus explicit negative assertions (`handleResponse`, `withStreamFailover`) guarding against SSE internals leaking in. the cli barrel test only asserts `typeof cli.loadCodexCliState`, leaving the exports of `observability.ts` (`CodexCliMetrics`, `incrementCodexCliMetric`, and any others), `sync.ts` (account sync coordination), and `writer.ts` (output formatting) entirely unpinned.

all four files are now Tier A semver-stable under `codex-multi-auth/cli`. if any of those modules rename or drop an export, the contract test won't catch it — the breakage is silent. given that `sync.ts` handles account sync coordination (which has concurrency-sensitive state), an unexpected rename or removal at that layer is precisely what you want the contract test to surface.

consider mirroring the `request` barrel pattern: add at least one positive assertion per file in the barrel, or add negative assertions for symbols that should NOT be reachable via the cli entrypoint (similar to the `handleResponse`/`withStreamFailover` guards).

```ts
// example additions
expect(typeof cli.incrementCodexCliMetric).toBe("function"); // observability.ts
expect(typeof cli.loadCodexCliState).toBe("function");       // state.ts (already present)
// pin at least one named export from sync.ts and writer.ts
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "Hide internal reques..."}

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🚫 Review skipped — only excluded labels are configured. (1)

• skip-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3284be90-3913-4f0f-bda2-949c1bb831da

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/pr5-package-subpath-exports-latest

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch refactor/pr5-package-subpath-exports-latest

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}