cache-manager

name	cache-manager
description	Manage OpenAPI spec cache and implementation state for efficient diff-based sync

Cache Manager

Smart caching system for saving tokens and time.

---

EXECUTION INSTRUCTIONS

When this skill is invoked, Claude MUST perform these steps in order:

Step 1: Determine Cache Mode

Check which mode is requested:

Flag	Mode	Action
--force	Force	Skip cache, always fetch fresh
--offline	Offline	Use cache only, fail if no cache
(default)	Smart	Check cache validity first

Step 2: Check Cache Existence

1. Use Read tool to check if .openapi-sync.cache.json exists
2. If file not found → Go to Step 5 (Full Fetch)
3. If file exists → Continue to Step 3

Step 3: Validate Cache (Smart Mode Only)

For Remote URL source (starts with http:// or https://):

1. Use WebFetch tool with prompt: "Make a HEAD request to check ETag and Last-Modified headers"
2. Compare response headers with cached values:
   • If ETag matches cached httpCache.etag → Cache is VALID
   • If Last-Modified matches cached httpCache.lastModified → Cache is VALID
   • Otherwise → Cache is STALE

For Local File source:

1. Use Bash tool: stat -f "%m" <filepath> (macOS) or stat -c "%Y" <filepath> (Linux)
2. Compare mtime with cached localCache.mtime:
   • If mtime equals cached value → Cache is VALID
   • If mtime is newer → Cache is STALE

Step 4: Use Cache (if VALID)

1. Read the cached spec from .openapi-sync.cache.json
2. Report to user: ✅ Using cached spec (ETag unchanged) or ✅ Using cached spec (file not modified)
3. Return the cached spec data

Step 5: Full Fetch (if STALE or no cache)

1. Report to user: 🔄 Fetching spec...
2. Fetch the spec:
   • Remote URL: Use WebFetch tool to GET the full spec
   • Local file: Use Read tool to read the file
3. Parse the JSON/YAML content
4. Validate it's a valid OpenAPI spec (has openapi or swagger field)
5. Update cache file (Step 6)

Step 6: Update Cache File

Write to .openapi-sync.cache.json with this structure:

{
  "version": "1.0.0",
  "_generated": "Auto-generated by /oas:sync. Do not edit manually.",
  "lastFetch": "<current ISO timestamp>",
  "specHash": "<SHA256 hash of normalized spec>",
  "source": "<original source URL or path>",
  "httpCache": {
    "etag": "<ETag header value or null>",
    "lastModified": "<Last-Modified header value or null>"
  },
  "localCache": {
    "mtime": "<file mtime in milliseconds or null>"
  },
  "meta": {
    "title": "<spec info.title>",
    "version": "<spec info.version>",
    "endpointCount": <number of endpoints>
  },
  "endpoints": { /* grouped by tag */ },
  "schemas": { /* schema name -> short hash */ }
}

---

ERROR HANDLING

For full error code reference, see ../../docs/ERROR-CODES.md.

Network Error During HEAD Request [E101, E102]

1. Log warning: "[E102] ⚠️ Network error checking cache, attempting full fetch..."
2. Try full fetch
3. If full fetch also fails AND cache exists:
   - Log: "[E102] ⚠️ Using cached version (network unavailable)"
   - Recovery: Use cached spec
4. If full fetch fails AND no cache:
   - Error: "[E101] ❌ Cannot fetch spec and no cache available"
   - Action: Abort operation

Cache File Corrupted [E602]

1. If JSON parse fails:
   - Log: "[E602] ⚠️ Cache corrupted, refetching..."
   - Recovery: Delete corrupted cache file, perform full fetch

Offline Mode Without Cache [E601]

1. If --offline flag AND no cache file:
   - Error: "[E601] ❌ Offline mode requires existing cache"
   - Fix: Run without --offline first to create cache
   - Action: Abort operation

Cache Write Failed [E604]

1. If cannot write cache file:
   - Warning: "[E604] ⚠️ Failed to write cache file"
   - Cause: Permission denied or disk full
   - Recovery: Continue without caching (operation succeeds)

---

REFERENCE: Cache File Locations

.openapi-sync.json       # User config (version controlled)
.openapi-sync.cache.json # Spec cache (add to .gitignore)
.openapi-sync.state.json # Implementation state (add to .gitignore)

REFERENCE: Hash Generation

To generate a spec hash for comparison:

1. Normalize the spec by sorting all object keys alphabetically
2. Convert to JSON string with no whitespace
3. Generate SHA256 hash
4. Use first 16 characters as short hash

REFERENCE: State File Structure

The .openapi-sync.state.json tracks implementation progress:

{
  "version": "1.0.0",
  "lastSync": "<timestamp of last /oas:sync>",
  "lastScan": "<timestamp of last codebase scan>",
  "implemented": {
    "<tag>": {
      "path": "<src path>",
      "endpoints": ["operationId1", "operationId2"],
      "files": { "api": "...", "types": "...", "hooks": "..." }
    }
  },
  "partial": {
    "<tag>": {
      "implemented": ["op1"],
      "missing": ["op2", "op3"]
    }
  },
  "missing": ["tag1", "tag2"],
  "coverage": {
    "total": { "endpoints": 100, "implemented": 80, "percentage": 80 },
    "byTag": { "<tag>": { ... } }
  }
}

---

ALGORITHM: Diff Computation

When computing diff between old and new spec:

Input: oldSpec (from cache), newSpec (freshly fetched)
Output: { added: [], removed: [], modified: [], unchanged: [] }

1. Create maps of endpoints by key (method + path)
2. For each endpoint in newSpec:
   - If not in oldSpec → added
   - If in oldSpec but different hash → modified
   - If in oldSpec and same hash → unchanged
3. For each endpoint in oldSpec:
   - If not in newSpec → removed
4. Return categorized changes

---

OUTPUT MESSAGES

Use these exact messages for consistency:

Situation	Message
Cache valid (ETag)	✅ Using cached spec (ETag unchanged)
Cache valid (mtime)	✅ Using cached spec (file not modified)
Cache stale	🔄 Spec changed, fetching updates...
No cache	📥 No cache found, fetching spec...
Force mode	🔄 Force mode: refetching spec...
Offline mode	📦 Offline mode: using cached spec
Network error	⚠️ Network error, using cached version

---

REFERENCE: Performance Optimization

For detailed performance optimization strategies, see ../../docs/PERFORMANCE.md.

Key optimizations implemented:

• HEAD requests for cache validation (minimal network cost)
• ETag/Last-Modified based caching (server-side validation)
• Local file mtime checking (no network needed)
• Retry strategy for transient failures