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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jellyplex-sync
-Version: 0.2.2
+Version: 0.3.2
 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>
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 
 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.2.0 is a major rewrite.** Subcommands, new materializer options, machine-readable `--json` output, default-sync-everything behavior, and a renamed model field (`tags` → `labels` in the Python API). If you depend on the old shape, **try the new version with `--dry-run` first**, and pin to a `0.1.x` release if anything looks off. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
+> ⚠️ **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
 
@@ -30,6 +30,8 @@ The script scans the source library, parses each movie folder for metadata (titl
 
 > ⚠️ **Movies only:** This script is designed exclusively for **movie libraries**. It does **not** support TV shows or miniseries. However, this is usually not a limitation in practice: for shows, Jellyfin and Plex use very similar directory structures, so you can typically point both apps to the same library without issues.
 
+> ⚠️ **Stacked / multi-part movies are not supported:** Plex's multi-part filename suffixes (`pt1`/`pt2`, `cd1`/`cd2`, `disc1`/`disc2`) are not recognized — each part is treated as a separate video, which will likely confuse the target scanner. Pre-join multi-disc releases with `mkvmerge` before adding them to your library.
+
 > ⚠️ **Hardlinks require a shared filesystem:** Source and target paths must live on the **same filesystem**. Hardlinks cannot span filesystems or physical disks. If they don't, switch to `--copy`. On Unraid's classic array this is a real concern — see the [Unraid section](#unraid-user-scripts) for details before running this tool there.
 
 ## Installation
@@ -60,10 +62,12 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into two subcommands:
+The CLI is split into four subcommands:
 
 - **`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.
 
 ### `sync`
 
@@ -140,22 +144,99 @@ Verify a target is a complete mirror before deleting the source:
 jellyplex-sync diff ~/Media/Jellyfin ~/Media/Plex
 ```
 
+### `plan`
+
+```bash
+jellyplex-sync 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`.
+
+Unlike `sync` and `diff`, the target directory does **not** need to exist. The whole point of `plan` is to answer "what WOULD happen" *before* any setup.
+
+Exit codes:
+
+- `0` — Plan produced successfully. Clashes and translation losses are reported but counted as informational, not failures.
+- `2` — setup error (source missing, format undetectable).
+
+#### Example
+
+Pre-flight a sync, see exactly which target filenames would be created:
+
+```bash
+jellyplex-sync plan ~/Media/Plex ~/Media/Jellyfin
+```
+
+Machine-readable, with `jq` to find videos that needed disambiguation:
+
+```bash
+jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
+    | jq '.movies[].videos[] | select(.disambiguation) | {source, target_name, disambiguation}'
+```
+
+### `import` (experimental)
+
+> ⚠️ **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
+```
+
+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.
+
+Semantically distinct from `sync`:
+
+- `sync` mirrors a structured library; the source stays intact.
+- `import` ingests from an unstructured dump; the source files are **moved** (deleted after successful copy) by default.
+- `import` never removes anything from the target — it only adds.
+
+**Materializer flags** (mutually exclusive):
+
+- `--move` (default) — copy each file to the target, then delete the source.
+- `--copy` — copy files; the source is kept. Safe for a test run without `--dry-run`.
+
+Other flags: `--dry-run`, `--create`, `--source-format`, `--target-format`, `-v`, `--debug`.
+
+#### Limitations
+
+- **Loose non-video files** (posters, `.nfo`, subtitles) in the staging area are not imported — there is no folder to assign them to. The target media server can download its own metadata.
+- **Asset directories** (extras, trailers) in the staging area are not collected.
+- **No `--json` output** yet for import.
+
+#### Example
+
+Move Plex-named video files into a new Jellyfin library:
+
+```bash
+jellyplex-sync import --create /mnt/staging /mnt/library/Jellyfin
+```
+
+Preview first, keeping the source:
+
+```bash
+jellyplex-sync import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
+```
+
 ### JSON output
 
-Both 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.
+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.
 
 The schema (still evolving — pin a version when consuming):
 
-- `operation`: `"sync"` or `"diff"`.
-- `exit_code`: the process exit code, mirrored in the document for convenience.
+- `operation`: `"sync"`, `"diff"`, or `"plan"`.
+- `exit_code` (sync, diff): the process exit code, mirrored in the document for convenience.
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
-- `summary` (sync only): counters for `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`.
+- `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`.
 - `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.
+- `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.
 
 #### `jq` examples
 
@@ -239,6 +320,8 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **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`.
 - **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.
 
 ## Library layouts
 
@@ -264,7 +347,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 [DEV.md](./DEV.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 [SPECS.md](./SPECS.md).
 
 ### Plex
 

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.2}/README.md

@@ -2,7 +2,7 @@
 
 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.2.0 is a major rewrite.** Subcommands, new materializer options, machine-readable `--json` output, default-sync-everything behavior, and a renamed model field (`tags` → `labels` in the Python API). If you depend on the old shape, **try the new version with `--dry-run` first**, and pin to a `0.1.x` release if anything looks off. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
+> ⚠️ **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
 
@@ -14,6 +14,8 @@ The script scans the source library, parses each movie folder for metadata (titl
 
 > ⚠️ **Movies only:** This script is designed exclusively for **movie libraries**. It does **not** support TV shows or miniseries. However, this is usually not a limitation in practice: for shows, Jellyfin and Plex use very similar directory structures, so you can typically point both apps to the same library without issues.
 
+> ⚠️ **Stacked / multi-part movies are not supported:** Plex's multi-part filename suffixes (`pt1`/`pt2`, `cd1`/`cd2`, `disc1`/`disc2`) are not recognized — each part is treated as a separate video, which will likely confuse the target scanner. Pre-join multi-disc releases with `mkvmerge` before adding them to your library.
+
 > ⚠️ **Hardlinks require a shared filesystem:** Source and target paths must live on the **same filesystem**. Hardlinks cannot span filesystems or physical disks. If they don't, switch to `--copy`. On Unraid's classic array this is a real concern — see the [Unraid section](#unraid-user-scripts) for details before running this tool there.
 
 ## Installation
@@ -44,10 +46,12 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into two subcommands:
+The CLI is split into four subcommands:
 
 - **`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.
 
 ### `sync`
 
@@ -124,22 +128,99 @@ Verify a target is a complete mirror before deleting the source:
 jellyplex-sync diff ~/Media/Jellyfin ~/Media/Plex
 ```
 
+### `plan`
+
+```bash
+jellyplex-sync 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`.
+
+Unlike `sync` and `diff`, the target directory does **not** need to exist. The whole point of `plan` is to answer "what WOULD happen" *before* any setup.
+
+Exit codes:
+
+- `0` — Plan produced successfully. Clashes and translation losses are reported but counted as informational, not failures.
+- `2` — setup error (source missing, format undetectable).
+
+#### Example
+
+Pre-flight a sync, see exactly which target filenames would be created:
+
+```bash
+jellyplex-sync plan ~/Media/Plex ~/Media/Jellyfin
+```
+
+Machine-readable, with `jq` to find videos that needed disambiguation:
+
+```bash
+jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
+    | jq '.movies[].videos[] | select(.disambiguation) | {source, target_name, disambiguation}'
+```
+
+### `import` (experimental)
+
+> ⚠️ **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
+```
+
+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.
+
+Semantically distinct from `sync`:
+
+- `sync` mirrors a structured library; the source stays intact.
+- `import` ingests from an unstructured dump; the source files are **moved** (deleted after successful copy) by default.
+- `import` never removes anything from the target — it only adds.
+
+**Materializer flags** (mutually exclusive):
+
+- `--move` (default) — copy each file to the target, then delete the source.
+- `--copy` — copy files; the source is kept. Safe for a test run without `--dry-run`.
+
+Other flags: `--dry-run`, `--create`, `--source-format`, `--target-format`, `-v`, `--debug`.
+
+#### Limitations
+
+- **Loose non-video files** (posters, `.nfo`, subtitles) in the staging area are not imported — there is no folder to assign them to. The target media server can download its own metadata.
+- **Asset directories** (extras, trailers) in the staging area are not collected.
+- **No `--json` output** yet for import.
+
+#### Example
+
+Move Plex-named video files into a new Jellyfin library:
+
+```bash
+jellyplex-sync import --create /mnt/staging /mnt/library/Jellyfin
+```
+
+Preview first, keeping the source:
+
+```bash
+jellyplex-sync import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
+```
+
 ### JSON output
 
-Both 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.
+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.
 
 The schema (still evolving — pin a version when consuming):
 
-- `operation`: `"sync"` or `"diff"`.
-- `exit_code`: the process exit code, mirrored in the document for convenience.
+- `operation`: `"sync"`, `"diff"`, or `"plan"`.
+- `exit_code` (sync, diff): the process exit code, mirrored in the document for convenience.
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
-- `summary` (sync only): counters for `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`.
+- `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`.
 - `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.
+- `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.
 
 #### `jq` examples
 
@@ -223,6 +304,8 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **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`.
 - **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.
 
 ## Library layouts
 
@@ -248,7 +331,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 [DEV.md](./DEV.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 [SPECS.md](./SPECS.md).
 
 ### Plex
 

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jellyplex-sync"
-version = "0.2.2"
+version = "0.3.2"
 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"

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.2}/src/jellyplex_sync/__init__.py

@@ -8,6 +8,7 @@ from .library import (
     Drop,
     DropError,
     FileEvent,
+    FolderClash,
     IgnoredEntry,
     LibraryReader,
     LibraryWriter,
@@ -22,11 +23,19 @@ from .materializer import (
     FileMaterializer,
     ForceCopyMaterializer,
     HardlinkMaterializer,
+    MoveMaterializer,
 )
 from .model import (
     MovieInfo,
     VideoInfo,
 )
+from .plan import (
+    DisambiguationNote,
+    Plan,
+    PlannedAsset,
+    PlannedFile,
+    PlannedMovie,
+)
 from .plex import (
     PlexLibraryReader,
     PlexLibraryWriter,
@@ -35,6 +44,8 @@ from .sync import (
     DiffEntry,
     DiffResult,
     diff,
+    import_media,
+    plan,
     sync,
 )
 
@@ -44,12 +55,15 @@ __all__ = [
     "CopyMaterializer",
     "DiffEntry",
     "DiffResult",
+    "DisambiguationNote",
     "Drop",
     "DropError",
     "FileEvent",
     "FileMaterializer",
+    "FolderClash",
     "ForceCopyMaterializer",
     "HardlinkMaterializer",
+    "MoveMaterializer",
     "IgnoredEntry",
     "JellyfinLibraryReader",
     "JellyfinLibraryWriter",
@@ -58,6 +72,10 @@ __all__ = [
     "LoggingReporter",
     "MovieClash",
     "MovieInfo",
+    "Plan",
+    "PlannedAsset",
+    "PlannedFile",
+    "PlannedMovie",
     "PlexLibraryReader",
     "PlexLibraryWriter",
     "Reporter",
@@ -65,5 +83,7 @@ __all__ = [
     "VideoInfo",
     "dedupe_drops",
     "diff",
+    "import_media",
+    "plan",
     "sync",
 ]

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.2}/src/jellyplex_sync/cli/sync.py

@@ -7,7 +7,7 @@ import sys
 
 import jellyplex_sync as jp
 
-_SUBCOMMANDS = {"sync", "diff"}
+_SUBCOMMANDS = {"sync", "diff", "plan", "import"}
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -90,6 +90,46 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     _add_io_args(diff_p)
 
+    plan_p = sub.add_parser(
+        "plan",
+        parents=[common],
+        help="Show the Plan a sync would execute, without touching the target.",
+    )
+    _add_io_args(plan_p)
+
+    import_p = sub.add_parser(
+        "import",
+        parents=[common],
+        help="Import video files from a staging area into a structured library.",
+    )
+    _add_io_args(import_p)
+    import_mode = import_p.add_mutually_exclusive_group()
+    import_mode.add_argument(
+        "--move",
+        dest="mode",
+        action="store_const",
+        const="move",
+        help="Move files: copy to target, then delete source (default).",
+    )
+    import_mode.add_argument(
+        "--copy",
+        dest="mode",
+        action="store_const",
+        const="copy",
+        help="Copy files; source is kept. On re-runs skip files whose size and mtime match.",
+    )
+    import_p.set_defaults(mode="move")
+    import_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done, don't change anything on disk.",
+    )
+    import_p.add_argument(
+        "--create",
+        action="store_true",
+        help="Create the target library directory if it doesn't exist.",
+    )
+
     return parser
 
 
@@ -156,6 +196,10 @@ def main() -> None:
         result = _do_sync(args)
     elif args.command == "diff":
         result = _do_diff(args)
+    elif args.command == "plan":
+        result = _do_plan(args)
+    elif args.command == "import":
+        result = _do_import(args)
     else:
         parser.error(f"unknown command: {args.command!r}")
         result = 2
@@ -242,6 +286,54 @@ def _do_diff(args: argparse.Namespace) -> int:
         return 99
 
 
+def _do_plan(args: argparse.Namespace) -> int:
+    from jellyplex_sync.sync import plan as plan_fn
+
+    try:
+        return plan_fn(
+            args.source,
+            args.target,
+            debug=args.debug,
+            source_format=args.source_format,
+            target_format=args.target_format,
+            as_json=args.json,
+        )
+    except KeyboardInterrupt:
+        logging.info("INTERRUPTED")
+        return 10
+    except Exception as exc:
+        logging.error("Exception: %s", exc)
+        return 99
+
+
+def _do_import(args: argparse.Namespace) -> int:
+    from jellyplex_sync.sync import import_media
+
+    if args.mode == "move":
+        materializer = jp.MoveMaterializer()
+    else:
+        materializer = jp.CopyMaterializer()
+
+    try:
+        return import_media(
+            args.source,
+            args.target,
+            dry_run=args.dry_run,
+            create=args.create,
+            verbose=args.verbose,
+            debug=args.debug,
+            source_format=args.source_format,
+            target_format=args.target_format,
+            materializer=materializer,
+        )
+    except KeyboardInterrupt:
+        logging.info("INTERRUPTED")
+        return 10
+    except Exception as exc:
+        logging.error("Exception: %s", exc)
+        return 99
+
+
 def _resolve_formats_for_json(args: argparse.Namespace) -> tuple[str, str]:
     """Re-run the same format resolution `sync()` did so the JSON payload
     reports the formats that were actually used. Returns ('?', '?') if

jellyplex_sync-0.3.2/src/jellyplex_sync/compare.py

@@ -0,0 +1,82 @@
+"""Plan-vs.-actual comparison: derive a DiffResult from a Plan.
+
+The classic `diff` subcommand answers "is the target in sync with what
+the source would produce?" In the 0.3 pipeline this becomes trivially
+expressible: build the Plan (no I/O on target), then compare it to
+whatever currently sits on the target filesystem.
+
+The shape of `DiffResult` is preserved from sync.py so the public CLI
+output and `--json` schema don't move. `drops` is left empty here —
+they belong to the Reporter the caller fed to the Planner; the caller
+can stitch them onto the DiffResult if they want them in the document.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from .plan import Plan
+from .sync import DiffEntry, DiffResult, MovieOnlyInSource
+
+
+def compare(plan: Plan) -> DiffResult:
+    """Compare `plan` against the actual contents of `plan.target_root`.
+
+    Pure: reads the target filesystem, returns a DiffResult, mutates
+    nothing. Walks one level deep into each movie folder — same depth
+    as the pre-0.3 diff implementation."""
+    planned_folder_names = {m.target_folder.name for m in plan.movies}
+    planned_by_name = {m.target_folder.name: m for m in plan.movies}
+
+    actual: dict[str, set[str]] = {}
+    if plan.target_root.is_dir():
+        for entry in plan.target_root.iterdir():
+            if not entry.is_dir():
+                continue
+            actual[entry.name] = {sub.name for sub in entry.iterdir()}
+
+    only_in_source_names = sorted(planned_folder_names - actual.keys())
+    only_in_source = tuple(
+        MovieOnlyInSource(
+            source_folder=planned_by_name[name].source_path.name,
+            expected_target=name,
+        )
+        for name in only_in_source_names
+    )
+
+    only_in_target = tuple(sorted(actual.keys() - planned_folder_names))
+
+    differing: list[DiffEntry] = []
+    for name in sorted(planned_folder_names & actual.keys()):
+        pm = planned_by_name[name]
+        expected_files = (
+            {pf.target_name for pf in pm.videos}
+            | {pf.target_name for pf in pm.loose_files}
+            | {a.folder_name for a in pm.assets}
+        )
+        src_only = tuple(sorted(expected_files - actual[name]))
+        tgt_only = tuple(sorted(actual[name] - expected_files))
+        if src_only or tgt_only:
+            differing.append(
+                DiffEntry(
+                    target_movie_name=name,
+                    only_in_source=src_only,
+                    only_in_target=tgt_only,
+                )
+            )
+
+    return DiffResult(
+        movies_only_in_source=only_in_source,
+        movies_only_in_target=only_in_target,
+        differing_movies=tuple(differing),
+        ignored=tuple(plan.ignored),
+    )
+
+
+def _planned_target_folder(plan: Plan, name: str) -> pathlib.Path | None:
+    """Helper: find the absolute target folder for a planned-movie name,
+    if any. Convenience for callers that want to print full paths."""
+    for m in plan.movies:
+        if m.target_folder.name == name:
+            return m.target_folder
+    return None