gitlytics 0.2.0__tar.gz → 0.2.2__tar.gz

{gitlytics-0.2.0 → gitlytics-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlytics
-Version: 0.2.0
+Version: 0.2.2
 Summary: Monitor and automate your GitHub repository traffic analytics.
 Author-email: Ameya Chopade <ameyaccod171@gmail.com>
 License: Apache-2.0

{gitlytics-0.2.0 → gitlytics-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitlytics"
-version = "0.2.0"
+version = "0.2.2"
 description = "Monitor and automate your GitHub repository traffic analytics."
 readme = "README.md"
 requires-python = ">=3.9"

{gitlytics-0.2.0 → gitlytics-0.2.2}/src/gitlytics/__init__.py

@@ -5,10 +5,11 @@ The public API for the gitlytics package.
 import os
 import logging
 import json
+from pathlib import Path
 
 # Single source of truth for the package version.
 # Mirrors the version in pyproject.toml — keep them in sync.
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 __all__ = ["fetch_traffic", "sync", "serve_dashboard", "__version__"]
 
@@ -22,6 +23,44 @@ logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
 
+_VALID_METRICS = {
+    "views", "clones", "referrers", "paths", "stars", "forks",
+    "language", "topics", "watchers_count", "pushed_at",
+    "created_at", "open_issues_count",
+}
+
+
+def _coerce_metrics(metrics):
+    # Accept list, tuple, or set. Reject strings, ints, dicts, etc.
+    if metrics is None:
+        return None
+    if isinstance(metrics, str):
+        raise ValueError(
+            "metrics must be a list/tuple/set of strings, not a single string. "
+            "Pass ['views', 'clones'] instead of 'views clones'."
+        )
+    if isinstance(metrics, (list, tuple, set, frozenset)):
+        result = list(metrics)
+        for m in result:
+            if not isinstance(m, str):
+                raise ValueError(f"metrics entries must be strings; got {type(m).__name__}.")
+        # Drop unknown metric names with a warning — better than crashing mid-fetch.
+        unknown = [m for m in result if m not in _VALID_METRICS]
+        if unknown:
+            logger.warning(f"Unknown metrics ignored: {unknown}")
+            result = [m for m in result if m in _VALID_METRICS]
+        return result
+    raise ValueError(f"metrics must be a list/tuple/set; got {type(metrics).__name__}.")
+
+
+def _write_json_safely(path: str, payload: dict) -> None:
+    # Create the parent dir so the user can pass any nested path.
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+
+
 def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_format: str = "dataframe", save_file: str = None, metrics: list = None):
     """
     Fetches the last 14 days of traffic data for one or all repositories.
@@ -43,6 +82,10 @@ def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_
         A ``pandas.DataFrame`` when ``return_format="dataframe"``, otherwise
         a ``dict`` matching the requested format.
     """
+    # Strip surrounding whitespace from the token (matches api._get_token).
+    token = (token or "").strip() if isinstance(token, str) else token
+    metrics = _coerce_metrics(metrics)
+
     # Hit the GitHub API and get back a tidy DataFrame (one row per day per repo)
     df = fetch_traffic_data(token, repo_name, metrics)
 
@@ -54,13 +97,14 @@ def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_
     if return_format == "dataframe":
         if save_file:
             if save_file.endswith(".json"):
-                # Save as a chart-ready JSON file
+                # Save as a chart-ready JSON file (always public-only when exported to disk)
                 payload = build_json_payload(df, return_format="timeseries", export_public_only=True)
-                with open(save_file, "w", encoding="utf-8") as f:
-                    json.dump(payload, f, indent=2)
+                _write_json_safely(save_file, payload)
             else:
                 # Save as a standard CSV file
-                df.to_csv(save_file, index=False)
+                p = Path(save_file)
+                p.parent.mkdir(parents=True, exist_ok=True)
+                df.to_csv(p, index=False)
         return df
 
     # Reject anything that isn't a known format before doing more work
@@ -71,13 +115,14 @@ def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_
             f"Choose one of: 'dataframe', 'timeseries', 'summary'."
         )
 
-    # Build the JSON-serialisable payload in the requested shape
-    payload = build_json_payload(df, return_format=return_format, export_public_only=False)
+    # Build the JSON-serialisable payload in the requested shape.
+    # When persisting to disk, strip private repos by default (security firewall).
+    export_public_only = bool(save_file)
+    payload = build_json_payload(df, return_format=return_format, export_public_only=export_public_only)
 
     # Save to disk if the user gave us a file path
     if save_file:
