jellyplex-sync 0.3.2__tar.gz → 0.4.0__tar.gz

{jellyplex_sync-0.3.2 → jellyplex_sync-0.4.0}/PKG-INFO

@@ -1,25 +1,33 @@
 Metadata-Version: 2.4
 Name: jellyplex-sync
-Version: 0.3.2
+Version: 0.4.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.
@@ -44,7 +52,7 @@ The easiest way to install the CLI is via [uv](https://docs.astral.sh/uv/):
 uv tool install jellyplex-sync
 ```
 
-This places `jellyplex-sync` on your `PATH` in an isolated environment. `pipx install jellyplex-sync` works the same way if you prefer pipx.
+This places `jellyplex` and `jellyplex-sync` on your `PATH` in an isolated environment. `pipx install jellyplex-sync` works the same way if you prefer pipx.
 
 ### Docker
 
@@ -62,17 +70,19 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into four subcommands:
+The main CLI is `jellyplex` with four subcommands:
+
+- **`jellyplex sync`** — mirror a source library into the target layout.
+- **`jellyplex diff`** — read-only comparison of source and target. No filesystem changes. Useful before deleting your source after a migration.
+- **`jellyplex plan`** — show the Plan a sync would execute (text or `--json`), without touching either side. Pre-flight check before sync, or machine-readable input for tooling.
+- **`jellyplex import`** — **(experimental)** import video files from a staging area into a structured library. See below.
 
-- **`sync`** — mirror a source library into the target layout (the historical operation; this is also the default if you omit the subcommand).
-- **`diff`** — read-only comparison of source and target. No filesystem changes. Useful before deleting your source after a migration.
-- **`plan`** — show the Plan a sync would execute (text or `--json`), without touching either side. Pre-flight check before sync, or machine-readable input for tooling.
-- **`import`** — **(experimental)** import video files from a staging area into a structured library. See below.
+For backward compatibility, `jellyplex-sync` is also installed as a standalone command that does exactly what `jellyplex sync` does — same options, no subcommand needed.
 
 ### `sync`
 
 ```bash
-jellyplex-sync sync [OPTIONS] /path/to/source/library /path/to/target/library
+jellyplex sync [OPTIONS] /path/to/source/library /path/to/target/library
 ```
 
 The first positional is the source library, the second is the target. By default the tool auto-detects whether the source is a Jellyfin or Plex layout and converts to the other format.
@@ -96,36 +106,45 @@ 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:
 
 ```bash
-jellyplex-sync sync --create ~/Media/Jellyfin ~/Media/Plex
+jellyplex sync --create ~/Media/Jellyfin ~/Media/Plex
 ```
 
 Migration with cleanup (target becomes a clean mirror):
 
 ```bash
-jellyplex-sync sync --delete --create ~/Media/Jellyfin ~/Media/Plex
+jellyplex sync --delete --create ~/Media/Jellyfin ~/Media/Plex
 ```
 
 Cross-filesystem copy with safe re-runs:
 
 ```bash
-jellyplex-sync sync --copy --create /mnt/nas/Movies /mnt/local/Plex
+jellyplex sync --copy --create /mnt/nas/Movies /mnt/local/Plex
 ```
 
 Dry-run a verbose, full sync with deletion:
 
 ```bash
-jellyplex-sync sync --dry-run --verbose --delete --create ~/Media/Jellyfin ~/Media/Plex
+jellyplex sync --dry-run --verbose --delete --create ~/Media/Jellyfin ~/Media/Plex
 ```
 
 ### `diff`
 
 ```bash
-jellyplex-sync diff [OPTIONS] /path/to/source/library /path/to/target/library
+jellyplex diff [OPTIONS] /path/to/source/library /path/to/target/library
 ```
 
 Compares the two libraries without touching anything. Reports movies that exist only on one side, file-level differences inside shared movies, translation losses (Plex labels with no Jellyfin equivalent, for example), and entries the scanner ignored.
@@ -141,13 +160,13 @@ Exit codes follow the Unix `diff` convention:
 Verify a target is a complete mirror before deleting the source:
 
 ```bash
-jellyplex-sync diff ~/Media/Jellyfin ~/Media/Plex
+jellyplex diff ~/Media/Jellyfin ~/Media/Plex
 ```
 
 ### `plan`
 
 ```bash
-jellyplex-sync plan [OPTIONS] /path/to/source/library /path/to/target/library
+jellyplex plan [OPTIONS] /path/to/source/library /path/to/target/library
 ```
 
 Shows the Plan a sync would execute — every movie folder, every translated video filename, every loose file, every asset subdirectory — without touching either filesystem. Useful as a pre-flight check ("will any movies clash? what gets translated?") or as a machine-readable input for tooling with `--json`.
@@ -164,13 +183,13 @@ Exit codes:
 Pre-flight a sync, see exactly which target filenames would be created:
 
 ```bash
-jellyplex-sync plan ~/Media/Plex ~/Media/Jellyfin
+jellyplex plan ~/Media/Plex ~/Media/Jellyfin
 ```
 
 Machine-readable, with `jq` to find videos that needed disambiguation:
 
 ```bash
-jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
+jellyplex plan --json ~/Media/Plex ~/Media/Jellyfin \
     | jq '.movies[].videos[] | select(.disambiguation) | {source, target_name, disambiguation}'
 ```
 
@@ -179,7 +198,7 @@ jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
 > ⚠️ **This subcommand is experimental.** The exact behaviour may change in future releases as real-world use cases become clearer. Always start with `--dry-run`.
 
 ```bash
-jellyplex-sync import [OPTIONS] /path/to/staging /path/to/target/library
+jellyplex import [OPTIONS] /path/to/staging /path/to/target/library
 ```
 
 Imports video files from a staging area — a flat directory (or directory tree) where properly named video files have been dumped without the one-folder-per-movie structure that `sync` expects. Files are grouped by their parsed movie identity (title, year, provider ID) and placed into the correct movie folder in the target library.
@@ -208,13 +227,13 @@ Other flags: `--dry-run`, `--create`, `--source-format`, `--target-format`, `-v`
 Move Plex-named video files into a new Jellyfin library:
 
 ```bash
-jellyplex-sync import --create /mnt/staging /mnt/library/Jellyfin
+jellyplex import --create /mnt/staging /mnt/library/Jellyfin
 ```
 
 Preview first, keeping the source:
 
 ```bash
-jellyplex-sync import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
+jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
 ```
 
 ### JSON output
@@ -228,55 +247,39 @@ 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`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`.
   - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
 - `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
 
 Show every file that would be replaced (with full paths):
 
 ```bash
-jellyplex-sync sync --json --dry-run /src /dst \
+jellyplex sync --json --dry-run /src /dst \
     | jq '.events[] | select(.action == "replace") | {source, target}'
 ```
 
 Verify nothing important gets deleted before running a migration with `--delete`:
 
 ```bash
-jellyplex-sync sync --json --dry-run --delete /src /dst \
+jellyplex sync --json --dry-run --delete /src /dst \
     | jq '.events[] | select(.action == "remove")'
 ```
 
 Action distribution:
 
 ```bash
-jellyplex-sync sync --json --dry-run /src /dst \
+jellyplex sync --json --dry-run /src /dst \
     | jq '[.events[].action] | group_by(.) | map({action: .[0], count: length})'
 ```
 
-### Default subcommand
-
-For backward compatibility, omitting the subcommand is treated as an implicit `sync` (as long as the first argument is a positional, not a flag):
-
-```bash
-jellyplex-sync ~/Media/Jellyfin ~/Media/Plex
-```
-
-is equivalent to
-
-```bash
-jellyplex-sync sync ~/Media/Jellyfin ~/Media/Plex
-```
-
-If you start with a flag, you must spell out `sync` explicitly.
-
 ### Docker
 
 ```bash
@@ -321,7 +324,7 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **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`.
 - **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.
 - **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
 
@@ -347,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
 
@@ -375,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.3.2 → jellyplex_sync-0.4.0}/README.md

