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

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jellyplex-sync
-Version: 0.3.1
+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>
@@ -44,7 +44,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,16 +62,19 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into three subcommands:
+The main CLI is `jellyplex` with 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.
+- **`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.
+
+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.
@@ -100,31 +103,31 @@ Use `--copy` when source and target are on different filesystems (NAS to local d
 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.
@@ -140,13 +143,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`.
@@ -163,16 +166,59 @@ 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}'
 ```
 
+### `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 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 import --create /mnt/staging /mnt/library/Jellyfin
+```
+
+Preview first, keeping the source:
+
+```bash
+jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
+```
+
 ### 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.
@@ -199,40 +245,24 @@ The schema (still evolving — pin a version when consuming):
 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

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/README.md

@@ -28,7 +28,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,16 +46,19 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into three subcommands:
+The main CLI is `jellyplex` with 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.
+- **`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.
+
+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.
@@ -84,31 +87,31 @@ Use `--copy` when source and target are on different filesystems (NAS to local d
 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.
@@ -124,13 +127,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`.
@@ -147,16 +150,59 @@ 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}'
 ```
 
+### `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 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 import --create /mnt/staging /mnt/library/Jellyfin
+```
+
+Preview first, keeping the source:
+
+```bash
+jellyplex import --copy --dry-run /mnt/staging /mnt/library/Jellyfin
+```
+
 ### 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.
@@ -183,40 +229,24 @@ The schema (still evolving — pin a version when consuming):
 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

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jellyplex-sync"
-version = "0.3.1"
+version = "0.3.4"
 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"
@@ -17,6 +17,7 @@ classifiers = [
 dependencies = []
 
 [project.scripts]
+jellyplex = "jellyplex_sync.cli.main:main"
 jellyplex-sync = "jellyplex_sync.cli.sync:main"
 
 [dependency-groups]

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

@@ -23,6 +23,7 @@ from .materializer import (
     FileMaterializer,
     ForceCopyMaterializer,
     HardlinkMaterializer,
+    MoveMaterializer,
 )
 from .model import (
     MovieInfo,
@@ -43,6 +44,7 @@ from .sync import (
     DiffEntry,
     DiffResult,
     diff,
+    import_media,
     plan,
     sync,
 )
@@ -61,6 +63,7 @@ __all__ = [
     "FolderClash",
     "ForceCopyMaterializer",
     "HardlinkMaterializer",
+    "MoveMaterializer",
     "IgnoredEntry",
     "JellyfinLibraryReader",
     "JellyfinLibraryWriter",
@@ -80,6 +83,7 @@ __all__ = [
     "VideoInfo",
     "dedupe_drops",
     "diff",
+    "import_media",
     "plan",
     "sync",
 ]

jellyplex_sync-0.3.1/src/jellyplex_sync/cli/sync.py → jellyplex_sync-0.3.4/src/jellyplex_sync/cli/main.py

@@ -7,12 +7,10 @@ import sys
 
 import jellyplex_sync as jp
 
-_SUBCOMMANDS = {"sync", "diff", "plan"}
-
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        prog="jellyplex-sync",
+        prog="jellyplex",
         description="Convert a media library between Plex and Jellyfin layouts.",
     )
 
@@ -41,7 +39,7 @@ def _build_parser() -> argparse.ArgumentParser:
     sync_p = sub.add_parser(
         "sync",
         parents=[common],
-        help="Mirror a source library into the target layout (default).",
+        help="Mirror a source library into the target layout.",
     )
     _add_io_args(sync_p)
     mode = sync_p.add_mutually_exclusive_group()
@@ -97,6 +95,39 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     _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
 
 
@@ -124,24 +155,9 @@ def _add_io_args(p: argparse.ArgumentParser) -> None:
     )
 
 
-def _inject_default_subcommand(argv: list[str]) -> list[str]:
-    """If the first positional argument isn't a known subcommand, treat the
-    call as `sync ...`. Keeps the historical invocation `jellyplex-sync
-    <source> <target>` working alongside the new `jellyplex-sync sync ...`.
-    """
-    if not argv:
-        return argv
-    first = argv[0]
-    if first.startswith("-"):
-        return argv
-    if first in _SUBCOMMANDS:
-        return argv
-    return ["sync", *argv]
-
-
 def main() -> None:
     parser = _build_parser()
-    args = parser.parse_args(_inject_default_subcommand(sys.argv[1:]))
+    args = parser.parse_args()
 
     # Under --json, INFO chatter on stderr distracts from the JSON document
     # on stdout. Quiet stderr to WARNING by default; --verbose or --debug
@@ -165,6 +181,8 @@ def main() -> None:
         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
@@ -204,8 +222,15 @@ def _do_sync(args: argparse.Namespace) -> int:
 
     if args.json:
         assert stats is not None and reporter is not None
-        source_short, target_short = _resolve_formats_for_json(args)
         from jellyplex_sync.json_output import write_sync_json
+        from jellyplex_sync.sync import _resolve_formats
+
+        resolved = _resolve_formats(
+            pathlib.Path(args.source),
+            args.source_format,
+            args.target_format,
+        )
+        source_short, target_short = resolved if resolved else ("?", "?")
 
         write_sync_json(
             sys.stdout,
@@ -271,19 +296,29 @@ def _do_plan(args: argparse.Namespace) -> int:
         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
-    resolution fails — sync() will already have logged the error and the
-    caller's exit code reflects it."""
-    import pathlib
+def _do_import(args: argparse.Namespace) -> int:
+    from jellyplex_sync.sync import import_media
 
-    from jellyplex_sync.sync import _resolve_formats
+    materializer = jp.MoveMaterializer() if args.mode == "move" else jp.CopyMaterializer()
 
-    resolved = _resolve_formats(
-        pathlib.Path(args.source), args.source_format, args.target_format
-    )
-    return resolved if resolved else ("?", "?")
+    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
 
 
 if __name__ == "__main__":

jellyplex_sync-0.3.4/src/jellyplex_sync/cli/sync.py

@@ -0,0 +1,186 @@
+#!/usr/bin/python3
+"""Backward-compatible ``jellyplex-sync`` entry point.
+
+Provides the same interface as the original single-command CLI: flat
+argument list, no subcommands.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import pathlib
+import sys
+
+import jellyplex_sync as jp
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    format_choices = [
+        jp.JellyfinLibraryReader.shortname(),
+        jp.PlexLibraryReader.shortname(),
+        "auto",
+    ]
+
+    parser = argparse.ArgumentParser(
+        prog="jellyplex-sync",
+        description="Mirror a source library into the target layout.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show more information messages.",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Show debug messages.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit a machine-readable JSON document on stdout. Logs continue to go to stderr.",
+    )
+    parser.add_argument("source", help="Source media library path.")
+    parser.add_argument("target", help="Target media library path.")
+    parser.add_argument(
+        "--source-format",
+        type=str,
+        choices=format_choices,
+        default="auto",
+        help="Source library format ('auto' detects from the source layout).",
+    )
+    parser.add_argument(
+        "--target-format",
+        type=str,
+        choices=format_choices,
+        default="auto",
+        help="Target library format ('auto' picks the opposite of the source).",
+    )
+
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--hardlink",
+        dest="mode",
+        action="store_const",
+        const="hardlink",
+        help="Use hardlinks (default; needs source and target on the same filesystem).",
+    )
+    mode.add_argument(
+        "--copy",
+        dest="mode",
+        action="store_const",
+        const="copy",
+        help="Copy files; on re-runs skip files whose size and mtime already match.",
+    )
+    mode.add_argument(
+        "--force-copy",
+        dest="mode",
+        action="store_const",
+        const="force-copy",
+        help="Always copy and overwrite, regardless of existing target state.",
+    )
+    parser.set_defaults(mode="hardlink")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done, don't change anything on disk.",
+    )
+    parser.add_argument(
+        "--delete",
+        action="store_true",
+        help="Remove stray folders from the target library.",
+    )
+    parser.add_argument(
+        "--create",
+        action="store_true",
+        help="Create the target library directory if it doesn't exist.",
+    )
+
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        level = logging.DEBUG
+    elif args.json and not args.verbose:
+        level = logging.WARNING
+    else:
+        level = logging.INFO
+
+    logging.basicConfig(
+        level=level,
+        stream=sys.stderr,
+        format="%(levelname)s: %(asctime)s -- %(message)s",
+    )
+
+    if args.mode == "hardlink":
+        materializer: jp.FileMaterializer = jp.HardlinkMaterializer()
+    elif args.mode == "copy":
+        materializer = jp.CopyMaterializer()
+    elif args.mode == "force-copy":
+        materializer = jp.ForceCopyMaterializer()
+    else:
+        raise ValueError(f"unknown materialization mode: {args.mode!r}")
+
+    from jellyplex_sync.library import CollectingReporter
+    from jellyplex_sync.sync import LibraryStats
+
+    stats = LibraryStats() if args.json else None
+    reporter = CollectingReporter() if args.json else None
+
+    try:
+        rc = jp.sync(
+            args.source,
+            args.target,
+            dry_run=args.dry_run,
+            delete=args.delete,
+            create=args.create,
+            verbose=args.verbose,
+            debug=args.debug,
+            source_format=args.source_format,
+            target_format=args.target_format,
+            materializer=materializer,
+            reporter=reporter,
+            stats=stats,
+        )
+    except KeyboardInterrupt:
+        logging.info("INTERRUPTED")
+        sys.exit(10)
+    except Exception as exc:
+        logging.error("Exception: %s", exc)
+        sys.exit(99)
+
+    if args.json:
+        assert stats is not None and reporter is not None
+        from jellyplex_sync.json_output import write_sync_json
+        from jellyplex_sync.sync import _resolve_formats
+
+        resolved = _resolve_formats(
+            pathlib.Path(args.source),
+            args.source_format,
+            args.target_format,
+        )
+        source_short, target_short = resolved if resolved else ("?", "?")
+
+        write_sync_json(
+            sys.stdout,
+            source_path=pathlib.Path(args.source),
+            source_format=source_short,
+            target_path=pathlib.Path(args.target),
+            target_format=target_short,
+            dry_run=args.dry_run,
+            exit_code=rc,
+            stats=stats,
+            drops=reporter.drops,
+        )
+
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/src/jellyplex_sync/discover.py

@@ -19,7 +19,8 @@ from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import Protocol
 
-from .library import ACCEPTED_VIDEO_SUFFIXES, IgnoredEntry
+from .library import ACCEPTED_VIDEO_SUFFIXES, IgnoredEntry, LibraryReader
+from .model import MovieInfo
 
 
 @dataclass(frozen=True)
@@ -86,3 +87,74 @@ class TwoLevelDiscoverer:
                 asset_dirs=tuple(sorted(assets)),
                 loose_files=tuple(sorted(loose)),
             )
+
+
+def _movie_key(movie: MovieInfo) -> tuple:
+    """Hashable grouping key derived from a MovieInfo. Two videos that
+    parse to the same title, year, and provider IDs end up in the same
+    group — labels and other ephemeral fields are excluded because they
+    vary per video, not per movie."""
+    return (movie.title, movie.year, tuple(sorted(movie.attributes.items())))
+
+
+class FlatDiscoverer:
+    """Discovers movies from individual video files, regardless of
+    directory structure. Every video file under `root` is parsed via
+    the supplied Reader to determine which movie it belongs to; files
+    with the same title, year, and provider IDs are grouped together.
+
+    Designed for staging-area workflows where video files are dumped
+    without the standard one-folder-per-movie layout. Scans
+    recursively, so half-sorted structures (files in random
+    subdirectories) are handled too.
+
+    Takes a `LibraryReader` because grouping requires format-aware
+    parsing — a deliberate trade-off: the TwoLevelDiscoverer is
+    format-agnostic (folders are the grouping), but flat sources
+    need filename parsing to find group boundaries.
+
+    Loose files and asset directories are not collected — in a flat
+    staging area there's no folder to assign them to. The target media
+    server can download its own metadata after the sync."""
+
+    def __init__(self, reader: LibraryReader) -> None:
+        self._reader = reader
+
+    def discover(
+        self,
+        root: pathlib.Path,
+        *,
+        ignored: list[IgnoredEntry] | None = None,
+    ) -> Iterable[DiscoveredGroup]:
+        groups: dict[tuple, list[pathlib.Path]] = {}
+        source_paths: dict[tuple, pathlib.Path] = {}
+
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            if path.name.startswith("."):
+                continue
+            if path.suffix.lower() not in ACCEPTED_VIDEO_SUFFIXES:
+                if ignored is not None:
+                    ignored.append(IgnoredEntry(path, "not a video file"))
+                continue
+
+            synthetic_folder = pathlib.Path(root / path.stem)
+            movie = self._reader.parse_movie(synthetic_folder)
+            if movie is None:
+                if ignored is not None:
+                    ignored.append(IgnoredEntry(path, "unparseable video filename"))
+                continue
+
+            key = _movie_key(movie)
+            groups.setdefault(key, []).append(path)
+            if key not in source_paths:
+                source_paths[key] = synthetic_folder
+
+        for key, video_files in groups.items():
+            yield DiscoveredGroup(
+                source_path=source_paths[key],
+                video_files=tuple(sorted(video_files)),
+                asset_dirs=(),
+                loose_files=(),
+            )

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/src/jellyplex_sync/jellyfin.py

@@ -125,7 +125,7 @@ class JellyfinLibraryWriter(_JellyfinBase):
             parts.append(f"[{key}id-{value}]")
 
         # Report any other provider IDs we couldn't fit; Jellyfin tolerates
-        # multiple bracket-IDs in the folder name, but jellyplex-sync only
+        # multiple bracket-IDs in the folder name, but jellyplex only
         # emits one for now.
         for key, value in movie.attributes.items():
             if primary and key == primary[0]:

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/src/jellyplex_sync/materializer.py

@@ -2,7 +2,7 @@
 
 A `FileMaterializer` knows how to make a target path reflect a source path.
 The first (and currently only) implementation, `HardlinkMaterializer`, uses
-filesystem hardlinks — the behavior jellyplex-sync has always had. Copy
+filesystem hardlinks — the behavior this tool has always had. Copy
 backends arrive in a later step of Paket 4.
 
 The seam exists so the CLI can swap materialization strategies (`--copy`,
@@ -146,6 +146,60 @@ class ForceCopyMaterializer:
         )
 
 
+class MoveMaterializer:
+    """Copy bytes from `src` to `dst`, then delete `src` on success.
+
+    Designed for staging-area workflows where the source is a temporary
+    dump and the target is the permanent library. Once the target file
+    is safely written (via `shutil.copy2`), the source is removed.
+
+    Re-run safety: if the target already exists with matching size and
+    mtime, the source is assumed to have been moved in a previous run
+    (or the copy was already successful) and is left alone.
+
+    If the source no longer exists but the target does, the file is
+    treated as already moved and silently skipped.
+    """
+
+    name = "move"
+
+    def materialize(
+        self,
+        src: pathlib.Path,
+        dst: pathlib.Path,
+        *,
+        dry_run: bool = False,
+        verbose: bool = False,
+        events: list[FileEvent] | None = None,
+    ) -> bool:
+        if not src.exists():
+            if dst.exists():
+                if verbose:
+                    log.info("Already moved '%s'", dst.name)
+                if events is not None:
+                    events.append(FileEvent(action="skip", target=dst))
+                return False
+            log.warning("Source '%s' does not exist, skipping", src)
+            return False
+
+        if dst.exists() and _same_size_and_mtime(src, dst):
+            if verbose:
+                log.info("Target '%s' is up to date, removing source", dst.name)
+            if events is not None:
+                events.append(FileEvent(action="skip", target=dst, source=src))
+            if not dry_run:
+                src.unlink()
+            return False
+
+        result = _copy(
+            src, dst, dry_run=dry_run, replaces_existing=dst.exists(), events=events
+        )
+        if result and not dry_run:
+            src.unlink()
+            log.info("Removed source '%s'", src.name)
+        return result
+
+
 def _same_size_and_mtime(a: pathlib.Path, b: pathlib.Path) -> bool:
     a_stat = a.stat()
     b_stat = b.stat()

{jellyplex_sync-0.3.1 → jellyplex_sync-0.3.4}/src/jellyplex_sync/sync.py

@@ -6,6 +6,7 @@ import re
 from collections.abc import Callable
 from dataclasses import dataclass, field
 
+from .discover import FlatDiscoverer
 from .jellyfin import JellyfinLibraryReader, JellyfinLibraryWriter
 from .library import (
     ACCEPTED_VIDEO_SUFFIXES,
@@ -19,7 +20,7 @@ from .library import (
     Reporter,
     dedupe_drops,
 )
-from .materializer import FileMaterializer, HardlinkMaterializer
+from .materializer import FileMaterializer, HardlinkMaterializer, MoveMaterializer
 from .planner import Planner
 from .plex import PlexLibraryReader, PlexLibraryWriter
 from .realize import Realizer, RealizeStats
@@ -575,3 +576,123 @@ def _print_plan(
 
 def _count_asset_files(asset) -> int:
     return len(asset.files) + sum(_count_asset_files(sf) for sf in asset.subfolders)
+
+
+# ---------------------------------------------------------------------------
+# import: move files from a staging area into a structured library
+# ---------------------------------------------------------------------------
+
+
+def import_media(
+    source: str,
+    target: str,
+    *,
+    dry_run: bool = False,
+    create: bool = False,
+    verbose: bool = False,
+    debug: bool = False,
+    source_format: str | None = None,
+    target_format: str | None = None,
+    reporter: Reporter | None = None,
+    materializer: FileMaterializer | None = None,
+    stats: LibraryStats | None = None,
+) -> int:
+    """Import video files from a staging area into a structured library.
+
+    Unlike `sync`, this uses `FlatDiscoverer` (groups by filename
+    parsing, not folder structure) and defaults to `MoveMaterializer`
+    (copy + delete source). The source can be a flat dump of video
+    files, a partially organised directory tree, or a mix.
+
+    Does not touch existing content in the target — it only adds.
+    """
+    if debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+
+    reporter = reporter or LoggingReporter(verbose=verbose)
+    materializer = materializer or MoveMaterializer()
+    source_path = pathlib.Path(source)
+    target_path = pathlib.Path(target)
+
+    resolved = _resolve_formats(source_path, source_format, target_format)
+    if resolved is None:
+        return 1
+    source_short, target_short = resolved
+
+    source_reader_cls, _ = _LIBRARY_TYPES[source_short]
+    _, target_writer_cls = _LIBRARY_TYPES[target_short]
+    source_reader = source_reader_cls(source_path)
+    target_writer = target_writer_cls(target_path)
+
+    if dry_run:
+        log.info("SOURCE %s (staging)", source_reader.base_dir)
+        log.info("TARGET %s", target_writer.base_dir)
+        log.info("IMPORTING %s → %s", source_short.capitalize(), target_short.capitalize())
+    else:
+        log.info(
+            "Importing from '%s' (%s) into '%s' (%s)",
+            source_reader.base_dir,
+            source_short.capitalize(),
+            target_writer.base_dir,
+            target_short.capitalize(),
+        )
+
+    if not source_reader.base_dir.is_dir():
+        log.error("Source directory '%s' does not exist", source_reader.base_dir)
+        return 1
+
+    if not target_writer.base_dir.is_dir():
+        if create:
+            target_writer.base_dir.mkdir(parents=True)
+        else:
+            log.error("Target directory '%s' does not exist", target_writer.base_dir)
+            return 1
+
+    lib_stats = stats if stats is not None else LibraryStats()
+
+    planner = Planner(
+        reader=source_reader,
+        writer=target_writer,
+        discoverer=FlatDiscoverer(source_reader),
+        reporter=reporter,
+    )
+    plan = planner.plan()
+
+    realize_stats = RealizeStats()
+    Realizer(materializer=materializer).apply(
+        plan,
+        dry_run=dry_run,
+        delete=False,
+        verbose=verbose,
+        stats=realize_stats,
+    )
+
+    lib_stats.movies_total += len(plan.movies)
+    lib_stats.movies_processed += realize_stats.movies_processed
+    lib_stats.items_linked += realize_stats.files_linked
+    lib_stats.ignored.extend(plan.ignored)
+    lib_stats.events.extend(realize_stats.events)
+    lib_stats.clashes.extend(plan.clashes)
+
+    verb = "moved" if isinstance(materializer, MoveMaterializer) else "copied"
+    summary = (
+        f"Summary: {lib_stats.movies_processed} movies imported, "
+        f"{lib_stats.items_linked} files {verb}, "
+        f"{len(lib_stats.ignored)} ignored, "
+        f"{len(lib_stats.clashes)} skipped due to clash."
+    )
+    log.info(summary)
+
+    if lib_stats.ignored:
+        log.info("Ignored item(s) in source (not imported):")
+        for item in lib_stats.ignored:
+            log.info("  '%s' (%s)", item.path.name, item.reason)
+
+    if lib_stats.clashes:
+        log.warning(
+            "%d movie(s) skipped because two or more source files map to the "
+            "same target name. Rename and re-run.",
+            len(lib_stats.clashes),
+        )
+
+    return 0