jellyplex-sync 0.3.4__tar.gz → 0.5.0__tar.gz

jellyplex_sync-0.3.4/README.md → jellyplex_sync-0.5.0/PKG-INFO

@@ -1,14 +1,38 @@
+Metadata-Version: 2.4
+Name: jellyplex-sync
+Version: 0.5.0
+Summary: Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror
+Keywords: plex,jellyfin,media-library,movies,sync,hardlink,mirror
+Author: Stefan Schönberger
+Author-email: Stefan Schönberger <stefan@sniner.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/sniner/jellyplex-sync
+Project-URL: Repository, https://github.com/sniner/jellyplex-sync
+Project-URL: Issues, https://github.com/sniner/jellyplex-sync/issues
+Project-URL: Changelog, https://github.com/sniner/jellyplex-sync/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
 # Bidirectional Movie Library Sync for Plex and Jellyfin
 
 Can't decide between Jellyfin and Plex? This tool might help. It synchronizes your **movie library** between Jellyfin and Plex formats in **both directions** — without duplicating any files. Instead, it uses **hardlinks** to mirror your collection efficiently, saving storage while keeping both libraries in sync.
 
-> ⚠️ **0.3.0 is another major rewrite.** The internals are reorganised into a clean `discover → plan → realize` pipeline with an immutable Plan as a first-class concept. User-visible: a new **`plan` subcommand** that shows what a sync would do (text or `--json`) without touching anything, and **video-level clashes now auto-resolve with a hash suffix** instead of aborting the movie. The `sync` and `diff` CLI is unchanged. If you depend on the old shape, **try the new version with `--dry-run` first**. Cautious users can pin to a `0.2.x` (or even `0.1.x`) release until they're comfortable. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
-
 ## Overview
 
 The script scans the source library, parses each movie folder for metadata (title, year, optional provider ID), and reproduces the same directory structure in the target location. Rather than copying video files, it creates hard links to avoid extra storage usage. Asset folders (e.g., `extras`, `subtitles`) are also mirrored. Loose top-level files (posters, NFOs, subtitles) are synced 1:1 by default since 0.2.0. With `--delete`, any files or folders in the target that are no longer present in the source will be removed.
 
-> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning.
+> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning. Folders you mark with `.jellyplex-sync-ignore` are the exception, see [Excluding folders](#excluding-folders).
 
 > **Note:** This tool is only useful if your media library is well-maintained and each movie resides in its own folder.
 
@@ -82,6 +106,15 @@ The first positional is the source library, the second is the target. By default
 
 Use `--copy` when source and target are on different filesystems (NAS to local disk, cross-pool moves, etc.). The size+mtime check makes re-runs cheap.
 
+#### Exit codes
+
+- `0` — sync completed (including "nothing to do").
+- `1` — setup error (missing directories, undecipherable format, hardlinks across
+  filesystem boundaries).
+- `2` — folder-level clash: the run was aborted, nothing was synced.
+- `3` — sync completed, but some items marked for removal could not be removed
+  (permissions, busy files); they remain in the target.
+
 #### Examples
 
 Mirror a Jellyfin library into a new Plex structure:
@@ -120,7 +153,8 @@ Exit codes follow the Unix `diff` convention:
 
 - `0` — in sync.
 - `1` — differences found.
-- `2` — setup error (missing directories, indecipherable format).
+- `2` — setup error (missing directories, indecipherable format), or one of the
+  library folders contains `.jellyplex-sync-ignore`.
 
 #### Example
 
@@ -203,6 +237,28 @@ Preview first, keeping the source:
 jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
 ```
 
+### Excluding folders
+
+To exclude a folder and everything below it, put an empty file named `.jellyplex-sync-ignore` into it:
+
+```bash
+touch ~/"Media/Plex/Some Movie (2001) {imdb-tt0000000}/.jellyplex-sync-ignore"
+```
+
+The marker means the same in both directions, so it does not matter whether the library is the source or the target of a run:
+
+- **In the source**, the folder is treated as if it did not exist. Nothing in it is synced or imported.
+- **In the target**, nothing is written into the folder and nothing is removed from it, not even with `--delete`. A marked folder that has no counterpart in the source is not reported as a stray.
+
+The marker works at any level: in a movie folder, in an asset folder such as `other`, or further down. The marker file itself is never copied to the other library.
+
+Things to know:
+
+- **Marking a source folder does not keep its copy in the target.** If the folder was synced before, its copy in the target becomes a stray: it is reported, and `--delete` removes it. The source folder is not touched. To keep the copy, put a marker into the target folder as well.
+- **A marked folder is also kept when `--delete` would remove a folder above it.** If a folder in the target has no counterpart in the source but contains a marked folder at any depth, the whole folder is kept.
+- **A marker in the library folder itself stops the run.** `sync` and `import` change nothing, print a warning and exit with code 0. `diff` exits with code 2, and `plan` shows an empty plan. A marked source library is not treated as an empty library, so `--delete` cannot clear the target this way.
+- At the end of a `sync` or `import` run, the number of marked folders is printed; `--verbose` lists them. `diff` and `plan` always list them. In the `--json` output they are in `marked_in_source` and `marked_in_target`.
+
 ### JSON output
 
 All three subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
@@ -214,15 +270,16 @@ The schema (still evolving — pin a version when consuming):
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
 - `summary`: counters; the set of fields depends on the operation.
-  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`, `clashes`.
-  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`, `marked_in_source`, `marked_in_target`.
+  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`, `marked_in_source`, `marked_in_target`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
+- `marked_in_source` / `marked_in_target`: full paths of the folders skipped because they contain `.jellyplex-sync-ignore` (see [Excluding folders](#excluding-folders)). A library folder in one of these lists means the run was stopped.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
-- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove`. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
+- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove` — `link` covers every creation, including copies in `--copy` mode. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
 - `clashes` (sync only): movie-level video clashes the disambiguator couldn't resolve at all. Normally empty since the hash-fallback resolves the practical cases.
 - `diff`-specific fields: `movies_only_in_source`, `movies_only_in_target`, `differing_movies`, `in_sync`.
-- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case.
+- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case. Videos and movies that lose labels or attributes in translation carry their own `drops` / `folder_drops` lists (same `{kind, key, value, reason}` shape as `translation_losses`, but per file — so you can see which file loses what).
 
 #### `jq` examples
 
@@ -288,10 +345,12 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Hardlinks (default)** — Video files are linked, not copied. Both libraries reference the same physical files on disk. Switch to `--copy` for cross-filesystem setups.
 - **Asset folders** — Subdirectories (e.g., `other`, `interviews`) are processed recursively with the same materialization strategy. Note: rename your Jellyfin `extras` folder to `other`, since Plex does not recognize `extras`.
 - **Loose top-level files** — Sidecar files (`.nfo`, posters, external subtitles, plain notes) at the top of a movie folder are synced 1:1 by default since 0.2.0. Pre-0.2.0 they were silently dropped — which made the tool unsafe for migrations. Dot-files (`.DS_Store`, `.stversions`, …) stay excluded.
-- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
+- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed, except folders marked with `.jellyplex-sync-ignore` and folders that contain one. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
+- **Hidden files and folders are skipped.** Names starting with a dot (`.DS_Store`, `.stversions`, `.Trash`) are skipped at every level of the source library, by `import` as well. They do not appear in the list of ignored items.
+- **Marked folders are skipped** on both sides, see [Excluding folders](#excluding-folders).
 - **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
-- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped, the clashing folders are listed, and you're asked to rename one side.
+- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped with exit code 2, the clashing folders are listed, and you're asked to rename one side.
 
 ## Library layouts
 
@@ -317,7 +376,7 @@ Each movie must reside in its own folder, with optional subfolders for extras. D
 
 #### Special filename handling
 
-Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [SPECS.md](./SPECS.md).
+Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [docs/SPECS.md](./docs/SPECS.md).
 
 ### Plex
 
@@ -345,6 +404,12 @@ Movies
         └── Making of.mkv
 ```
 
+## Development
+
+The pipeline architecture and internal vocabulary are documented in
+[docs/DEV.md](./docs/DEV.md); the Plex/Jellyfin format details and translation
+rules live in [docs/SPECS.md](./docs/SPECS.md).
+
 ## License
 
 This project is licensed under the [BSD 3-Clause License](./LICENSE).

jellyplex_sync-0.3.4/PKG-INFO → jellyplex_sync-0.5.0/README.md

@@ -1,30 +1,12 @@
-Metadata-Version: 2.4
-Name: jellyplex-sync
-Version: 0.3.4
-Summary: Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror
-Author: Stefan Schönberger
-Author-email: Stefan Schönberger <stefan@sniner.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
 # Bidirectional Movie Library Sync for Plex and Jellyfin
 
 Can't decide between Jellyfin and Plex? This tool might help. It synchronizes your **movie library** between Jellyfin and Plex formats in **both directions** — without duplicating any files. Instead, it uses **hardlinks** to mirror your collection efficiently, saving storage while keeping both libraries in sync.
 
-> ⚠️ **0.3.0 is another major rewrite.** The internals are reorganised into a clean `discover → plan → realize` pipeline with an immutable Plan as a first-class concept. User-visible: a new **`plan` subcommand** that shows what a sync would do (text or `--json`) without touching anything, and **video-level clashes now auto-resolve with a hash suffix** instead of aborting the movie. The `sync` and `diff` CLI is unchanged. If you depend on the old shape, **try the new version with `--dry-run` first**. Cautious users can pin to a `0.2.x` (or even `0.1.x`) release until they're comfortable. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
-
 ## Overview
 
 The script scans the source library, parses each movie folder for metadata (title, year, optional provider ID), and reproduces the same directory structure in the target location. Rather than copying video files, it creates hard links to avoid extra storage usage. Asset folders (e.g., `extras`, `subtitles`) are also mirrored. Loose top-level files (posters, NFOs, subtitles) are synced 1:1 by default since 0.2.0. With `--delete`, any files or folders in the target that are no longer present in the source will be removed.
 
-> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning.
+> **Warning:** This script will **overwrite the entire target directory**. Do not store or edit anything manually in the target library path. The source library is treated as the **only source of truth**, and any unmatched content in the target folder may be deleted without warning. Folders you mark with `.jellyplex-sync-ignore` are the exception, see [Excluding folders](#excluding-folders).
 
 > **Note:** This tool is only useful if your media library is well-maintained and each movie resides in its own folder.
 
@@ -98,6 +80,15 @@ The first positional is the source library, the second is the target. By default
 
 Use `--copy` when source and target are on different filesystems (NAS to local disk, cross-pool moves, etc.). The size+mtime check makes re-runs cheap.
 
+#### Exit codes
+
+- `0` — sync completed (including "nothing to do").
+- `1` — setup error (missing directories, undecipherable format, hardlinks across
+  filesystem boundaries).
+- `2` — folder-level clash: the run was aborted, nothing was synced.
+- `3` — sync completed, but some items marked for removal could not be removed
+  (permissions, busy files); they remain in the target.
+
 #### Examples
 
 Mirror a Jellyfin library into a new Plex structure:
@@ -136,7 +127,8 @@ Exit codes follow the Unix `diff` convention:
 
 - `0` — in sync.
 - `1` — differences found.
-- `2` — setup error (missing directories, indecipherable format).
+- `2` — setup error (missing directories, indecipherable format), or one of the
+  library folders contains `.jellyplex-sync-ignore`.
 
 #### Example
 
@@ -219,6 +211,28 @@ Preview first, keeping the source:
 jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
 ```
 
+### Excluding folders
+
+To exclude a folder and everything below it, put an empty file named `.jellyplex-sync-ignore` into it:
+
+```bash
+touch ~/"Media/Plex/Some Movie (2001) {imdb-tt0000000}/.jellyplex-sync-ignore"
+```
+
+The marker means the same in both directions, so it does not matter whether the library is the source or the target of a run:
+
+- **In the source**, the folder is treated as if it did not exist. Nothing in it is synced or imported.
+- **In the target**, nothing is written into the folder and nothing is removed from it, not even with `--delete`. A marked folder that has no counterpart in the source is not reported as a stray.
+
+The marker works at any level: in a movie folder, in an asset folder such as `other`, or further down. The marker file itself is never copied to the other library.
+
+Things to know:
+
+- **Marking a source folder does not keep its copy in the target.** If the folder was synced before, its copy in the target becomes a stray: it is reported, and `--delete` removes it. The source folder is not touched. To keep the copy, put a marker into the target folder as well.
+- **A marked folder is also kept when `--delete` would remove a folder above it.** If a folder in the target has no counterpart in the source but contains a marked folder at any depth, the whole folder is kept.
+- **A marker in the library folder itself stops the run.** `sync` and `import` change nothing, print a warning and exit with code 0. `diff` exits with code 2, and `plan` shows an empty plan. A marked source library is not treated as an empty library, so `--delete` cannot clear the target this way.
+- At the end of a `sync` or `import` run, the number of marked folders is printed; `--verbose` lists them. `diff` and `plan` always list them. In the `--json` output they are in `marked_in_source` and `marked_in_target`.
+
 ### JSON output
 
 All three subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
@@ -230,15 +244,16 @@ The schema (still evolving — pin a version when consuming):
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
 - `summary`: counters; the set of fields depends on the operation.
-  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`, `clashes`.
-  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`, `marked_in_source`, `marked_in_target`.
+  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`, `marked_in_source`, `marked_in_target`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
+- `marked_in_source` / `marked_in_target`: full paths of the folders skipped because they contain `.jellyplex-sync-ignore` (see [Excluding folders](#excluding-folders)). A library folder in one of these lists means the run was stopped.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
-- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove`. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
+- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove` — `link` covers every creation, including copies in `--copy` mode. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
 - `clashes` (sync only): movie-level video clashes the disambiguator couldn't resolve at all. Normally empty since the hash-fallback resolves the practical cases.
 - `diff`-specific fields: `movies_only_in_source`, `movies_only_in_target`, `differing_movies`, `in_sync`.
-- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case.
+- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case. Videos and movies that lose labels or attributes in translation carry their own `drops` / `folder_drops` lists (same `{kind, key, value, reason}` shape as `translation_losses`, but per file — so you can see which file loses what).
 
 #### `jq` examples
 
@@ -304,10 +319,12 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Hardlinks (default)** — Video files are linked, not copied. Both libraries reference the same physical files on disk. Switch to `--copy` for cross-filesystem setups.
 - **Asset folders** — Subdirectories (e.g., `other`, `interviews`) are processed recursively with the same materialization strategy. Note: rename your Jellyfin `extras` folder to `other`, since Plex does not recognize `extras`.
 - **Loose top-level files** — Sidecar files (`.nfo`, posters, external subtitles, plain notes) at the top of a movie folder are synced 1:1 by default since 0.2.0. Pre-0.2.0 they were silently dropped — which made the tool unsafe for migrations. Dot-files (`.DS_Store`, `.stversions`, …) stay excluded.
-- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
+- **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed, except folders marked with `.jellyplex-sync-ignore` and folders that contain one. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
+- **Hidden files and folders are skipped.** Names starting with a dot (`.DS_Store`, `.stversions`, `.Trash`) are skipped at every level of the source library, by `import` as well. They do not appear in the list of ignored items.
+- **Marked folders are skipped** on both sides, see [Excluding folders](#excluding-folders).
 - **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
-- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped, the clashing folders are listed, and you're asked to rename one side.
+- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped with exit code 2, the clashing folders are listed, and you're asked to rename one side.
 
 ## Library layouts
 
@@ -333,7 +350,7 @@ Each movie must reside in its own folder, with optional subfolders for extras. D
 
 #### Special filename handling
 
-Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [SPECS.md](./SPECS.md).
+Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [docs/SPECS.md](./docs/SPECS.md).
 
 ### Plex
 
@@ -361,6 +378,12 @@ Movies
         └── Making of.mkv
 ```
 
+## Development
+
+The pipeline architecture and internal vocabulary are documented in
+[docs/DEV.md](./docs/DEV.md); the Plex/Jellyfin format details and translation
+rules live in [docs/SPECS.md](./docs/SPECS.md).
+
 ## License
 
 This project is licensed under the [BSD 3-Clause License](./LICENSE).

jellyplex_sync-0.5.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "jellyplex-sync"
+version = "0.5.0"
+description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
+requires-python = ">=3.11"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+keywords = [
+    "plex",
+    "jellyfin",
+    "media-library",
+    "movies",
+    "sync",
+    "hardlink",
+    "mirror",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = []
+
+[[project.authors]]
+name = "Stefan Schönberger"
+email = "stefan@sniner.dev"
+
+[project.urls]
+Homepage = "https://github.com/sniner/jellyplex-sync"
+Repository = "https://github.com/sniner/jellyplex-sync"
+Issues = "https://github.com/sniner/jellyplex-sync/issues"
+Changelog = "https://github.com/sniner/jellyplex-sync/blob/main/CHANGELOG.md"
+
+[project.scripts]
+jellyplex = "jellyplex_sync.cli.main:main"
+jellyplex-sync = "jellyplex_sync.cli.sync:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5,<9",
+    "jellyplex-gen>=0.1.0",
+    "ruff>=0.15.5,<0.16",
+    "basedpyright>=1.38.2,<2",
+]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = ["tests"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnknownArgumentType = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportMissingTypeArgument = false
+reportPrivateUsage = false
+reportUnusedCallResult = false
+reportMissingTypeStubs = false
+
+[tool.ruff]
+line-length = 96
+
+[tool.ruff.lint]
+ignore = ["E402"]
+extend-select = [
+    "I",
+    "UP",
+    "SIM",
+    "B",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"

jellyplex_sync-0.3.4/pyproject.toml → jellyplex_sync-0.5.0/pyproject.toml.orig

@@ -1,21 +1,33 @@
 [project]
 name = "jellyplex-sync"
-version = "0.3.4"
+version = "0.5.0"
 description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
 authors = [{ name = "Stefan Schönberger", email = "stefan@sniner.dev" }]
 requires-python = ">=3.11"
 readme = "README.md"
 license = "BSD-3-Clause"
 license-files = ["LICENSE"]
+keywords = ["plex", "jellyfin", "media-library", "movies", "sync", "hardlink", "mirror"]
 classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
 ]
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/sniner/jellyplex-sync"
+Repository = "https://github.com/sniner/jellyplex-sync"
+Issues = "https://github.com/sniner/jellyplex-sync/issues"
+Changelog = "https://github.com/sniner/jellyplex-sync/blob/main/CHANGELOG.md"
+
 [project.scripts]
 jellyplex = "jellyplex_sync.cli.main:main"
 jellyplex-sync = "jellyplex_sync.cli.sync:main"
@@ -24,13 +36,15 @@ jellyplex-sync = "jellyplex_sync.cli.sync:main"
 dev = [
     "pytest>=8.3.5,<9",
     "jellyplex-gen>=0.1.0",
+    "ruff>=0.15.5,<0.16",
+    "basedpyright>=1.38.2,<2",
 ]
 
 [tool.uv]
 default-groups = "all"
 
 [build-system]
-requires = ["uv_build>=0.10.4,<0.11.0"]
+requires = ["uv_build>=0.12,<0.13"]
 build-backend = "uv_build"
 
 [tool.pytest.ini_options]
@@ -38,11 +52,27 @@ addopts = "-ra -q"
 testpaths = ["tests"]
 
 [tool.pyright]
-typeCheckingMode = "standard"
+typeCheckingMode = "strict"
 useLibraryCodeForTypes = true
 venvPath = "."
 venv = ".venv"
 
+# Tests stay at standard-level strictness: annotating every pytest
+# fixture parameter adds noise, not safety. The library itself is
+# checked strict.
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnknownArgumentType = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportMissingTypeArgument = false
+reportPrivateUsage = false
+reportUnusedCallResult = false
+reportMissingTypeStubs = false
+
 [tool.ruff]
 line-length = 96
 

{jellyplex_sync-0.3.4 → jellyplex_sync-0.5.0}/src/jellyplex_sync/__init__.py

@@ -1,3 +1,7 @@
+from .compare import (
+    DiffEntry,
+    DiffResult,
+)
 from .jellyfin import (
     JellyfinLibraryReader,
     JellyfinLibraryWriter,
@@ -14,6 +18,7 @@ from .library import (
     LibraryWriter,
     LoggingReporter,
     MovieClash,
+    NullReporter,
     Reporter,
     StrictReporter,
     dedupe_drops,
@@ -41,8 +46,8 @@ from .plex import (
     PlexLibraryWriter,
 )
 from .sync import (
-    DiffEntry,
-    DiffResult,
+    LibraryStats,
+    SyncResult,
     diff,
     import_media,
     plan,
@@ -63,15 +68,17 @@ __all__ = [
     "FolderClash",
     "ForceCopyMaterializer",
     "HardlinkMaterializer",
-    "MoveMaterializer",
     "IgnoredEntry",
     "JellyfinLibraryReader",
     "JellyfinLibraryWriter",
     "LibraryReader",
+    "LibraryStats",
     "LibraryWriter",
     "LoggingReporter",
+    "MoveMaterializer",
     "MovieClash",
     "MovieInfo",
+    "NullReporter",
     "Plan",
     "PlannedAsset",
     "PlannedFile",
@@ -80,6 +87,7 @@ __all__ = [
     "PlexLibraryWriter",
     "Reporter",
     "StrictReporter",
+    "SyncResult",
     "VideoInfo",
     "dedupe_drops",
     "diff",