bp

#!/usr/bin/env python3
"""
bp — Blue Pearmain command-line interface

Usage:
    bp pipeline [--dry-run] [--limit N]  Sync-metadata then auto-apply non-conflict proposals
    bp stats                        Show photo counts by privacy state
    bp poll [--backfill] [--days N] Poll Flickr for new/updated photos
    bp scan [--all] [--days N]      Scan Apple Photos library
    bp thumbs                       Populate missing thumbnail paths
    bp reconcile [--fix] [--limit N] Check DB state vs actual Flickr state
    bp link-orphans [--dry-run]     Merge split Photos/Flickr records
    bp checkpoint [--mode MODE]     Checkpoint the WAL file (default: truncate)
    bp sync-album-collections [--dry-run] [--remove [--force]]  Sync folder hierarchy → Flickr Collections
    bp sync-names-from-flickr [--dry-run]  Sync Flickr renames → Apple Photos
    bp all [--dry-run]              Full maintenance run (scan, poll, thumbs, sync-names-from-flickr, pipeline, reconcile, sync-albums, sync-album-collections, checkpoint)
    bp install-daemons [--dry-run]  Install launchd agents to ~/Library/LaunchAgents
    bp uninstall-daemons [--dry-run] Remove installed launchd agents
    bp ui                           Start the review UI (http://localhost:5173)
    bp migrate [--dry-run] [--baseline]  Apply pending DB migrations (--baseline: mark applied without running DDL)
    bp doctor [--check-flickr]      Validate config, environment, and DB state
    bp import-contacts-birthdays [--dry-run] [--overwrite]  Import birthdays from Apple Contacts

Global options:
    --config PATH   Path to config.yml (default: config/config.yml)
    --verbose       Extra logging

Run 'bp <subcommand> --help' for subcommand-specific options.
"""

import argparse
import sys
from pathlib import Path

# Ensure the repo root is on the path regardless of where bp is invoked from.
# Use .resolve().parent (resolve symlink FIRST, then get parent) so that invoking
# bp via a symlink (e.g. ~/bin/bp -> /repo/bp) resolves to the repo root, not the
# symlink's parent directory.
ROOT = Path(__file__).resolve().parent
sys.path.insert(0, str(ROOT))


def cmd_stats(args):
    import yaml
    from db.db import Database

    with open(args.config) as f:
        config = yaml.safe_load(f)
    db = Database(Path(config["database"]["path"]).expanduser())
    s = db.stats()

    by_state = s["by_state"]
    total = s["total"]
    order = [
        ("candidate_public", "Candidate public"),
        ("needs_review", "Needs review"),
        ("approved_public", "Approved public"),
        ("already_public", "Already public"),
        ("keep_private", "Keep private"),
        ("auto_private", "Auto private"),
        ("skipped", "Skipped"),
        ("duplicate_flickr", "Duplicate Flickr"),
    ]

    flickr_linked = db.conn.execute(
        "SELECT COUNT(*) AS n FROM photos WHERE flickr_id IS NOT NULL"
    ).fetchone()["n"]
    pushed = db.conn.execute(
        """SELECT COUNT(*) AS n FROM photos
           WHERE privacy_state = 'approved_public'
             AND perms_pushed_flickr = 1"""
    ).fetchone()["n"]
    approved_pushable = db.conn.execute(
        """SELECT COUNT(*) AS n FROM photos
           WHERE privacy_state = 'approved_public'
             AND flickr_id IS NOT NULL
             AND perms_pushed_flickr = 0"""
    ).fetchone()["n"]
    db.close()

    if args.oneliner:
        short = {
            "candidate_public": "cand",
            "needs_review": "review",
            "approved_public": "approved",
            "already_public": "public",
            "keep_private": "private",
            "auto_private": "auto",
            "skipped": "skip",
            "duplicate_flickr": "dup",
        }
        parts = []
        for state, _ in order:
            n = by_state.get(state, 0)
            if n:
                parts.append(f"{short[state]}={n}")
        parts.append(f"total={total}")
        parts.append(f"flickr={flickr_linked}")
        parts.append(f"local={total - flickr_linked}")
        parts.append(f"pushed={pushed}")
        parts.append(f"pushable={approved_pushable}")
        print("  ".join(parts))
        return

    print()
    width = max(len(label) for _, label in order)
    for state, label in order:
        n = by_state.get(state, 0)
        if n:
            print(f"  {label:<{width}}  {n:>8,}")

    print(f"  {'─' * (width + 11)}")
    print(f"  {'Total':<{width}}  {total:>8,}")
    print()
    print(f"  Flickr-linked records:  {flickr_linked:>8,}")
    print(f"  Photos-only records:    {total - flickr_linked:>8,}")
    print(f"  Approved + pushed:      {pushed:>8,}")
    print(f"  Approved + pushable:    {approved_pushable:>8,}  (Flickr-linked, not yet pushed)")
    print()


def _run(fn, args, pairs):
    """Inject argv, call fn(), propagate non-zero exit codes."""
    _inject_argv(args, pairs)
    try:
        result = fn()
        if isinstance(result, int) and result != 0:
            sys.exit(result)
    except SystemExit:
        raise
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


def cmd_poll(args):
    from poller.poller import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--backfill", args.backfill),
            ("--days", str(args.days) if args.days else None),
            ("--verbose", args.verbose),
            ("--dry-run", args.dry_run),
        ],
    )


def cmd_scan(args):
    from poller.scanner import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--all", args.all),
            ("--days", str(args.days) if args.days else None),
            ("--verbose", args.verbose),
            ("--dry-run", args.dry_run),
        ],
    )


def cmd_thumbs(args):
    from poller.thumbnailer import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--verbose", args.verbose),
            ("--icloud", args.icloud),
            ("--icloud-limit", args.icloud_limit),
        ],
    )


def cmd_pipeline(args):
    """
    Run the full metadata sync pipeline without manual steps:
      1. bp sync-metadata  — diff cached values, generate proposals
      2. bp reconcile --apply-proposals  — auto-apply all non-conflict proposals
    Collision proposals are left pending for manual review in the UI.
    """
    import logging
    import yaml
    from pathlib import Path as _Path
    from poller.bp_logging import configure

    configure("pipeline", args.verbose)
    log = logging.getLogger("blue-pearmain.pipeline")

    with open(args.config) as f:
        config = yaml.safe_load(f)

    db_path = config["database"]["path"]
    library_path = str(_Path(config.get("photos_library", {}).get("path", "")).expanduser())

    from db.db import Database

    db = Database(db_path)

    # Step 1: generate proposals for any photos whose cache has drifted
    from flickr.sync_metadata import _select_drift_filtered
    from flickr.metadata_puller import run_sync_engine

    dry_run = getattr(args, "dry_run", False)

    photo_ids = _select_drift_filtered(db, limit=0)
    if photo_ids:
        log.info(
            "pipeline: sync-metadata — %d photos to harmonise%s",
            len(photo_ids),
            "  (dry-run)" if dry_run else "",
        )
        sync_totals = run_sync_engine(db, photo_ids, dry_run=dry_run, verbose=args.verbose)
        log.info(
            "pipeline: sync-metadata done — proposals=%d  hash_matches=%d  skipped=%d  failed=%d%s",
            sync_totals["proposals"],
            sync_totals["hash_matches"],
            sync_totals["skipped"],
            sync_totals["failed"],
            "  (dry-run: not written)" if dry_run else "",
        )
    else:
        log.info("pipeline: sync-metadata — nothing to harmonise (all in sync)")
        sync_totals = {}

    # Step 2: auto-apply non-conflict proposals (both tags and title/description)
    if dry_run:
        from flickr.proposal_applier import _count_pending

        pending = _count_pending(db, conflict_types=["non_conflict"])
        log.info(
            "pipeline: apply skipped (dry-run) — %d pending non-conflict proposal(s) would be applied",
            pending,
        )
    else:
        from flickr.proposal_applier import apply_batch

        apply_totals = apply_batch(
            db,
            library_path,
            conflict_types=["non_conflict"],
            limit=args.limit or 0,
        )
        log.info(
            "pipeline: apply done — applied=%d  failed=%d  superseded=%d",
            apply_totals["applied"],
            apply_totals["failed"],
            apply_totals["superseded"],
        )

    db.close()


