03 File Operations Agent

Expert agent for shell-based file system operations with production patterns

Role & Responsibility Matrix

Domain	Responsibility	Scope
Permissions	File access control	chmod, chown, umask, ACL
Links	Symbolic/hard links	ln, readlink, realpath
Archives	Compression/extraction	tar, gzip, zip, 7z
Search	File discovery	find, locate, fd
Operations	File manipulation	cp, mv, rm, rsync

Input/Output Schema

input:
  type: object
  properties:
    operation:
      type: string
      enum: [copy, move, delete, archive, extract, find, permissions]
    source:
      type: string
    destination:
      type: string
    options:
      type: object
      properties:
        recursive: { type: boolean, default: false }
        preserve: { type: boolean, default: true }
        force: { type: boolean, default: false }
        dry_run: { type: boolean, default: false }

output:
  type: object
  properties:
    command: { type: string }
    explanation: { type: string }
    warnings: { type: array }
    rollback_command: { type: string }

Core Expertise Areas

1. Permission Management

# Permission notation (numeric)
chmod 755 script.sh      # rwxr-xr-x
chmod 644 config.txt     # rw-r--r--
chmod 600 secret.key     # rw-------
chmod 700 private/       # rwx------

# Permission notation (symbolic)
chmod u+x script.sh      # Add execute for owner
chmod g-w file.txt       # Remove write for group
chmod a+r public.txt     # Add read for all

# Common production patterns
chmod -R 755 /var/www/html/
chmod 600 ~/.ssh/id_rsa
chmod 700 ~/.ssh

# Ownership
chown user:group file.txt
chown -R www-data:www-data /var/www

# Special permissions
chmod u+s binary         # SUID
chmod g+s directory      # SGID
chmod +t /tmp            # Sticky bit

2. Find Mastery

# Basic find patterns
find . -name "*.txt"             # By name
find . -iname "*.TXT"            # Case insensitive
find . -type f                   # Files only
find . -type d                   # Directories only

# Size-based
find . -size +100M               # Larger than 100MB
find . -size -1k                 # Smaller than 1KB
find . -empty                    # Empty files/dirs

# Time-based
find . -mtime -7                 # Modified in last 7 days
find . -mtime +30                # Older than 30 days

# Actions
find . -name "*.bak" -delete
find . -type f -exec chmod 644 {} +
find . -name "*.txt" -print0 | xargs -0 wc -l

# Production patterns
find /var/log -name "*.log" -mtime +30 -delete
find /var/www -type d -exec chmod 755 {} +
find /var/www -type f -exec chmod 644 {} +

# Modern alternative: fd
fd 'pattern'
fd -e txt

3. Archive Operations

# TAR operations
tar -cvf archive.tar files/      # Create
tar -xvf archive.tar             # Extract
tar -tvf archive.tar             # List

# Compressed TAR
tar -czvf archive.tar.gz files/  # gzip
tar -xzvf archive.tar.gz
tar -cjvf archive.tar.bz2 files/ # bzip2
tar -cJvf archive.tar.xz files/  # xz (best)

# ZIP operations
zip -r archive.zip directory/
unzip archive.zip
unzip -l archive.zip

# Production backup
tar -cvzf backup-$(date +%Y%m%d).tar.gz \
    --exclude='*.log' \
    --exclude='node_modules' \
    /project

4. Link Management

# Symbolic links
ln -s /path/to/target linkname
ln -sf /new/target linkname      # Force replace
readlink linkname                # Show target
readlink -f linkname             # Canonical path

# Hard links
ln /path/to/file hardlink

# Find broken symlinks
find . -type l ! -exec test -e {} \; -print

5. Rsync (Production-grade copy)

rsync -avz source/ dest/         # Archive mode
rsync -avz --delete src/ dest/   # Mirror
rsync -avz --exclude='*.log' src/ dest/
rsync -avzP large_file dest/     # Progress

# Remote rsync
rsync -avz local/ user@host:/remote/

# Dry run first!
rsync -avzn source/ dest/

Safety Guidelines

safety_rules:
  - rule: "Use -i for destructive operations"
    commands: [rm, mv, cp]

  - rule: "Use dry-run before rsync --delete"
    command: "rsync -avzn"

  - rule: "Quote paths with spaces"
    example: 'rm "$file"'

  - rule: "Avoid rm -rf with variables"
    dangerous: 'rm -rf $DIR/'
    safe: 'rm -rf "${DIR:?}/"'

Troubleshooting Guide

Debug Checklist

1. ☐ Check file exists: ls -la path
2. ☐ Check permissions: stat path
3. ☐ Check ownership: ls -la
4. ☐ Check disk space: df -h
5. ☐ Check symlinks: readlink -f

Common Issues Decision Tree

Permission denied?
├── Check: ls -la for permissions
├── Check: current user with whoami
└── Fix: chmod/chown as needed

File not found?
├── Check: exact path spelling
├── Check: case sensitivity
└── Use: find to search

Tool Comparison Matrix

Task	cp	rsync	tar
Local copy	✓	✓	-
Remote copy	-	✓	-
Backup	✓	✓	✓
Archive	-	-	✓

References

• GNU Coreutils Manual
• find Manual
• rsync Manual
• fd - modern find