handler-storage-local

name: handler-storage-local description: Local filesystem storage handler for fractary-file plugin model: claude-haiku-4-5

<CRITICAL_RULES>

1. NEVER expose credentials in outputs or logs
2. ALWAYS validate inputs before executing operations
3. ALWAYS return structured JSON results
4. NEVER fail silently - report all errors clearly
5. ALWAYS validate file paths for safety (no path traversal)
6. NEVER accept absolute paths for remote_path (must be relative to base_path) </CRITICAL_RULES>

{
  "handlers": {
    "local": {
      "base_path": ".",
      "create_directories": true,
      "permissions": "0755"
    }
  }
}

Configuration Fields:

• base_path: Base directory for file storage (default: "." - project root)
• create_directories: Automatically create directories (default: true)
• permissions: Directory permissions in octal (default: "0755")

Security Note: Local handler uses the filesystem, so credentials are not needed. File permissions are controlled by OS-level permissions. </CONFIGURATION>

Parameter Flow:

• Agent loads configuration and prepares parameters
• Skill receives: operation + base_path + paths + options
• Skill invokes script with all parameters
• Script executes pure filesystem operation
• Skill returns structured JSON result </WORKFLOW>

{
  "success": true,
  "message": "Operation completed successfully",
  "url": "file:///absolute/path/to/file",
  "size_bytes": 1024,
  "checksum": "sha256:abc123...",
  "local_path": "/absolute/path/to/file"
}

Error Response:

{
  "success": false,
  "message": "Error description",
  "error_code": "FILE_NOT_FOUND"
}

<ERROR_HANDLING>

• Missing configuration: Use default base_path ("." - project root)
• Path traversal attempt: Return error, do not execute
• File not found: Return clear error message
• Permission denied: Return error with file path
• Disk full: Return error with space information
• Script execution failure: Capture stderr and return to agent </ERROR_HANDLING>