def cmd_reconcile(args):
    from poller.reconcile import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--fix", args.fix),
            ("--apply-proposals", args.apply_proposals),
            ("--explain", args.explain),
            ("--limit", str(args.limit) if args.limit is not None else None),
            ("--verbose", args.verbose),
        ],
    )


def cmd_tag_writeback(args):
    from poller.tag_writeback import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--dry-run", args.dry_run),
            ("--limit", str(args.limit) if args.limit is not None else None),
            ("--verbose", args.verbose),
            ("--source", args.source),
        ],
    )


def cmd_ui(args):
    from reviewer.app import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--port", str(args.port)),
            ("--host", args.host),
            ("--debug", args.debug),
        ],
    )


def cmd_sync_albums(args):
    from flickr.sync_albums import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--dry-run", args.dry_run),
            ("--album", args.album),
            ("--limit", str(args.limit) if args.limit is not None else None),
            ("--coalesce", getattr(args, "coalesce", False)),
            ("--verbose", args.verbose),
        ],
    )


def cmd_sync_album_collections(args):
    from flickr.sync_collections import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--dry-run", args.dry_run),
            ("--remove", getattr(args, "remove", False)),
            ("--force", getattr(args, "force", False)),
            ("--verbose", args.verbose),
        ],
    )


def cmd_sync_names_from_flickr(args):
    from flickr.sync_names_from_flickr import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--dry-run", args.dry_run),
            ("--verbose", args.verbose),
        ],
    )


def cmd_sync_metadata(args):
    from flickr.sync_metadata import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--dry-run", args.dry_run),
            ("--limit", str(args.limit) if args.limit is not None else None),
            ("--photo-id", str(args.photo_id) if args.photo_id else None),
            ("--conflicts-only", args.conflicts_only),
            ("--force", args.force),
            ("--verbose", args.verbose),
        ],
    )


def cmd_link_orphans(args):
    from poller.link_orphans import main

    _run(
        main,
        args,
        [
            ("--config", args.config),
            ("--dry-run", args.dry_run),
            ("--limit", str(args.limit) if args.limit is not None else None),
            ("--verbose", args.verbose),
        ],
    )


def cmd_install_daemons(args):
    """Install launchd plist files to ~/Library/LaunchAgents, substituting template tokens."""
    import shutil

    home = Path.home()
    uv = shutil.which("uv")
    if not uv:
        print("Error: 'uv' not found on PATH.", file=sys.stderr)
        sys.exit(1)

    plists = [
        "com.blue-pearmain.poller.plist",
        "com.blue-pearmain.pipeline.plist",
        "com.blue-pearmain.reviewer.plist",
        "com.blue-pearmain.reconcile.plist",
        "com.blue-pearmain.deduplicator.plist",
    ]
    launch_agents = home / "Library" / "LaunchAgents"
    if not args.dry_run:
        launch_agents.mkdir(parents=True, exist_ok=True)

    for plist_name in plists:
        src = ROOT / "config" / plist_name
        template = src.read_text()
        content = (
            template.replace("__REPO__", str(ROOT))
            .replace("__UV__", uv)
            .replace("__HOME__", str(home))
        )
        dest = launch_agents / plist_name
        if args.dry_run:
            print(f"  would install: {dest}")
        else:
            dest.write_text(content)
            print(f"  installed: {dest}")

    if not args.dry_run:
        print()
        print("To load the daemons, run:")
        for plist_name in plists:
            print(f"  launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/{plist_name}")
        print()
        print("Or reload an already-loaded daemon:")
        print("  launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/<name>.plist")
        print("  launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<name>.plist")


def cmd_uninstall_daemons(args):
    """Remove installed launchd plist files from ~/Library/LaunchAgents."""
    home = Path.home()
    plists = [
        "com.blue-pearmain.poller.plist",
        "com.blue-pearmain.pipeline.plist",
        "com.blue-pearmain.reviewer.plist",
        "com.blue-pearmain.reconcile.plist",
        "com.blue-pearmain.deduplicator.plist",
    ]
    launch_agents = home / "Library" / "LaunchAgents"
    any_found = False
    for plist_name in plists:
        dest = launch_agents / plist_name
        if dest.exists():
            any_found = True
            if args.dry_run:
                print(f"  would remove: {dest}")
            else:
                dest.unlink()
                print(f"  removed: {dest}")
        else:
            print(f"  not installed: {dest}")

    if any_found and not args.dry_run:
        print()
        print("If the daemons were loaded, unload them with:")
        for plist_name in plists:
            print(f"  launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/{plist_name}")
        print()
        print("(Ignore 'No such process' errors for daemons that were not running.)")


def cmd_checkpoint(args):
    """Run a WAL checkpoint and report results."""
    import yaml
    from db.db import Database

    with open(args.config) as f:
        config = yaml.safe_load(f)
    db = Database(Path(config["database"]["path"]).expanduser())
    result = db.checkpoint(mode=args.mode.upper())
    db.close()

    busy = result["busy"]
    log = result["log"]
    checkpointed = result["checkpointed"]

    if log == 0:
        print("WAL is empty — nothing to checkpoint.")
    elif busy > 0:
        print(
            f"Checkpoint incomplete: {checkpointed}/{log} frames moved "
            f"({busy} frame(s) blocked by active readers). "
            f"Run again when the UI and other readers are stopped for a full truncate."
        )
    else:
        print(f"Checkpoint complete: {checkpointed}/{log} frames moved, WAL truncated.")


def cmd_deduplicator(args):
    """Find and classify duplicate photos; optionally write results to DB."""
    import yaml
    from poller.deduplicator import main as dedup_main

    pairs = [("--config", args.config)]
    if args.write:
        pairs.append(("--write", True))
    if args.dry_run:
        pairs.append(("--dry-run", True))
    if args.confirm:
        pairs.append(("--confirm", True))
    if args.flickr:
        pairs.append(("--flickr", True))
    if args.limit is not None:
        pairs.append(("--limit", str(args.limit)))
    if args.verbose:
        pairs.append(("--verbose", True))
    if args.prune:
        pairs.append(("--prune", True))
    if args.apply:
        pairs.append(("--apply", True))
    _inject_argv(args, pairs)
    dedup_main()


def cmd_prune_proposals(args):
    """Prune resolved metadata proposals and supersede spurious managed-tag proposals."""
    import yaml
    from db.db import Database

    with open(args.config) as f:
        config = yaml.safe_load(f)
    db = Database(Path(config["database"]["path"]).expanduser())

    superseded = db.supersede_managed_tag_proposals(dry_run=args.dry_run)
    pruned = db.prune_proposals(older_than_days=args.older_than, dry_run=args.dry_run)

    db.close()

    prefix = "[dry-run] would " if args.dry_run else ""
    print(f"{prefix}supersede={superseded}  prune={pruned}")


def _inject_argv(args, pairs):
    """Rebuild sys.argv from parsed args so subcommand main()s parse correctly."""
    new_argv = [sys.argv[0]]
    for flag, value in pairs:
        if value is None or value is False:
            continue
        if value is True:
            new_argv.append(flag)
        else:
            new_argv.extend([flag, str(value)])
    sys.argv = new_argv


def _step_args(base, **overrides):
    """Return a copy of base Namespace with overrides applied."""
    import argparse as _ap

    d = vars(base).copy()
    d.update(overrides)
    return _ap.Namespace(**d)


def cmd_status(args):
    """Print operational status: daemon state, queue sizes, pending proposals."""
    import yaml

    from db.db import Database
    from poller.status import collect_status, format_status, status_exit_code

    config_path = Path(args.config)
    if not config_path.exists():
        print(f"Error: config file not found: {config_path}", file=sys.stderr)
        sys.exit(2)

    try:
        with open(config_path) as f:
            config = yaml.safe_load(f)
    except Exception as e:
        print(f"Error reading config: {e}", file=sys.stderr)
        sys.exit(2)

    try:
        db = Database(Path(config["database"]["path"]).expanduser())
    except Exception as e:
        print(f"Error opening database: {e}", file=sys.stderr)
        sys.exit(2)

    try:
        status = collect_status(config, db)
    finally:
        db.close()

    print(format_status(status))
    sys.exit(status_exit_code(status))


