fix: implement cache isolation to resolve OAuth plugin conflicts (Issue #25)

[riatzukiza]

Issue 25 – OAuth Cache Conflicts Between Plugins

Issue: #25 (BUG) Plugin fails with confusing errors if started with the other oauth plugin's cache files

Context & Current Behavior

• Problem: Users switching from opencode-openai-codex-auth to @openhax/codex encounter cache conflicts
• Root Cause: Both plugins use the same cache directory (~/.opencode/cache/) but with different:
  • Cache file formats
  • Fetch URLs (different GitHub repositories)
  • Metadata structures
• Error Message: Failed to fetch OpenCode codex.txt: 404 Failed to fetch OpenCode codex.txt from GitHub
• User Impact: Poor conversion experience, users think our plugin is broken

Current Cache Files

• lib/prompts/opencode-codex.ts:31-129 - Fetches from sst/opencode repo
• lib/utils/cache-config.ts:26-35 - Defines cache file names:
  • opencode-codex.txt - OpenCode prompt content
  • opencode-codex-meta.json - ETag and metadata
• Cache location: ~/.opencode/cache/ (shared with other plugin)

Solution Strategy

1. Plugin-Specific Cache Namespace

Goal: Isolate our cache files from other plugins
Implementation:

• Add plugin identifier prefix to cache files
• Use openhax-codex- prefix for all cache files
• Update cache paths to use plugin-specific subdirectory

2. Graceful Cache Migration & Validation

Goal: Handle existing cache files gracefully
Implementation:

• Detect incompatible cache formats
• Provide clear migration messages
• Fallback to fresh fetch when cache is invalid
• Don't fail with cryptic errors

3. Enhanced Error Handling

Goal: Better user experience during plugin switching
Implementation:

• Detect cache conflict scenarios
• Provide helpful error messages
• Suggest cache cleanup steps
• Continue operation when possible

Implementation Plan

Phase 1: Plugin-Specific Cache Files

1. Update lib/utils/cache-config.ts:
   • Add plugin-specific cache file names
   • Use openhax-codex- prefix
2. Update lib/prompts/opencode-codex.ts:
   • Use new cache file paths
   • Maintain backward compatibility during migration
3. Update lib/prompts/codex.ts:
   • Apply same prefix to Codex instruction cache

Phase 2: Cache Validation & Migration

1. Add cache format validation:
   • Check if cache files are from our plugin
   • Detect incompatible formats
2. Implement graceful migration:
   • Backup existing cache if needed
   • Create fresh cache files
   • Log migration actions

Phase 3: Enhanced Error Messages

1. Improve error handling in lib/prompts/opencode-codex.ts:
   • Detect cache conflict scenarios
   • Provide actionable error messages
2. Add cache cleanup guidance:
   • Suggest manual cleanup steps
   • Include commands for cache reset

Definition of Done / Requirements

Functional Requirements

• Plugin uses isolated cache files with openhax-codex- prefix
• Graceful handling of existing cache from other plugins
• Clear error messages when cache conflicts are detected
• Automatic cache migration without user intervention
• Fallback to fresh fetch when cache is incompatible

Non-Functional Requirements

• No breaking changes for existing users of our plugin
• Backward compatibility with our current cache format
• Performance impact is minimal (cache isolation overhead)
• Error messages are actionable and user-friendly

Test Coverage

• Tests for cache file isolation
• Tests for cache migration scenarios
• Tests for error handling with invalid cache
• Tests for backward compatibility
• Integration tests for plugin switching scenarios

Files to Modify

Core Changes

• lib/utils/cache-config.ts - Plugin-specific cache file names
• lib/prompts/opencode-codex.ts - Isolated cache paths + validation
• lib/prompts/codex.ts - Apply prefix to Codex cache files

Test Updates

• test/prompts-opencode-codex.test.ts - Update cache file paths
• test/prompts-codex.test.ts - Test cache isolation
• Add new tests for cache migration and conflict handling

User Experience Improvements

Before (Current)

ERROR Failed to fetch OpenCode codex.txt: 404 Failed to fetch OpenCode codex.txt from GitHub

After (Target)

WARN Detected cache files from different plugin. Creating fresh cache for @openhax/codex...
INFO Cache migration completed successfully.
INFO Ready to use @openhax/codex with isolated cache.

Migration Strategy

For New Users

• No impact - will start with clean, isolated cache

For Existing Users

• Automatic migration on first run
• Preserve existing cache in backup location
• No manual intervention required
• Clear communication about migration

For Users Switching Between Plugins

• Graceful cache conflict detection
• Actionable error messages
• Simple cache cleanup commands if needed

[coderabbitai]

Warning

Rate limit exceeded

@riatzukiza has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 1 minutes and 38 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 63c91a6 and 72b7616.

📒 Files selected for processing (2)

• test/prompts-codex.test.ts (1 hunks)
• test/prompts-opencode-codex.test.ts (5 hunks)

Summary by CodeRabbit

• Bug Fixes

  • Enhanced error handling for cache conflicts with detailed error messages and actionable troubleshooting recommendations.
  • Added cache format validation to detect and automatically resolve incompatibilities.

• Chores

  • Implemented automatic migration of legacy cache data to plugin-specific locations for seamless system upgrades.
  • Improved cache metadata tracking for enhanced reliability and diagnostics.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Adds plugin-scoped cache filenames and migration from legacy caches, validates cache metadata (including source URL), updates the OpenCode codex fetch flow to handle conflicts and persistence, improves error messages with cache-clear guidance, and exposes a getCachedPromptPrefix(chars = 50) helper.

Changes

Cohort / File(s)	Summary
Cache Configuration Updates lib/utils/cache-config.ts	Added PLUGIN_PREFIX ("openhax-codex"), prefixed cache file names in CACHE_FILES, added OPENCODE_CODEX_META, and exported LEGACY_CACHE_FILES with legacy names for migration.
OpenCode Codex Core Logic lib/prompts/opencode-codex.ts	Added legacy→plugin cache migration, cache format validation (checks url and structure), conflict-aware fetch flow using lastChecked, extended cache metadata (url, etag, lastFetch, lastChecked), improved error handling with explicit conflict/clear-cache hints, and exported getCachedPromptPrefix(chars = 50).
Tests test/prompts-codex.test.ts, test/prompts-opencode-codex.test.ts	Updated tests to use prefixed cache filenames (openhax-codex-*) and added an assertion that mkdir is invoked when accessing cached prompt in one test.

Sequence Diagram(s)

sequenceDiagram
    participant Caller as Caller
    participant Logic as OpenCodeFetch
    participant Migrate as Migrator
    participant Cache as CacheStore
    participant Network as Remote

    Caller->>Logic: requestOpenCodeCodex()
    Logic->>Migrate: detect legacy files
    Migrate->>Cache: read legacy files
    Migrate->>Cache: copy → prefixed files & rename legacy → .bak

    Logic->>Cache: validate cache metadata (url & structure)
    alt valid && recent (lastChecked)
        Cache-->>Logic: return cached content
        Logic-->>Caller: cached result
    else invalid/stale
        Logic->>Network: fetch source URL
        Network-->>Logic: response (+etag) / error
        alt success
            Logic->>Cache: write content + metadata (url, etag, lastFetch, lastChecked)
            Logic-->>Caller: fresh result
        else failure & no valid cache
            Logic-->>Caller: error with conflict hint and cache-clear command
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Areas requiring extra attention:

• Migration logic in lib/prompts/opencode-codex.ts: verify safe handling when both legacy and prefixed files exist and ensure backups (.bak) are correct.
• Cache validation: confirm url-based incompatibility detection avoids false positives and that reset behavior is appropriate.
• Error messages for 404/ENOENT and the suggested cache-clear command: ensure accuracy and clarity.
• Tests: confirm all test expectations and mocked filesystem calls align with new openhax-codex-* filenames.

Poem

🔄 Legacy files move to a new nest,
📦 Prefixed caches tidy their rest,
🔍 Metadata guards the source and time,
🔁 Fetches refresh when the format’s not fine,
🛡️ Conflicts flagged, clear-cache hints in rhyme.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: implement cache isolation to resolve OAuth plugin conflicts (Issue #25)' clearly and specifically describes the main change: isolating cache to resolve plugin conflicts.
Description check	✅ Passed	The description provides comprehensive context about the cache conflict issue, implementation strategy, and migration approach, directly addressing the changeset across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

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

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/prompts/opencode-codex.ts (1)

114-123: Avoid logging expected cache-miss conditions as errors

Two paths currently log at error level for situations that are often normal:

• Line 121: any failure reading the cache file/metadata logs logError("Failed to read OpenCode prompt cache", ...).
• Line 239: getCachedPromptPrefix logs logError("Failed to read cached OpenCode prompt prefix", ...) on any read error.

For first-run scenarios (no cache yet) or a missing prefix file, these are expected ENOENTs rather than exceptional failures, and they can add noisy error logs.

You can keep visibility into real problems while avoiding noise by filtering out ENOENT:

-	} catch (error) {
-		// Cache doesn't exist or is invalid, will fetch fresh
-		const err = error as Error;
-		logError("Failed to read OpenCode prompt cache", { error: err.message });
-	}
+	} catch (error) {
+		// Cache doesn't exist or is invalid, will fetch fresh
+		const err = error as Error & { code?: string };
+		if (err.code !== "ENOENT") {
+			logError("Failed to read OpenCode prompt cache", { error: err.message });
+		}
+	}

