visionpack 0.0.1__py3-none-any.whl

visionpack/__init__.py

@@ -0,0 +1,5 @@
+"""VisionPack public Python API."""
+
+from visionpack.core.project import Dataset, Project
+
+__all__ = ["Dataset", "Project"]

visionpack/__main__.py

@@ -0,0 +1,4 @@
+from visionpack.cli.main import main
+
+if __name__ == "__main__":
+    main()

visionpack/cli/__init__.py

@@ -0,0 +1 @@
+"""Command line interface package."""

visionpack/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Individual CLI command handlers."""

visionpack/cli/commands/annotate.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import argparse
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("annotate", help="Prepare or ingest annotation batches")
+    nested = parser.add_subparsers(dest="annotate_command", required=True)
+
+    prepare = nested.add_parser("prepare", help="Prepare images for annotation")
+    prepare.add_argument("--target", required=True)
+    prepare.set_defaults(func=run_scaffold)
+
+    ingest = nested.add_parser("ingest", help="Ingest reviewed annotations")
+    ingest.add_argument("source")
+    ingest.add_argument("--format", required=True)
+    ingest.set_defaults(func=run_scaffold)
+
+    review = nested.add_parser("review", help="Review annotations")
+    review.set_defaults(func=run_scaffold)
+
+
+def run_scaffold(args: argparse.Namespace) -> int:
+    print("vp annotate is scaffolded but not implemented in this MVP slice yet.")
+    return 1

visionpack/cli/commands/diff.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import argparse
+import json
+
+from visionpack.core.project import Project
+from visionpack.diff import diff_snapshots
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("diff", help="Diff two snapshots")
+    parser.add_argument("left")
+    parser.add_argument("right")
+    parser.add_argument("--json", action="store_true", help="Print JSON")
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    result = diff_snapshots(project, args.left, args.right)
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return 0
+    print(f"Diff {args.left} -> {args.right}")
+    for key in (
+        "assets_added",
+        "assets_removed",
+        "annotations_added",
+        "annotations_removed",
+        "annotations_modified",
+        "classes_added",
+        "classes_removed",
+    ):
+        print(f"{key}: {len(result[key])}")
+    print(f"splits_changed: {result['splits_changed']}")
+    return 0

visionpack/cli/commands/export.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from visionpack.core.project import Project
+from visionpack.formats.classification import export_imagefolder
+from visionpack.formats.coco import export_coco
+from visionpack.formats.yolo import export_yolo
+from visionpack.progress import cli_progress
+from visionpack.snapshot import open_snapshot
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("export", help="Export a dataset")
+    parser.add_argument("--format", required=True, choices=["yolo", "coco", "imagefolder"], help="Output format")
+    parser.add_argument("--output", required=True, help="Output directory")
+    parser.add_argument(
+        "--split",
+        nargs="?",
+        const="default",
+        default=None,
+        help="Export into train/val/test using a split (defaults to 'default' when given without a value)",
+    )
+    parser.add_argument(
+        "--snapshot",
+        help="Export the dataset as it was at this snapshot version (e.g. v2) instead of the current state",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    if args.snapshot:
+        project = open_snapshot(project, args.snapshot)
+    output = Path(args.output)
+    with cli_progress(f"Exporting {args.format}") as callback:
+        if args.format == "coco":
+            summary = export_coco(project, output, split_id=args.split, progress=callback)
+            detail = f"{summary['images']} images, {summary['annotations']} annotations, {summary['objects']} objects"
+            message = f"Exported COCO dataset to {output.resolve()}: {detail}"
+        elif args.format == "imagefolder":
+            summary = export_imagefolder(project, output, split_id=args.split, progress=callback)
+            message = f"Exported ImageFolder dataset to {output.resolve()}: {summary['images']} images"
+        else:
+            summary = export_yolo(project, output, split_id=args.split, progress=callback)
+            detail = f"{summary['images']} images, {summary['labels']} label files, {summary['objects']} objects"
+            message = f"Exported YOLO dataset to {output.resolve()}: {detail}"
+    print(message)
+
+    if args.split:
+        sets = ", ".join(f"{name}={count}" for name, count in summary.get("sets", {}).items())
+        print(f"Split {args.split!r}: {sets}")
+        if summary.get("skipped"):
+            print(f"Skipped {summary['skipped']} assets not assigned to any set in split {args.split!r}")
+    return 0

visionpack/cli/commands/fsck.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import argparse
+
+from visionpack.core.project import Project
+from visionpack.fsck import run_fsck
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("fsck", help="Check index <-> object-store integrity")
+    parser.add_argument(
+        "--deep",
+        action="store_true",
+        help="Re-hash every stored object to detect silent corruption (reads all bytes)",
+    )
+    parser.add_argument(
+        "--no-orphans",
+        action="store_true",
+        help="Skip the scan for unreferenced objects in the store",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    report = run_fsck(project, deep=args.deep, check_orphans=not args.no_orphans)
+    mode = "deep" if args.deep else "quick"
+    print(
+        f"fsck ({mode}): checked {report.checked_assets} assets, {report.checked_objects} objects "
+        f"-> {len(report.errors)} errors, {len(report.warnings)} warnings"
+    )
+    for issue in report.issues[:50]:
+        print(f"[{issue.severity}] {issue.code}: {issue.message}")
+    if len(report.issues) > 50:
+        print(f"... {len(report.issues) - 50} more")
+    if report.ok:
+        print("OK: dataset is consistent." if not report.warnings else "OK (with warnings).")
+    return 0 if report.ok else 1

visionpack/cli/commands/import_.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from visionpack.core.errors import VisionPackError
+from visionpack.core.lock import project_lock
+from visionpack.core.project import Project
+from visionpack.formats.classification import ImageFolderImporter
+from visionpack.formats.coco import CocoImporter
+from visionpack.formats.yolo import YoloImporter
+from visionpack.progress import cli_progress
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("import", help="Import a dataset")
+    parser.add_argument("source", help="Input dataset path (YOLO/ImageFolder root, or COCO annotation JSON)")
+    parser.add_argument("--format", required=True, choices=["yolo", "coco", "imagefolder"], help="Input format")
+    parser.add_argument("--images", help="Image directory (required for --format coco)")
+    parser.add_argument(
+        "--task",
+        default=None,
+        choices=["detection", "classification", "segmentation", "keypoints"],
+        help="Override project task",
+    )
+    parser.add_argument("--copy", default="ingest", choices=["copy", "move", "hardlink", "reference", "ingest"], help="Asset copy mode")
+    parser.add_argument("--name", help="Name to record this source under in visionpack.yaml")
+    parser.add_argument(
+        "--no-record",
+        action="store_true",
+        help="Do not add this import as a source in visionpack.yaml (use for one-off/throwaway imports)",
+    )
+    parser.add_argument("--class-map", help="Reserved for explicit class mapping files")
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    with project_lock(project.root):
+        return _run_locked(project, args)
+
+
+def _run_locked(project: Project, args: argparse.Namespace) -> int:
+    if args.task and project.manifest.task != args.task:
+        project.manifest.task = args.task
+        project.save_manifest()
+
+    if args.format == "coco":
+        if not args.images:
+            raise VisionPackError("--images is required when importing COCO (the directory holding the image files)")
+        importer = CocoImporter(project, Path(args.source), Path(args.images), copy_mode=args.copy)
+        label = "COCO"
+    elif args.format == "imagefolder":
+        importer = ImageFolderImporter(project, Path(args.source), copy_mode=args.copy)
+        label = "ImageFolder"
+    else:
+        importer = YoloImporter(project, Path(args.source), copy_mode=args.copy)
+        label = "YOLO"
+
+    with cli_progress(f"Importing {label}") as callback:
+        summary = importer.run(progress=callback)
+
+    print(
+        f"Imported {label} dataset: "
+        f"{summary.assets} assets, {summary.annotations} annotations, {summary.objects} objects"
+    )
+    if summary.orphan_labels:
+        print(f"Warnings: {summary.orphan_labels} label files had no matching image")
+    if summary.classes_added:
+        print("Classes were discovered and written to visionpack.yaml")
+
+    if not args.no_record:
+        recorded = _record_source(project, args)
+        if recorded:
+            print(f"Recorded source {recorded!r} in visionpack.yaml (re-pull later with `vp sync --source {recorded}`)")
+
+    if summary.failures:
+        _report_failures(summary.failures)
+        return 1
+    return 0
+
+
+def _report_failures(failures: list) -> None:
+    print(f"Skipped {len(failures)} unreadable/corrupt image(s):")
+    for failure in failures[:20]:
+        print(f"  - {failure.path}: {failure.error}")
+    if len(failures) > 20:
+        print(f"  ... {len(failures) - 20} more")
+
+
+def _record_source(project: Project, args: argparse.Namespace) -> str | None:
+    """Append this import as a declared source so the manifest stays the source of
+    truth and the data can be re-pulled with `vp sync`. Skips silently when an
+    equivalent source is already declared (re-importing the same path)."""
+    entry = _source_entry(project, args)
+    # Dedupe on location identity only: a reloaded source carries pydantic default
+    # keys (class_map/credentials={}) the fresh entry lacks, so compare the parts
+    # that actually identify where the data comes from.
+    identity = _identity(entry)
+    if any(_identity(declared) == identity for declared in project.manifest.sources):
+        return None
+    # name first for readability in the manifest
+    entry = {"name": _unique_name(project, args), **entry}
+    project.manifest.sources.append(entry)
+    project.save_manifest()
+    return entry["name"]
+
+
+def _identity(source: dict) -> tuple:
+    return (source.get("format"), source.get("root"), source.get("images"), source.get("labels"))
+
+
+def _source_entry(project: Project, args: argparse.Namespace) -> dict[str, str]:
+    if args.format == "coco":
+        return {
+            "format": "coco",
+            "images": _rel(project, args.images),
+            "labels": _rel(project, args.source),
+            "copy": args.copy,
+        }
+    fmt = "imagefolder" if args.format == "imagefolder" else "yolo"
+    return {"format": fmt, "root": _rel(project, args.source), "copy": args.copy}
+
+
+def _rel(project: Project, path: str) -> str:
+    """A project-relative, posix-style location, so the manifest stays portable."""
+    resolved = Path(path).resolve()
+    try:
+        rel = Path(os.path.relpath(resolved, project.root)).as_posix()
+    except ValueError:  # different drive on Windows
+        return resolved.as_posix()
+    return rel if rel.startswith((".", "/")) else f"./{rel}"
+
+
+def _unique_name(project: Project, args: argparse.Namespace) -> str:
+    base = Path(args.name or Path(args.source).stem or args.format).name or args.format
+    taken = {source.get("name") for source in project.manifest.sources}
+    if base not in taken:
+        return base
+    suffix = 2
+    while f"{base}-{suffix}" in taken:
+        suffix += 1
+    return f"{base}-{suffix}"

visionpack/cli/commands/init.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import argparse
+
+from visionpack.core.project import Project
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("init", help="Initialize a VisionPack project")
+    parser.add_argument("path", nargs="?", default=".", help="Project directory")
+    parser.add_argument("--name", help="Dataset name")
+    parser.add_argument(
+        "--task",
+        default="detection",
+        choices=["detection", "classification", "segmentation", "keypoints"],
+        help="Computer vision task",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.init(args.path, name=args.name, task=args.task)
+    print(f"Initialized VisionPack dataset at {project.root}")
+    print(f"Manifest: {project.manifest_path}")
+    return 0

visionpack/cli/commands/pack.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from visionpack.core.errors import VisionPackError
+from visionpack.core.project import Project
+from visionpack.packing import pack_archive, pack_training
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("pack", help="Pack a dataset for archive, training, or review")
+    parser.add_argument("--profile", required=True, help="Pack profile name (from visionpack.yaml)")
+    parser.add_argument("--output", help="Output path (archive file, or directory for WebDataset shards)")
+    parser.add_argument(
+        "--split",
+        nargs="?",
+        const="default",
+        default=None,
+        help="For training packs: emit per-set shards from this split (default 'default' when given without a value)",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    profile = project.manifest.pack_profiles.get(args.profile)
+    if profile is None:
+        raise VisionPackError(f"Pack profile not found in visionpack.yaml: {args.profile}")
+
+    fmt = str(profile.get("format", "tar.zst"))
+    output = Path(args.output) if args.output else None
+
+    if fmt == "webdataset":
+        summary = pack_training(project, output=output, profile_name=args.profile, split_id=args.split)
+        sets = ", ".join(f"{name}={count}" for name, count in summary.sets.items())
+        print(
+            f"Packed WebDataset to {summary.path} "
+            f"({summary.shards} shards, {summary.samples} samples; {sets})"
+        )
+        if summary.skipped:
+            print(f"Skipped {summary.skipped} assets not assigned to any set in split {args.split!r}")
+        return 0
+
+    if fmt in {"tar", "tar.zst"}:
+        summary = pack_archive(project, output=output, profile_name=args.profile)
+        print(
+            f"Packed archive: {summary.path} "
+            f"({summary.format}, {summary.files} files, {summary.assets} assets, {summary.size_bytes} bytes)"
+        )
+        return 0
+
+    raise VisionPackError(
+        f"Pack profile {args.profile!r} uses unsupported format {fmt!r}. "
+        "Supported: 'webdataset' (training), 'tar'/'tar.zst' (archive)."
+    )

visionpack/cli/commands/snapshot.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import argparse
+import json
+
+from visionpack.core.lock import project_lock
+from visionpack.core.project import Project
+from visionpack.snapshot import create_snapshot, list_snapshots, load_snapshot
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("snapshot", help="Manage dataset snapshots")
+    nested = parser.add_subparsers(dest="snapshot_command", required=True)
+
+    create = nested.add_parser("create", help="Create a snapshot")
+    create.add_argument("-m", "--message", required=True, help="Snapshot message")
+    create.set_defaults(func=run_create)
+
+    list_parser = nested.add_parser("list", help="List snapshots")
+    list_parser.set_defaults(func=run_list)
+
+    show = nested.add_parser("show", help="Show snapshot details")
+    show.add_argument("version", help="Snapshot version, e.g. v1")
+    show.set_defaults(func=run_show)
+
+
+def run_create(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    with project_lock(project.root):
+        snapshot = create_snapshot(project, args.message)
+    print(f"Created snapshot {snapshot['version']}: {snapshot['message']}")
+    return 0
+
+
+def run_list(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    snapshots = list_snapshots(project)
+    for item in snapshots:
+        stats = item.get("stats", {})
+        counts = f"{stats.get('assets', '?')} imgs, {stats.get('objects', '?')} objs"
+        print(f"{item['version']:<5} {item['created_at']}  {counts:<20}  {item['message']}")
+    if not snapshots:
+        print("No snapshots. Create one with: vp snapshot create -m <message>")
+    return 0
+
+
+def run_show(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    print(json.dumps(load_snapshot(project, args.version), indent=2, sort_keys=True))
+    return 0

visionpack/cli/commands/split.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import argparse
+
+from visionpack.core.lock import project_lock
+from visionpack.core.project import Project
+from visionpack.split import create_split, lock_split
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("split", help="Create and manage deterministic, versioned splits")
+    nested = parser.add_subparsers(dest="split_command", required=True)
+
+    create = nested.add_parser("create", help="Create a deterministic train/val/test split")
+    create.add_argument("--train", type=float, default=0.8, help="Train fraction (default 0.8)")
+    create.add_argument("--val", type=float, default=0.1, help="Validation fraction (default 0.1)")
+    create.add_argument("--test", type=float, default=0.1, help="Test fraction (default 0.1)")
+    create.add_argument(
+        "--strategy",
+        choices=["stratified", "random", "hash"],
+        default="stratified",
+        help="stratified=balanced per class (default), random=exact global ratios, hash=stable as data grows",
+    )
+    create.add_argument("--by", choices=["class"], default="class", help="Stratification key (stratified strategy)")
+    create.add_argument("--seed", type=int, default=0, help="Seed mixed into the content hash for reproducibility")
+    create.add_argument("--id", dest="split_id", default="default", help="Split id (default: 'default')")
+    create.add_argument("--force", action="store_true", help="Overwrite even if the split is locked")
+    create.set_defaults(func=run_create)
+
+    lock = nested.add_parser("lock", help="Lock a split so it cannot be changed")
+    lock.add_argument("--id", dest="split_id", default="default", help="Split id (default: 'default')")
+    lock.set_defaults(func=run_lock)
+
+    list_parser = nested.add_parser("list", help="List splits")
+    list_parser.set_defaults(func=run_list)
+
+    show = nested.add_parser("show", help="Show set sizes for a split")
+    show.add_argument("--id", dest="split_id", default="default", help="Split id (default: 'default')")
+    show.set_defaults(func=run_show)
+
+
+def run_create(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    with project_lock(project.root):
+        split = create_split(
+            project,
+            train=args.train,
+            val=args.val,
+            test=args.test,
+            strategy=args.strategy,
+            seed=args.seed,
+            split_id=args.split_id,
+            by=args.by,
+            force=args.force,
+        )
+    sizes = ", ".join(f"{name}={len(ids)}" for name, ids in split.sets.items())
+    print(f"Created split {split.id!r} (strategy={split.strategy}, seed={args.seed}): {sizes}")
+    return 0
+
+
+def run_lock(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    with project_lock(project.root):
+        split = lock_split(project, args.split_id)
+    print(f"Locked split {split.id!r}. It will be captured as-is in snapshots.")
+    return 0
+
+
+def run_list(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    splits = project.index.splits()
+    for split in splits:
+        sizes = ", ".join(f"{name}={len(ids)}" for name, ids in split.sets.items())
+        lock = " [locked]" if split.locked else ""
+        print(f"{split.id}  strategy={split.strategy}{lock}  {sizes}")
+    if not splits:
+        print("No splits. Create one with: vp split create")
+    return 0
+
+
+def run_show(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    split = next((item for item in project.index.splits() if item.id == args.split_id), None)
+    if split is None:
+        print(f"No split named {args.split_id!r}. Create one with: vp split create")
+        return 1
+    print(f"Split {split.id!r}  strategy={split.strategy}  locked={split.locked}")
+    for name, ids in split.sets.items():
+        print(f"  {name}: {len(ids)} images")
+    return 0

visionpack/cli/commands/stats.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import argparse
+import json
+
+from visionpack.core.project import Project
+from visionpack.stats import collect_stats, split_breakdown
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("stats", help="Show dataset statistics")
+    parser.add_argument("--by", choices=["class", "split"], help="Focus output on one dimension")
+    parser.add_argument("--json", action="store_true", help="Print JSON")
+    parser.add_argument("--html", help="Reserved for HTML reports")
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+    stats = collect_stats(project)
+    if args.json:
+        print(json.dumps(stats, indent=2, sort_keys=True))
+        return 0
+    if args.by == "class":
+        for class_id, count in stats["class_distribution"].items():
+            print(f"{class_id}: {count}")
+        return 0
+    if args.by == "split":
+        breakdown = split_breakdown(project)
+        if breakdown is None:
+            print("No split named 'default'. Create one with: vp split create")
+            return 0
+        lock = " [locked]" if breakdown["locked"] else ""
+        print(f"Split 'default' (strategy={breakdown['strategy']}){lock}")
+        for set_name, info in breakdown["sets"].items():
+            print(f"{set_name}: {info['images']} images, {info['objects']} objects")
+            for class_id, count in info["class_distribution"].items():
+                print(f"  {class_id}: {count}")
+        return 0
+    print(f"Images: {stats['assets']}")
+    print(f"Annotations: {stats['annotations']}")
+    print(f"Objects: {stats['objects']}")
+    print(f"Classes: {stats['classes']}")
+    print(f"Images without annotations: {stats['images_without_annotations']}")
+    print(f"Average labels per image: {stats['avg_labels_per_image']}")
+    return 0

visionpack/cli/commands/sync.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import argparse
+
+from visionpack.core.lock import project_lock
+from visionpack.core.project import Project
+from visionpack.progress import cli_progress
+from visionpack.sources import plan_sources, sync_sources
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "sync",
+        help="Reconcile the dataset with the sources declared in visionpack.yaml",
+    )
+    parser.add_argument("--source", help="Sync only this source (by name); default syncs all")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report what each source would ingest (found/matched/unmatched) without writing",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project = Project.open(".")
+
+    if args.dry_run:
+        plans = plan_sources(project, args.source)
+        for plan in plans:
+            print(f"[{plan.name}] {plan.format}")
+            print(f"  images: {plan.images_uri}")
+            if plan.labels_uri:
+                print(f"  labels: {plan.labels_uri}")
+            print(
+                f"  found {plan.images_found} images, {plan.labels_found} labels"
+                f" -> {plan.matched} matched"
+            )
+            if plan.images_without_label:
+                print(f"  {plan.images_without_label} images without a label")
+            if plan.labels_without_image:
+                print(f"  {plan.labels_without_image} labels without an image")
+            print(f"  classes: {', '.join(plan.class_names) if plan.class_names else '(none discovered)'}")
+        return 0
+
+    with project_lock(project.root):
+        summaries = sync_sources(project, args.source, progress_factory=cli_progress)
+    total_added = 0
+    total_failures = 0
+    for summary in summaries:
+        total_added += summary.assets_added
+        total_failures += len(summary.failures)
+        print(
+            f"[{summary.name}] +{summary.assets_added} new assets "
+            f"({summary.assets_existing} already present), "
+            f"{summary.annotations} annotations, {summary.objects} objects"
+        )
+        if summary.classes_added:
+            print(f"  {summary.classes_added} new classes merged into visionpack.yaml")
+        if summary.images_without_label:
+            print(f"  warning: {summary.images_without_label} images had no matching label")
+        if summary.labels_without_image:
+            print(f"  warning: {summary.labels_without_image} labels had no matching image")
+        if summary.failures:
+            print(f"  skipped {len(summary.failures)} unreadable/corrupt image(s):")
+            for failure in summary.failures[:10]:
+                print(f"    - {failure.path}: {failure.error}")
+            if len(summary.failures) > 10:
+                print(f"    ... {len(summary.failures) - 10} more")
+    print(f"Synced {len(summaries)} source(s): {total_added} new assets total.")
+    return 1 if total_failures else 0