-        with open(save_file, "w", encoding="utf-8") as f:
-            json.dump(payload, f, indent=2)
+        _write_json_safely(save_file, payload)
 
     return payload
 
@@ -98,10 +143,12 @@ def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str
             exported JSON — acts as a security firewall.
         metrics: Optional list of metrics to fetch (e.g., ``["views", "clones"]``).
     """
-    if data_dir and not os.path.isabs(data_dir) and not os.path.exists(data_dir):
-        parent_dir = os.path.join("..", data_dir)
-        if os.path.exists(parent_dir):
-            data_dir = parent_dir
+    # Strip the token. Resolve the data_dir to an absolute path but NEVER redirect
+    # to a sibling directory — respect the user's CWD.
+    token = (token or "").strip() if isinstance(token, str) else token
+    metrics = _coerce_metrics(metrics)
+    if data_dir:
+        data_dir = str(Path(data_dir).expanduser().resolve())
 
     # Hand off to the automation engine — it handles deduplication and schema migration
     run_sync(
@@ -145,17 +192,13 @@ def serve_dashboard(host: str = "127.0.0.1", port: int = 8000, token: str = None
     _orig_data_dir = os.environ.get("GITLYTICS_DATA_DIR")
     try:
         if token:
-            os.environ["GITLYTICS_TOKEN"] = token
+            os.environ["GITLYTICS_TOKEN"] = (token or "").strip()
         if data_dir:
-            from pathlib import Path
-            abs_data_dir = os.path.abspath(data_dir)
-            if not os.path.exists(abs_data_dir) and not os.path.isabs(data_dir):
-                parent_dir = os.path.abspath(os.path.join("..", data_dir))
-                if os.path.exists(parent_dir):
-                    abs_data_dir = parent_dir
-            if not os.path.exists(abs_data_dir):
+            abs_data_dir = str(Path(data_dir).expanduser().resolve())
+            p = Path(abs_data_dir)
+            if not p.exists():
                 print(f"⚠️ Warning: The specified data directory '{data_dir}' (resolved to '{abs_data_dir}') does not exist.")
-            elif not any(Path(abs_data_dir).glob("traffic_*.csv")):
+            elif not any(p.glob("traffic_*.csv")):
                 print(f"⚠️ Warning: No traffic_*.csv database files found in '{data_dir}' (resolved to '{abs_data_dir}').")
             os.environ["GITLYTICS_DATA_DIR"] = abs_data_dir
         uvicorn.run("gitlytics.api:app", host=host, port=port, reload=False)

{gitlytics-0.2.0 → gitlytics-0.2.2}/src/gitlytics/api.py

@@ -5,7 +5,9 @@ Powers the FastAPI backend — serves traffic data and the React dashboard to th
 import hashlib
 import logging
 import os
+import shutil
 import time as _time
+import uuid
 from pathlib import Path
 
 import pandas as pd
@@ -28,15 +30,14 @@ logger = logging.getLogger(__name__)
 
 app = FastAPI(title="GitHub Traffic API")
 
-# Only allow requests from localhost — never deployed publicly
+# Only allow requests from localhost — never deployed publicly.
+# Vite's dev port (5173) is intentionally excluded from the production allowlist.
 _ALLOWED_ORIGINS = [
     "http://localhost",
     "http://localhost:3000",
-    "http://localhost:5173",
     "http://localhost:8000",
     "http://127.0.0.1",
     "http://127.0.0.1:3000",
-    "http://127.0.0.1:5173",
     "http://127.0.0.1:8000",
 ]
 
@@ -45,13 +46,18 @@ app.add_middleware(
     allow_origins=_ALLOWED_ORIGINS,
     allow_credentials=True,
     allow_methods=["GET", "POST"],
-    allow_headers=["Content-Type"],
+    # `Authorization` is required for cross-origin deployments that pass the
+    # GitHub PAT in a header. Same-origin requests are unaffected.
+    allow_headers=["Content-Type", "Authorization"],
 )
 
 
 _auth_cache: dict = {}  # sha256_prefix -> (valid, username, expires_at)
 _AUTH_CACHE_TTL = 300  # 5 minutes
 
+# Hard cap on CSV upload size — prevents DoS via /api/upload-csv.
+_MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+
 
 def _get_token(token: str = None) -> str:
     # C-2: explicit empty string must not fall through to the env token
@@ -62,14 +68,14 @@ def _get_token(token: str = None) -> str:
 
 def _validate_token_cached(token: str):
     # M-1: cache validation results to avoid a double HTTP round-trip on every /api/traffic call
+    from gitlytics.core import validate_token as _validate_token
     key = hashlib.sha256(token.encode()).hexdigest()[:16]
     now = _time.time()
     if key in _auth_cache:
         valid, username, expires = _auth_cache[key]
         if now < expires:
             return valid, username
-    from gitlytics.core import validate_token
-    valid, username = validate_token(token)
+    valid, username = _validate_token(token)
     _auth_cache[key] = (valid, username, now + _AUTH_CACHE_TTL)
     return valid, username
 
@@ -115,10 +121,22 @@ def get_username_data(username: str = Body("", embed=True)):
         raise HTTPException(status_code=400, detail="Username is required.")
     try:
         profile = get_public_user(username.strip())
+        # Distinguish "user found" (login matches the request) from "GitHub failed
+        # and we returned a stub". Returning 200 for the latter would silently mask
+        # upstream outages.
+        if profile.get("login") == username.strip() and profile.get("html_url"):
+            pass
+        elif profile.get("login") == username.strip():
+            # Found but GitHub didn't include html_url — still treat as success.
+            pass
+        else:
+            raise HTTPException(status_code=502, detail="GitHub did not return a profile.")
         repos = get_public_repos(username.strip())
         return {"profile": profile, "repos": repos}
     except ValueError as exc:
         raise HTTPException(status_code=404, detail=str(exc))
+    except HTTPException:
+        raise
     except Exception as exc:
         logger.warning(f"Username fetch failed for {username}: {exc}")
         raise HTTPException(status_code=500, detail="Failed to fetch GitHub data.")
@@ -170,9 +188,14 @@ def get_traffic(token: str = Body("", embed=True)):
 
     df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
 
-    # Build a quick view-sum map to find the top 20 repos for deep fetching
+    # Build a quick view-sum map to find the top 20 repos for deep fetching.
+    # Guard against the subset-metrics case where `views` may be absent.
     repos_with_views = []
-    if not df.empty and "repository" in df.columns and "views" in df.columns:
+    if (
+        not df.empty
+        and "repository" in df.columns
+        and "views" in df.columns
+    ):
         for repo_name, group in df.groupby("repository"):
             repos_with_views.append({"repository": repo_name, "total_views": int(group["views"].sum())})
 
@@ -192,16 +215,34 @@ def upload_csv(file: UploadFile = File(...)):
         if data_dir:
             data_dir_path = Path(data_dir)
             data_dir_path.mkdir(parents=True, exist_ok=True)
+            # Stream the upload to disk so we don't buffer the whole file in
+            # memory. Enforce the size cap on the way in.
+            dest = data_dir_path / f"traffic_uploaded_{uuid.uuid4().hex}.csv"
+            total = 0
+            with open(dest, "wb") as out:
+                while True:
+                    chunk = file.file.read(1024 * 1024)
+                    if not chunk:
+                        break
+                    total += len(chunk)
+                    if total > _MAX_UPLOAD_BYTES:
+                        out.close()
+                        try:
+                            dest.unlink()
+                        except OSError:
+                            pass
+                        raise HTTPException(
+                            status_code=413,
+                            detail=f"CSV too large. Maximum size is {_MAX_UPLOAD_BYTES // (1024 * 1024)} MB.",
+                        )
+                    out.write(chunk)
             file.file.seek(0)
-            content = file.file.read()
-            file.file.seek(0)
-            dest = data_dir_path / f"traffic_uploaded_{int(_time.time())}.csv"
-            with open(dest, "wb") as f:
-                f.write(content)
         df = process_uploaded_csv(file.file)
         df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
         payload = build_react_payload(df, deep_stats=None)
         return payload
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=400, detail=str(e))
 
@@ -224,6 +265,10 @@ def serve_index():
 @app.get("/{full_path:path}")
 def serve_spa_fallback(full_path: str):
     """SPA catch-all — returns index.html so React Router handles navigation."""
+    # Any unhandled /api/* path is a real 404, not a SPA route.
+    if full_path.startswith("api/"):
+        return JSONResponse(status_code=404, content={"error": "Not found."})
+
     asset_file = frontend_dir / full_path
     if asset_file.exists() and asset_file.is_file():
         return FileResponse(asset_file)

{gitlytics-0.2.0 → gitlytics-0.2.2}/src/gitlytics/automation.py

@@ -74,7 +74,14 @@ def export_json_database(data_dir: str, export_path: str, export_public_only: bo
     export_file.parent.mkdir(parents=True, exist_ok=True)
 
     with open(export_file, "w", encoding="utf-8") as f:
-        json.dump(payload, f, indent=2)
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+
+
+def _normalize_field(name: str) -> str:
+    # Strip BOM, lower-case, and trim so older CSVs match the new schema.
+    if not isinstance(name, str):
+        return ""
+    return name.lstrip("").strip().lower()
 
 
 def _merge_schema(existing_fields: list, new_fields: list) -> list:
@@ -83,18 +90,30 @@ def _merge_schema(existing_fields: list, new_fields: list) -> list:
     Existing fields keep their original order; new fields are appended at the end
     so historical rows stay compatible with the updated schema.
     """
