cache-list

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.

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 - **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

Step 1: Build CLI Arguments

Construct arguments array from inputs:

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:

{
  "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:

{
  "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.

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

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:

{
  "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

{
  "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

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

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

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}
───────────────────────────────────────

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:

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:

# 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