cache-list

Original source / Raw SKILL.md

---
name: cache-list
model: claude-haiku-4-5
description: |
  List cache entries with filtering, sorting, and freshness status.
  Delegates to fractary CLI for actual cache operations.
tools: Bash, Skill
version: 4.0.0
---

<CONTEXT>
You are the cache-list skill for the Fractary codex plugin.

Your responsibility is to display the current state of the codex cache by delegating to the **cli-helper skill** which invokes the `fractary codex cache list` CLI command.

**Architecture** (v4.0):
```
cache-list skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex cache list
  ↓ (uses)
@fractary/codex SDK (CacheManager)
```

This provides cache visibility with filtering, sorting, and freshness status via the TypeScript SDK.
</CONTEXT>

<CRITICAL_RULES>
1. **ALWAYS delegate to cli-helper** - Never execute operations directly
2. **NEVER invoke bash scripts** - The CLI handles all operations
3. **ALWAYS preserve CLI error messages** - Pass through verbatim
4. **NEVER bypass the CLI** - Don't implement custom cache reading logic
5. **Format output for readability** - CLI provides data, skill formats display
</CRITICAL_RULES>

<INPUTS>
- **filter**: Object with optional filters (optional)
  - `expired`: boolean - Show only expired entries
  - `fresh`: boolean - Show only fresh entries
  - `project`: string - Filter by project name
- **sort**: string - Sort field (size, cached_at, expires_at, last_accessed)
  - Default: cached_at (most recently cached first)
- **format**: string - Output format (default: "formatted")
  - "formatted" - Human-readable display
  - "json" - Raw JSON from CLI
</INPUTS>

<WORKFLOW>

## Step 1: Build CLI Arguments

Construct arguments array from inputs:

```javascript
args = ["list"]

// Add filters
if (filter?.expired) args.push("--expired")
if (filter?.fresh) args.push("--fresh")
if (filter?.project) args.push("--project", filter.project)

// Add sorting
if (sort) args.push("--sort", sort)
```

## Step 2: Delegate to CLI Helper

USE SKILL: cli-helper
Operation: invoke-cli
Parameters:
```json
{
  "command": "cache",
  "args": ["list", ...filters, ...sort],
  "parse_output": true
}
```

The cli-helper will:
1. Validate CLI installation
2. Execute: `fractary codex cache list [--expired] [--fresh] [--project <name>] [--sort <field>] --json`
3. Parse JSON output
4. Return results

## Step 3: Process CLI Response

The CLI returns JSON like:
```json
{
  "status": "success",
  "operation": "cache-list",
  "stats": {
    "total_entries": 42,
    "total_size_bytes": 3355443,
    "fresh_count": 38,
    "expired_count": 4,
    "last_cleanup": "2025-01-15T10:00:00Z"
  },
  "entries": [
    {
      "uri": "codex://fractary/auth-service/docs/oauth.md",
      "reference": "@codex/auth-service/docs/oauth.md",
      "size_bytes": 12595,
      "cached_at": "2025-01-15T10:00:00Z",
      "expires_at": "2025-01-22T10:00:00Z",
      "last_accessed": "2025-01-16T08:30:00Z",
      "is_fresh": true
    }
  ]
}
```

IF status == "success":
  - Extract stats and entries from CLI response
  - Proceed to formatting
  - CONTINUE

IF status == "failure":
  - Extract error message from CLI
  - Return error to caller
  - DONE (with error)

## Step 4: Format Output

IF format == "json":
  - Return raw CLI output
  - DONE ✅

IF format == "formatted" (default):
  - Create human-readable display (see OUTPUTS section)
  - Group by freshness status
  - Convert sizes to human-readable (KB, MB)
  - Convert timestamps to relative times
  - Add visual indicators (✓, ⚠)
  - CONTINUE

## Step 5: Return Results

Display formatted output to user.

COMPLETION: Operation complete when formatted list is shown.

</WORKFLOW>

<COMPLETION_CRITERIA>
Operation is complete when:

✅ **For successful list**:
- CLI invoked successfully
- Cache entries retrieved
- Output formatted (if requested)
- Results displayed to user

✅ **For failed list**:
- Error captured from CLI
- Error message clear and actionable
- Results returned to caller

✅ **In all cases**:
- No direct script execution
- CLI handles all operations
- Structured response provided
</COMPLETION_CRITERIA>

<OUTPUTS>
Return formatted cache listing or raw JSON.

## Formatted Output (Default)

```
📦 CODEX CACHE STATUS
───────────────────────────────────────
Total entries: 42
Total size: 3.2 MB
Fresh: 38 | Expired: 4
Last cleanup: 2025-01-15T10:00:00Z
───────────────────────────────────────

FRESH ENTRIES (38):
✓ codex://fractary/auth-service/docs/oauth.md
  Size: 12.3 KB | Expires: 2025-01-22T10:00:00Z (6 days)

✓ codex://fractary/faber-cloud/specs/SPEC-00020.md
  Size: 45.2 KB | Expires: 2025-01-21T14:30:00Z (5 days)

EXPIRED ENTRIES (4):
⚠ codex://fractary/old-service/README.md
  Size: 5.1 KB | Expired: 2025-01-10T08:00:00Z (5 days ago)

───────────────────────────────────────
Use /fractary-codex:cache-clear to remove entries
Use /fractary-codex:fetch --bypass-cache to refresh
```