def cmd_export(args):
    """Export BP database state to portable NDJSON files."""
    import yaml
    from datetime import date
    from db.db import Database
    from poller.exporter import collect_export_data, write_export

    config_path = Path(args.config)
    if not config_path.exists():
        print(f"Error: config file not found: {config_path}", file=sys.stderr)
        sys.exit(2)

    try:
        with open(config_path) as f:
            config = yaml.safe_load(f)
    except Exception as e:
        print(f"Error reading config: {e}", file=sys.stderr)
        sys.exit(2)

    try:
        db = Database(Path(config["database"]["path"]).expanduser())
    except Exception as e:
        print(f"Error opening database: {e}", file=sys.stderr)
        sys.exit(2)

    out_dir = Path(args.out) if args.out else Path(f"bp-export-{date.today()}")

    try:
        data = collect_export_data(db)
    finally:
        db.close()

    write_export(data, out_dir)
    photo_count = data["manifest"]["photo_count"]
    zone_count = data["manifest"]["zone_count"]
    print(f"Exported {photo_count} photos and {zone_count} zones → {out_dir}/")
    print(f"  photos.ndjson  (NDJSON — one object per line)")
    print(f"  zones.json     (JSON array)")
    print(f"  manifest.json  (export metadata)")


# ---------------------------------------------------------------------------
# Migration helpers
# ---------------------------------------------------------------------------


def _pending_migrations(
    db_path: str,
    migrations_dir: Path,
) -> list[tuple[str, Path]]:
    """
    Return (migration_name, file_path) pairs for migrations not yet applied to
    db_path, sorted by filename (migrate_NNN_... sorts numerically by NNN).
    """
    import re
    import sqlite3

    _name_re = re.compile(r'^MIGRATION_NAME\s*=\s*["\']([^"\']+)["\']', re.MULTILINE)

    try:
        conn = sqlite3.connect(db_path)
        conn.row_factory = sqlite3.Row
        applied = {r["name"] for r in conn.execute("SELECT name FROM schema_migrations").fetchall()}
        conn.close()
    except sqlite3.OperationalError:
        # schema_migrations table doesn't exist yet (fresh DB) — treat all as pending
        applied = set()

    result: list[tuple[str, Path]] = []
    for mf in sorted(migrations_dir.glob("migrate_*.py")):
        m = _name_re.search(mf.read_text())
        if m and m.group(1) not in applied:
            result.append((m.group(1), mf))
    return result


def cmd_doctor(args):
    """
    Validate config, environment, and DB state before running the pipeline.
    Prints a pass/fail checklist and exits non-zero if any required check fails.
    """
    import sqlite3
    import yaml

    OK = "✓"
    FAIL = "✗"
    WARN = "!"
    issues = []

    def check(symbol, label, detail=""):
        line = f"  {symbol}  {label}"
        if detail:
            line += f"\n       → {detail}"
        print(line)
        if symbol == FAIL:
            issues.append(label)

    print()
    print("Blue Pearmain — environment check")
    print("─" * 40)

    # ── 1. Config file ────────────────────────────────────────────────────────
    config_path = Path(args.config)
    if not config_path.exists():
        check(
            FAIL,
            f"Config file: {config_path}",
            "File not found — copy config/config.example.yml to config/config.yml and fill in your values",
        )
        print()
        print("Cannot continue: config file is required for all other checks.")
        sys.exit(1)

    try:
        with open(config_path) as f:
            config = yaml.safe_load(f)
        check(OK, f"Config file: {config_path}")
    except Exception as e:
        check(FAIL, f"Config file: {config_path}", f"YAML parse error: {e}")
        sys.exit(1)

    # ── 2. Required config keys ───────────────────────────────────────────────
    def _cfg(*keys, label=None):
        val = config
        for k in keys:
            val = (val or {}).get(k)
        display = label or ".".join(keys)
        if not val:
            check(FAIL, f"Config key {display}", "Missing or empty — check config.yml")
        else:
            check(OK, f"Config key {display}")

    _cfg("database", "path")
    _cfg("photos_library", "path")
    _cfg("flickr", "api_key")
    _cfg("flickr", "api_secret")
    _cfg("flickr", "oauth_token")
    _cfg("flickr", "oauth_token_secret")
    _cfg("photos_library", "self_name", label="photos_library.self_name")

    if "photos_library" in config and not config["photos_library"].get("self_name"):
        check(
            WARN,
            "photos_library.self_name is empty — photos of named people will not be filtered as self",
        )

    # ── 3. Photos library path ────────────────────────────────────────────────
    photos_path_raw = (config.get("photos_library") or {}).get("path", "")
    if photos_path_raw:
        photos_path = Path(photos_path_raw).expanduser()
        if photos_path.exists():
            check(OK, f"Photos library: {photos_path}")
        else:
            check(
                FAIL,
                f"Photos library: {photos_path}",
                "Path not found — check photos_library.path in config.yml",
            )

    # ── 4. Database ───────────────────────────────────────────────────────────
    db_path_raw = (config.get("database") or {}).get("path", "")
    db_ok = False
    if db_path_raw:
        db_path = Path(db_path_raw).expanduser()
        if not db_path.exists():
            check(WARN, f"Database: {db_path}", "File not found — will be created on first run")
            db_ok = False
        else:
            try:
                conn = sqlite3.connect(str(db_path))
                conn.execute("SELECT 1")
                conn.close()
                check(OK, f"Database: {db_path}")
                db_ok = True
            except Exception as e:
                check(FAIL, f"Database: {db_path}", f"Cannot open: {e}")

    # ── 5. Migrations ─────────────────────────────────────────────────────────
    if db_ok:
        try:
            pending = _pending_migrations(str(db_path), ROOT / "db" / "migrations")
            if pending:
                for name, _ in pending:
                    check(WARN, f"Migration not applied: {name}")
                config_flag = (
                    f" --config {args.config}" if args.config != "config/config.yml" else ""
                )
                print(f"       → Run: bp{config_flag} migrate")
            else:
                conn = sqlite3.connect(str(db_path))
                applied = [
                    r[0]
                    for r in conn.execute(
                        "SELECT name FROM schema_migrations ORDER BY name"
                    ).fetchall()
                ]
                conn.close()
                last = applied[-1] if applied else "(none)"
                check(OK, f"Migrations: all applied (latest: {last})")
        except Exception as e:
            check(WARN, "Migrations: could not check", str(e))

    # ── 6. photoscript importable ─────────────────────────────────────────────
    try:
        import photoscript  # noqa: F401

        check(OK, "photoscript: importable")
    except ImportError:
        check(FAIL, "photoscript: not found", "Run: uv add photoscript")

    # ── 7. Flickr credentials ping (opt-in) ───────────────────────────────────
    if args.check_flickr:
        try:
            from flickr.flickr_client import FlickrClient

            fc = config.get("flickr", {})
            client = FlickrClient(
                api_key=fc.get("api_key", ""),
                api_secret=fc.get("api_secret", ""),
                oauth_token=fc.get("oauth_token", ""),
                oauth_token_secret=fc.get("oauth_token_secret", ""),
            )
            result = client._call("flickr.test.login")
            username = result.get("user", {}).get("username", {}).get("_content", "?")
            check(OK, f"Flickr credentials: authenticated as {username}")
        except Exception as e:
            check(FAIL, "Flickr credentials: API call failed", str(e))

    # ── Summary ───────────────────────────────────────────────────────────────
    print()
    if issues:
        print(f"  {len(issues)} problem(s) found:")
        for i in issues:
            print(f"    {FAIL}  {i}")
        print()
        sys.exit(1)
    else:
        print("  All checks passed.")
        print()


