toolsets/batch-ops/doc.md

# batch‑ops

Bulk file operations — rename, find‑and‑replace, aggregate stats, and batch copy.
Pure‑stdlib, safe‑by‑default (dry‑run preview before changes).

---

## When to Use This Toolset

- Renaming multiple files with regex patterns
- Finding and replacing text across many files
- Getting aggregate file statistics for a directory
- Copying files matching a glob pattern
- Any repetitive file operation best automated

---

## Process

```
Scope → Preview → Execute → Verify
```

1. **Scope**: Define the directory and pattern. Use dry‑run first!
2. **Preview**: Run with `dry_run=True` (default) to see what will change
3. **Execute**: Run with `dry_run=False` to apply changes
4. **Verify**: Check the results — run `batch_stats` to confirm

> ⚠️ **Always dry‑run first.** All destructive operations default to `dry_run=True`.

---

## Function Reference

### `batch_rename`

Rename files matching a regex pattern.

**When to use:** Normalizing filenames, adding prefixes/suffixes, date formatting.

**Args:** `directory` (str), `pattern` (str), `replacement` (str),
`dry_run` (bool, default true), `recursive` (bool, default false)

**Returns:** `{changes: [{old_name, new_name}], count, dry_run, directory}`

### `batch_find_replace`

Find‑and‑replace across text files.

**When to use:** Updating URLs, changing variable names, fixing typos across a codebase.

**Args:** `directory` (str), `pattern` (str, glob), `find_text` (str),
`replace_text` (str), `dry_run` (bool, default true), `recursive` (bool)

**Returns:** `{changes: [{file, matches}], total_files, total_matches, dry_run, directory}`

### `batch_stats`

Aggregate statistics for files in a directory.

**When to use:** Understanding project structure, finding large files, auditing.

**Args:** `directory` (str), `pattern` (str, default "*"), `recursive` (bool)

**Returns:** `{file_count, total_size_bytes, extensions, largest_file, smallest_file, directory}`

### `batch_copy`

Copy files matching a pattern to a destination.

**When to use:** Collecting files from subdirectories, backing up specific file types.

**Args:** `source_dir` (str), `dest_dir` (str), `pattern` (str, default "*"),
`recursive` (bool), `overwrite` (bool, default false)

**Returns:** `{copied: [...], count, skipped: [...], dest_dir}`

---

## Common Patterns

### Audit then Clean
```
batch_stats → understand file composition
batch_rename(dry_run=True) → preview changes
batch_rename(dry_run=False) → apply
batch_stats → verify result
```

### Find and Fix
```
batch_find_replace(dry_run=True) → see what matches
batch_find_replace(dry_run=False) → apply changes
git diff → verify changes are expected
```

---

## Guidelines

### Do
- **Always dry‑run first** — default is `dry_run=True`
- Use `batch_stats` before and after to verify changes
- Test regex patterns on a single file before batch‑renaming
- Use `text_diff` (from text‑transform) to verify find‑replace results

### Don't
- Don't batch‑rename without confirming the regex matches the right files
- Don't find‑replace in binary files — use glob patterns to restrict to text files
- Don't copy with `overwrite=True` without checking destination first
- Don't run recursive operations on root directories — scope tightly

### Safety Features
- All destructive ops default to `dry_run=True`
- `batch_rename` skips files where target name already exists
- `batch_copy` skips existing files unless `overwrite=True`
- All functions validate directory existence before operating