@@ -2,8 +2,6 @@
 
 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.
@@ -28,7 +26,7 @@ The easiest way to install the CLI is via [uv](https://docs.astral.sh/uv/):
 uv tool install jellyplex-sync
 ```
 
-This places `jellyplex-sync` on your `PATH` in an isolated environment. `pipx install jellyplex-sync` works the same way if you prefer pipx.
+This places `jellyplex` and `jellyplex-sync` on your `PATH` in an isolated environment. `pipx install jellyplex-sync` works the same way if you prefer pipx.
 
 ### Docker
 
@@ -46,17 +44,19 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into four subcommands:
+The main CLI is `jellyplex` with four subcommands:
+
+- **`jellyplex sync`** — mirror a source library into the target layout.
+- **`jellyplex diff`** — read-only comparison of source and target. No filesystem changes. Useful before deleting your source after a migration.
+- **`jellyplex plan`** — show the Plan a sync would execute (text or `--json`), without touching either side. Pre-flight check before sync, or machine-readable input for tooling.
+- **`jellyplex import`** — **(experimental)** import video files from a staging area into a structured library. See below.
 
-- **`sync`** — mirror a source library into the target layout (the historical operation; this is also the default if you omit the subcommand).
-- **`diff`** — read-only comparison of source and target. No filesystem changes. Useful before deleting your source after a migration.
-- **`plan`** — show the Plan a sync would execute (text or `--json`), without touching either side. Pre-flight check before sync, or machine-readable input for tooling.
-- **`import`** — **(experimental)** import video files from a staging area into a structured library. See below.
+For backward compatibility, `jellyplex-sync` is also installed as a standalone command that does exactly what `jellyplex sync` does — same options, no subcommand needed.
 
 ### `sync`
 
 ```bash
-jellyplex-sync sync [OPTIONS] /path/to/source/library /path/to/target/library
+jellyplex sync [OPTIONS] /path/to/source/library /path/to/target/library
 ```
 
 The first positional is the source library, the second is the target. By default the tool auto-detects whether the source is a Jellyfin or Plex layout and converts to the other format.
@@ -80,36 +80,45 @@ 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:
 
 ```bash
-jellyplex-sync sync --create ~/Media/Jellyfin ~/Media/Plex
+jellyplex sync --create ~/Media/Jellyfin ~/Media/Plex
 ```
 
 Migration with cleanup (target becomes a clean mirror):
 
 ```bash
-jellyplex-sync sync --delete --create ~/Media/Jellyfin ~/Media/Plex
+jellyplex sync --delete --create ~/Media/Jellyfin ~/Media/Plex
 ```
 
 Cross-filesystem copy with safe re-runs:
 
 ```bash
-jellyplex-sync sync --copy --create /mnt/nas/Movies /mnt/local/Plex
+jellyplex sync --copy --create /mnt/nas/Movies /mnt/local/Plex
 ```
 
 Dry-run a verbose, full sync with deletion:
 
 ```bash
-jellyplex-sync sync --dry-run --verbose --delete --create ~/Media/Jellyfin ~/Media/Plex
+jellyplex sync --dry-run --verbose --delete --create ~/Media/Jellyfin ~/Media/Plex
 ```
 
 ### `diff`
 
 ```bash
-jellyplex-sync diff [OPTIONS] /path/to/source/library /path/to/target/library
+jellyplex diff [OPTIONS] /path/to/source/library /path/to/target/library
 ```
 
 Compares the two libraries without touching anything. Reports movies that exist only on one side, file-level differences inside shared movies, translation losses (Plex labels with no Jellyfin equivalent, for example), and entries the scanner ignored.
@@ -125,13 +134,13 @@ Exit codes follow the Unix `diff` convention:
 Verify a target is a complete mirror before deleting the source:
 
 ```bash
-jellyplex-sync diff ~/Media/Jellyfin ~/Media/Plex
+jellyplex diff ~/Media/Jellyfin ~/Media/Plex
 ```
 
 ### `plan`
 
 ```bash
-jellyplex-sync plan [OPTIONS] /path/to/source/library /path/to/target/library
+jellyplex plan [OPTIONS] /path/to/source/library /path/to/target/library
 ```
 
 Shows the Plan a sync would execute — every movie folder, every translated video filename, every loose file, every asset subdirectory — without touching either filesystem. Useful as a pre-flight check ("will any movies clash? what gets translated?") or as a machine-readable input for tooling with `--json`.
@@ -148,13 +157,13 @@ Exit codes:
 Pre-flight a sync, see exactly which target filenames would be created:
 
 ```bash
-jellyplex-sync plan ~/Media/Plex ~/Media/Jellyfin
+jellyplex plan ~/Media/Plex ~/Media/Jellyfin
 ```
 
 Machine-readable, with `jq` to find videos that needed disambiguation:
 
 ```bash
-jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
+jellyplex plan --json ~/Media/Plex ~/Media/Jellyfin \
     | jq '.movies[].videos[] | select(.disambiguation) | {source, target_name, disambiguation}'
 ```
 
@@ -163,7 +172,7 @@ jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
 > ⚠️ **This subcommand is experimental.** The exact behaviour may change in future releases as real-world use cases become clearer. Always start with `--dry-run`.
 
 ```bash
-jellyplex-sync import [OPTIONS] /path/to/staging /path/to/target/library
+jellyplex import [OPTIONS] /path/to/staging /path/to/target/library
 ```
 
 Imports video files from a staging area — a flat directory (or directory tree) where properly named video files have been dumped without the one-folder-per-movie structure that `sync` expects. Files are grouped by their parsed movie identity (title, year, provider ID) and placed into the correct movie folder in the target library.
@@ -192,13 +201,13 @@ Other flags: `--dry-run`, `--create`, `--source-format`, `--target-format`, `-v`
 Move Plex-named video files into a new Jellyfin library:
 
 ```bash
-jellyplex-sync import --create /mnt/staging /mnt/library/Jellyfin
+jellyplex import --create /mnt/staging /mnt/library/Jellyfin
 ```
 
 Preview first, keeping the source:
 
 ```bash
-jellyplex-sync import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
+jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
 ```
 
 ### JSON output
@@ -212,55 +221,39 @@ 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`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`.
   - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
 - `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
 
 Show every file that would be replaced (with full paths):
 
 ```bash
-jellyplex-sync sync --json --dry-run /src /dst \
+jellyplex sync --json --dry-run /src /dst \
     | jq '.events[] | select(.action == "replace") | {source, target}'
 ```
 
 Verify nothing important gets deleted before running a migration with `--delete`:
 
 ```bash
-jellyplex-sync sync --json --dry-run --delete /src /dst \
+jellyplex sync --json --dry-run --delete /src /dst \
     | jq '.events[] | select(.action == "remove")'
 ```
 
 Action distribution:
 
 ```bash
-jellyplex-sync sync --json --dry-run /src /dst \
+jellyplex sync --json --dry-run /src /dst \
     | jq '[.events[].action] | group_by(.) | map({action: .[0], count: length})'
 ```
 
-### Default subcommand
-
-For backward compatibility, omitting the subcommand is treated as an implicit `sync` (as long as the first argument is a positional, not a flag):
-
-```bash
-jellyplex-sync ~/Media/Jellyfin ~/Media/Plex
-```
-
-is equivalent to
-
-```bash
-jellyplex-sync sync ~/Media/Jellyfin ~/Media/Plex
-```
-
-If you start with a flag, you must spell out `sync` explicitly.
-
 ### Docker
 
 ```bash
@@ -305,7 +298,7 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **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`.
 - **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.
 - **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
 
@@ -331,7 +324,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
 
@@ -359,6 +352,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.4.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "jellyplex-sync"
+version = "0.4.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"