-    merged = list(existing_fields)
+    # Normalize on the fly so 'Date' and 'date' are treated identically.
+    norm_existing = [_normalize_field(f) for f in existing_fields]
+    merged_norm = list(norm_existing)
+    original_for_norm = list(existing_fields)
     for col in new_fields:
-        if col not in merged:
+        n = _normalize_field(col)
+        if n and n not in merged_norm:
             # A new column appeared in the API response — add it so it gets saved
             logger.info(f"Schema upgrade: adding new column '{col}' to existing CSV.")
-            merged.append(col)
-    return merged
+            merged_norm.append(n)
+            original_for_norm.append(col)
+    # Return the original-cased names where possible so the CSV header stays human-readable.
+    return original_for_norm
 
 
 def run_sync_cycle(token: str, repo_names=None, data_dir="./data", output_mode="monthly", export_json=None, export_public_only=True, metrics: list = None):
     # Fetch fresh traffic data from GitHub
     df = fetch_traffic_data(token, repo_names, metrics)
+
+    # Always regenerate the export if requested, even when fresh data is empty,
+    # so the export file never becomes silently stale.
+    if export_json:
+        export_json_database(data_dir, export_json, export_public_only)
+
     if df.empty:
         logger.info("No traffic data found to sync.")
         return
@@ -108,18 +127,19 @@ def run_sync_cycle(token: str, repo_names=None, data_dir="./data", output_mode="
 
     if file_exists:
         # Read the existing column headers so we can migrate the schema if needed
-        with open(csv_path, "r", encoding="utf-8") as f:
+        with open(csv_path, "r", encoding="utf-8-sig", newline="") as f:
             reader = csv.reader(f)
             try:
                 existing_fields = next(reader)
             except StopIteration:
                 pass
 
-        # Load all existing rows into a dict keyed by (repo, date) for deduplication
+        # Load all existing rows in one pass — avoid iterrows() on large files.
         try:
             existing_df = pd.read_csv(csv_path)
-            for _, row in existing_df.iterrows():
-                existing_data[(str(row["repository"]), str(row["date"]))] = row.to_dict()
+            for record in existing_df.to_dict("records"):
+                key = (str(record.get("repository", "")), str(record.get("date", "")))
+                existing_data[key] = record
         except Exception as exc:
             logger.warning(f"Could not read existing CSV '{csv_path}': {exc}. Starting fresh.")
 
@@ -132,24 +152,32 @@ def run_sync_cycle(token: str, repo_names=None, data_dir="./data", output_mode="
 
     # Merge fresh data into existing rows — preserves columns not present in this sync run
     new_records_added = 0
-    for _, row in df.iterrows():
-        key = (str(row["repository"]), str(row["date"]))
+    for record in df.to_dict("records"):
+        key = (str(record.get("repository", "")), str(record.get("date", "")))
         if key not in existing_data:
             new_records_added += 1
-            existing_data[key] = row.to_dict()
+            existing_data[key] = record
         else:
-            existing_data[key].update(row.to_dict())
+            existing_data[key].update(record)
 
     # Sort all rows by date and repo name before writing back to disk
     final_rows = []
     for v in existing_data.values():
         # Fill any missing schema columns with empty strings for old rows
-        clean_row = {k: v.get(k, "") for k in existing_fields}
+        clean_row = {}
+        for k in existing_fields:
+            nk = _normalize_field(k)
+            if nk in v:
+                clean_row[k] = v[nk]
+            else:
+                # Try to match by normalized name to old-style keys in the dict.
+                match = next((orig for orig in v.keys() if _normalize_field(orig) == nk), None)
+                clean_row[k] = v[match] if match is not None else ""
         final_rows.append(clean_row)
 
-    final_rows.sort(key=lambda x: (x.get("date", ""), x.get("repository", "")))
+    final_rows.sort(key=lambda x: (str(x.get("date", "")), str(x.get("repository", ""))))
 
-    # Write everything back to the CSV file atomically
+    # Write everything back to the CSV file
     with open(csv_path, "w", newline="", encoding="utf-8") as f:
         writer = csv.DictWriter(f, fieldnames=existing_fields, extrasaction='ignore')
         writer.writeheader()
@@ -157,10 +185,15 @@ def run_sync_cycle(token: str, repo_names=None, data_dir="./data", output_mode="
 
     logger.info(f"Successfully processed traffic data. Added {new_records_added} new daily records to {csv_path}")
 
-    # If the user wants a JSON export, regenerate it from the full database
-    if export_json:
-        export_json_database(data_dir, export_json, export_public_only)
-        logger.info(f"Exported historical database to {export_json}")
+
+def _interruptible_sleep(total_seconds: float) -> None:
+    # Sleep in short chunks so SIGINT/SIGTERM (Ctrl-C, docker stop) is responsive.
+    chunk = 1.0
+    elapsed = 0.0
+    while elapsed < total_seconds:
+        remaining = total_seconds - elapsed
+        time.sleep(min(chunk, remaining))
+        elapsed += chunk
 
 
 def run_sync(token: str, repo_names=None, data_dir="./data", output_mode="monthly", schedule_cron=None, export_json=None, export_public_only=True, metrics: list = None):
@@ -173,7 +206,7 @@ def run_sync(token: str, repo_names=None, data_dir="./data", output_mode="monthl
     # Parse the cron expression — fail early if the format is wrong
     try:
         croniter(schedule_cron, datetime.now(timezone.utc))  # validate only
-    except ValueError as e:
+    except (ValueError, KeyError, TypeError) as e:
         logger.error(f"Invalid cron expression: {e}")
         return
 
@@ -190,21 +223,25 @@ def run_sync(token: str, repo_names=None, data_dir="./data", output_mode="monthl
 
         sleep_secs = (next_run - now_utc).total_seconds()
 
-        # Sleep until the next scheduled run
-        if sleep_secs > 0:
-            logger.info(f"Scheduled next sync for {next_run.strftime('%Y-%m-%d %H:%M:%S UTC')}. Sleeping...")
-            time.sleep(sleep_secs)
+        # Guard against negative/zero sleep (clock skew): minimum 1s to avoid hot-looping.
+        if sleep_secs <= 0:
+            sleep_secs = 1.0
+
+        logger.info(f"Scheduled next sync for {next_run.strftime('%Y-%m-%d %H:%M:%S UTC')}. Sleeping {sleep_secs:.0f}s...")
+        _interruptible_sleep(sleep_secs)
 
         try:
             # Always re-validate the token before fetching to catch expiry early
             is_valid, msg = validate_token(token)
             if not is_valid:
                 # Distinguish between a dead token (stop forever) and a network blip (retry next cycle)
+                msg_lower = msg.lower()
                 is_auth_failure = (
                     "401" in msg
-                    or "authentication failed" in msg.lower()
-                    or "invalid token" in msg.lower()
-                    or "revoked" in msg.lower()
+                    or "authentication failed" in msg_lower
+                    or "invalid token" in msg_lower
+                    or "revoked" in msg_lower
+                    or "bad credentials" in msg_lower
                 )
                 if is_auth_failure:
                     logger.critical(
@@ -217,6 +254,11 @@ def run_sync(token: str, repo_names=None, data_dir="./data", output_mode="monthl
                     continue
 
             run_sync_cycle(token, repo_names, data_dir, output_mode, export_json, export_public_only, metrics)
+        except SystemExit:
+            raise
+        except KeyboardInterrupt:
+            logger.info("Daemon interrupted by user. Exiting.")
+            raise
         except Exception as e:
             # Don't let a single bad cycle kill the daemon — just log and carry on
             logger.error(f"Daemon encountered unexpected error: {e}. Recovering for next cycle.")

{gitlytics-0.2.0 → gitlytics-0.2.2}/src/gitlytics/cli.py

@@ -6,7 +6,6 @@ Achieves 100% feature parity with the Python API.
 import argparse
 import sys
 import os
-import json
 
 # Import the three public functions that power every subcommand
 from gitlytics import fetch_traffic, sync, serve_dashboard
@@ -16,7 +15,14 @@ def parse_repo_names(repo_arg: str):
     # Turn "owner/repo1, owner/repo2" into ["owner/repo1", "owner/repo2"], or None if empty
     if not repo_arg:
         return None
-    return [r.strip() for r in repo_arg.split(",")]
+    names = [r.strip() for r in repo_arg.split(",")]
+    # Validate the format up front so the user gets a clear error instead of a 404.
+    for name in names:
+        if "/" not in name:
+            raise argparse.ArgumentTypeError(
+                f"Invalid repo name {name!r}: expected 'owner/repo' format."
+            )
+    return names
 
 
 def main():
@@ -72,13 +78,14 @@ def main():
 
     args = parser.parse_args()
 
-    # Print help and exit if the user didn't give a subcommand
+    # Print help and exit cleanly (code 0) if the user didn't give a subcommand.
     if not args.command:
         parser.print_help()
-        sys.exit(1)
+        sys.exit(0)
 
     # Resolve token: CLI flag wins, then environment variables
-    token = getattr(args, "token", None) or os.environ.get("GITLYTICS_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    raw_token = getattr(args, "token", None)
+    token = (raw_token or os.environ.get("GITLYTICS_TOKEN") or os.environ.get("GITHUB_TOKEN") or "").strip() or None
 
     # fetch and sync both need a token — bail early with a clear message
     if args.command in ["fetch", "sync"] and not token:
@@ -86,31 +93,56 @@ def main():
         sys.exit(1)
 
     if args.command == "fetch":
-        repos = parse_repo_names(args.repo_name)
-        result = fetch_traffic(
-            token=token,
-            repo_name=repos,
-            print_table=args.print_table,
-            return_format=args.return_format,
-            save_file=args.save_file,
-            metrics=args.metrics
-        )
+        try:
+            repos = parse_repo_names(args.repo_name)
+        except argparse.ArgumentTypeError as exc:
+            print(f"❌ Error: {exc}")
+            sys.exit(2)
+        try:
+            result = fetch_traffic(
+                token=token,
+                repo_name=repos,
+                print_table=args.print_table,
+                return_format=args.return_format,
+                save_file=args.save_file,
+                metrics=args.metrics
+            )
+        except ValueError as exc:
+            print(f"❌ Error: {exc}")
+            sys.exit(2)
         # Give the user a hint if they didn't ask for any output
         if not args.print_table and not args.save_file:
-            print("Fetch successful. Use --print-table or --save-file to see results.")
+            try:
+                import pandas as pd
+                if isinstance(result, pd.DataFrame):
+                    print(f"Fetch successful. {len(result)} row(s) across {result['repository'].nunique() if not result.empty else 0} repo(s).")
+                    print("First 5 rows:")
+                    print(result.head().to_string(index=False))
+                else:
+                    print(f"Fetch successful. Use --print-table or --save-file to see results.")
+            except Exception:
+                print("Fetch successful. Use --print-table or --save-file to see results.")
 
     elif args.command == "sync":
-        repos = parse_repo_names(args.repo_name)
-        sync(
-            token=token,
-            repo_name=repos,
-            data_dir=args.data_dir,
-            output_mode=args.output_mode,
-            schedule_cron=args.schedule_cron,
-            export_json=args.export_json,
-            export_public_only=args.export_public_only,
-            metrics=args.metrics
-        )
+        try:
+            repos = parse_repo_names(args.repo_name)
+        except argparse.ArgumentTypeError as exc:
+            print(f"❌ Error: {exc}")
+            sys.exit(2)
+        try:
+            sync(
+                token=token,
+                repo_name=repos,
+                data_dir=args.data_dir,
+                output_mode=args.output_mode,
+                schedule_cron=args.schedule_cron,
+                export_json=args.export_json,
+                export_public_only=args.export_public_only,
+                metrics=args.metrics
+            )
+        except ValueError as exc:
+            print(f"❌ Error: {exc}")
+            sys.exit(2)
 
     elif args.command == "dashboard":
         print(f"\n[Gitlytics] Starting Gitlytics Dashboard on http://{args.host}:{args.port}\n")