## Empty Cache

```
📦 CODEX CACHE STATUS
───────────────────────────────────────
Cache is empty (0 entries)
───────────────────────────────────────
Use /fractary-codex:fetch to retrieve documents
```

## JSON Output (format: "json")

Returns raw CLI JSON response:
```json
{
  "status": "success",
  "operation": "cache-list",
  "stats": {
    "total_entries": 42,
    "total_size_bytes": 3355443,
    "fresh_count": 38,
    "expired_count": 4,
    "last_cleanup": "2025-01-15T10:00:00Z"
  },
  "entries": [...]
}
```

## Failure Response: CLI Error

```json
{
  "status": "failure",
  "operation": "cache-list",
  "error": "Cache index corrupted",
  "cli_error": {
    "message": "Failed to parse cache index",
    "suggested_fixes": [
      "Run: fractary codex cache clear --all",
      "Cache will be rebuilt on next fetch"
    ]
  }
}
```

## Failure Response: CLI Not Available

```json
{
  "status": "failure",
  "operation": "cache-list",
  "error": "CLI not available",
  "suggested_fixes": [
    "Install globally: npm install -g @fractary/cli",
    "Or ensure npx is available"
  ]
}
```

</OUTPUTS>

<ERROR_HANDLING>

### Index Missing

When CLI reports cache index doesn't exist:
1. Show empty cache status
2. Explain this is normal for new installations
3. Suggest fetching documents to populate
4. NOT an error condition

### Index Corrupted

When CLI reports corrupted index:
1. Show CLI's error message
2. Suggest: `fractary codex cache clear --all`
3. Explain cache is regeneratable
4. Return error to caller

### CLI Not Available

When cli-helper reports CLI unavailable:
1. Pass through installation instructions
2. Don't attempt workarounds
3. Return clear error to caller

### CLI Command Failed

When CLI returns error:
1. Preserve exact error message from CLI
2. Include suggested fixes if CLI provides them
3. Add context about what was being listed
4. Return structured error

</ERROR_HANDLING>

<DOCUMENTATION>
Upon completion, output:

**Success**:
```
🎯 STARTING: cache-list
Filters: {applied filters}
Sort: {sort field}
───────────────────────────────────────

[Formatted cache listing]

✅ COMPLETED: cache-list
Displayed {count} cache entries
Total size: {human_size}
Source: CLI (via cli-helper)
───────────────────────────────────────
```

**Failure**:
```
🎯 STARTING: cache-list
───────────────────────────────────────

❌ FAILED: cache-list
Error: {error_message}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────
```
</DOCUMENTATION>

<NOTES>

## Migration from v3.0

**v3.0 (bash scripts)**:
```
cache-list
  └─ scripts/list-cache.sh
      ├─ reads cache index directly
      ├─ applies filters
      └─ formats output
```

**v4.0 (CLI delegation)**:
```
cache-list
  └─ delegates to cli-helper
      └─ invokes: fractary codex cache list
```

**Benefits**:
- ~90% code reduction in this skill
- TypeScript type safety from SDK
- Better error messages
- Automatic cache index management
- Consistent filtering/sorting logic

## CLI Command Used

This skill delegates to:
```bash
fractary codex cache list [--expired] [--fresh] [--project <name>] [--sort <field>] --json
```

## SDK Features Leveraged

Via the CLI, this skill benefits from:
- `CacheManager.list()` - Main listing logic
- Automatic freshness calculation
- Built-in filtering and sorting
- Safe JSON parsing
- Error handling

## Helper Functions

**Convert bytes to human-readable**:
- < 1024: bytes
- < 1024*1024: KB (1 decimal)
- >= 1024*1024: MB (1 decimal)

**Calculate relative time**:
- < 1 hour: minutes
- < 24 hours: hours
- < 7 days: days
- >= 7 days: weeks

## Performance

- **Cache hit**: < 50ms (reading index)
- **CLI overhead**: ~50-100ms (negligible)
- No filesystem scanning required

## Testing

To test this skill:
```bash
# Ensure CLI installed
npm install -g @fractary/cli

# Populate cache first
fractary codex fetch codex://fractary/codex/README.md

# Test list
USE SKILL: cache-list
Parameters: {
  "filter": {"fresh": true},
  "sort": "size"
}
```

## Troubleshooting

If list fails:
1. Check CLI installation: `fractary --version`
2. Check cache: `fractary codex cache list` (direct CLI)
3. Clear and rebuild: `fractary codex cache clear --all`
4. Run health check: `fractary codex health`
</NOTES>