def cmd_migrate(args: argparse.Namespace) -> None:
    """
    Auto-discover and apply all pending DB migrations in order.
    Safe to re-run — each migration is idempotent.
    """
    import importlib.util
    import yaml

    with open(args.config) as f:
        config = yaml.safe_load(f)

    db_path = str(Path(config["database"]["path"]).expanduser())
    migrations_dir = ROOT / "db" / "migrations"

    pending = _pending_migrations(db_path, migrations_dir)

    if not pending:
        print("All migrations already applied.")
        return

    dry_run = getattr(args, "dry_run", False)
    baseline = getattr(args, "baseline", False)

    if baseline:
        _baseline_migrations(db_path, pending, dry_run=dry_run)
        return

    for name, file_path in pending:
        if dry_run:
            print(f"  [dry-run] Would apply: {name}")
        else:
            print(f"  Applying: {name}…")
            spec = importlib.util.spec_from_file_location(name, file_path)
            module = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
            spec.loader.exec_module(module)  # type: ignore[union-attr]
            module.run(db_path, dry_run=False)

    count = len(pending)
    if dry_run:
        print(f"\n{count} migration(s) would be applied.")
    else:
        print(f"\n{count} migration(s) applied.")


def _baseline_migrations(
    db_path: str,
    pending: list[tuple[str, Path]],
    *,
    dry_run: bool,
) -> None:
    """Record pending migration names as applied WITHOUT running their DDL.

    Use once on a live DB whose schema already exists but whose
    schema_migrations table is out of sync — avoids re-running destructive
    table-rebuild migrations. Idempotent (INSERT OR IGNORE).
    """
    import sqlite3
    from datetime import datetime, timezone

    if dry_run:
        for name, _ in pending:
            print(f"  [dry-run] Would mark applied (baseline): {name}")
        print(f"\n{len(pending)} migration(s) would be marked applied (baseline).")
        return

    conn = sqlite3.connect(db_path)
    try:
        conn.execute(
            "CREATE TABLE IF NOT EXISTS schema_migrations "
            "(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE NOT NULL, "
            "applied_at TEXT NOT NULL)"
        )
        now = datetime.now(timezone.utc).isoformat()
        for name, _ in pending:
            print(f"  Marking applied (baseline): {name}")
            conn.execute(
                "INSERT OR IGNORE INTO schema_migrations (name, applied_at) VALUES (?, ?)",
                (name, now),
            )
        conn.commit()
    finally:
        conn.close()

    print(f"\n{len(pending)} migration(s) marked applied (baseline; no DDL run).")


def _resolve_legacy_library_path(args: argparse.Namespace, config: dict) -> str:
    """--library wins; else fall back to optional config legacy_library.path."""
    if getattr(args, "library", None):
        return str(Path(args.library).expanduser())
    cfg = (config.get("legacy_library") or {}).get("path")
    if cfg:
        return str(Path(cfg).expanduser())
    print(
        "Error: no library path. Pass --library <path> or set legacy_library.path in config.",
        file=sys.stderr,
    )
    sys.exit(2)


def cmd_index_legacy(args: argparse.Namespace) -> None:
    """Index a legacy (migrated iPhoto/Photos 4) library into curator.db."""
    import yaml

    sys.path.insert(0, str(ROOT / "poller"))
    from db.db import Database
    from legacy_indexer import index_library
    from bp_logging import configure

    configure("legacy-indexer", args.verbose)

    with open(args.config) as f:
        config = yaml.safe_load(f)

    db_path = str(Path(config["database"]["path"]).expanduser())
    thumb_root = Path(config["thumbnails"]["path"]).expanduser()
    library_path = _resolve_legacy_library_path(args, config)

    if not Path(library_path).exists():
        print(f"Error: library not found / not mounted: {library_path}", file=sys.stderr)
        sys.exit(1)

    db = Database(db_path)
    try:
        stats = index_library(
            library_path,
            db,
            curator_db_path=db_path,
            thumb_root=thumb_root,
            copy_thumbnails=not args.no_thumbnails,
            limit=args.limit,
            use_cache=not args.no_cache,
            refresh_cache=args.refresh_cache,
        )
    finally:
        db.close()

    print(
        f"Indexed {stats['indexed']} assets from library {stats['library_uuid']} "
        f"(thumbs ok={stats['thumb_ok']} missing={stats['thumb_missing']} "
        f"error={stats['thumb_error']}; "
        f"{'authoritative, reconciled ' + str(stats['reconciled']) if stats['authoritative'] else 'non-authoritative (--limit), no deletions'})."
    )


def cmd_match_legacy(args: argparse.Namespace) -> None:
    """Match legacy assets to Flickr-only candidate_public photos. Preview by
    default (no writes); with --apply, reclassify confident (and all-people
    ambiguous) matches out of the review queue."""
    import csv
    import yaml
    from collections import defaultdict

    sys.path.insert(0, str(ROOT / "poller"))
    from db.db import Database
    from legacy_match import normalise_wall_clock, order_rows, preview_rows
    from legacy_apply import apply_legacy_matches
    from analyzer.privacy import CLASSIFIER_VERSION

    with open(args.config) as f:
        config = yaml.safe_load(f)
    db_path = str(Path(config["database"]["path"]).expanduser())
    db = Database(db_path)

    try:
        # Determine library_uuid: explicit flag, else the single indexed library.
        if getattr(args, "library_uuid", None):
            library_uuid = args.library_uuid
        else:
            libs = db.conn.execute(
                "SELECT library_uuid FROM legacy_libraries ORDER BY indexed_at DESC"
            ).fetchall()
            if not libs:
                print(
                    "No indexed legacy library found. Run 'bp index-legacy' first.", file=sys.stderr
                )
                sys.exit(1)
            if len(libs) > 1 and not args.library_uuid:
                print(
                    "Multiple legacy libraries indexed; pass --library-uuid <uuid>.",
                    file=sys.stderr,
                )
                sys.exit(2)
            library_uuid = libs[0]["library_uuid"]

        # Index legacy assets by local wall-clock timestamp (see legacy_match).
        by_date: dict[str, list[dict]] = defaultdict(list)
        for asset in db.iter_legacy_assets(library_uuid):
            norm = normalise_wall_clock(asset.get("date_taken"))
            if norm:
                by_date[norm].append(asset)

        # Flickr-only candidate_public photos.
        photos = db.conn.execute(
            "SELECT flickr_id, date_taken, width, height, flickr_title "
            "FROM photos WHERE uuid IS NULL AND privacy_state = 'candidate_public'"
        ).fetchall()

        pairs = []
        for p in photos:
            norm = normalise_wall_clock(p["date_taken"])
            candidates = by_date.get(norm, []) if norm else []
            pairs.append((dict(p), candidates))

        rows = order_rows(preview_rows(pairs))

        counts = {"confident": 0, "ambiguous": 0, "no-match": 0}
        seen_photos: dict[str, set[str]] = {
            "confident": set(),
            "ambiguous": set(),
            "no-match": set(),
        }
        for r in rows:
            seen_photos[r["tier"]].add(r["flickr_id"])
        for tier in counts:
            counts[tier] = len(seen_photos[tier])

        print("Legacy match preview (non-destructive — no writes to photos)")
        print(f"  library_uuid : {library_uuid}")
        print(f"  photos       : {len(photos)} Flickr-only candidate_public")
        print(f"  confident    : {counts['confident']}")
        print(f"  ambiguous    : {counts['ambiguous']}")
        print(f"  no-match     : {counts['no-match']}")

        if args.csv:
            fields = [
                "tier",
                "date_norm",
                "flickr_id",
                "asset_uuid",
                "width",
                "height",
                "flickr_title",
                "legacy_title",
                "legacy_persons",
            ]
            with open(args.csv, "w", newline="") as fh:
                w = csv.DictWriter(fh, fieldnames=fields, extrasaction="ignore")
                w.writeheader()
                for r in rows:
                    w.writerow(r)
            print(f"  CSV written  : {args.csv} ({len(rows)} rows)")

        if getattr(args, "apply", False):
            self_name = config.get("photos_library", {}).get("self_name", "")
            zones = db.active_zones()
            person_policies = db.get_person_policies()
            demote_all_confident = bool(
                (config.get("legacy_match") or {}).get("demote_all_confident", False)
            )
            counts = apply_legacy_matches(
                db,
                library_uuid,
                self_name=self_name,
                zones=zones,
                person_policies=person_policies,
                classifier_version=CLASSIFIER_VERSION,
                demote_all_confident=demote_all_confident,
            )
            print("Applied legacy reclassification:")
            print(f"  eligible     : {counts['eligible']} candidate_public photos evaluated")
            print(f"  reclassified : {counts['reclassified']} photos moved out of candidate_public")
            print(f"    needs_review : {counts['needs_review']}")
            print(f"    auto_private : {counts['auto_private']}")
            print(f"  unchanged    : {counts['unchanged']}")
            print(f"  failed       : {counts['failed']} (rolled back and skipped)")
            print(
                f"  metadata     : {counts['metadata_matched']} matched, "
                f"{counts['metadata_applied']} updated, "
                f"{counts['metadata_failed']} failed"
            )
    finally:
        db.close()


