# resrm Development Guide Interested in the internals of resrm? This guide describes the current `resrm` codebase for maintainers. It focuses on how the project is organised, what calls what, how removed files flow into the trash store, and which invariants matter when changing the code. --- ## 1. What resrm does `resrm` is a command-line replacement for common `rm` usage. By default it moves files and directories into a per-user trash directory instead of permanently deleting them. Its core pipeline is: ```text Filesystem path | | resrm PATH v Per-user trash directory files/ moved file or directory metadata.json original path, uuid, deletion timestamp | | resrm --restore ID_OR_BASENAME v Restored path original location, or current directory if the original path exists ``` `resrm` deliberately keeps the implementation simple. It does not try to be a full desktop-trash implementation, filesystem snapshot tool, backup system, sandbox, or forensic recovery tool. The main data stored for a trashed item is: ```text id random uuid hex string orig_path resolved original path timestamp deletion time in ISO format ``` Permanent deletion is still available with: ```bash resrm --skip-trash PATH ``` Trash entries are also permanently removed by automatic pruning and by `resrm --empty`. --- ## 2. Repository layout The project is a small Python package under `src/resrm/`. ```text src/resrm/ __init__.py package marker cli.py console-script shim that imports core.main core.py CLI, trash metadata, restore, delete, prune logic tests/ __init__.py test package marker; no substantive tests currently pyproject.toml Poetry package metadata and console script poetry.lock locked dependency graph README.md user-facing documentation LICENCE GPL-3.0-or-later licence text .pre-commit-config.yaml Bandit, Black, and generic pre-commit hooks .gitea/workflows/ lint, dependency audit, SBOM and Grype workflows dist/ built release artifacts, not source ``` The installed command is configured in `pyproject.toml`: ```toml [tool.poetry.scripts] resrm = "resrm.cli:main" ``` `src/resrm/cli.py` currently contains only: ```python from resrm.core import main ``` All runtime behaviour is in `src/resrm/core.py`. --- ## 3. Main runtime flows ### 3.1 CLI entry flow All user-facing behaviour enters through `resrm.core.main()`. ```text resrm command -> resrm.cli.main import shim -> resrm.core.main(argv) -> prune_old_trash() -> build argparse parser -> install argcomplete hooks -> parse arguments -> dispatch to list, inspect, empty, restore, or remove branch ``` The supported action surface is: ```text PATH... move paths to trash by default -r allow directories -f, --force ignore missing paths and suppress interactive prompt -i ask before removing each path --skip-trash permanently delete instead of moving to trash -l, --list list current user's trash metadata --restore ITEM... restore by id prefix or exact basename --inspect ITEM... show metadata and filesystem details for matches --empty permanently remove all current user's trash entries -V, --version print installed package version ``` ### 3.2 Subcommand call graph ```mermaid flowchart TD A[resrm.core.main] --> B[prune_old_trash] B --> C[build argparse parser] C --> D[argcomplete.autocomplete] D --> E[parse args] E -->|--list| F[list_trash] E -->|--inspect| G[inspect_entry] E -->|--empty| H[empty_trash] E -->|--restore| I[restore_many] I --> J[find_candidates] J --> K[restore_one] E -->|paths| L[recursive rm-like directory check] L --> M[move_to_trash] M -->|default| N[move path into trash/files/uuid] N --> O[append metadata.json entry] M -->|--skip-trash| P[unlink or shutil.rmtree] ``` Current dependency direction is intentionally minimal: ```text cli.py imports core.main only core.py depends on argparse, argcomplete, json, os, shutil, sys, uuid, datetime, textwrap, importlib.metadata, pathlib, and standard library pwd/grp/stat imports in platform-specific helper paths ``` If the codebase grows, prefer moving focused behaviours into modules such as `trash.py`, `metadata.py`, and `restore.py` rather than making `core.py` larger. --- ## 4. Trash storage Trash storage is local filesystem state. There is no database server. For the effective uid running the command, `get_trash_paths()` returns: ```text trash directory: /files metadata file: /metadata.json ``` The base path is chosen by `get_trash_base_for_user(uid)`: ```text uid 0: /root/.local/share/resrm other uid: /.local/share/resrm fallback: Path.home()/.local/share/resrm ``` At import time, these globals are initialised: ```python TRASH_DIR, META_FILE = get_trash_paths() meta = load_meta() ``` Because `meta` is loaded once at import time, code that changes metadata on disk through a different metadata file must load and save that file explicitly. ### 4.1 Metadata format `metadata.json` is a JSON list of dictionaries. Example entry: ```json { "id": "f7f3e07ef50a4ec8be0a843f79fbdf1a", "orig_path": "/home/alice/project/file.txt", "timestamp": "2026-06-28T10:24:03.123456" } ``` Important details: ```text id generated with uuid.uuid4().hex orig_path stored as str(path.resolve()) after the move succeeds timestamp generated with datetime.datetime.now().isoformat() ``` There is no schema version field at the time of writing. If metadata format changes, decide whether old metadata files need migration or tolerant reading. ### 4.2 Trash object naming Trashed filesystem objects are moved to: ```text /files/ ``` The original basename is not used in the stored filename. User-facing commands expose the first eight characters through `short_id()`. Short ids are convenient but not guaranteed globally unique. `find_candidates()` treats the provided identifier as an id prefix after checking exact basename matches. --- ## 5. Data objects The codebase currently uses dictionaries rather than dataclasses. Metadata dictionaries are expected to contain: ```text id: str orig_path: str timestamp: str ``` Primary helpers that consume metadata entries: ```text short_id(fullid) returns first eight characters human_time(ts) displays ISO timestamp as YYYY-MM-DD HH:MM entry_display(entry, width) formats one list-style row; currently unused find_candidates(identifier) exact basename first, then id prefix restore_one(entry) moves files/ back to a target path inspect_entry(identifier) prints details from metadata and lstat ``` If adding richer metadata, update every helper that assumes these keys exist. --- ## 6. Removing paths The removal entry point is the path-processing branch in `main()`. ```text PATH... -> for each argument -> reject directory unless -r is provided -> move_to_trash(path, interactive, force, skip_trash) ``` `move_to_trash()` handles several behaviours: ```text missing path: -f/--force: ignore otherwise: print an rm-like error interactive mode: -i without -f prompts before removal --skip-trash: directory and not symlink: shutil.rmtree(path) otherwise: path.unlink() default trash mode: reject root-owned path unless running as euid 0 choose trash base from owner uid when possible move path to files/ append metadata entry to that owner's metadata.json ``` ### 6.1 Directory handling The CLI mimics common `rm` behaviour for directories: ```text directory without -r: print "Is a directory" and skip directory with -r: move the directory tree to trash directory with -r --skip-trash: permanently remove it with shutil.rmtree ``` There is no separate `-R` alias at the time of writing. ### 6.2 Force and interactive behaviour `-f` suppresses errors for missing paths and disables the interactive prompt in `move_to_trash()` because the prompt only runs when `interactive and not force`. `-i` asks: ```text remove 'PATH'? [y/N] ``` Only the exact answer `y` proceeds. ### 6.3 Root-owned files Before moving to trash, `move_to_trash()` checks: ```python st = path.stat() if st.st_uid == 0 and os.geteuid() != 0: print("resrm: permission denied: ... (root-owned file, try sudo)") return ``` This is a product guardrail. It avoids giving non-root users the impression that `resrm` can safely or consistently manage root-owned files. It is not a privilege boundary by itself. ### 6.4 Owner-based trash selection Default trash mode selects the trash base from the file owner's uid when possible, not necessarily from the invoking user's uid: ```text owner uid -> pwd.getpwuid(owner_uid).pw_dir -> ~/.local/share/resrm fallback -> current TRASH_DIR.parent ``` This matters for `sudo resrm`: root can move a user-owned file into that user's resrm trash area instead of root's global trash area. If changing this behaviour, consider restore visibility, ownership, sudo workflows, and existing metadata files. --- ## 7. Listing and inspecting trash ### 7.1 Listing `list_trash()` reads the in-memory `meta` list for the current effective user and prints: ```text ID Deleted at Original path -------- ------------------- ------------- ``` Long paths are shortened from the left to fit a display width of 80 characters. `list_trash()` does not verify that each corresponding `files/` object still exists. It displays metadata state. ### 7.2 Inspecting `inspect_entry(identifier)` uses `find_candidates()` and prints details for every matching entry: ```text ID Original Deleted at Stored at Type Size Permissions Ownership ``` It uses `trash_path.lstat()` so symlink entries are inspected as symlinks rather than through their targets. Type display currently distinguishes directories, symlinks, and files. `--inspect` uses the current effective user's global `TRASH_DIR` and `meta`, so it inspects the trash visible to the invoking user. --- ## 8. Restoring files Restore is driven by `restore_many()` and `restore_one()`. ```text --restore ITEM... -> for each item -> find_candidates(item) -> if no match: print and continue -> if one match: restore_one(entry) -> if multiple matches: prompt for selection ``` Candidate lookup is intentionally simple: ```text 1. exact basename match against Path(entry["orig_path"]).name 2. id prefix match against entry["id"].startswith(identifier) ``` Exact basename matches take priority over id prefix matches. ### 8.1 Restore target path `restore_one()` starts with: ```python src = TRASH_DIR / entry["id"] dest = Path(entry["orig_path"]) ``` If the original destination already exists, restore falls back to the current directory with the original basename: ```python if dest.exists(): dest = Path.cwd() / dest.name ``` Then it creates parent directories and moves the trashed object: ```python dest.parent.mkdir(parents=True, exist_ok=True) shutil.move(str(src), str(dest)) ``` After a successful move, it removes the metadata entry from `meta` and saves the current metadata file. ### 8.2 Restore limitations Current restore behaviour does not provide conflict resolution beyond the current-directory fallback. If that fallback destination also exists, `shutil.move()` may fail or may apply platform-dependent behaviour. Restore does not validate that `entry["orig_path"]` is safe, expected, or still belongs to the user. The metadata file is trusted local state selected by the invoking user. --- ## 9. Pruning and emptying trash ### 9.1 Automatic pruning `main()` calls `prune_old_trash()` before argument parsing. This means any invocation can delete old trash entries before performing the requested action. The retention period is controlled by: ```text RESRM_TRASH_LIFE ``` Rules: ```text default: 7 days invalid value: 7 days minimum: 1 day ``` Entries older than the cutoff are removed from `TRASH_DIR/files/` and from `meta`. Directories are removed with `shutil.rmtree(..., ignore_errors=True)`. Files are removed with `unlink(missing_ok=True)`. ### 9.2 Emptying trash `empty_trash()` permanently removes every object directly under the current user's `TRASH_DIR`, clears `meta`, and writes the empty metadata list. There is no confirmation prompt for `--empty` at the time of writing. Treat changes to this behaviour as user-facing compatibility changes. --- ## 10. Symlink behaviour Symlink handling depends on the operation: ```text default trash mode: shutil.move moves the symlink itself when the path argument is a symlink --skip-trash: path.is_dir() and not path.is_symlink() uses shutil.rmtree otherwise path.unlink removes the symlink itself inspect: lstat is used and symlink targets are displayed with os.readlink ``` One important detail: the root-owned-file guard currently uses `path.stat()`, which follows symlinks. If changing symlink semantics, review that guard carefully and decide whether `lstat()` is more appropriate for the intended security model. --- ## 11. Development commands Install dependencies: ```bash poetry install ``` Run the CLI in the development environment: ```bash poetry run resrm --help ``` Run pre-commit hooks: ```bash poetry run pre-commit run --all-files ``` Build release artifacts: ```bash poetry build ``` There is a `tests/` package marker, but no substantive pytest suite is configured in `pyproject.toml` at the time of writing. If tests are added, add pytest as a development dependency and prefer focused tests using temporary directories and isolated metadata files. --- ## 12. Automation and security scanning Gitea pull request workflow: ```text .gitea/workflows/lint-and-security.yml -> install pre-commit -> pre-commit run --all-files -> install Poetry and poetry-plugin-export -> poetry export dependencies -> pip-audit dependency audit ``` Scheduled/manual security workflow: ```text .gitea/workflows/security-scan.yml -> install verified Cosign, Syft, and Grype -> generate SBOM -> scan for vulnerabilities -> notify Node-RED on fixable Medium/High/Critical vulnerabilities -> fail workflow on those vulnerabilities ``` Pre-commit currently includes Bandit, Black, trailing whitespace, EOF, YAML, and TOML checks. Bandit is configured for `src/resrm/` with: ```text -lll -iii -s B110,B112 ``` Be careful when suppressing security checks. Prefer making the code obviously safe and documenting intentional tradeoffs. --- ## 13. Common maintenance tasks ### 13.1 Add a new CLI option 1. Add the argparse option in `core.py`. 2. Decide whether it affects removal, restore, listing, inspection, pruning, or emptying. 3. Update argcomplete if the option accepts trash identifiers. 4. Update README usage examples. 5. Update this guide if the runtime flow or safety model changes. 6. Add focused tests if a test suite exists, or add the test infrastructure if the behaviour is important enough to protect. ### 13.2 Change metadata format 1. Update the metadata writer in `move_to_trash()`. 2. Update `load_meta()`, `save_meta()`, `find_candidates()`, `restore_one()`, `inspect_entry()`, and `list_trash()` as needed. 3. Decide whether old metadata files should continue to work. 4. Consider adding a `version` field before making incompatible changes. 5. Add tests with temporary metadata files. There is currently no migration system. Do not silently break existing user metadata unless the project intentionally accepts that compatibility break. ### 13.3 Change trash location semantics Start with these functions and call sites: ```text get_trash_base_for_user() get_trash_paths() move_to_trash() owner-based trash selection restore_one() source path construction inspect_entry() stored path display ``` Important questions: 1. Which user should own the trash entry when running under sudo? 2. Which metadata file should `--list`, `--restore`, and `--inspect` read? 3. What happens to existing trash entries under the old path? 4. Does the change affect root-owned files or normal user files differently? ### 13.4 Change restore behaviour Start with `find_candidates()`, `restore_many()`, and `restore_one()`. Preserve these expectations unless intentionally redesigning the tool: ```text restores by exact basename or id prefix prompts when there are multiple candidates does not overwrite an existing original path removes metadata only after a successful move prints a clear failure message when restore fails ``` If adding overwrite or merge behaviour, require explicit user intent and document the consequences. ### 13.5 Change permanent deletion behaviour Start with the `skip_trash` branch in `move_to_trash()`, `prune_old_trash()`, and `empty_trash()`. Permanent deletion paths are the highest-risk parts of the tool. Review directory handling, symlink handling, error reporting, and confirmation semantics before changing them. ### 13.6 Add tests Good first test areas: ```text get_trash_base_for_user chooses expected paths load_meta returns [] for missing or malformed metadata find_candidates prioritises exact basename before id prefix move_to_trash moves files and writes metadata move_to_trash rejects directories without -r at the CLI layer --skip-trash removes a symlink rather than its target restore_one restores to original path when free restore_one falls back to current directory when original path exists prune_old_trash honours default, invalid, and minimum retention values empty_trash clears files and metadata ``` Use temporary directories and monkeypatch module globals such as `TRASH_DIR`, `META_FILE`, and `meta` to avoid touching a real user's trash. --- ## 14. Important maintenance hazards ### 14.1 Import-time global state `TRASH_DIR`, `META_FILE`, and `meta` are initialised at import time. This keeps the script simple, but it makes testing and multi-user behaviour easier to get wrong. If refactoring, consider passing a small trash context object through functions instead of relying on globals. ### 14.2 Metadata is trusted local state Restore uses `orig_path` from metadata to decide where to create parent directories and move restored files. Do not treat arbitrary attacker-controlled metadata as safely sandboxed input. ### 14.3 `--empty` and pruning are permanent The default remove flow is reversible, but `--empty`, auto-prune, and `--skip-trash` are not. Keep this distinction clear in code paths and documentation. ### 14.4 Short ids can collide The display id is the first eight characters of a UUID. Code should be prepared for multiple matches and should not assume an eight-character prefix uniquely identifies an entry. ### 14.5 Basename lookup can be ambiguous Exact basename restore is convenient but ambiguous. `restore_many()` prompts when multiple candidates match. Preserve that behaviour when changing lookup logic. ### 14.6 Symlink and ownership checks need care Some operations use `stat()` and some use `lstat()`. Be explicit about whether the code should operate on a symlink itself or its target. ### 14.7 Root and sudo workflows are product-sensitive The README promises sudo support for root-owned files. Changes that affect euid handling, owner-based trash paths, root-owned rejection, or `/root/.local/share/resrm` should be tested manually under sudo before release. ### 14.8 Existing user trash matters Users may have real files in `~/.local/share/resrm/files` and important metadata in `metadata.json`. Migration and compatibility decisions can affect their ability to restore data. --- ## 15. Troubleshooting guide ### 15.1 `resrm` says a path is root-owned The path's owner uid is `0`, and the current effective uid is not root. Re-run with sudo if you intentionally want root to manage that path. ### 15.2 A directory is not removed Like `rm`, `resrm` requires `-r` for directories: ```bash resrm -r directory ``` ### 15.3 A restored file does not return to its original path If the original path already exists, `restore_one()` restores to the current directory using the original basename. ### 15.4 A trash item is missing Check, in order: 1. Was it removed with `--skip-trash`? 2. Was it removed by `resrm --empty`? 3. Was it pruned because it was older than `RESRM_TRASH_LIFE` days? 4. Are you running as the same effective user that owns the relevant trash metadata? 5. Was it moved into the file owner's trash while running through sudo? ### 15.5 Completion does not show entries Check that argcomplete is installed and registered for the shell: ```bash eval "$(register-python-argcomplete resrm)" ``` Completion candidates come from the metadata loaded for the current effective user. ### 15.6 Pruning happens unexpectedly Every `resrm` invocation calls `prune_old_trash()` before parsing arguments. Check `RESRM_TRASH_LIFE`; invalid values fall back to 7 days and values below 1 are treated as 1 day. --- ## 16. Practical code-reading map ```text Feature/question Start with CLI option behaviour core.py:main() Console script entry point pyproject.toml and cli.py Trash base path get_trash_base_for_user() Current user's trash globals get_trash_paths(), TRASH_DIR, META_FILE Metadata loading/saving load_meta(), save_meta() Automatic pruning prune_old_trash() Listing trash list_trash() Identifier matching find_candidates() Restore flow restore_many(), restore_one() Permanent delete move_to_trash(skip_trash=True) Default move to trash move_to_trash(skip_trash=False) Inspection output inspect_entry() Shell completion id_name_completer inside main() Packaging pyproject.toml Automation .gitea/workflows/ and .pre-commit-config.yaml ``` --- ## 17. Glossary **Trash base** The directory containing `files/` and `metadata.json` for one user. **Trash file directory** The `files/` directory under the trash base, containing UUID-named moved objects. **Metadata file** The JSON file that records ids, original paths, and timestamps. **Trash id** The full UUID hex string generated for a trashed object. **Short id** The first eight characters of a trash id, used for display and restore convenience. **Original path** The resolved path stored before a moved object is restored. **Skip trash** Permanent deletion mode enabled with `--skip-trash`. **Prune** Automatic permanent deletion of old trash entries according to `RESRM_TRASH_LIFE`. --- ## 18. Final maintenance model Most changes should preserve this model: ```text Move paths into a per-user trash area by default -> store minimal metadata needed to find and restore them -> list, inspect, and restore from trusted local metadata -> avoid overwriting existing original paths during restore -> reserve permanent deletion for explicit or retention-based flows ``` Before changing code, ask: 1. Is this a remove, restore, metadata, pruning, or presentation concern? 2. Does this touch permanent deletion or only trash movement? 3. What happens to existing `metadata.json` files? 4. Which effective user and which file owner should control the trash entry? 5. Does the change behave correctly under sudo? 6. Does it operate on symlinks or symlink targets? 7. Does it preserve non-overwrite restore behaviour? 8. Are `--skip-trash`, `--empty`, and auto-prune clearly documented as permanent? 9. Are there focused tests or manual checks for the edge case being changed? Keeping those boundaries clear is the main way to maintain `resrm` without turning a narrow safer-rm utility into a misleading backup or sandbox tool.