pix-cli 0.1.0__py3-none-any.whl

pix/__init__.py

@@ -0,0 +1,9 @@
+"""pix package."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+
+try:
+    __version__ = _package_version("pix-cli")
+except PackageNotFoundError:  # pragma: no cover - only when running uninstalled
+    __version__ = "0.1.0"

pix/cli.py

@@ -0,0 +1,116 @@
+"""pix command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import ConfigError, init_config, load_settings
+from .doctor import doctor
+from .logger import Logger
+from .shrink import shrink
+from .sync import backup, publish
+
+
+def _add_logging_args(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("-v", "--verbose", action="store_true", default=None)
+    group.add_argument("--quiet", action="store_true", default=None)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pix", description="Batch AVIF shrink and image-host sync.")
+    parser.add_argument("--config", type=Path, default=None, metavar="PATH")
+    parser.add_argument("--version", action="version", version=f"pix {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    shrink = subparsers.add_parser("shrink", help="compress images to AVIF")
+    shrink.add_argument("-s", "--source", type=Path, required=True)
+    shrink.add_argument("-d", "--dest", type=Path, required=True)
+    shrink.add_argument("-w", "--width", type=int, default=None)
+    shrink.add_argument("-q", "--quality", type=int, default=None)
+    shrink.add_argument("-e", "--effort", type=int, default=None)
+    shrink.add_argument("-m", "--min-size", type=str, default=None)
+    shrink.add_argument("--force", action="store_true")
+    shrink.add_argument("--prune", action="store_true")
+    shrink.add_argument("--allow-empty", action="store_true")
+    shrink.add_argument("--dry-run", action="store_true")
+    _add_logging_args(shrink)
+
+    backup = subparsers.add_parser("backup", help="bidirectionally mirror originals")
+    backup.add_argument("-s", "--source", type=Path, required=True)
+    backup.add_argument("-d", "--dest", required=True)
+    backup.add_argument("--exclude", action="append", default=None, metavar="GLOB")
+    backup.add_argument(
+        "--max-delete",
+        type=int,
+        default=None,
+        metavar="PERCENT",
+        help="abort if more than PERCENT%% of files are deleted (default: 10)",
+    )
+    backup.add_argument("--allow-empty", action="store_true")
+    backup.add_argument("--resync", action="store_true")
+    backup.add_argument("--dry-run", action="store_true")
+    _add_logging_args(backup)
+
+    publish = subparsers.add_parser("publish", help="bidirectionally mirror compressed images")
+    publish.add_argument("-s", "--source", type=Path, required=True)
+    publish.add_argument("-d", "--dest", required=True)
+    publish.add_argument("--base-url", default=None)
+    publish.add_argument("--urls", action=argparse.BooleanOptionalAction, default=None)
+    publish.add_argument("--exclude", action="append", default=None, metavar="GLOB")
+    publish.add_argument(
+        "--max-delete",
+        type=int,
+        default=None,
+        metavar="PERCENT",
+        help="abort if more than PERCENT%% of files are deleted (default: 10)",
+    )
+    publish.add_argument("--allow-empty", action="store_true")
+    publish.add_argument("--resync", action="store_true")
+    publish.add_argument("--dry-run", action="store_true")
+    _add_logging_args(publish)
+
+    subparsers.add_parser("doctor", help="check runtime dependencies and configuration")
+
+    config = subparsers.add_parser("config", help="manage the configuration file")
+    config_sub = config.add_subparsers(dest="config_command", required=True)
+    init = config_sub.add_parser("init", help="write the default config file")
+    init.add_argument("--force", action="store_true")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:  # --help/--version and argparse errors
+        return int(exc.code) if isinstance(exc.code, int) else 0
+
+    if args.command == "config":
+        return init_config(args)
+
+    try:
+        settings = load_settings(args.config)
+    except ConfigError as exc:
+        print(f"pix: error: {exc}", file=sys.stderr)
+        return 2
+
+    log = Logger(
+        verbose=bool(getattr(args, "verbose", False)),
+        quiet=bool(getattr(args, "quiet", False)),
+    )
+    handlers = {
+        "shrink": shrink,
+        "backup": backup,
+        "publish": publish,
+        "doctor": doctor,
+    }
+    return handlers[args.command](args, settings, log)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pix/config.py

@@ -0,0 +1,172 @@
+"""Configuration loading and validation."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import os
+import re
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+DEFAULTS: dict[str, Any] = {
+    "shrink": {
+        "width": 1920,
+        "quality": 85,
+        "effort": 5,
+        "min_size": 0,
+        "include": ["jpg", "jpeg", "png", "webp"],
+    },
+    "backup": {
+        "exclude": [],
+        "max_delete": 10,
+    },
+    "publish": {
+        "base_url": "",
+        "urls": False,
+        "exclude": [],
+        "max_delete": 10,
+    },
+    "rclone": {
+        "binary": "rclone",
+    },
+}
+
+_SIZE_RE = re.compile(r"^(\d+)([KMG]?)$", re.IGNORECASE)
+_SIZE_UNITS = {"": 1, "K": 1024, "M": 1024**2, "G": 1024**3}
+
+
+class ConfigError(Exception):
+    """Invalid or unreadable configuration."""
+
+
+def parse_size(value: str | int) -> int:
+    if isinstance(value, int) and not isinstance(value, bool):
+        if value < 0:
+            raise ValueError("size must not be negative")
+        return value
+    if not isinstance(value, str):
+        raise ValueError(f"invalid size: {value!r}")
+    match = _SIZE_RE.fullmatch(value.strip())
+    if match is None:
+        raise ValueError(f"invalid size: {value!r}")
+    return int(match.group(1)) * _SIZE_UNITS[match.group(2).upper()]
+
+
+def default_config_path() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "pix" / "config.toml"
+        return Path.home() / "AppData" / "Roaming" / "pix" / "config.toml"
+    base = os.environ.get("XDG_CONFIG_HOME")
+    if base:
+        return Path(base) / "pix" / "config.toml"
+    return Path.home() / ".config" / "pix" / "config.toml"
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    """Read a TOML config file; a missing file is an empty override."""
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: top level must be a table")
+    return data
+
+
+def _deep_update(target: dict[str, Any], source: dict[str, Any]) -> None:
+    for key, value in source.items():
+        current = target.get(key)
+        if isinstance(current, dict) and isinstance(value, dict):
+            _deep_update(current, value)
+        else:
+            target[key] = value
+
+
+def load_settings(explicit: Path | None = None) -> dict[str, Any]:
+    path = explicit if explicit is not None else default_config_path()
+    if explicit is not None and not path.is_file():
+        raise ConfigError(f"config file not found: {path}")
+    overrides = load_config(path)
+    settings = copy.deepcopy(DEFAULTS)
+    _deep_update(settings, overrides)
+    validate_settings(settings)
+    return settings
+
+
+def require_int(name: str, value: Any, minimum: int, maximum: int | None = None) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ConfigError(f"{name} must be an integer")
+    if value < minimum or (maximum is not None and value > maximum):
+        if maximum is None:
+            raise ConfigError(f"{name} must be >= {minimum}")
+        raise ConfigError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+def _require_excludes(name: str, value: Any) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ConfigError(f"{name} must be a list of strings")
+    return value
+
+
+def validate_settings(settings: dict[str, Any]) -> None:
+    for section in ("shrink", "backup", "publish", "rclone"):
+        if not isinstance(settings.get(section), dict):
+            raise ConfigError(f"[{section}] must be a table")
+
+    shrink = settings["shrink"]
+    require_int("shrink.width", shrink["width"], 1)
+    require_int("shrink.quality", shrink["quality"], 1, 100)
+    require_int("shrink.effort", shrink["effort"], 0, 9)
+    try:
+        shrink["min_size"] = parse_size(shrink["min_size"])
+    except ValueError as exc:
+        raise ConfigError(f"shrink.min_size: {exc}") from exc
+
+    include = shrink["include"]
+    if not isinstance(include, list) or not all(
+        isinstance(item, str) and item and not item.startswith(".") for item in include
+    ):
+        raise ConfigError("shrink.include must be a list of extensions without dots")
+
+    for section in ("backup", "publish"):
+        _require_excludes(f"{section}.exclude", settings[section]["exclude"])
+        require_int(f"{section}.max_delete", settings[section]["max_delete"], -1, 100)
+
+    publish = settings["publish"]
+    if not isinstance(publish["base_url"], str):
+        raise ConfigError("publish.base_url must be a string")
+    if not isinstance(publish["urls"], bool):
+        raise ConfigError("publish.urls must be a boolean")
+
+    if not isinstance(settings["rclone"]["binary"], str) or not settings["rclone"]["binary"]:
+        raise ConfigError("rclone.binary must be a non-empty string")
+
+
+def init_config(args: argparse.Namespace) -> int:
+    path = args.config if args.config is not None else default_config_path()
+    if path.exists() and not args.force:
+        print(
+            f"pix: error: config file already exists: {path} (use --force to overwrite)",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        template = Path(__file__).with_name("default_config.toml").read_text(encoding="utf-8")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(template, encoding="utf-8")
+    except OSError as exc:
+        print(f"pix: error: {path}: {exc}", file=sys.stderr)
+        return 2
+    print(f"wrote {path}")
+    return 0

pix/default_config.toml

@@ -0,0 +1,32 @@
+# pix configuration
+# Command-line flags override these values.
+
+[shrink]
+# Longest edge in pixels.
+width = 1920
+# AVIF quality, 1-100.
+quality = 85
+# libvips effort, 0-9 (higher is slower).
+effort = 5
+# Skip sources smaller than this; accepts bytes or 0, 500K, 1M, 2G.
+min_size = 0
+# Extensions to scan, written without dots.
+include = ["jpg", "jpeg", "png", "webp"]
+
+[backup]
+# rclone exclude globs; command-line --exclude is appended after these.
+exclude = []
+# Maximum percent of files rclone may delete (-1 disables, 0 forbids).
+max_delete = 10
+
+[publish]
+# Public URL prefix; must start with http:// or https://.
+base_url = ""
+# Emit a JSON URL manifest.
+urls = false
+exclude = []
+max_delete = 10
+
+[rclone]
+# rclone executable name or path.
+binary = "rclone"

pix/doctor.py

@@ -0,0 +1,54 @@
+"""doctor subcommand."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import shutil
+import sys
+from typing import Any
+
+from . import __version__
+from .config import default_config_path
+from .logger import Logger
+from .rclone import RCLONE_HINT, RCLONE_MIN, probe_rclone
+from .shrink import PYVIPS_HINT
+
+
+def doctor(args: argparse.Namespace, settings: dict[str, Any], log: Logger) -> int:
+    issues = 0
+    print(f"pix {__version__}")
+    print(f"python {platform.python_version()} ({platform.system().lower()})")
+
+    try:
+        import pyvips
+
+        libvips = ".".join(str(pyvips.version(index)) for index in range(3))
+        print(f"vips  {libvips} via pyvips {pyvips.__version__} (API mode)")
+    except Exception as exc:
+        print("vips  unavailable")
+        print(PYVIPS_HINT, file=sys.stderr)
+        print(f"pix: error: {exc}", file=sys.stderr)
+        issues = 1
+
+    binary = settings["rclone"]["binary"]
+    version, parsed, _error = probe_rclone(binary)
+    location = shutil.which(binary) or binary
+    if parsed is None:
+        print(f"rclone missing ({binary})")
+        print(RCLONE_HINT, file=sys.stderr)
+        issues = 1
+    elif parsed[:2] < RCLONE_MIN:
+        print(f"rclone {version} ({location}) too old; need >= 1.66")
+        print(RCLONE_HINT, file=sys.stderr)
+        issues = 1
+    else:
+        print(f"rclone {version} ({location}) bisync ok")
+
+    config_path = args.config if args.config is not None else default_config_path()
+    if config_path.is_file():
+        print(f"config {config_path} (ok)")
+    else:
+        print(f"config {config_path} (missing (using defaults))")
+
+    return 1 if issues else 0

pix/logger.py

@@ -0,0 +1,26 @@
+"""stderr logging."""
+
+from __future__ import annotations
+
+import sys
+
+
+class Logger:
+    def __init__(self, verbose: bool = False, quiet: bool = False) -> None:
+        self.verbose = verbose
+        self.quiet = quiet
+
+    def info(self, message: str) -> None:
+        if not self.quiet:
+            print(message, file=sys.stderr)
+
+    def detail(self, message: str) -> None:
+        if self.verbose and not self.quiet:
+            print(message, file=sys.stderr)
+
+    def warning(self, message: str) -> None:
+        if not self.quiet:
+            print(f"pix: warning: {message}", file=sys.stderr)
+
+    def error(self, message: str) -> None:
+        print(f"pix: error: {message}", file=sys.stderr)

pix/rclone.py

@@ -0,0 +1,72 @@
+"""rclone probing and execution."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from .logger import Logger
+
+RCLONE_MIN = (1, 66)
+RCLONE_HINT = (
+    "install rclone >= 1.66: https://rclone.org/downloads/ "
+    "(Windows: winget search rclone)"
+)
+
+
+def merge_excludes(*groups: list[str] | None) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for group in groups:
+        for item in group or []:
+            if item not in seen:
+                seen.add(item)
+                merged.append(item)
+    return merged
+
+
+def has_files(path: Path) -> bool:
+    return any(item.is_file() for item in path.rglob("*"))
+
+
+def probe_rclone(binary: str) -> tuple[str | None, tuple[int, int, int] | None, str | None]:
+    try:
+        result = subprocess.run([binary, "version"], capture_output=True, text=True)
+    except FileNotFoundError:
+        return None, None, f"rclone not found: {binary}"
+    except OSError as exc:
+        return None, None, f"cannot run rclone: {exc}"
+    output = f"{result.stdout or ''}\n{result.stderr or ''}".strip()
+    match = re.search(r"rclone v(\d+)\.(\d+)(?:\.(\d+))?", output)
+    if match is None:
+        if result.returncode != 0:
+            return None, None, f"rclone version failed with exit code {result.returncode}"
+        return None, None, "cannot parse rclone version"
+    parsed = (int(match.group(1)), int(match.group(2)), int(match.group(3) or 0))
+    return f"{parsed[0]}.{parsed[1]}.{parsed[2]}", parsed, None
+
+
+def check_rclone(binary: str, log: Logger) -> str | None:
+    version, parsed, error = probe_rclone(binary)
+    if parsed is None:
+        log.error(error or "rclone unavailable")
+        log.error(RCLONE_HINT)
+        return None
+    if parsed[:2] < RCLONE_MIN:
+        log.error(f"rclone {version} is too old; need >= 1.66")
+        log.error(f"upgrade rclone: {RCLONE_HINT}")
+        return None
+    return version
+
+
+def run_rclone(cmd: list[str]) -> int:
+    try:
+        return subprocess.run(cmd).returncode
+    except FileNotFoundError:
+        print(f"pix: error: rclone not found: {cmd[0]}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"pix: error: cannot run rclone: {exc}", file=sys.stderr)
+        return 1

pix/shrink.py

@@ -0,0 +1,368 @@
+"""shrink subcommand."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from .config import ConfigError, parse_size, require_int
+from .logger import Logger
+
+STATE_VERSION = 1
+STATE_DIR = ".pix"
+
+PYVIPS_HINT = """pyvips/libvips 不可用。
+
+推荐重装（会自带 libvips）：
+  uv tool install --force pix-cli
+
+也可以手动安装 libvips：
+  Windows: 从 https://github.com/libvips/libvips/releases 下载
+           vips-dev-w64-web-*.zip，解压后把 <vips>\\bin 加入 PATH
+  Linux:   sudo apt install libvips42
+
+注意：uv 只能安装 Python 包，不能单独安装原生 libvips。
+      pyvips[binary] 的作用就是把 libvips 一起打包进 Python 环境。"""
+
+
+def _scan_sources(source: Path, include: list[str]) -> list[Path]:
+    allowed = {item.lower() for item in include}
+    paths = [
+        path
+        for path in source.rglob("*")
+        if path.is_file() and path.suffix.lower().lstrip(".") in allowed
+    ]
+    paths.sort(key=lambda path: path.relative_to(source).as_posix())
+    return paths
+
+
+def _target_map(
+    sources: list[Path], source: Path, dest: Path
+) -> tuple[dict[Path, Path], dict[str, list[str]]]:
+    targets: dict[Path, Path] = {}
+    owners: dict[str, list[str]] = {}
+    for src in sources:
+        rel = src.relative_to(source)
+        out_rel = rel.with_suffix(".avif")
+        key = out_rel.as_posix()
+        owners.setdefault(key, []).append(rel.as_posix())
+        targets[src] = dest / out_rel
+    conflicts = {key: rels for key, rels in owners.items() if len(rels) > 1}
+    return targets, conflicts
+
+
+def _load_state(path: Path, params: str, log: Logger) -> dict[str, Any]:
+    empty = {"version": STATE_VERSION, "params": params, "files": {}}
+    if not path.is_file():
+        return empty
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        log.warning(f"cannot read state {path}: {exc}; rebuilding")
+        return empty
+    if (
+        not isinstance(data, dict)
+        or data.get("version") != STATE_VERSION
+        or not isinstance(data.get("files"), dict)
+        or not all(
+            isinstance(key, str) and isinstance(value, dict)
+            for key, value in data["files"].items()
+        )
+    ):
+        log.warning(f"unrecognized state {path}; rebuilding")
+        return empty
+    return {
+        "version": STATE_VERSION,
+        "params": data.get("params") if isinstance(data.get("params"), str) else "",
+        "files": data["files"],
+    }
+
+
+def _save_state(path: Path, state: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def _acquire_lock(path: Path) -> bool:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError:
+        return False
+    try:
+        os.write(fd, f"{os.getpid()}\n".encode())
+    finally:
+        os.close(fd)
+    return True
+
+
+def _release_lock(path: Path) -> None:
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def _skip_reason(
+    src_stat: os.stat_result,
+    dest_path: Path,
+    entry: dict[str, Any] | None,
+    params_match: bool,
+    min_size: int,
+) -> str | None:
+    if min_size > 0 and src_stat.st_size < min_size:
+        return "small"
+    if entry is None or not params_match:
+        return None
+    try:
+        out_stat = dest_path.stat()
+    except OSError:
+        return None
+    if (
+        entry.get("src_size") == src_stat.st_size
+        and entry.get("src_mtime_ns") == src_stat.st_mtime_ns
+        and entry.get("out_size") == out_stat.st_size
+    ):
+        return "state"
+    return None
+
+
+def _prune(
+    state: dict[str, Any],
+    source: Path,
+    dest: Path,
+    source_count: int,
+    dry_run: bool,
+    allow_empty: bool,
+    log: Logger,
+) -> tuple[int, int, int]:
+    files = state["files"]
+    if source_count == 0 and files:
+        if not allow_empty:
+            log.error(
+                "source has no images but state has entries; refusing to prune "
+                "(use --allow-empty to override)"
+            )
+            return 0, 0, len(files)
+    stale = sorted(rel for rel in files if not (source / rel).is_file())
+    deleted = 0
+    failed = 0
+    for rel in stale:
+        if dry_run:
+            print(f"prune {rel}")
+            deleted += 1
+            continue
+        out_path = dest / Path(rel).with_suffix(".avif")
+        try:
+            out_path.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            log.error(f"prune {rel}: {exc}")
+            failed += 1
+            continue
+        del files[rel]
+        deleted += 1
+        log.detail(f"pruned {rel}")
+    return deleted, failed, 0
+
+
+def _log_summary(log: Logger, counters: dict[str, int]) -> None:
+    log.info(
+        "summary: converted={converted} skipped={state} too-small={small} "
+        "empty-protected={protected} failed={failed} deleted={deleted}".format(**counters)
+    )
+
+
+def shrink(args: argparse.Namespace, settings: dict[str, Any], log: Logger) -> int:
+    config = settings["shrink"]
+    try:
+        width = require_int(
+            "width", args.width if args.width is not None else config["width"], 1
+        )
+        quality = require_int(
+            "quality", args.quality if args.quality is not None else config["quality"], 1, 100
+        )
+        effort = require_int(
+            "effort", args.effort if args.effort is not None else config["effort"], 0, 9
+        )
+        min_size = (
+            parse_size(args.min_size) if args.min_size is not None else config["min_size"]
+        )
+    except (ConfigError, ValueError) as exc:
+        log.error(str(exc))
+        return 2
+
+    source = args.source
+    dest = args.dest
+    if not source.is_dir():
+        log.error(f"source is not a directory: {source}")
+        return 2
+    if dest.exists() and not dest.is_dir():
+        log.error(f"dest is not a directory: {dest}")
+        return 2
+
+    try:
+        sources = _scan_sources(source, config["include"])
+    except OSError as exc:
+        log.error(f"cannot scan {source}: {exc}")
+        return 1
+    targets, conflicts = _target_map(sources, source, dest)
+    if conflicts:
+        log.error("multiple sources map to the same output:")
+        for key, rels in sorted(conflicts.items()):
+            print(f"  {key} <- {', '.join(rels)}", file=sys.stderr)
+        return 2
+
+    params = f"w={width};q={quality};e={effort}"
+    state_file = dest / STATE_DIR / "state.json"
+    lock_file = dest / STATE_DIR / "lock"
+
+    if not args.dry_run:
+        try:
+            if not _acquire_lock(lock_file):
+                log.error(
+                    f"another shrink appears to be running ({lock_file}); "
+                    "remove the file if it is stale"
+                )
+                return 1
+        except OSError as exc:
+            log.error(f"cannot create lock {lock_file}: {exc}")
+            return 1
+
+    log.info(f"scanning {source}: {len(sources)} image(s)")
+    state = _load_state(state_file, params, log)
+    params_match = state["params"] == params
+    files = state["files"]
+    counters = {
+        "converted": 0,
+        "state": 0,
+        "small": 0,
+        "protected": 0,
+        "failed": 0,
+        "deleted": 0,
+    }
+    status = 0
+    pyvips = None
+    encoded: set[str] = set()
+
+    try:
+        for src in sources:
+            rel = src.relative_to(source).as_posix()
+            try:
+                src_stat = src.stat()
+            except OSError as exc:
+                log.error(f"{rel}: {exc}")
+                counters["failed"] += 1
+                status = 1
+                continue
+
+            reason = None if args.force else _skip_reason(
+                src_stat, targets[src], files.get(rel), params_match, min_size
+            )
+            if reason == "small":
+                counters["small"] += 1
+                log.detail(f"skip {rel} (too small)")
+                continue
+            if reason == "state":
+                counters["state"] += 1
+                log.detail(f"skip {rel} (unchanged)")
+                continue
+
+            if args.dry_run:
+                print(rel)
+                counters["converted"] += 1
+                continue
+
+            if pyvips is None:
+                try:
+                    import pyvips as pyvips_module
+                except Exception as exc:
+                    log.error(PYVIPS_HINT)
+                    log.error(str(exc))
+                    status = 1
+                    break
+                pyvips = pyvips_module
+
+            dest_path = targets[src]
+            tmp = dest_path.with_name(f".{dest_path.name}.{os.getpid()}.tmp.avif")
+            try:
+                dest_path.parent.mkdir(parents=True, exist_ok=True)
+                try:
+                    img = pyvips.Image.thumbnail(str(src), width, size="down", linear=True)
+                    img.write_to_file(str(tmp), Q=quality, keep="none", effort=effort)
+                    os.replace(tmp, dest_path)
+                except Exception:
+                    try:
+                        tmp.unlink()
+                    except OSError:
+                        pass
+                    raise
+                out_stat = dest_path.stat()
+            except Exception as exc:
+                log.error(f"{rel}: {exc}")
+                counters["failed"] += 1
+                status = 1
+                continue
+
+            files[rel] = {
+                "src_size": src_stat.st_size,
+                "src_mtime_ns": src_stat.st_mtime_ns,
+                "out_size": out_stat.st_size,
+                "out_mtime_ns": out_stat.st_mtime_ns,
+            }
+            encoded.add(rel)
+            counters["converted"] += 1
+            log.detail(f"encoded {rel}")
+            if counters["converted"] % 200 == 0:
+                try:
+                    _save_state(state_file, state)
+                except OSError as exc:
+                    log.error(f"cannot write state {state_file}: {exc}")
+                    status = 1
+
+        if args.prune:
+            deleted, failed, protected = _prune(
+                state, source, dest, len(sources), args.dry_run, args.allow_empty, log
+            )
+            counters["deleted"] += deleted
+            counters["failed"] += failed
+            counters["protected"] += protected
+            if failed or protected:
+                status = 1
+
+        if not params_match and status == 0 and not args.dry_run:
+            # Only keep entries written under the new parameters; stale entries
+            # would otherwise be skipped after min_size or include changes.
+            state["files"] = {
+                rel: entry for rel, entry in state["files"].items() if rel in encoded
+            }
+    except KeyboardInterrupt:
+        log.error("interrupted")
+        status = 1
+    finally:
+        if not args.dry_run:
+            if params_match or status == 0:
+                state["params"] = params
+            try:
+                _save_state(state_file, state)
+            except OSError as exc:
+                log.error(f"cannot write state {state_file}: {exc}")
+                status = 1
+            _release_lock(lock_file)
+
+    _log_summary(log, counters)
+    return status

pix/sync.py

@@ -0,0 +1,142 @@
+"""backup and publish subcommands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from .config import ConfigError, require_int
+from .logger import Logger
+from .rclone import check_rclone, has_files, merge_excludes, run_rclone
+
+
+def backup(args: argparse.Namespace, settings: dict[str, Any], log: Logger) -> int:
+    config = settings["backup"]
+    source = args.source
+    if not source.is_dir():
+        log.error(f"source is not a directory: {source}")
+        return 2
+    try:
+        max_delete = require_int(
+            "max-delete",
+            args.max_delete if args.max_delete is not None else config["max_delete"],
+            -1,
+            100,
+        )
+    except ConfigError as exc:
+        log.error(str(exc))
+        return 2
+
+    try:
+        has_files_found = has_files(source)
+    except OSError as exc:
+        log.error(f"cannot scan {source}: {exc}")
+        return 1
+    if not has_files_found and not (args.allow_empty and args.resync):
+        log.error("source is empty; use --allow-empty together with --resync to proceed")
+        return 2
+
+    binary = settings["rclone"]["binary"]
+    version = check_rclone(binary, log)
+    if version is None:
+        return 1
+
+    excludes = merge_excludes(config["exclude"], args.exclude)
+    cmd = [binary, "bisync", str(source), args.dest]
+    for pattern in excludes:
+        cmd += ["--exclude", pattern]
+    cmd += ["--max-delete", str(max_delete)]
+    if args.resync:
+        cmd.append("--resync")
+    if args.dry_run:
+        cmd.append("--dry-run")
+    cmd.append("--progress" if args.verbose else "--quiet")
+
+    log.info(f"bisync {source} <-> {args.dest} (rclone {version})")
+    log.detail(" ".join(cmd))
+    return run_rclone(cmd)
+
+
+def _collect_avif(source: Path) -> list[Path]:
+    files = [
+        path for path in source.rglob("*") if path.is_file() and path.suffix.lower() == ".avif"
+    ]
+    files.sort(key=lambda path: path.relative_to(source).as_posix())
+    return files
+
+
+def publish(args: argparse.Namespace, settings: dict[str, Any], log: Logger) -> int:
+    config = settings["publish"]
+    source = args.source
+    if not source.is_dir():
+        log.error(f"source is not a directory: {source}")
+        return 2
+    try:
+        max_delete = require_int(
+            "max-delete",
+            args.max_delete if args.max_delete is not None else config["max_delete"],
+            -1,
+            100,
+        )
+    except ConfigError as exc:
+        log.error(str(exc))
+        return 2
+
+    try:
+        avifs = _collect_avif(source)
+    except OSError as exc:
+        log.error(f"cannot scan {source}: {exc}")
+        return 1
+    if not avifs and not (args.allow_empty and args.resync):
+        log.error(
+            "source contains no .avif files; use --allow-empty together with --resync "
+            "to proceed"
+        )
+        return 2
+
+    base_url = args.base_url if args.base_url is not None else config["base_url"]
+    urls = args.urls if args.urls is not None else config["urls"]
+    if base_url and not base_url.startswith(("http://", "https://")):
+        log.error("base-url must start with http:// or https://")
+        return 2
+    if urls and not base_url:
+        log.error("--urls requires a base URL (--base-url or [publish].base_url)")
+        return 2
+
+    binary = settings["rclone"]["binary"]
+    version = check_rclone(binary, log)
+    if version is None:
+        return 1
+
+    excludes = merge_excludes([".pix/**"], config["exclude"], args.exclude)
+    cmd = [binary, "bisync", str(source), args.dest]
+    for pattern in excludes:
+        cmd += ["--exclude", pattern]
+    cmd += ["--max-delete", str(max_delete)]
+    if args.resync:
+        cmd.append("--resync")
+    if args.dry_run:
+        cmd.append("--dry-run")
+    cmd.append("--progress" if args.verbose else "--quiet")
+
+    log.info(f"bisync {source} <-> {args.dest} (rclone {version})")
+    log.detail(" ".join(cmd))
+    code = run_rclone(cmd)
+    if code != 0 or args.dry_run or not urls:
+        return code
+
+    root = base_url.rstrip("/")
+    try:
+        files = _collect_avif(source)
+    except OSError as exc:
+        log.error(f"cannot scan {source}: {exc}")
+        return 1
+    manifest = {
+        rel: f"{root}/{quote(rel, safe='/')}"
+        for rel in (path.relative_to(source).as_posix() for path in files)
+    }
+    print(json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True))
+    return code

pix_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: pix-cli
+Version: 0.1.0
+Summary: Batch AVIF shrink and image-host sync CLI
+Author-email: uzvg <uzvg@qq.com>
+Requires-Python: >=3.11
+Requires-Dist: pyvips[binary]>=3.2
+Description-Content-Type: text/markdown
+
+# pix
+
+Batch AVIF shrink and image-host sync CLI.
+
+`pix` 把本地图片目录增量压缩为 AVIF，再通过 rclone bisync 备份原图、发布压缩图到图床。只处理显式传入的路径和远端。
+
+```bash
+pix shrink  -s ./photos -d ./out -w 1920 -q 85
+pix backup  -s ./photos -d onedrive:photos --resync
+pix publish -s ./out -d r2:images --base-url https://img.example.com --urls
+pix doctor
+pix config init
+```
+
+`backup` / `publish` 是双向镜像，不是单向备份：删除会双向传播。默认 `--max-delete 10`（删除百分比，即 10%），超过该比例时 rclone 会拒绝；首次运行或修改排除项后必须显式 `--resync`，先跑 `--dry-run` 更安全。
+
+> Status: implementation complete; real R2 and Windows smoke tests pending (see roadmap).
+
+## Docs
+
+- [Architecture](docs/architecture.md) — behavior spec
+- [Development](docs/development.md) — setup, tests, build
+- [Decisions](docs/decisions.md) — technical decisions and rationale
+- [Roadmap](docs/roadmap.md) — status and tasks
+
+## Quick start
+
+```bash
+uv sync
+uv run pytest
+```

pix_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+pix/__init__.py,sha256=gRYT_Cw6vsRunTh7WKL9SZSCZE0wcOdWrecSDfDYgbg,290
+pix/cli.py,sha256=vcrih_Kv8O4E0AC6dCkqd8qWS5rBZWwkiGfvy7QvoAk,4539
+pix/config.py,sha256=FTbwpUlCJlBlm0V1yt5Zt1mu9v2uveckCBnioImXIhs,5872
+pix/default_config.toml,sha256=q6y5sm_b90LGhRC-bQMd978qheSPO9Xx4abcmJqTIsE,765
+pix/doctor.py,sha256=z2ZrS-dsVPh2grdFda4XRze-0xUcGEd4rwxBZY6rl18,1676
+pix/logger.py,sha256=QUijBqc6CHFUKtF9L_1PcuTRCOS_FDt6eVzq3XD_Dik,704
+pix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pix/rclone.py,sha256=vvVReBo_XFHjmfoKBjPoFVUGaJxwe1zBGD4klLNpNgE,2290
+pix/shrink.py,sha256=DcptFJhDZ5j8zZrd-iFUhPHPp4uuoQdEHimdCjh446Y,11686
+pix/sync.py,sha256=yhlkl9OCCm0FsLwLNius7B9BNkpWVjevScNVcF6kKSg,4517
+pix_cli-0.1.0.dist-info/METADATA,sha256=yB9ZwSA6v4mzPTgtHH9ETGt3eMqnbn8LOBWuyTpGZJo,1323
+pix_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pix_cli-0.1.0.dist-info/entry_points.txt,sha256=1TW3gP0Yaf19T624ac9xUG9x8tLkQgPnfWlj3yNgOsY,37
+pix_cli-0.1.0.dist-info/RECORD,,

pix_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pix_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pix = pix.cli:main