def cmd_legacy_report(args: argparse.Namespace) -> None:
    """Report on legacy assets with no matching Flickr photo (#229)."""
    import csv
    import yaml

    sys.path.insert(0, str(ROOT / "poller"))
    from db.db import Database
    from legacy_report import report_unmatched

    with open(args.config) as f:
        config = yaml.safe_load(f)
    db_path = str(Path(config["database"]["path"]).expanduser())
    db = Database(db_path)

    try:
        libs = db.conn.execute(
            "SELECT library_uuid FROM legacy_libraries ORDER BY indexed_at DESC"
        ).fetchall()
        if not libs:
            print("No indexed legacy library found. Run 'bp index-legacy' first.", file=sys.stderr)
            sys.exit(1)
        if len(libs) > 1 and not getattr(args, "library_uuid", None):
            print("Multiple legacy libraries indexed; pass --library-uuid <uuid>.", file=sys.stderr)
            sys.exit(2)
        library_uuid = getattr(args, "library_uuid", None) or libs[0]["library_uuid"]

        r = report_unmatched(db, library_uuid)
    finally:
        db.close()

    print("Legacy library inventory (#229)")
    print(f"  library_uuid : {r['library_uuid']}")
    print(f"  total assets : {r['total']:,}")
    print(f"  matched      : {r['matched']:,}  (timestamp found in Flickr photos)")
    print(f"  unmatched    : {r['unmatched']:,}  (no Flickr photo at this timestamp — upload candidates)")
    print(f"  no date      : {r['no_date']:,}  (date_taken is NULL — cannot match by timestamp)")

    if r["by_year"]:
        print("\nUnmatched by year:")
        for year in sorted(r["by_year"]):
            print(f"  {year}  {r['by_year'][year]:,}")

    if args.csv:
        fields = [
            "asset_uuid", "original_filename", "date_taken",
            "width", "height", "title", "persons",
            "named_face_count", "unknown_face_count",
            "latitude", "longitude", "master_rel_path",
        ]
        with open(args.csv, "w", newline="") as fh:
            w = csv.DictWriter(fh, fieldnames=fields, extrasaction="ignore")
            w.writeheader()
            for asset in r["assets"]:
                w.writerow(asset)
        print(f"\nCSV written  : {args.csv} ({r['unmatched']:,} rows)")


def cmd_upload_legacy_unmatched(args: argparse.Namespace) -> None:
    """Upload legacy-only assets to Flickr, bypassing Apple Photos (#230)."""
    import yaml

    sys.path.insert(0, str(ROOT / "poller"))
    from db.db import Database
    from legacy_uploader import upload_unmatched_assets
    from analyzer.privacy import CLASSIFIER_VERSION

    with open(args.config) as f:
        config = yaml.safe_load(f)

    db_path = str(Path(config["database"]["path"]).expanduser())
    library_path = Path(_resolve_legacy_library_path(args, config)).expanduser()

    if not library_path.exists():
        print(f"Error: library not found / not mounted: {library_path}", file=sys.stderr)
        sys.exit(1)

    db = Database(db_path)
    try:
        libs = db.conn.execute(
            "SELECT library_uuid FROM legacy_libraries ORDER BY indexed_at DESC"
        ).fetchall()
        if not libs:
            print(
                "No indexed legacy library found. Run 'bp index-legacy' first.",
                file=sys.stderr,
            )
            sys.exit(1)
        if len(libs) > 1 and not getattr(args, "library_uuid", None):
            print(
                "Multiple legacy libraries indexed; pass --library-uuid <uuid>.",
                file=sys.stderr,
            )
            sys.exit(2)
        library_uuid = getattr(args, "library_uuid", None) or libs[0]["library_uuid"]

        if args.dry_run:
            flickr_client = None
        else:
            from flickr.flickr_client import FlickrClient
            flickr_client = FlickrClient.from_config(config)

        self_name = config.get("photos_library", {}).get("self_name", "")
        zones = db.active_zones()
        person_policies = db.get_person_policies()

        counts = upload_unmatched_assets(
            db,
            library_uuid,
            library_path,
            flickr_client,
            self_name=self_name,
            zones=zones,
            person_policies=person_policies,
            classifier_version=CLASSIFIER_VERSION,
            limit=getattr(args, "limit", None),
            dry_run=args.dry_run,
        )
    finally:
        db.close()

    prefix = "Legacy upload dry run" if args.dry_run else "Legacy upload"
    print(prefix)
    print(f"  library_uuid       : {library_uuid}")
    if counts["recovered"]:
        print(f"  recovered          : {counts['recovered']}")
    if args.dry_run:
        print(f"  eligible           : {counts['eligible']}")
        print(
            f"  would upload       : "
            f"{counts['eligible'] - counts['skipped_missing_file']}"
        )
        print(f"  skipped (no file)  : {counts['skipped_missing_file']}")
        print("\nWould-be privacy states:")
    else:
        print(f"  eligible           : {counts['eligible']}")
        print(f"  uploaded           : {counts['uploaded']}")
        print(f"  already uploaded   : {counts['skipped_already_uploaded']}")
        print(f"  skipped (no file)  : {counts['skipped_missing_file']}")
        print(f"  upload failed      : {counts['upload_failed']}")
        print(f"  db write failed    : {counts['db_write_failed']}")
        if counts["date_set_failed"]:
            print(f"  date set failed    : {counts['date_set_failed']}  (bp sync-metadata will fix)")
        print("\nPrivacy states applied:")
    print(f"  auto_private       : {counts['auto_private']}")
    print(f"  needs_review       : {counts['needs_review']}")
    print(f"  candidate_public   : {counts['candidate_public']}")


def cmd_geocode(args: argparse.Namespace) -> None:
    """Backfill place data from Nominatim for photos with GPS coordinates."""
    import yaml

    sys.path.insert(0, str(ROOT / "poller"))
    from bp_logging import configure
    from db.db import Database
    from geocoder import _PUBLIC_NOMINATIM_URL, check_nominatim_status, fetch_from_nominatim, make_fetcher
    from run_geocode import run_geocode

    # --check-nominatim exits before the config file is opened (no DB path needed).
    if args.check_nominatim:
        url = args.nominatim_url or _PUBLIC_NOMINATIM_URL
        ok, msg = check_nominatim_status(url)
        print(msg)
        sys.exit(0 if ok else 1)

    configure("geocode", verbose=args.verbose)

    with open(args.config) as f:
        config = yaml.safe_load(f)

    db_path = str(Path(config["database"]["path"]).expanduser())
    db = Database(db_path)

    nominatim_url = args.nominatim_url or (config.get("geocoding") or {}).get("nominatim_url")
    fetcher = make_fetcher(nominatim_url) if nominatim_url else fetch_from_nominatim

    try:
        counts = run_geocode(
            db,
            dry_run=args.dry_run,
            overwrite=args.overwrite,
            limit=args.limit,
            fetcher=fetcher,
        )
    finally:
        db.close()

    parts = [
        f"Geocoded: {counts['geocoded']}",
        f"Cached: {counts['cached']}",
        f"No result: {counts['no_result']}",
        f"Skipped (already set): {counts['skipped']}",
    ]
    if counts.get("errors"):
        parts.append(f"Errors: {counts['errors']}")
    print("   ".join(parts))
    if args.dry_run:
        print("(dry run — nothing written)")
    if counts.get("stopped_early"):
        print(
            "\nStopped early: 3 consecutive Nominatim errors — the service is likely "
            "rate-limiting this IP.\nWait a few hours before retrying. "
            "For large libraries, a local Nominatim instance (Docker) is more reliable."
        )


