cache-clear

Step 1: Validate Scope

Check that scope is one of: all, expired, pattern

IF scope is invalid:

• Error: "Invalid scope"
• List valid scopes: all, expired, pattern
• STOP

IF scope == "all" AND confirmed != true:

• Set dry_run = true (force preview first)
• Continue to show what would be deleted
• Then ask for confirmation

Step 2: Build CLI Arguments

Construct arguments array from inputs:

args = ["cache", "clear"]

// Add scope
if (scope === "all") args.push("--all")
if (scope === "expired") args.push("--expired")
if (scope === "pattern" && filter?.pattern) {
  args.push("--pattern", filter.pattern)
}

// Add dry-run flag if requested or scope=all without confirmation
if (dry_run || (scope === "all" && !confirmed)) {
  args.push("--dry-run")
}

Step 3: Delegate to CLI Helper

USE SKILL: cli-helper Operation: invoke-cli Parameters:

{
  "command": "cache",
  "args": ["clear", ...scope_flags, ...dry_run_flag],
  "parse_output": true
}

The cli-helper will:

1. Validate CLI installation
2. Execute: fractary codex cache clear [--all|--expired|--pattern <p>] [--dry-run] --json
3. Parse JSON output
4. Return results

Step 4: Process CLI Response

The CLI returns JSON like:

Dry-Run:

{
  "status": "success",
  "operation": "cache-clear",
  "dry_run": true,
  "would_delete": {
    "count": 4,
    "size_bytes": 8483,
    "entries": [
      {
        "uri": "codex://fractary/old-service/README.md",
        "size_bytes": 5242,
        "reason": "Expired 5 days ago"
      }
    ]
  }
}

Actual Deletion:

{
  "status": "success",
  "operation": "cache-clear",
  "dry_run": false,
  "deleted": {
    "count": 4,
    "size_bytes": 8483,
    "entries": [...]
  },
  "cache_stats": {
    "before": {"total_entries": 42, "total_size_bytes": 3355443},
    "after": {"total_entries": 38, "total_size_bytes": 3347960}
  }
}

IF status == "success" AND dry_run == true:

• Display preview (see OUTPUTS section)
• IF scope == "all": Ask for confirmation
• STOP (wait for user action)

IF status == "success" AND dry_run == false:

• Display deletion results (see OUTPUTS section)
• DONE ✅

IF status == "failure":

• Extract error message from CLI
• Return error to caller
• DONE (with error)

Step 5: Handle Confirmation (scope=all only)

IF scope == "all" AND dry_run preview shown:

• Ask user: "Delete entire cache? This will remove {count} entries ({size})"
• Options:
  • "Yes, delete all" → Retry with confirmed=true, dry_run=false
  • "Cancel" → STOP
• STOP (wait for user choice)

Step 6: Return Results

Display formatted output to user.

COMPLETION: Operation complete when results shown.