Update RemoveSamples extension to v1.1.0 (Test Mode, Quarantine & safer detection)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,58 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+---
+name: Bug report
+about: Report a problem with Remove Samples for NZBGet
+title: "[Bug]: "
+labels: ["bug"]
+assignees: []
+---
+
+### Pre-flight
+- [ ] I updated Remove Samples via NZBGet **Extension Manager** and retested.
+- [ ] I read the README and Troubleshooting notes.
+
+### Environment
+- **Platform:** Docker (Linux) | Unraid | Linux | Windows | macOS
+- **NZBGet version:** v23.x
+- **Remove Samples version:** 1.0.x
+- **Python version:** (if known)
+
+### Extensions order (from _Settings → Categories_)
+1) Completion
+2) PasswordDetector
+3) FakeDetector
+4) ExtendedUnpacker
+5) Remove Samples
+6) Clean
+
+### Remove Samples settings
+- Remove Directories: Yes/No
+- Remove Files: Yes/No
+- Video threshold (MB): 150 (default)
+- Audio threshold (MB): 2 (default)
+
+### Steps to reproduce
+1.
+2.
+3.
+
+### Example filenames/sizes
+- `movie.sample.mkv` (90 MB)
+- `movie.mkv` (1.4 GB)
+
+### Expected
+<!-- What you expected to happen -->
+
+### Actual
+<!-- What actually happened -->
+
+### Debug log (short snippet)
+> Turn **Debug = Yes** temporarily, reproduce once, paste key lines. Redact personal paths.

.github/workflows/manifest.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Check manifest.json exists
       run: |

.github/workflows/prospector.yml

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.8'
 
@@ -30,7 +30,7 @@ jobs:
       run: prospector --zero-exit main.py
 
     - name: Upload Prospector report
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       if: always()
       with:
         name: prospector-report

.github/workflows/tests.yml

@@ -17,10 +17,10 @@ jobs:
         python-version: ['3.8', '3.9', '3.10', '3.11']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 

.gitignore

@@ -206,4 +206,7 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-.vscode/
+.vscode/
+
+# Kilo Code (keep everything private)
+.kilocode/

AGENTS.md