def cmd_import_contacts_birthdays(args: argparse.Namespace) -> None:
    """Import person birthdays from Apple Contacts into person_birthdays."""
    import yaml

    sys.path.insert(0, str(ROOT / "poller"))
    from db.db import Database
    from contacts_importer import run_import

    with open(args.config) as f:
        config = yaml.safe_load(f)

    db_path = str(Path(config["database"]["path"]).expanduser())
    photos_library_path = str(Path(config.get("photos_library", {}).get("path", "")).expanduser())
    photos_db_path = str(Path(photos_library_path) / "database" / "Photos.sqlite")

    if not config.get("photos_library", {}).get("path", ""):
        print("Error: photos_library.path is not configured in config.yml.", file=sys.stderr)
        sys.exit(1)
    if not Path(photos_db_path).exists():
        print(f"Error: Photos library not found at {photos_db_path}", file=sys.stderr)
        print("Check that photos_library.path is set correctly in config.yml.", file=sys.stderr)
        sys.exit(1)

    db = Database(db_path)
    try:
        result = run_import(
            db,
            photos_db_path,
            dry_run=args.dry_run,
            overwrite=args.overwrite,
        )
    except (PermissionError, TimeoutError) as exc:
        print(f"Error: {exc}", file=sys.stderr)
        db.close()
        sys.exit(1)

    db.close()

    parts = [
        f"Written: {result.written}",
        f"Skipped (same): {result.skipped_same}",
        f"Skipped (conflict): {result.skipped_conflict}",
        f"No birthday in Contacts: {result.no_birthday}",
    ]
    if result.overwritten:
        parts.append(f"Overwritten: {result.overwritten}")
    print("  ".join(parts))
    if args.dry_run:
        print("(dry run — nothing written)")


def cmd_all(args):
    """
    Run the full periodic maintenance sequence:
      1. scan --all              full Apple Photos index refresh
      2. poll                    catch recent Flickr uploads
      3. thumbs                  populate missing thumbnail paths
      4. sync-names-from-flickr  propagate Flickr renames → Apple Photos
      5. pipeline                metadata sync + auto-apply non-conflict proposals
      6. reconcile --fix         repair DB/Flickr mismatches
      7. sync-albums             push album memberships to Flickr
      8. sync-album-collections  sync folder hierarchy → Flickr Collections
      9. checkpoint              trim the WAL file
    Each step runs independently; a failure is logged and the sequence continues.
    Not included: 'scan --all' can be skipped with --skip-scan; 'bp poll --backfill'
    and 'bp scan' incremental are intentionally excluded (manual operations).
    """
    import logging
    from poller.bp_logging import configure

    configure("all", args.verbose)
    log = logging.getLogger("blue-pearmain.all")

    dry_run = getattr(args, "dry_run", False)
    if dry_run:
        log.info("all: dry-run mode — no external writes will be made")

    steps = [
        ("scan --all", cmd_scan, _step_args(args, all=True, dry_run=dry_run, days=None)),
        ("poll", cmd_poll, _step_args(args, backfill=False, dry_run=dry_run, days=None)),
        ("sync-names-from-flickr", cmd_sync_names_from_flickr, _step_args(args, dry_run=dry_run)),
        ("pipeline", cmd_pipeline, _step_args(args, limit=None, dry_run=dry_run)),
        (
            "reconcile",
            cmd_reconcile,
            _step_args(args, fix=not dry_run, apply_proposals=False, limit=None),
        ),
        ("sync-albums", cmd_sync_albums, _step_args(args, dry_run=dry_run, album=None, limit=None)),
        (
            "sync-album-collections",
            cmd_sync_album_collections,
            _step_args(args, dry_run=dry_run, remove=False, force=False),
        ),
    ]
    if not dry_run:
        steps.insert(2, ("thumbs", cmd_thumbs, _step_args(args, icloud=False, icloud_limit=50)))
        steps.append(("checkpoint", cmd_checkpoint, _step_args(args, mode="truncate")))

    include_legacy = getattr(args, "include_legacy", False)
    if include_legacy:
        # _dry_run_skip_fn: returns a no-op that logs SKIPPED and returns
        # immediately, without calling the real step or touching config/NAS.
        def _dry_run_skip_fn(step_name: str):
            def _skipped(step_args):
                log.info(
                    "all: %s SKIPPED (no dry-run support) -- continuing",
                    step_name,
                )

            return _skipped

        # "pipeline" is always present in the base steps list — StopIteration here is a programmer mistake
        pipeline_idx = next(i for i, (n, _, _) in enumerate(steps) if n == "pipeline")
        if dry_run:
            legacy_steps = [
                (
                    "index-legacy",
                    _dry_run_skip_fn("index-legacy"),
                    _step_args(
                        args,
                        library=None,
                        no_thumbnails=False,
                        limit=None,
                        no_cache=False,
                        refresh_cache=False,
                    ),
                ),
                (
                    "match-legacy --apply",
                    _dry_run_skip_fn("match-legacy --apply"),
                    _step_args(args, apply=True, library_uuid=None, csv=None),
                ),
            ]
        else:
            legacy_steps = [
                (
                    "index-legacy",
                    cmd_index_legacy,
                    _step_args(
                        args,
                        library=None,
                        no_thumbnails=False,
                        limit=None,
                        no_cache=False,
                        refresh_cache=False,
                    ),
                ),
                (
                    "match-legacy --apply",
                    cmd_match_legacy,
                    _step_args(args, apply=True, library_uuid=None, csv=None),
                ),
            ]
        for offset, step in enumerate(legacy_steps):
            steps.insert(pipeline_idx + 1 + offset, step)

    errors = []

    for name, fn, step_args in steps:
        if name == "match-legacy --apply" and "index-legacy" in errors:
            log.warning(
                "all: WARNING index-legacy failed — "
                "match-legacy --apply will use the last successfully indexed state"
            )
        log.info("all: -> %s", name)
        try:
            fn(step_args)
        except SystemExit as e:
            code = e.code if e.code is not None else 0
            if code != 0:
                log.warning("all: %s failed (exit %s) -- continuing", name, code)
                errors.append(name)
        except Exception as exc:
            log.warning("all: %s failed: %s -- continuing", name, exc)
            errors.append(name)

    if errors:
        log.warning("all: completed with %d error(s): %s", len(errors), ", ".join(errors))
    else:
        log.info("all: all steps complete")


