Add convenience filter flags for file selection

[gregpriday]

Summary

Add shorthand CLI flags (--ext, --max-depth, --min-size, --max-size) to simplify common file filtering scenarios without requiring glob patterns or profile modifications.

Problem Statement

Users currently need verbose glob patterns for common filtering tasks:

Current approach (verbose):

# Filter by extensions
copytree --filter "**/*.{js,ts,tsx}"

# Limit directory depth (not currently possible)
# Users must manually craft complex patterns

# Filter by file size (not currently possible)
# Users must use profiles or post-process results

This creates friction for quick, ad-hoc filtering tasks and makes the CLI less approachable for new users.

User Story

As a developer sharing code with AI assistants
I want simple flags to filter by extension, depth, and size
So that I can quickly scope my output without writing glob patterns or modifying profiles

Proposed Solution

Add four new CLI flags that work alongside existing --filter patterns:

# Filter by file extensions (shorthand)
copytree --ext .js,.ts,.tsx

# Limit traversal depth
copytree --max-depth 3

# Filter by file size
copytree --min-size 1KB --max-size 100KB

# Combined usage
copytree --ext .py --max-depth 2 --max-size 50KB

Affected Components

• bin/copytree.js - Add CLI option definitions
• src/pipeline/stages/FileDiscoveryStage.js - Implement filtering logic
• src/utils/ignoreWalker.js - Add depth limiting to traversal
• src/commands/copy.js - Pass options to pipeline

Implementation Approach

1. Extension Filter (--ext)

Convert comma-separated extensions to glob pattern:

// Input: --ext .js,.ts,.tsx
// Convert to: --filter "**/*.{js,ts,tsx}"

2. Depth Limiting (--max-depth)

Add depth tracking to walkWithIgnore():

// Track current depth relative to root
// Skip recursion when depth >= maxDepth

3. Size Filters (--min-size, --max-size)

Filter in FileDiscoveryStage after stat collection:

// Support human-readable units: 1KB, 10MB, 1GB
// Filter files outside the size range

Tasks

• Add CLI options in bin/copytree.js
  • --ext <extensions> - Comma-separated list (e.g., .js,.ts)
  • --max-depth <n> - Maximum directory depth (integer)
  • --min-size <size> - Minimum file size (supports KB, MB, GB)
  • --max-size <size> - Maximum file size (supports KB, MB, GB)
• Implement extension filter in FileDiscoveryStage.js
• Add depth limiting to ignoreWalker.js
• Implement size filtering in FileDiscoveryStage.js
• Add size parsing utility (human-readable → bytes)
• Add tests for each filter type
• Update CLI reference docs
• Add examples to README

Acceptance Criteria

• --ext .js,.ts correctly filters to only JavaScript/TypeScript files
• --max-depth 2 limits traversal to 2 levels deep from root
• --min-size 1KB excludes files smaller than 1024 bytes
• --max-size 10MB excludes files larger than 10485760 bytes
• Flags work in combination (e.g., --ext .py --max-depth 3 --max-size 100KB)
• Size parsing supports units: B, KB, MB, GB (case-insensitive)
• Error messages are clear for invalid input (e.g., negative depth, invalid size format)
• Existing --filter patterns still work and combine with new flags

Additional Context

Competitor examples:

• fd tool: fd --extension js --max-depth 3
• rg tool: rg --max-filesize 1M
• tree command: tree -L 3 (depth limiting)

Related configuration:

• Current max file size limit: 10MB (from src/config.js)
• Users can override via MAX_FILE_SIZE env var