Files

## What This Skill Does (and Doesn't) **YES:** Organize existing files, find duplicates, analyze disk usage, batch rename/move, clean up clutter **NO:** Open files, create files/folders, copy files, extract archives, basic file browsing — use standard file operations for those This is a power tool for reorganization, not a replacement for basic file commands. ## Path Security (Non-Negotiable) - Canonicalize ALL paths before any operation: resolve `..`, `~`, symlinks, then validate - After canonicalization, reject if path is outside user's home or explicitly allowed directories - NEVER follow symlinks during traversal — report them as "symlink to X, skipped" and let user decide - Block these paths absolutely: `/`, `/etc`, `/var`, `/usr`, `/System`, `/Library`, `C:\Windows`, `C:\Program Files` - Paths containing `..` after canonicalization = reject with explanation ## Fast Path vs Safe Path **Fast path (1-9 files):** Execute immediately with brief confirmation: "Move 3 files to Archive? [Y/n]" **Safe path (10+ files):** Create manifest, show summary, require explicit "yes" or review This prevents confirmation fatigue for simple operations while protecting bulk actions. ## Trash Handling - Use the operating system's native trash: `trash` CLI on macOS/Linux, Recycle Bin API on Windows - If OS trash unavailable, move to `~/.local/share/file-organizer-trash/` with metadata sidecar - Metadata sidecar (JSON): original path, deletion timestamp, operation ID — NOT path-in-filename - Never permanently delete without explicit "permanently delete" or "empty trash" command ## Undo System - Every operation creates an undo record in `~/.local/share/file-organizer/undo/TIMESTAMP.json` - Record contains: operation type, source paths, destination paths, checksums of moved files - "Undo last" reverses the most recent operation using the record - Undo records expire after 30 days — warn user before expiry - NO shell scripts for undo — JSON metadata only, executed by the agent ## Symlink Policy - During directory traversal: skip symlinks, report them separately - "This folder contains 12 symlinks pointing outside — review before proceeding?" - Never follow symlinks automatically — they're a classic attack vector - User can explicitly request "follow symlinks" but must confirm each external target ## Duplicate Detection (Scalable) - Phase 1: Group by exact size (instant, no I/O) - Phase 2: Hash first 4KB of same-size files (fast filter) - Phase 3: Full hash only for files matching phase 2 - For >10,000 files, require confirmation: "This will take ~15 minutes. Proceed?" - Cache hashes in `~/.local/share/file-organizer/hash-cache.db` (SQLite) with mtime invalidation ## Bulk Operations - **Batch rename:** Preview ALL transformations if <50 files, first/last 10 if more, always show total count - **Batch move:** Verify destination has space before starting, atomic per-file with rollback on error - **Progress:** Update every 5% or 30 seconds, whichever is less frequent — not per-file spam - **Error handling:** On ANY error, stop, report what succeeded/failed, offer "continue skipping errors" or "rollback completed" ## Organization Proposals - Analyze directory contents FIRST, then propose: "80% images, 15% videos, 5% docs — organize by date or type?" - Always show concrete examples: "vacation-photo.jpg → 2024/06-June/vacation-photo.jpg" - Preserve original filenames unless user requests rename pattern - Create `.file-organizer-manifest.json` in destination documenting the reorganization for future reference ## Size Analysis - Top consumers by directory, not individual files — users think in folders - Flag known safe-to-delete: node_modules, __pycache__, .gradle, build/, target/, Pods/ - Calculate actual vs apparent size (sparse files, hardlinks) - For cleanup suggestions, always state recoverability: "Deleting node_modules: fully recoverable with npm install" ## Platform Specifics - macOS: Respect .app bundles (they're directories), use `trash` via Homebrew if available - Windows: Use long path prefix `\\?\` for paths >260 chars, use shell API for Recycle Bin - Linux: XDG trash spec (`~/.local/share/Trash/`), handle different filesystem capabilities ## Limits and Failures - Refuse operations on >100,000 files without explicit override: "This affects 250K files. Type 'I understand' to proceed" - If manifest would exceed 10MB, paginate: "Showing batch 1 of 15 (page through with 'next')" - Network drives: detect by response time, warn about reliability, suggest local copy first - Disk full: check before starting, reserve 1% headroom, fail gracefully with partial completion report