# IDEA.md – a bulk file renamer for Windows and macOS This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on what was learned building File Renamer, a desktop program for Windows and macOS written in Rust with Claude Code. ## 1. What to build A desktop program that **renames many files at once** by rules, with a preview before anything happens and the ability to undo afterwards. The model is Bulk Rename Utility (BRU), which only exists for Windows. The goal is the same tool on Windows and macOS – the same rules, the same rule files, the same safety – and it should compile for Linux too. The program must have: - **A path field and a folder tree** (drives and volumes, the home folder; subfolders are read only when expanded). Dragging a folder into the window works. - **A file list** with the columns Name, New Name, Size, Modified and Status. Changed names are highlighted, conflicts are shown in red with the reason. Sorting on every column, **natural sorting** on name (`report2` before `report10`). - **A simple filter**: a wildcard mask (`*.jpg;*.png`), match case, files, folders, hidden, subfolders. - **Eleven panels** below the list, each with an on/off box and a reset button (R). They run in numerical order on every selected file: | # | Panel | Does | |---|---|---| | 1 | RegEx | Regular expression with `\1` (also `$1`, `${name}`). *Simple*: wildcards `*`/`?` that capture. *Inc. Ext.* includes the extension | | 2 | Name | Keep / Remove / Fixed / Reverse | | 3 | Replace | Literal find and replace, *Match Case*, *First* (first match only) | | 4 | Case | Same / lower / UPPER / Title / Sentence, with exception words (`PDF:iPhone`) | | 5 | Remove | First n, last n, from–to, characters, words, crop before/after, digits, letters, symbols, accents, high ASCII, trim, double spaces, leading dots | | 6 | Move/Copy Parts | Move or copy the first/last n characters to the start, the end or a position, with a separator | | 7 | Add | Prefix, insert at a position (negative counts from the end), suffix, *Word Space* (space before capitals) | | 8 | Auto Date | Created, modified, accessed, now or EXIF *Picture taken*; prefix or suffix; fixed formats (DMY, MDY, YMD …) or a custom strftime format; separators within the date and towards the name; four-digit year; time offset in hours | | 9 | Append Folder Name | The folder name, one or more levels, as prefix or suffix, with a separator | | 10 | Numbering | Prefix / suffix / both / insert; start, step, padding, separator; *Break* (restart when the first n characters change); per folder; base 10, 2, 8, 16, 36, letters (A … Z, AA …), Roman numerals | | 11 | Extension | Same / lower / UPPER / Title / New / Extra / Remove | - **A preview** that recalculates as you type. - **Rename**, **Reset** and **Revert** (undo the latest batch, even after a restart), with a confirmation dialog before renaming. - **Rule files**: all the panels and the filter saved as a `.renamer` file in TOML. The file name shows in the title bar. The latest settings are restored at start. - **A status bar** with the number of objects, selected, to rename and conflicts. **Not** included: BRU's panels 12–14 (advanced filters, copy/move to another location, attributes, timestamps, JavaScript), importing BRU's `.bru` files, a light theme. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **Rust** (edition 2024), a Cargo workspace with two crates. - **Important: a UI-free core** (`core`) with the rules, the check, the rename, scanning, rule files and natural sorting. Everything is tested without a window. One file per panel under `rules/`. `Rules` holds the settings (serde), `Compiled` runs them in numerical order. - **The steps see the name without its extension.** Only RegEx with *Inc. Ext.* and Extension touch the extension. - **eframe/egui** (0.36) with wgpu for the window. Can be swapped. - **The preview only recalculates when the rules or a generation counter change.** Bump the generation when the list or the selection changes, or the list shows stale names. - **The menu as data**, egui in the window on Windows and the system menu bar on macOS (`muda`), with keyboard shortcuts from a single source. Menu and keyboard produce the same `Action`. - `regex`, `chrono` for dates, an EXIF reader for *Picture taken*, `serde` + `toml` for rule files. - **Per-user data**: settings and the log (`journal.json`) in the user's data directory. - Packaging: Windows cross-compiled with `cargo xwin` from Linux/WSL, an NSIS installer and a portable zip; macOS `aarch64-apple-darwin`, `.app` and dmg. ## 3. Decisions that turned out to matter **Positions are counted in characters, never in bytes.** "Remove the first three" must take `Års` off `Årsmöte`. In UTF-8, å takes two bytes. Keep all position arithmetic in one helper module (`text.rs`) and use it in every panel. **No rename runs if any selected row has an error.** A half-finished rename, where half the files got new names, is harder to sort out than none at all. Check every row against the others and against the file system before renaming: - duplicates among the new names - names that already exist on disk (and aren't one of the files being renamed) - an empty name - names that are invalid on Windows: `<>:"/\|?*`, control characters, the reserved names `CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9` (also with an extension), a trailing dot or space, a leading space (allowed, but almost always a leftover of a removed part), `.` and `..`, and over 255 – counted both in UTF-16 units (NTFS) and in UTF-8 bytes (APFS) **Compare names ignoring case.** NTFS and APFS normally don't distinguish `Photo.jpg` from `photo.jpg`. On a case-sensitive file system the check is stricter than it needs to be, but never too lax. **Windows naming rules apply on every platform.** A file with a colon in its name can be created on a Mac, but not copied to a Windows drive or a USB stick. **Rename in two steps.** Every file first gets a temporary name and then its new one. That's what makes `a`→`b` and `b`→`a` in the same batch work, and `photo.jpg`→`Photo.jpg` work on a case-insensitive file system – where the system otherwise says the target already exists, because it's the file itself. **Deepest first.** With subfolders, both a folder and files in it can be renamed. Take the files first, while their paths are still right, and the folder last. Split the renames into groups per folder; each group does its two steps. **All or nothing.** If a rename fails, the ones already done are rolled back in reverse order, including earlier groups', and the error is reported with the file's name. **The log and Revert.** Save every completed batch in `journal.json`. Revert renames back in reverse order (the folders, renamed last, go back first), even after a restart – but only after checking that every file still exists under its new name and that nothing else has taken its old one. Otherwise Revert refuses and says which rows don't match. **Numbering follows the list order** among the selected files, and the list sorts naturally. Then the numbers are the ones you see. **Readable rule files.** TOML with `#[serde(default)]` on every panel, so missing fields get their default and older files still open. **Developer hooks from day one**, so an agent can review the interface with no one at the screen: - `_WINDOW=1440x900@10,30` – size and position - `_SCREENSHOT=file.ppm`, `_SCREENSHOT_DELAY=N` – save an image of the window and exit - `_DATA_DIR=dir` – settings and log out of the way - `_DEBUG_MENU=File` – open a menu in the window - `_DEBUG_STATE=…` – steps in order: `folder=path`, `rules=file.renamer`, `select=all` or `select=a.jpg+b.jpg`, `sort=size|modified|new`, `notree`, `do=rename|revert`, `do=confirm` ## 4. Pitfalls - **Don't count positions in bytes.** Count characters everywhere (see section 3), and test with å, ä and ö. - **Don't trust `rename` to refuse to overwrite.** On macOS, `rename` silently replaces a file that already exists. If a file has appeared under the new name since the preview, it would vanish. Check the target and never overwrite; have a test for it. - **Don't let a custom date format crash the program.** chrono panics on an unknown `%` code, and the format is typed while the preview runs – a half-typed code is enough. Validate the format first and show an unknown format as written. - **Don't forget reserved names with an extension.** `CON.txt` is as invalid as `CON` on Windows. - **Don't rename the folder before the files in it.** The paths to the files are wrong after that. Deepest first. - **Bump the generation when the list or selection changes**, or the preview shows stale names. - **Don't put the system Cut/Copy/Paste in the macOS menu**; the native menu takes ⌘C/⌘V away from text fields. - **An empty reader drive (A:, a DVD with no disc) must not make the folder tree sluggish.** Read subfolders only when they're expanded. - **A fully covered window isn't drawn on macOS**, and then no screenshot is taken. Place the window visibly. - **Check the interface's characters on Windows.** A character the font lacks (e.g. `→`) is drawn as an empty box. Look at a screenshot from Windows, not just macOS. ## 5. Requirements and measurements - The core: File Renamer has 75 unit tests. Every panel has its own tests, and the rename is tested against real files in a temporary directory. - Examples to test against: - Remove first 3 on `Årsmöte` gives `möte` - Numbering with letters: 27 → `AA`; Roman: 1994 → `MCMXCIV` - Replace `BR`→`BRU4` followed by Remove first 3 on `BR_setup…` gives `4U_setup…` (the steps run in order) - `a`↔`b` in the same batch, with the content checked afterwards - `photo.jpg`→`Photo.jpg` on a case-insensitive file system - a rule file with a panel missing can be read - A rename of 11 objects followed by Revert must give exactly the same file list as before (`diff` empty), and the log must be empty. ## 6. How it's verified - `cargo clippy --workspace --all-targets` with no warnings, `cargo test --workspace --release`, and `cargo check --target` for the platform you're not on (catches errors in `#[cfg(windows)]` code). - **Tests in the core**: every panel, positions in characters, the check (duplicates, already exists, invalid names, case), the rename (crossing renames, case-only renames, folder and file in the same batch, a failed rename rolled back, no overwriting), Revert (refuses when the old name has been taken), rule files round-tripped. - **The interface is reviewed with screenshots** from the real binary using the developer hooks. - **Rename and Revert are tried against real files through the app**, with the data directory out of the way and a comparison of the folder's contents before and after. - Use **made-up files and a neutral path** in screenshots meant for others – not the home folder. ## 7. Way of working - **Plan first**: go through the model (Bulk Rename Utility) panel by panel and write a table of what each panel does and what's deliberately left out. Split the build into tasks: skeleton, the rules, the file list, safety, the interface, rule files, verification on the other platform. - **Ask about real decisions**, for example which panels to include and how to handle departures from the model. - **One task at a time**, with the measurement in the closing comment. - **What needs a human** – the installer, the menu and keys on the other platform, the folder tree with real drives – becomes a separate verification task. ## 8. The prompt > Build a desktop program for [Windows and macOS, and it should compile for Linux] in [Rust with eframe/egui] that renames many files at once, modelled on Bulk Rename Utility: a file list with the old and new name side by side, and eleven rule panels that run in order on every selected file. > > Read all of IDEA.md below first. It describes the panels, the safety rules, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Go through the model and write a plan. Split the work into tasks and say what's not included. > 2. Build the rules, the check and the rename in a library without an interface, with tests, before building the window. Positions are counted in characters. > 3. No rename may run if any row has an error, renaming happens in two steps, and Revert must work even after a restart. > 4. Build the developer hooks (window size, screenshot, data directory, debug steps) early and review every interface change with a screenshot from the real binary. > 5. Try rename and Revert against real files in a temporary folder, and compare the folder's contents before and after. > > Panels I want in addition to or instead of the eleven: [list, or "the eleven in IDEA.md"]. > > [paste IDEA.md here]