@@ -0,0 +1,147 @@
+# AGENTS.md — RemoveSamples-NZBGet
+
+Briefing for coding agents and new maintainers working on this repo. Keep changes safe, small, and well tested.
+
+## 1) What this project does
+RemoveSamples-NZBGet is a Post-Processing extension for NZBGet v23+. It finds and removes “sample” clips and junk assets from completed downloads using name patterns and size thresholds. It only performs destructive actions when the overall download status indicates success.
+
+Goals:
+- Idempotent and predictable runs
+- Contract correctness
+- Clear, minimal logs with a one-line summary
+- Cross-platform behavior on Windows and Linux
+
+Execution order: after ExtendedUnpacker, before Clean and before media managers scan the payload.
+
+## 2) Contract snapshot
+
+Exit codes:
+- `POSTPROCESS_SUCCESS = 93`
+- `POSTPROCESS_ERROR   = 94`
+- `POSTPROCESS_NONE    = 95`
+
+Env vars read at runtime:
+
+**Required**
+- `NZBPP_DIRECTORY`
+- `NZBPP_STATUS` with fallback `NZBPP_TOTALSTATUS`
+
+**Optional**
+- `NZBPP_NZBNAME`
+- `NZBPP_CATEGORY`
+
+Required options provided as env vars:
+- `NZBPO_REMOVEDIRECTORIES`
+- `NZBPO_REMOVEFILES`
+- `NZBPO_DEBUG`
+- `NZBPO_VIDEOSIZETHRESHOLDMB`
+- `NZBPO_VIDEOEXTS`
+- `NZBPO_AUDIOSIZETHRESHOLDMB`
+- `NZBPO_AUDIOEXTS`
+
+Optional toggles (read only if present, some land in v1.1.0):
+- `NZBPO_TESTMODE`
+- `NZBPO_BLOCKIMPORTDURINGTEST`
+- `NZBPO_RELATIVEPERCENT`
+- `NZBPO_PROTECTEDPATHS`
+- `NZBPO_DENYPATTERNS`
+- `NZBPO_IMAGESAMPLES`
+- `NZBPO_JUNKEXTRAS`
+- `NZBPO_CATEGORYTHRESHOLDS`
+- `NZBPO_QUARANTINEMODE`
+- `NZBPO_QUARANTINEMAXAGEDAYS`
+
+If you need a new `NZBPO_*` key, open an issue first.
+
+## 3) Detection model
+- Name patterns: case-insensitive matches for words like `sample`, common dot variants, and typical scene junk. Never hard-code titles. Prefer pattern lists that are user configurable.
+- Size thresholds: treat very small video or audio as samples. Defaults come from the options above. Relative-percent can be used when enabled.
+- Category overrides: when enabled, thresholds may vary by `NZBPP_CATEGORY`.
+
+## 4) Safety rules
+- If `NZBPP_STATUS` or `NZBPP_TOTALSTATUS` is not success, exit 95 without changing files.
+- **Perform deletions or moves only when `NZBPO_REMOVEFILES=yes` or `NZBPO_REMOVEDIRECTORIES=yes`. When `NZBPO_TESTMODE=yes`, never modify files (simulate only).**
+- Never traverse above `NZBPP_DIRECTORY`. Reject symlinks.
+- Respect `PROTECTEDPATHS` and deny lists. When quarantine is enabled, move to `_samples_quarantine` and optionally purge by age.
+- Keep the Windows UTF-8 console safeguard near the top of `main.py` so debug logs do not throw `UnicodeEncodeError`.
+- Never traverse above `NZBPP_DIRECTORY`. Reject symlinks and Windows junctions.
+
+## 5) Logs
+- `[INFO]` actions, `[ERROR]` failures, `[DEBUG]` only when `NZBPO_DEBUG` is true.
+- Always print one final summary line, for example:
+  `Summary: removed 2 files, 1 dir; quarantined 0; errors 0; exit=93`
+- Return the correct exit code.
+
+## 6) Local test recipes
+
+Linux or macOS (bash):
+```bash
+export NZBPP_DIRECTORY="/abs/path/to/testdir"
+export NZBPP_STATUS=SUCCESS
+export NZBPO_REMOVEDIRECTORIES=yes
+export NZBPO_REMOVEFILES=yes
+export NZBPO_DEBUG=no
+export NZBPO_VIDEOSIZETHRESHOLDMB=150
+export NZBPO_VIDEOEXTS=".mkv,.mp4,.avi,.mov,.ts,.m4v"
+export NZBPO_AUDIOSIZETHRESHOLDMB=2
+export NZBPO_AUDIOEXTS=".mp3,.flac,.m4a,.ogg,.wav"
+export NZBPO_TESTMODE=yes
+# Optional toggles:
+# export NZBPO_BLOCKIMPORTDURINGTEST=yes
+# export NZBPO_QUARANTINEMODE=yes
+# export NZBPO_QUARANTINEMAXAGEDAYS=30
+
+python3 main.py; echo "exit=$?"
+```
+
+Windows PowerShell:
+```powershell
+$env:NZBPP_DIRECTORY = "C:\Path\To\testdir"
+$env:NZBPP_STATUS = "SUCCESS"
+$env:NZBPO_REMOVEDIRECTORIES = "yes"
+$env:NZBPO_REMOVEFILES = "yes"
+$env:NZBPO_DEBUG = "no"
+$env:NZBPO_VIDEOSIZETHRESHOLDMB = "150"
+$env:NZBPO_VIDEOEXTS = ".mkv,.mp4,.avi,.mov,.ts,.m4v"
+$env:NZBPO_AUDIOSIZETHRESHOLDMB = "2"
+$env:NZBPO_AUDIOEXTS = ".mp3,.flac,.m4a,.ogg,.wav"
+$env:NZBPO_TESTMODE = "yes"
+# Optional toggles (uncomment as needed)
+# $env:NZBPO_BLOCKIMPORTDURINGTEST = "yes"
+# $env:NZBPO_QUARANTINEMODE = "yes"
+# $env:NZBPO_QUARANTINEMAXAGEDAYS = "30"
+
+python .\main.py; echo "exit=$LASTEXITCODE"
+```
+
+Test corpus guidelines:
+- Include nested `sample` folders, tiny audio, a few image assets, long and Unicode paths. Verify summary text and exit code.
+
+## 7) Coding guidelines
+- Keep env parsing helpers tight and explicit. Do not assume casing or presence.
+- Avoid OS-specific path assumptions. Use `pathlib` where possible.
+- Do not hard-code user policy. Use options and flags.
+
+## 8) Versioning and PR checklist
+- Increment version when behavior changes and update the changelog.
+- PR title in imperative mood and scoped, for example: `fix: honor ProtectedPaths under dry run`.
+- Include what you tested, on which OS, and the observed exit code.
+- Acceptance criteria:
+  - Contract header values unchanged
+  - Required env keys and option names intact
+  - One summary line in logs
+  - Windows UTF-8 safeguard present
+  - Local smoke test completed
+
+## 9) Common tasks
+- Adjust thresholds: change option defaults and descriptions, not the detection core.
+- Add deny pattern: extend `NZBPO_DENYPATTERNS` list, not hard-coded checks.
+- Protect a file or dir: add to `NZBPO_PROTECTEDPATHS`.
+- Enable quarantine: set `QuarantineMode=Yes`, optionally `QuarantineMaxAgeDays>0`.
+
+## 10) Ownership
+If uncertain, run a one-minute local simulation and include 2–3 bullets of findings in the PR.
+
+Maintainer: Anunnaki-Astronaut
+
+URL: https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## v1.1.0
+
+This release introduces several powerful new features for more flexible and safer sample detection, along with a new Test Mode for previewing changes.
+
+### New Features
+*   **Test Mode**: A new safe-run option that logs what the script *would* remove without changing any files. Perfect for tuning settings.
+*   **Block Import During Test**: An optional companion to Test Mode that tells NZBGet to report a failure, preventing media managers from importing a download during a test run.
+*   **Relative Size % Detection**: A new detection method that identifies a video file as a sample if its size is below a certain percentage of the largest video in the same download. This allows for dynamic thresholds based on the content (e.g., 8% of a 10 GB movie vs. 8% of a 2 GB TV episode).
+*   **Category Thresholds**: Users can now override the global Relative Size % for specific NZBGet categories.
+*   **Protected Names/Paths**: A new option to specify file and directory names/patterns that should *never* be removed, giving users full control to protect important assets like subtitles or posters.
+*   **Deny Patterns**: An extra list of user-defined patterns to flag additional files for removal.
+*   **Image Samples & Junk Extras**: Optional toggles to remove common image-based samples and other release clutter like `.url` files.
+*   **Quarantine Mode**: Instead of permanently deleting files, this mode moves them to a `_samples_quarantine` subfolder for review.
+*   **Quarantine Max Age**: An automatic purge option to delete files from the quarantine folder after a specified number of days.
+
+### Notes
+*   Change history for versions prior to v1.1.0 can be found in the release tags on GitHub.