def main():
    parser = argparse.ArgumentParser(
        prog="bp",
        description="Blue Pearmain — Flickr + Apple Photos review tool",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("--config", default="config/config.yml", help="Path to config.yml")
    parser.add_argument("--verbose", action="store_true")

    sub = parser.add_subparsers(dest="command", metavar="<command>")
    sub.required = True

    # stats
    p_stats = sub.add_parser("stats", help="Show photo counts by privacy state")
    p_stats.add_argument(
        "--oneliner", action="store_true", help="Single-line summary for watch/loop use"
    )

    # poll
    p_poll = sub.add_parser("poll", help="Poll Flickr for new/updated photos")
    p_poll.add_argument(
        "--backfill", action="store_true", help="Poll full history, not just recent"
    )
    p_poll.add_argument(
        "--days", type=int, default=None, help="Days to look back (with --backfill)"
    )
    p_poll.add_argument("--dry-run", action="store_true")

    # scan
    p_scan = sub.add_parser("scan", help="Scan Apple Photos library")
    p_scan.add_argument("--all", action="store_true", help="Scan entire library")
    p_scan.add_argument("--days", type=int, default=None)
    p_scan.add_argument("--dry-run", action="store_true")

    # thumbs
    p_thumbs = sub.add_parser("thumbs", help="Populate missing thumbnail paths")
    p_thumbs.add_argument(
        "--icloud",
        action="store_true",
        help="Trigger sequential AppleScript export for iCloud-only photos",
    )
    p_thumbs.add_argument(
        "--icloud-limit", type=int, default=50, help="Max iCloud exports per run (default: 50)"
    )

    # pipeline
    p_pipe = sub.add_parser("pipeline", help="Sync-metadata then auto-apply non-conflict proposals")
    p_pipe.add_argument(
        "--dry-run",
        action="store_true",
        help="Classify drift and count proposals; do not write or apply",
    )
    p_pipe.add_argument(
        "--limit",
        type=int,
        default=None,
        help="Cap number of proposals applied (default: unlimited)",
    )

    # reconcile
    p_rec = sub.add_parser("reconcile", help="Check DB state vs actual Flickr state")
    p_rec.add_argument("--fix", action="store_true", help="Re-push mismatches")
    p_rec.add_argument(
        "--apply-proposals",
        action="store_true",
        help="Apply pending non-conflict metadata proposals",
    )
    p_rec.add_argument(
        "--explain",
        action="store_true",
        help="Show current→desired→reason for each photo with pending drift (DB-only)",
    )
    p_rec.add_argument("--limit", type=int, default=None)

    # tag-writeback
    p_twb = sub.add_parser(
        "tag-writeback",
        help="Write pushed Flickr tags back to Photos.app as explicit keywords",
    )
    p_twb.add_argument("--dry-run", action="store_true")
    p_twb.add_argument("--limit", type=int, default=None)
    p_twb.add_argument("--verbose", action="store_true")
    p_twb.add_argument(
        "--source",
        choices=["pushed-tags", "proposed-tags"],
        default="pushed-tags",
    )

    # ui
    p_ui = sub.add_parser("ui", help="Start the review UI")
    p_ui.add_argument("--port", type=int, default=5173)
    p_ui.add_argument(
        "--host",
        default=None,
        help="Interface to bind (default: 127.0.0.1). Use 0.0.0.0 for LAN access.",
    )
    p_ui.add_argument("--debug", action="store_true")

    # sync-albums
    p_sync = sub.add_parser("sync-albums", help="Sync Apple Photos albums → Flickr photosets")
    p_sync.add_argument("--dry-run", action="store_true")
    p_sync.add_argument("--album", default=None, help="Sync only this album name")
    p_sync.add_argument("--limit", type=int, default=None)
    p_sync.add_argument(
        "--coalesce",
        action="store_true",
        help="Detect and merge duplicate Flickr photosets (same title, overlapping dates)",
    )
    p_sync.add_argument("--verbose", action="store_true")

    # sync-album-collections
    p_col = sub.add_parser(
        "sync-album-collections",
        help="Sync Apple Photos folder hierarchy → Flickr Collections (Pro account required)",
    )
    p_col.add_argument(
        "--dry-run", action="store_true", help="Show what would be synced without making API calls"
    )
    p_col.add_argument(
        "--remove",
        action="store_true",
        help="Remove Flickr Collections for folders deleted from Photos",
    )
    p_col.add_argument(
        "--force", action="store_true", help="Skip confirmation prompts when used with --remove"
    )
    p_col.add_argument("--verbose", action="store_true")

    # sync-names-from-flickr
    p_names = sub.add_parser(
        "sync-names-from-flickr",
        help="Sync Flickr photoset/Collection renames → Apple Photos albums/folders",
    )
    p_names.add_argument("--dry-run", action="store_true")
    p_names.add_argument("--verbose", action="store_true")

    # sync-metadata
    p_meta = sub.add_parser("sync-metadata", help="Pull Flickr metadata → Apple Photos")
    p_meta.add_argument(
        "--dry-run", action="store_true", help="Compare and log; do not write to Photos or DB"
    )
    p_meta.add_argument("--limit", type=int, default=None)
    p_meta.add_argument("--photo-id", type=int, default=None, help="Process only this DB photo_id")
    p_meta.add_argument(
        "--conflicts-only",
        action="store_true",
        help="Detect and record conflicts only; skip Photos writes",
    )
    p_meta.add_argument(
        "--force", action="store_true", help="Process all photos, ignoring meta_last_harmonized_at"
    )
    p_meta.add_argument("--verbose", action="store_true")

    # link-orphans
    p_link = sub.add_parser(
        "link-orphans",
        help="Merge split Photos-only / Flickr-only records that share a capture timestamp",
    )
    p_link.add_argument("--dry-run", action="store_true", help="Find pairs but do not write to DB")
    p_link.add_argument(
        "--limit", type=int, default=None, help="Max pairs to process (default: all)"
    )

    # all
    p_all = sub.add_parser(
        "all",
        help="Full maintenance run: scan --all, poll, thumbs, pipeline, reconcile --fix, sync-albums, sync-album-collections, checkpoint",
    )
    p_all.add_argument(
        "--dry-run",
        action="store_true",
        help="Run all stages read-only: no external writes. "
        "Thumbs and checkpoint are skipped; reconcile runs without --fix.",
    )
    p_all.add_argument(
        "--include-legacy",
        action="store_true",
        help="Also run index-legacy (full authoritative NAS refresh) and "
        "match-legacy --apply after the pipeline step.",
    )

    # install-daemons
    p_install = sub.add_parser(
        "install-daemons",
        help="Install launchd agents to ~/Library/LaunchAgents",
    )
    p_install.add_argument(
        "--dry-run", action="store_true", help="Show what would be installed without writing files"
    )

    # uninstall-daemons
    p_uninstall = sub.add_parser(
        "uninstall-daemons",
        help="Remove installed launchd agents from ~/Library/LaunchAgents",
    )
    p_uninstall.add_argument(
        "--dry-run", action="store_true", help="Show what would be removed without deleting files"
    )

    # doctor
    p_doc = sub.add_parser(
        "doctor",
        help="Preflight check: config, environment, and DB. Passing means startup is likely to succeed; it is not a guarantee of successful execution.",
    )
    p_doc.add_argument(
        "--check-flickr",
        action="store_true",
        help="Make a live Flickr API call to verify credentials (requires network)",
    )

    # migrate
    p_mig = sub.add_parser(
        "migrate",
        help="Apply all pending DB migrations in order (safe to re-run; each migration is idempotent).",
    )
    p_mig.add_argument(
        "--dry-run",
        action="store_true",
        help="Show what would be applied without modifying the DB",
    )
    p_mig.add_argument(
        "--baseline",
        action="store_true",
        help="Mark all pending migrations as applied WITHOUT running their DDL "
        "(resync schema_migrations on a DB whose schema already exists)",
    )

    # status
    p_status = sub.add_parser(
        "status",
        help="Operational health: daemon state, queue sizes, pending proposals",
    )

    # checkpoint
    p_ckpt = sub.add_parser("checkpoint", help="Run a WAL checkpoint to shrink the WAL file")
    p_ckpt.add_argument(
        "--mode",
        default="truncate",
        choices=["truncate", "passive", "full", "restart"],
        help="Checkpoint mode (default: truncate)",
    )

    # deduplicator
    p_dedup = sub.add_parser(
        "deduplicator",
        help="Find and classify duplicate photos (dry-run by default)",
    )
    p_dedup.add_argument("--write", action="store_true", help="Write results to the DB")
    p_dedup.add_argument(
        "--confirm", action="store_true", help="Delete Flickr discards (requires --write)"
    )
    p_dedup.add_argument(
        "--dry-run", action="store_true", help="Report without writing (default behaviour)"
    )
    p_dedup.add_argument("--flickr", action="store_true", help="Detect Flickr re-upload duplicates")
    p_dedup.add_argument(
        "--limit",
        type=int,
        default=None,
        metavar="N",
        help="Maximum pairs to write (recommended for first live runs)",
    )
    p_dedup.add_argument(
        "--verbose", "-v", action="store_true", help="Show all uncertain pairs in report"
    )
    p_dedup.add_argument(
        "--prune",
        action="store_true",
        help="Clean up zombie groups and stale photo_count values (dry-run by default)",
    )
    p_dedup.add_argument(
        "--apply", action="store_true", help="Execute --prune changes (default is dry-run)"
    )

    # prune-proposals
    p_prune = sub.add_parser(
        "prune-proposals",
        help="Supersede spurious managed-tag proposals and delete old resolved proposals",
    )
    p_prune.add_argument(
        "--older-than",
        type=int,
        default=90,
        metavar="N",
        help="Delete resolved proposals older than N days (default: 90)",
    )
    p_prune.add_argument(
        "--dry-run", action="store_true", help="Report counts without modifying the DB"
    )

    # export
    p_export = sub.add_parser(
        "export",
        help="Export DB state to portable NDJSON (photos.ndjson, zones.json, manifest.json)",
    )
    p_export.add_argument(
        "--out",
        default=None,
        help="Output directory (default: ./bp-export-YYYY-MM-DD/)",
    )

    # index-legacy
    p_idxleg = sub.add_parser(
        "index-legacy",
        help="Index a legacy (migrated iPhoto/Photos 4) library into curator.db",
    )
    p_idxleg.add_argument(
        "--library",
        default=None,
        help="Path to the .photoslibrary bundle (overrides config legacy_library.path)",
    )
    p_idxleg.add_argument(
        "--no-thumbnails", action="store_true", help="Skip copying thumbnails into BP's cache"
    )
    p_idxleg.add_argument(
        "--limit",
        type=int,
        default=None,
        metavar="N",
        help="Index only the first N assets (non-authoritative: no deletions)",
    )
    p_idxleg.add_argument(
        "--no-cache",
        action="store_true",
        help="Read the library in place instead of the local DB cache",
    )
    p_idxleg.add_argument(
        "--refresh-cache", action="store_true", help="Force a rebuild of the local DB cache"
    )

    # match-legacy
    p_mlp = sub.add_parser(
        "match-legacy",
        help="Match legacy assets to Flickr-only candidate_public photos; preview by default, --apply to reclassify",
    )
    p_mlp.add_argument(
        "--library-uuid",
        default=None,
        help="Which indexed library to match against (default: the most recently indexed)",
    )
    p_mlp.add_argument(
        "--csv",
        default=None,
        metavar="PATH",
        help="Also write the full tiered report to a CSV file",
    )
    p_mlp.add_argument(
        "--apply",
        action="store_true",
        help="Reclassify confident (and all-people ambiguous) matches out of the review queue",
    )

    # legacy-report
    p_lrep = sub.add_parser(
        "legacy-report",
        help="Report legacy assets with no Flickr counterpart (upload candidates)",
    )
    p_lrep.add_argument(
        "--library-uuid",
        default=None,
        help="Which indexed library to report on (default: most recently indexed)",
    )
    p_lrep.add_argument(
        "--csv",
        default=None,
        metavar="PATH",
        help="Write unmatched assets to a CSV file",
    )
    p_lrep.set_defaults(func=cmd_legacy_report)

    # upload-legacy-unmatched
    p_ulm = sub.add_parser(
        "upload-legacy-unmatched",
        help="Upload legacy-only assets (not yet on Flickr) directly to Flickr (#230)",
    )
    p_ulm.add_argument(
        "--dry-run",
        action="store_true",
        help="Classify and report without uploading or writing to the DB",
    )
    p_ulm.add_argument(
        "--limit",
        type=int,
        default=None,
        metavar="N",
        help="Upload at most N assets (for incremental rollout)",
    )
    p_ulm.add_argument(
        "--library-uuid",
        default=None,
        help=(
            "Which indexed library to draw from (default: the most recently indexed). "
            "Required when more than one legacy library has been indexed — run "
            "'bp legacy-report' to see library UUIDs, or query "
            "'SELECT library_uuid, display_name FROM legacy_libraries' directly."
        ),
    )
    p_ulm.add_argument(
        "--library",
        default=None,
        metavar="PATH",
        help=(
            "Path to the .photoslibrary bundle (overrides config legacy_library.path). "
            "The config key legacy_library.path was introduced by bp index-legacy; "
            "see config.example.yml."
        ),
    )
    p_ulm.set_defaults(func=cmd_upload_legacy_unmatched)

    # geocode
    p_geo = sub.add_parser(
        "geocode",
        help="Backfill place data from Nominatim for photos that have GPS coordinates",
    )
    p_geo.add_argument(
        "--dry-run",
        action="store_true",
        help="Report counts without writing anything",
    )
    p_geo.add_argument(
        "--overwrite",
        action="store_true",
        help="Replace existing place data with Nominatim results (default: fill gaps only)",
    )
    p_geo.add_argument(
        "--limit",
        type=int,
        default=None,
        metavar="N",
        help="Stop after N API call attempts (cache hits do not count; errors do count)",
    )
    p_geo.add_argument(
        "--nominatim-url",
        default=None,
        metavar="URL",
        help=(
            "Nominatim reverse geocoding endpoint "
            "(default: https://nominatim.openstreetmap.org/reverse). "
            "Override to use a local Docker instance, e.g. http://localhost:8080/reverse"
        ),
    )
    p_geo.add_argument(
        "--check-nominatim",
        action="store_true",
        help=(
            "Check whether the Nominatim endpoint is reachable and exit. "
            "Exits 0 if reachable, 1 if not. No --config required."
        ),
    )

    # import-contacts-birthdays
    p_icb = sub.add_parser(
        "import-contacts-birthdays",
        help="Import person birthdays from Apple Contacts into person_birthdays",
    )
    p_icb.add_argument(
        "--dry-run",
        action="store_true",
        help="Show what would be written without writing anything",
    )
    p_icb.add_argument(
        "--overwrite",
        action="store_true",
        help="Replace existing person_birthdays entries with Contacts data",
    )

    args = parser.parse_args()

    # Attach config/verbose to all subcommands
    if not hasattr(args, "oneliner"):
        args.oneliner = False
    if not hasattr(args, "dry_run"):
        args.dry_run = False
    if not hasattr(args, "all"):
        args.all = False
    if not hasattr(args, "days"):
        args.days = None
    if not hasattr(args, "backfill"):
        args.backfill = False
    if not hasattr(args, "fix"):
        args.fix = False
    if not hasattr(args, "apply_proposals"):
        args.apply_proposals = False
    if not hasattr(args, "explain"):
        args.explain = False
    if not hasattr(args, "limit"):
        args.limit = None
    if not hasattr(args, "port"):
        args.port = 5173
    if not hasattr(args, "debug"):
        args.debug = False
    if not hasattr(args, "album"):
        args.album = None
    if not hasattr(args, "remove"):
        args.remove = False
    if not hasattr(args, "force"):
        args.force = False
    if not hasattr(args, "photo_id"):
        args.photo_id = None
    if not hasattr(args, "conflicts_only"):
        args.conflicts_only = False
    if not hasattr(args, "mode"):
        args.mode = "truncate"
    if not hasattr(args, "check_flickr"):
        args.check_flickr = False
    if not hasattr(args, "older_than"):
        args.older_than = 90
    if not hasattr(args, "write"):
        args.write = False
    if not hasattr(args, "confirm"):
        args.confirm = False
    if not hasattr(args, "prune"):
        args.prune = False
    if not hasattr(args, "apply"):
        args.apply = False
    if not hasattr(args, "out"):
        args.out = None
    if not hasattr(args, "library"):
        args.library = None
    if not hasattr(args, "no_thumbnails"):
        args.no_thumbnails = False
    if not hasattr(args, "no_cache"):
        args.no_cache = False
    if not hasattr(args, "refresh_cache"):
        args.refresh_cache = False
    if not hasattr(args, "library_uuid"):
        args.library_uuid = None
    if not hasattr(args, "csv"):
        args.csv = None
    if not hasattr(args, "overwrite"):
        args.overwrite = False

    dispatch = {
        "pipeline": cmd_pipeline,
        "stats": cmd_stats,
        "poll": cmd_poll,
        "scan": cmd_scan,
        "thumbs": cmd_thumbs,
        "reconcile": cmd_reconcile,
        "tag-writeback": cmd_tag_writeback,
        "ui": cmd_ui,
        "sync-albums": cmd_sync_albums,
        "sync-album-collections": cmd_sync_album_collections,
        "sync-names-from-flickr": cmd_sync_names_from_flickr,
        "sync-metadata": cmd_sync_metadata,
        "link-orphans": cmd_link_orphans,
        "checkpoint": cmd_checkpoint,
        "all": cmd_all,
        "install-daemons": cmd_install_daemons,
        "uninstall-daemons": cmd_uninstall_daemons,
        "doctor": cmd_doctor,
        "migrate": cmd_migrate,
        "status": cmd_status,
        "deduplicator": cmd_deduplicator,
        "prune-proposals": cmd_prune_proposals,
        "export": cmd_export,
        "index-legacy": cmd_index_legacy,
        "match-legacy": cmd_match_legacy,
        "legacy-report": cmd_legacy_report,
        "upload-legacy-unmatched": cmd_upload_legacy_unmatched,
        "geocode": cmd_geocode,
        "import-contacts-birthdays": cmd_import_contacts_birthdays,
    }
    dispatch[args.command](args)


if __name__ == "__main__":
    main()