Merge pull request 'Bug fix and more' (#20) from some-changes into main

Reviewed-on: #20
2026-06-28 06:47:33 +00:00
parent c411e6240a 44003035e9
commit 6651bc0e56
5 changed files with 825 additions and 1 deletions
@@ -0,0 +1,616 @@
+# mirro Development Guide
+
+Interested in the internals of mirro?
+
+This guide describes the current `mirro` codebase for maintainers. It focuses on how the project is organised, what the command does, how backup and restore data flows through the CLI, and which invariants matter when changing the code.
+
+---
+
+## 1. What mirro does
+
+`mirro` is a small safety-first command-line wrapper for editing text files.
+
+Its main edit pipeline is:
+
+```text
+target file
+  |
+  | mirro FILE
+  v
+temporary editable copy
+  |
+  | $EDITOR exits
+  v
+content comparison
+  |
+  | changed only
+  v
+timestamped backup of original content
+  |
+  v
+overwrite target with edited content
+```
+
+`mirro` deliberately keeps a narrow scope. It manages text content backups around manual editor sessions. It is not a filesystem snapshotter, a version-control system, a transactional editor, a privilege escalation tool, or a sandbox.
+
+The command also supports backup inspection and maintenance flows:
+
+```text
+mirro --list                         list files in the backup directory
+mirro --restore-last FILE            restore newest backup matching FILE's basename
+mirro --restore BACKUP               restore backup to path from its header
+mirro --prune-backups[=N|all]        remove old or all backup files
+mirro --diff FILE BACKUP             show unified diff from backup to current file
+mirro --status                       show current-directory files with backup history
+```
+
+---
+
+## 2. Repository layout
+
+The project is a single Python package under `src/mirro/`.
+
+```text
+src/mirro/
+  __init__.py              package marker
+  main.py                  argparse CLI and all current runtime behavior
+
+tests/
+  test_mirro.py            pytest coverage for helpers and CLI branches
+
+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
+mirro.png                  README logo
+```
+
+The installed command is configured in `pyproject.toml`:
+
+```toml
+[tool.poetry.scripts]
+mirro = "mirro.main:main"
+```
+
+There is no `src/mirro/__main__.py` at the time of writing, so `python -m mirro` is not the supported entry point. Use the installed `mirro` command or `poetry run mirro` during development.
+
+---
+
+## 3. Main runtime flows
+
+All user-facing behavior enters through `mirro.main.main()`.
+
+```text
+mirro command
+  -> mirro.main.main()
+     -> build argparse parser
+     -> install argcomplete hook
+     -> parse known args, leaving editor/file positionals untouched
+     -> dispatch to diff, list, status, restore-last, restore, prune, or edit flow
+```
+
+The current implementation keeps parsing, filesystem operations, editor invocation, backup formatting, restore behavior, pruning, and display in one file. That is acceptable for the current size, but new behavior should avoid making `main.py` harder to reason about. If a feature grows beyond a few focused helpers, consider extracting it into a small module with tests.
+
+### 3.1 CLI dispatch order
+
+Dispatch order matters because each branch returns before later behavior runs:
+
+```text
+--diff
+--list
+--status
+--restore-last
+--restore
+--prune-backups
+normal edit flow
+```
+
+If a future option can be combined with other options, decide whether it should be a global modifier or an action branch. Most existing options are action branches.
+
+### 3.2 Normal edit flow
+
+The normal edit flow is the core product behavior:
+
+```text
+parse positional arguments
+  -> choose first non-option/non-+ argument as target file
+  -> pass remaining positionals to editor
+  -> read $EDITOR, defaulting to nano
+  -> resolve target and backup directory
+  -> check write access to target or parent directory
+  -> read existing target, or prepopulate a new file message
+  -> write content to a temporary file
+  -> run editor without a shell
+  -> read edited temp file
+  -> delete temp file
+  -> compare edited content to original content
+  -> if unchanged, print "file hasn't changed"
+  -> if changed, back up original content and overwrite target
+```
+
+The implementation reads and writes text as UTF-8:
+
+```python
+path.read_text(encoding="utf-8", errors="replace")
+path.write_text(content, encoding="utf-8")
+```
+
+That means invalid input bytes are replaced during reads and rewritten as UTF-8 if the file is saved. `mirro` is intended for text files, not arbitrary binary files.
+
+### 3.3 Editor argument handling
+
+`main()` parses known `mirro` options and preserves unknown positional arguments for the editor. In normal edit mode, the first positional argument that does not start with `-` or `+` is treated as the target file; the rest are editor extras.
+
+The editor command comes from:
+
+```text
+$EDITOR, or nano when unset
+```
+
+It is split with `editor.split()` and executed with `subprocess.call()` without `shell=True`.
+
+For `nano`, extras are placed before the temporary path:
+
+```text
+nano EXTRA... TEMP
+```
+
+For other editors, extras are placed after the temporary path:
+
+```text
+editor TEMP EXTRA...
+```
+
+Be careful when changing this. Editor option order differs across editors, and the current behavior is intentionally permissive rather than a full editor-specific parser.
+
+---
+
+## 4. Backup storage
+
+The default backup directory is:
+
+```text
+~/.local/share/mirro
+```
+
+Under `sudo`, `Path.home()` normally resolves to root's home, so the default becomes:
+
+```text
+/root/.local/share/mirro
+```
+
+Users can override it with:
+
+```bash
+mirro --backup-dir /path/to/backups FILE
+```
+
+Backups are plain text files named with the original basename and a UTC timestamp:
+
+```text
+filename.ext.orig.YYYYMMDDTHHMMSS
+```
+
+The backup content starts with a mirro header:
+
+```text
+# ---------------------------------------------------
+# mirro backup
+# Original file: /path/to/original
+# Timestamp: 2025-11-10 17:44:00 UTC
+# Delete this header if you want to restore the file
+# ---------------------------------------------------
+
+original file content follows here
+```
+
+The original path in the header is used by `--restore BACKUP` to decide where to write restored content.
+
+### 4.1 Backup creation
+
+`backup_original(original_path, original_content, backup_dir)` owns backup file creation.
+
+It currently:
+
+```text
+creates backup_dir if needed
+uses UTC timestamps
+writes a text header
+writes original_content after the header
+returns the backup path
+```
+
+There is no database or manifest. The backup filename and header are the persistence format.
+
+### 4.2 Backup matching limits
+
+Several features match backups by basename:
+
+```text
+--restore-last FILE       matches target.name + ".orig."
+--diff FILE BACKUP        requires backup name to start with target.name + ".orig."
+--status                  maps backups to current-directory files by basename
+```
+
+This is simple and predictable, but two files with the same basename in different directories share the same backup-name prefix in a single backup directory. `--restore BACKUP` is more specific because it reads the original path from the backup header.
+
+### 4.3 Timestamp collisions
+
+Backup filenames have one-second timestamp resolution. If the same basename is backed up twice in the same backup directory during the same second, the later backup can reuse the same path.
+
+If this becomes a practical problem, fix it by making backup names unique while preserving the existing readable prefix format.
+
+---
+
+## 5. Restore, diff, status, and prune behavior
+
+### 5.1 `--restore-last FILE`
+
+Restore-last flow:
+
+```text
+resolve backup directory
+resolve target file
+find backup files whose names start with target.name + ".orig."
+choose newest by filesystem mtime
+read backup text
+strip mirro header only
+write restored text to target
+```
+
+This action does not read the `Original file:` header to verify the backup belongs to the same absolute path. It is basename-based.
+
+### 5.2 `--restore BACKUP`
+
+Restore flow:
+
+```text
+resolve BACKUP as absolute/~ path or backup-dir filename
+read backup text
+extract Original file path from mirro header
+strip mirro header only
+check write access to target or target parent
+create target parent directories if needed
+write restored text to target
+```
+
+This action can create parent directories for the target path from the backup header. Treat backup files and backup directories as trusted local state.
+
+### 5.3 Header stripping
+
+`strip_mirro_header()` removes only a header that starts with mirro's separator line and continues through the first blank line.
+
+It intentionally does not strip arbitrary leading comments, shebangs, or non-mirro headers.
+
+### 5.4 `--diff FILE BACKUP`
+
+Diff flow:
+
+```text
+resolve current file
+resolve backup as absolute/~ path or backup-dir filename
+require backup filename to start with current file basename + ".orig."
+read current text
+read backup text and strip mirro header
+print unified diff from backup to current file
+```
+
+Diff output uses ANSI colour codes directly for file headers, hunk lines, additions, and removals.
+
+### 5.5 `--status`
+
+Status flow:
+
+```text
+read backup directory
+group backup files by text before ".orig."
+scan regular files in current directory only
+print files whose basename has backups
+```
+
+`--status` does not recurse into subdirectories and does not validate backup headers.
+
+### 5.6 `--prune-backups`
+
+Prune supports three forms:
+
+```bash
+mirro --prune-backups
+mirro --prune-backups=14
+mirro --prune-backups=all
+```
+
+Default mode reads:
+
+```text
+MIRRO_BACKUPS_LIFE
+```
+
+If the environment variable is missing, invalid, or less than `1`, the code falls back to `30` days after printing a warning for invalid values.
+
+Age-based pruning removes regular files in the backup directory whose mtime is older than the cutoff. `all` mode removes every regular file in the backup directory. There is currently no confirmation prompt, dry-run mode, or mirro-header validation before deletion.
+
+---
+
+## 6. Development commands
+
+Install dependencies:
+
+```bash
+poetry install
+```
+
+Run the CLI in the development environment:
+
+```bash
+poetry run mirro --help
+```
+
+Run pre-commit hooks:
+
+```bash
+poetry run pre-commit run --all-files
+```
+
+Run the pytest suite:
+
+```bash
+poetry run pytest
+```
+
+Run the README's full coverage command:
+
+```bash
+poetry run pytest -vvvv --cov=mirro --cov-report=term-missing --disable-warnings
+```
+
+Build release artifacts:
+
+```bash
+poetry build
+```
+
+When adding behavior, add focused tests under `tests/`. Prefer temporary directories and monkeypatching over tests that modify real user files or depend on a real editor.
+
+---
+
+## 7. 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
+  -> export Poetry dependencies
+  -> pip-audit dependency audit
+```
+
+Scheduled/manual security workflow:
+
+```text
+.gitea/workflows/security-scan.yml
+  -> install Cosign
+  -> verify and install Syft
+  -> verify and install 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.
+
+---
+
+## 8. Common maintenance tasks
+
+### 8.1 Add a new CLI option
+
+1. Add the argparse option in `main.py`.
+2. Decide whether it is a global modifier or an action branch.
+3. Place action branches before normal edit flow.
+4. Preserve editor positional parsing unless the option intentionally changes it.
+5. Update README usage examples.
+6. Add tests for parser behavior and the affected operation.
+
+### 8.2 Change backup format
+
+1. Update `backup_original()`.
+2. Update `strip_mirro_header()` or `extract_original_path()` if header semantics change.
+3. Decide whether existing backup files must remain restorable.
+4. Update README examples and this guide.
+5. Add tests with representative old and new backup text.
+
+Existing backups are user data. Do not break restoration of current backup headers without a deliberate compatibility decision.
+
+### 8.3 Change restore behavior
+
+Start with the `--restore` and `--restore-last` branches in `main.py`.
+
+Be explicit about whether the change affects:
+
+```text
+basename matching
+header parsing
+target path creation
+write permission checks
+backup directory trust
+confirmation requirements
+```
+
+If adding confirmation or dry-run support, cover both interactive and non-interactive behavior in tests.
+
+### 8.4 Change editor handling
+
+Start with normal edit flow near `$EDITOR` parsing.
+
+Preserve these invariants unless intentionally redesigning editor invocation:
+
+```text
+do not edit the real file directly
+write the initial content to a temporary file
+run the editor without shell=True
+compare content before creating a backup
+create a backup before overwriting the target
+delete the temporary file after reading it
+```
+
+If changing how editor arguments are ordered, test at least `nano` and one non-`nano` editor shape with monkeypatched `subprocess.call()`.
+
+### 8.5 Add tests
+
+Good first test areas:
+
+```text
+backup filename/header creation
+header stripping preserves shebangs
+restore rejects missing backup files
+restore uses Original file from header
+restore-last chooses newest basename match
+diff rejects mismatched backup basenames
+prune rejects invalid values and handles all mode
+normal edit does not write unchanged files
+normal edit backs up before changed writes
+permission-denied branches return 1
+```
+
+Avoid tests that require root. Use `tmp_path`, `monkeypatch`, `capsys`, and patched `sys.argv` as the current suite does.
+
+---
+
+## 9. Important maintenance hazards
+
+### 9.1 `main.py` owns everything
+
+The project is currently simple enough for one runtime module, but `main.py` contains parsing, editor invocation, backup I/O, restore, diff, status, prune, and display. Keep new changes focused. If a branch becomes complicated, extract helper functions before adding more nested logic.
+
+### 9.2 Backups are plain trusted files
+
+Backups are not signed, checksummed, authenticated, or stored in a database. The restore path comes from the text header. Do not treat arbitrary attacker-controlled backup files as safe input.
+
+### 9.3 Basename matching is intentionally simple
+
+`--restore-last`, `--diff`, and `--status` mainly use backup filenames, not the `Original file:` header. This is convenient but can mix history for files with the same basename. Be careful when changing matching semantics because existing users may rely on the current naming scheme.
+
+### 9.4 Prune removes regular files in the backup directory
+
+`--prune-backups=all` removes every regular file in the selected backup directory, not only files with mirro headers or `.orig.` names. Age-based pruning has the same broad backup-directory scope. This makes `--backup-dir` a powerful option.
+
+### 9.5 Restore can create parent directories
+
+`--restore BACKUP` creates missing parent directories for the path stored in the backup header. This is useful for recovery, but it also means backup header paths are operationally significant.
+
+### 9.6 Text encoding is lossy for invalid bytes
+
+Reads use `errors="replace"`. If a file contains invalid UTF-8 and the edit is saved, replacement characters may be written. Keep user-facing language clear that `mirro` is for text files.
+
+### 9.7 Symlinks are not special-cased
+
+The current code uses `Path.exists()`, `read_text()`, `write_text()`, and `os.access()` in their normal path-following forms. If a target path is a symlink, operations generally affect the symlink target. Do not document or assume no-follow semantics unless the implementation is changed.
+
+### 9.8 `$EDITOR` is trusted local configuration
+
+`mirro` runs the configured editor as the current user. This is expected behavior, but it means `$EDITOR` is part of the local trust boundary.
+
+---
+
+## 10. Troubleshooting guide
+
+### 10.1 `Need elevated privileges to open` or `create`
+
+The target file or parent directory is not writable by the current process. Re-run in the correct account, adjust permissions, or use `sudo` when intentionally editing privileged files.
+
+### 10.2 `file hasn't changed`
+
+The content after the editor exited matched the content initially placed in the temporary file. No backup was created and the target was not overwritten.
+
+### 10.3 `No history found for FILE`
+
+`--restore-last` could not find backup files whose names start with `FILE`'s basename plus `.orig.` in the selected backup directory. Check `--backup-dir` and `mirro --list`.
+
+### 10.4 `Could not determine original file location from backup header`
+
+`--restore` found the backup file, but the text did not contain a readable `# Original file:` line before the first blank line.
+
+### 10.5 Diff says the backup does not match the file
+
+`--diff` requires the backup filename to start with the current file's basename plus `.orig.`. Use the matching backup file or pass the intended current file.
+
+### 10.6 Prune did not use the expected age
+
+`mirro --prune-backups` reads `MIRRO_BACKUPS_LIFE`. Invalid, missing, zero, or negative values fall back to `30` days. Use `mirro --prune-backups=N` to pass an explicit age.
+
+---
+
+## 11. Practical code-reading map
+
+Feature/question | Start with | Then read
+--- | --- | ---
+Version output | `get_version()` | `pyproject.toml`
+Backup writing | `backup_original()` | normal edit flow near end of `main()`
+Header stripping | `strip_mirro_header()` | restore and diff branches
+Original path parsing | `extract_original_path()` | `--restore` branch
+CLI option behavior | `main()` parser setup | action branch dispatch order
+Editor invocation | normal edit flow | tests using patched `subprocess.call()`
+Backup listing | `--list` branch | README examples
+Restore latest | `--restore-last` branch | backup filename format
+Restore specific backup | `--restore` branch | `extract_original_path()`
+Diff output | `--diff` branch | `difflib.unified_diff`
+Status output | `--status` branch | basename grouping logic
+Pruning | `--prune-backups` branch | `MIRRO_BACKUPS_LIFE` docs
+Tests | `tests/test_mirro.py` | pytest docs
+Packaging | `pyproject.toml` | Poetry docs
+Automation | `.gitea/workflows/` | `.pre-commit-config.yaml`
+
+---
+
+## 12. Glossary
+
+**Target file** The file the user asked `mirro` to edit or restore.
+
+**Temporary file** The editable copy passed to `$EDITOR` during normal edit flow.
+
+**Backup directory** The directory containing mirro backup files, defaulting to `~/.local/share/mirro`.
+
+**Backup file** A plain text file named like `name.orig.YYYYMMDDTHHMMSS` containing a mirro header and original content.
+
+**Mirro header** The leading comment block that records the original path and backup timestamp.
+
+**Restore-last** The action that restores the newest backup matching a target basename.
+
+**Restore** The action that restores a specific backup to the original path recorded in its header.
+
+**Prune** Deletion of files from the selected backup directory by age or all-at-once mode.
+
+---
+
+## 13. Final maintenance model
+
+Most changes should preserve this model:
+
+```text
+Edit a temporary text copy
+  -> compare before writing
+  -> back up original content only when changed
+  -> then overwrite the target with edited content
+  -> keep backup inspection and restoration simple and explicit
+```
+
+Before changing code, ask:
+
+1. Is this a CLI parsing concern, backup-format concern, editor-invocation concern, or restore/prune concern?
+2. Does the change preserve the temporary-file editing model?
+3. Is the backup created before the target is overwritten?
+4. Are existing backup files still restorable?
+5. Does basename-based matching still behave predictably?
+6. Does `--backup-dir` remain clearly treated as trusted local state?
+7. Are text encoding and binary-file limitations explicit?
+8. Are README examples and shell completion expectations still accurate?
+9. Are there focused tests for the edge case being changed?
+
+Keeping those boundaries clear is the main way to maintain `mirro` without turning a narrow safe-editing wrapper into a misleading general-purpose recovery system.
@@ -0,0 +1,193 @@
+# mirro Threat Model and Security Scope
+
+`mirro` is a command-line systems administration tool. It is designed to be executed intentionally by an operator, sometimes with elevated privileges, to edit text files through a temporary copy and save a backup before changed content is written back.
+
+Because of that design, `mirro`'s security model is different from that of a network service, web application, daemon, sandbox, or setuid program. `mirro` does not attempt to defend against arbitrary local compromise of the account executing it. If an attacker can control the command line, environment, working directory, `EDITOR`, selected backup directory, installed Python package, or editor binary used by the operator, they may be able to influence what `mirro` does. That situation is considered a local trust-boundary failure outside `mirro`'s intended security model.
+
+`mirro` is for text-file editing safety. It does not provide full filesystem rollback, access-control enforcement, sandboxing, cryptographic integrity, or protection from a hostile local environment.
+
+## Core Assumptions
+
+`mirro` assumes that the person running the tool understands what they are asking it to do.
+
+In particular:
+
+- If `mirro` is run as root, the root user is assumed to control and understand the command line, environment, `EDITOR`, backup directory, and target file being used.
+- If `--backup-dir` is used, the selected directory and its contents are assumed to be trusted local administrative state chosen by the operator.
+- If `--restore` is used, the selected backup file is assumed to be trusted and intentionally selected by the operator.
+- If `--restore-last` is used, the operator accepts basename-based matching in the selected backup directory.
+- If `--prune-backups` is used, the operator intends to delete regular files from the selected backup directory according to the requested mode.
+- The configured editor is assumed to be the trusted editor implementation that the operator intended to execute.
+- The operator is expected to understand the impact of editing or restoring privileged files, especially when running as root.
+
+## What mirro Records
+
+`mirro` backups are plain text files. A backup records:
+
+- The original file path in a header.
+- A UTC timestamp in the header.
+- The original text content after the header.
+
+Backup filenames include:
+
+- The original file basename.
+- The `.orig.` marker.
+- A UTC timestamp with one-second resolution.
+
+`mirro` does not record:
+
+- File ownership.
+- File permissions.
+- ACLs.
+- Extended attributes.
+- Capabilities.
+- SELinux, AppArmor, or other MAC labels.
+- File hashes or signatures.
+- A database manifest.
+- A transactional history across multiple files.
+
+Backups can contain sensitive file contents. Backup directories must be protected accordingly.
+
+## What Is In Scope
+
+`mirro` tries to protect careful administrators from common editing mistakes that occur when changing text files.
+
+In-scope security and safety concerns include:
+
+- Normal edit mode must not edit the target file directly through the editor.
+- Normal edit mode must use a temporary file for the editor session.
+- Normal edit mode must not overwrite the target when edited content is unchanged.
+- Normal edit mode must create the backup before writing changed content to the target.
+- The editor should be invoked without `shell=True`.
+- The temporary file should be removed after the editor session is read back.
+- Backup headers should preserve enough information to identify the original path.
+- Header stripping should remove only mirro's own backup header, not arbitrary comments or shebangs.
+- `--diff` should reject backups whose filename does not match the target file basename.
+- Permission checks should fail clearly when the current process cannot write the target or target parent.
+- Dependency and source scans should continue to run in project automation.
+
+These measures are defense-in-depth. They reduce the chance of accidental data loss or unintended edits when `mirro` is used normally by an administrator.
+
+## What Is Out Of Scope
+
+The following are generally out of scope and should not be reported as `mirro` vulnerabilities unless they also bypass one of `mirro`'s explicit safety mechanisms:
+
+- A malicious local user who can already control the root user's command line, shell environment, working directory, `EDITOR`, `PATH`, Python environment, installed package, or editor binary.
+- A root user intentionally editing or restoring a sensitive file.
+- A root user intentionally selecting a malicious backup file with `--restore`.
+- A root user intentionally pointing `--backup-dir` at a malicious or shared directory.
+- A user intentionally setting `EDITOR` to a malicious command.
+- A user relying on `mirro` to preserve ownership, permissions, ACLs, xattrs, capabilities, MAC labels, or binary file bytes.
+- A user relying on `mirro` as a sandbox for untrusted editors, untrusted local users, or untrusted backup files.
+- A compromised system where an attacker already controls root-owned files, root's shell, root's Python packages, root's environment, or editor binaries.
+- Reports that amount to "if root runs this tool with malicious options, root can overwrite files."
+
+`mirro` is a tool for administrators, not a sandbox for hostile local users. It cannot make unsafe local trust decisions safe if the operator's own execution environment is already attacker-controlled.
+
+## Trusted Backup Directories
+
+By default, `mirro` stores backups in:
+
+```text
+~/.local/share/mirro
+```
+
+Operators may override this with `--backup-dir`.
+
+Backup directories should be treated as trusted local state. Backups contain file contents and an `Original file:` path that `--restore` uses as the write target. A maliciously edited backup can cause `mirro --restore` to write attacker-chosen content to the path recorded in the header, subject to the privileges of the user running `mirro`.
+
+The backup directory should not be world-writable or shared with untrusted users. Before restoring, especially as root, the operator should be confident that the selected backup is the intended one and has not been tampered with.
+
+## Restore Behavior
+
+`mirro` has two restore modes:
+
+```bash
+mirro --restore-last /path/to/file
+mirro --restore file.orig.20250101T010203
+```
+
+`--restore-last` finds the newest backup whose filename starts with the target file's basename plus `.orig.`. It does not verify that the backup header's original path matches the requested target path.
+
+`--restore` reads the selected backup file, extracts the `Original file:` path from its header, strips the mirro header, creates missing parent directories if needed, and writes the restored text to that target.
+
+Both restore modes overwrite text at the target path when the current process has permission. There is currently no confirmation prompt or dry-run mode for restore.
+
+This is intentional current behavior, but it means restore operations should be treated as privileged file writes when run with elevated permissions.
+
+## Prune Behavior
+
+`mirro --prune-backups` deletes regular files from the selected backup directory.
+
+Supported forms are:
+
+```bash
+mirro --prune-backups
+mirro --prune-backups=14
+mirro --prune-backups=all
+```
+
+Default mode reads `MIRRO_BACKUPS_LIFE`, falling back to `30` days for missing or invalid values. Numeric mode removes regular files older than the cutoff. `all` mode removes every regular file in the backup directory.
+
+Prune does not currently require confirmation, provide a dry run, or validate that files contain mirro headers before deleting them. Operators should use `--backup-dir` carefully.
+
+## Editor Execution
+
+`mirro` runs the configured editor as the current user:
+
+```text
+$EDITOR, or nano when unset
+```
+
+The editor command is split with `editor.split()` and executed with `subprocess.call()` without `shell=True`. This avoids shell expansion by `mirro` itself, but it does not make the editor trusted. A malicious editor can read, modify, delete, or exfiltrate files accessible to the current user.
+
+`EDITOR` is part of the local trust boundary. Do not run `mirro` with elevated privileges while inheriting an untrusted environment.
+
+## Text Encoding and Binary Files
+
+`mirro` reads text using UTF-8 with replacement for invalid bytes and writes UTF-8 text.
+
+This means `mirro` is not byte-preserving for arbitrary binary files or text files with invalid UTF-8. If such a file is edited and saved, invalid byte sequences may be replaced.
+
+Reports that `mirro` is not a binary-safe editor wrapper are not security issues by themselves. User-facing documentation should keep describing `mirro` as a text-file editing wrapper.
+
+## Symlinks and Filesystem Races
+
+`mirro` does not currently implement no-follow symlink protections. It uses normal path operations such as `Path.exists()`, `read_text()`, `write_text()`, and `os.access()`. If the selected target path is a symlink, operations generally affect the symlink target.
+
+Because `mirro` operates on a live filesystem, concurrent changes can affect what exists at the moment it reads, backs up, restores, prunes, or writes. `mirro` does not claim to provide transactional filesystem semantics.
+
+Avoid using `mirro` in hostile writable directories or on paths that untrusted users can replace while the command is running, especially with elevated privileges.
+
+## Local Compromise
+
+`mirro` includes some hardening for ordinary safe editing, such as editing a temporary file, comparing before writeback, creating a backup before overwrite, and avoiding `shell=True` for editor invocation.
+
+However, local compromise cannot be ruled out completely for a privileged CLI tool. If an attacker can influence the administrator's shell, environment, backup directory, backup files, Python packages, current working directory, editor binary, or command-line arguments, they may be able to influence `mirro`'s behavior.
+
+Such scenarios are treated as local compromise or operator trust failures, not as vulnerabilities in `mirro` by themselves.
+
+## Security Report Guidance
+
+Useful vulnerability reports include issues where `mirro` behaves unsafely despite the documented trust model. Examples include:
+
+- Normal edit mode overwrites the target file even though edited content is unchanged.
+- Normal edit mode writes changed content before creating the backup.
+- Normal edit mode invokes the editor through a shell in a way that enables shell injection.
+- Header stripping removes non-mirro content such as a shebang or ordinary leading comments.
+- `--diff` accepts a clearly mismatched backup filename despite its basename check.
+- A permission failure is silently ignored and `mirro` proceeds with a write that should have been rejected.
+- Temporary files are predictably named or left behind with sensitive content in ordinary successful operation.
+- Project automation stops running meaningful lint, dependency audit, or security scans.
+
+Less useful reports, and normally out of scope, include:
+
+- "Root can edit dangerous files."
+- "Root can restore malicious content from a malicious backup."
+- "Root can choose a dangerous backup directory."
+- "A malicious `$EDITOR` can execute code."
+- "A malicious local user can compromise `mirro` after already controlling root's environment, Python packages, backup files, or editor binary."
+- "`mirro` does not preserve file permissions, ownership, ACLs, xattrs, capabilities, or binary bytes."
+- "`mirro --prune-backups=all` deletes files from the backup directory selected by the operator."
+
+Reports about concrete bypasses of `mirro`'s documented safety behavior are welcome. The project does not treat intentional administrator-controlled execution as a vulnerability by itself.
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mirro"
-version = "0.6.2"
+version = "0.6.3"
 description = "A safe editing wrapper: edits a temp copy, compares, and saves original backup if changed."
 authors = ["Marco D'Aleo <marco@marcodaleo.com>"]
 license = "GPL-3.0-or-later"
@@ -491,6 +491,10 @@ def main():
    target = Path(file_arg).expanduser().resolve()
    backup_dir = Path(args.backup_dir).expanduser().resolve()

+    if target.is_dir():
+        print(f"'{target}' is a directory!")
+        return 1
+
    # Permission checks
    parent = target.parent
    if target.exists() and not os.access(target, os.W_OK):
@@ -174,6 +174,17 @@ def test_main_missing_argument(capsys):
    )


+def test_main_rejects_directory(tmp_path, capsys):
+    target = tmp_path / "dir"
+    target.mkdir()
+
+    with patch("sys.argv", ["mirro", str(target)]):
+        result = mirro.main()
+
+    assert result == 1
+    assert f"'{target}' is a directory!" in capsys.readouterr().out
+
+
 # ============================================================
 # main: unchanged file
 # ============================================================