cache-manager

# 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:

`