File Resource Map

English · Français · 中文

A macOS-only, local-first map for understanding a folder before reorganizing it. It turns the complete folder hierarchy into a zoomable view, lets you draft moves or removals without touching the real files, and exports a plain Markdown plan that you can review yourself or give to your own model to carry out.

The app only plans: nothing on disk changes while you work. Execution happens only if you choose it after reviewing the exported plan.

What it does

• Shows a large folder as a zoomable map.
• Lets you select one or several items and draft a move or a move to macOS Trash.
• Keeps every draft reversible with undo, redo, and clear controls.
• Exports the reviewed moves, Trash items, absolute paths, and safeguards as Markdown.
• Stays on your Mac: no account, cloud service, analytics, or database.

Safe by design

Inside the app: drafts exist only in the current browser session. File Resource Map never moves, renames, overwrites, or deletes real files. Before export, it rescans the active folder and stops if a source, destination, or name conflict has changed.

After export: the .md file is a readable plan, not a shell script or a one-click delete button. Open it and check every absolute path. You may keep it as a record, apply the plan yourself, or give the complete file to your own model with local file access and explicitly ask it to carry out the reviewed moves and Trash actions. The app does not run the plan; whether and how it is executed remains your decision and responsibility.

Requirements

• macOS
• Node.js 20 or newer
• npm

The current implementation uses the macOS folder chooser and the system open command. Windows and Linux are not supported.

Quick start

git clone https://github.com/bopensourcez/file-resource-map.git
cd file-resource-map
npm ci
./start-resource-map.command

The app first opens the repository's synthetic sample folder. Select Choose folder to map one of your own folders. The service is available only on 127.0.0.1 and uses a new random access token for each run. To stop it, press Ctrl+C in its terminal or close that terminal window.

From map to action

1. Inspect the map, then select items and draft moves or Trash actions.
2. Review the visual marks and the Drafts drawer; undo, redo, or clear anything that is not right.
3. Export the plan as .md, open it, and check every absolute source and destination path again.
4. Choose what happens next: keep the file as a record, carry out the plan yourself, or send the entire file to your own model that has permission to access your local files. Tell the model explicitly to follow only the reviewed plan.
5. After any real file operation, rescan the folder and verify the result.

The exported plan lists moves with their source, destination folder, and expected result; it also lists items intended for macOS Trash and the execution safeguards. See the concise usage guide for the in-app workflow.

Core interactions

• Click a node to select it; use Shift + click to add or remove items.
• Click a filename or Open to open it with the default macOS app.
• Drag an item onto a folder to draft a move.
• Use the visible Trash action, the context menu, Delete, or Backspace to draft a removal.
• Use the toolbar or ⌘Z / ⌘⇧Z to undo and redo.
• Rescan before exporting if the real folder may have changed.

Languages

The interface supports English, French, and Simplified Chinese from one codebase. It detects the browser language, falls back to English, and remembers an explicit choice. Filenames, paths, and user data are never translated. Terminology is kept consistent in the trilingual glossary.

Developer verification

npm ci
npm run verify

npm run verify runs the unit tests, production build, browser tests, and release checks. Generate sanitized documentation screenshots with npm run screenshots. After staging intended release files, use npm run verify:clean to repeat installation and all checks from a temporary clean copy of the Git index.

Project structure

fixtures/       synthetic sample data
public/         HTML and styles; generated bundle is ignored
scripts/        release, i18n, link, privacy, and screenshot checks
src/            application and translation source
tests/          server and browser tests
docs/           usage, terminology, and sanitized images

Help and feedback

For questions, ideas, and reproducible bugs, open an issue. Contributions are welcome; read CONTRIBUTING.md and CODE_OF_CONDUCT.md first. Report vulnerabilities privately as described in SECURITY.md, without exposing private paths or files in a public issue.

Known limitations

• macOS only.
• Drafts live only in the current browser session.
• The app creates plans but never executes them.
• Very large folders may require zooming out substantially.

License

MIT. See LICENSE. The English license file is the only legally authoritative license text. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.