cache-management

# cache-management skill

Use this skill when the user wants to:
- Understand why a task did or did not use the cache
- List or inspect cache entries
- Clear all or specific task caches
- Tune input glob patterns to improve cache hit rate

## How caching works

For each task:

1. Collect all files matching the `inputs` glob patterns (sorted by path)
2. Hash each file: SHA-256(filePath + ":" + fileContent)
3. Combine into a cache key: SHA-256(taskName + command + join(fileHashes))
4. Truncate to 16 hex characters: e.g. `a3f2b1c4e2d1f890`
5. Check `.mtr-cache/<taskName>/<key>/meta.json`
   - Hit: skip task, restore output files, mark status "cached"
   - Miss: run task, save outputs + meta.json on success

The cache key changes whenever any input file changes (content or path).

## Cache directory layout

```
.mtr-cache/
  lint/
    a3f2b1c4e2d1f890/
      meta.json          { ts, durationMs, exitCode, command }
    b81d220e1f4a3c9d/
      meta.json
  build/
    5c1a8e90f7b2d041/
      meta.json
      outputs/
        packages/server/dist/mtr.js
        packages/web/dist/index.html
```

## Listing cache entries

```bash
mtr cache ls
```

Or via web UI: Cache tab.

Output columns: TASK, KEY, SIZE, CREATED, COMMAND

## Clearing cache

```bash
# Clear everything
mtr cache clear

# Clear one task only
mtr cache clear build
mtr cache clear lint

# Or via HTTP API
curl -X DELETE http://localhost:3300/api/cache
curl -X DELETE http://localhost:3300/api/cache/build
```

## When a task is not being cached

Common reasons:

1. No `inputs` defined - cache key will be constant for the same command, so it will hit after the first run. If inputs are left empty, any file change will not affect the key.
2. Input glob too narrow - the file that changed is not covered by the glob pattern.
3. `--force` flag was used - bypasses cache entirely.
4. Task failed - failed runs are not written to cache.
5. Outputs list missing - task runs but output files are not restored on cache hit (they are simply re-run).

## Debugging cache misses

Check what files are covered by your inputs:

```bash
# List files matching a glob (requires glob CLI or node)
node -e "
const {glob} = require('glob');
glob('packages/*/src/**/*.ts').then(files => {
  console.log(files.sort().join('\n'));
});
"
```

Check the cache key for a specific task:
```bash
# Not a direct command, but the cache key appears in mtr status output
mtr status
# Look at the CACHE column for the key
```

## Best practices

- Define `inputs` as tightly as possible (exclude generated files, node_modules, dist)
- Define `outputs` for tasks that produce files used by downstream tasks (build, codegen)
- Do not include large binary files in `inputs` - they increase hash computation time
- Run `mtr cache clear build` when you want to force a rebuild after a dependency install

## Cache API

```
GET  /api/cache
DELETE /api/cache
DELETE /api/cache/:taskName
```

GET response:
```json
[
  {
    "taskName": "lint",
    "key": "a3f2b1c4",
    "ts": 1742482200000,
    "sizeBytes": 4096,
    "command": "pnpm -r lint"
  }
]
```