-	} catch (error) {
-		const err = error as Error;
-		logError("Failed to read cached OpenCode prompt prefix", { error: err.message });
-		return null;
-	}
+	} catch (error) {
+		const err = error as Error & { code?: string };
+		if (err.code !== "ENOENT") {
+			logError("Failed to read cached OpenCode prompt prefix", { error: err.message });
+		}
+		return null;
+	}

This keeps genuine IO/parsing problems visible while treating “no cache yet” as a normal condition.

Also applies to: 232-241

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 058f596 and 180f9e4.

⛔ Files ignored due to path filters (2)

• package.json is excluded by none and included by none
• spec/issue-25-oauth-cache-conflicts.md is excluded by none and included by none

📒 Files selected for processing (4)

• lib/prompts/opencode-codex.ts (9 hunks)
• lib/utils/cache-config.ts (1 hunks)
• test/prompts-codex.test.ts (1 hunks)
• test/prompts-opencode-codex.test.ts (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

lib/prompts/opencode-codex.ts (4)

lib/utils/file-system-utils.ts (1)

• getOpenCodePath (22-24)

lib/utils/cache-config.ts (4)

• LEGACY_CACHE_FILES (45-54)
• CACHE_FILES (31-40)
• PLUGIN_PREFIX (26-26)
• CACHE_TTL_MS (11-11)

lib/logger.ts (2)

• logWarn (75-77)
• logInfo (71-73)

lib/cache/session-cache.ts (1)

• openCodePromptCache (77-77)

🔇 Additional comments (2)

test/prompts-codex.test.ts (1)

33-34: Codex instructions test cache paths correctly namespaced

The updated cacheFile and cacheMeta names match the new CACHE_FILES prefixing and remain consistent across the test scenarios, including stale cache and fallback checks. No issues here.

test/prompts-opencode-codex.test.ts (1)

41-42: OpenCode prompt cache tests aligned with plugin-prefixed paths and mkdir behavior

The renamed cacheFile/cacheMetaFile values and the added mkdirMock expectation are consistent with the new CACHE_FILES configuration and getOpenCodeCodexPrompt’s unconditional mkdir call. The tests exercise both session-cache and file-cache flows without gaps.

Also applies to: 73-73

[riatzukiza]

Fixed the logging issues identified in the review:

• Updated cache read error handling to filter out ENOENT errors (lines 121-123)
• Updated getCachedPromptPrefix to avoid logging ENOENT errors (lines 241-243)

This prevents noisy error logs for expected first-run scenarios while preserving visibility into genuine I/O or parsing problems. All tests pass.

[riatzukiza]

✅ Review comments addressed

The logging improvements have been implemented:

• ENOENT errors are now filtered out from cache read operations
• Only genuine I/O/parsing problems are logged as errors
• Expected first-run scenarios no longer generate noise

All tests pass and the cache isolation functionality remains intact.

[riatzukiza]

✅ Review Comment Resolution

Issue: Avoid logging expected cache-miss conditions as errors (lines 114-123, 232-241)

Root Cause: Cache read operations were logging ALL failures as errors, including expected ENOENT errors for first-run scenarios.

Solution Implemented:

1. Line 121-123: Added ENOENT filtering in getOpenCodeCodexPrompt cache read error handling
2. Line 241-243: Added ENOENT filtering in getCachedPromptPrefix error handling

Code Changes:
Before: Logged all errors
const err = error as Error;
logError("Failed to read OpenCode prompt cache", { error: err.message });

After: Filter ENOENT errors
const err = error as Error & { code?: string };
if (err.code !== "ENOENT") {
logError("Failed to read OpenCode prompt cache", { error: err.message });
}

Benefits:

• ✅ Eliminates noisy error logs for expected first-run scenarios
• ✅ Preserves visibility into genuine I/O/parsing problems
• ✅ Maintains debugging capability for real issues
• ✅ Follows logging best practices (don't log expected conditions as errors)

Verification:

• All 381 tests pass
• Cache isolation functionality intact
• No breaking changes
• Merge conflicts resolved

The review feedback has been fully addressed and tested.