github-traffic-tracker 0.2.8a0__py3-none-any.whl

ghtraf/__init__.py

@@ -0,0 +1,9 @@
+"""ghtraf — GitHub Traffic Tracker CLI.
+
+Zero-server GitHub traffic analytics. Daily collection via Actions,
+gist-backed storage, client-side dashboard.
+"""
+
+from ghtraf._version import __version__, __app_name__
+
+__all__ = ["__version__", "__app_name__"]

ghtraf/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running as: python -m ghtraf"""
+
+import sys
+
+from ghtraf.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ghtraf/_version.py

@@ -0,0 +1,70 @@
+"""
+Version information for ghtraf (GitHub Traffic Tracker CLI).
+
+This file is the canonical source for version numbers.
+The __version__ string is automatically updated by git hooks
+with build metadata (branch, build number, date, commit hash).
+
+Format: MAJOR.MINOR.PATCH[-PHASE]_BRANCH_BUILD-YYYYMMDD-COMMITHASH
+Example: 0.2.0-alpha_main_4-20260226-a1b2c3d4
+"""
+
+# Version components - edit these for version bumps
+MAJOR = 0
+MINOR = 2
+PATCH = 8
+PHASE = "alpha"  # Per-MINOR feature set: None, "alpha", "beta", "rc1", etc.
+
+# Auto-updated by git hooks - do not edit manually
+__version__ = "0.2.8-alpha_main_12-20260228-4691eea"
+__app_name__ = "ghtraf"
+
+
+def get_version():
+    """Return the full version string including branch and build info."""
+    return __version__
+
+
+def get_base_version():
+    """Return the semantic version string (MAJOR.MINOR.PATCH[-PHASE])."""
+    if "_" in __version__:
+        return __version__.split("_")[0]
+    base = f"{MAJOR}.{MINOR}.{PATCH}"
+    if PHASE:
+        base = f"{base}-{PHASE}"
+    return base
+
+
+def get_pip_version():
+    """
+    Return PEP 440 compliant version for pip/setuptools.
+
+    Converts our version format to PEP 440:
+    - Main branch: 0.2.0-alpha_main_3-20260226-hash -> 0.2.0a0
+    - Dev branch: 0.2.0-alpha_dev_3-20260226-hash -> 0.2.0a0.dev3
+    """
+    base = f"{MAJOR}.{MINOR}.{PATCH}"
+
+    # Map phase to PEP 440 pre-release segment
+    phase_map = {"alpha": "a0", "beta": "b0"}
+    if PHASE:
+        base += phase_map.get(PHASE, PHASE)
+
+    if "_" not in __version__:
+        return base
+
+    parts = __version__.split("_")
+    branch = parts[1] if len(parts) > 1 else "unknown"
+
+    if branch == "main":
+        return base
+    else:
+        build_info = "_".join(parts[2:]) if len(parts) > 2 else ""
+        build_num = build_info.split("-")[0] if "-" in build_info else "0"
+        return f"{base}.dev{build_num}"
+
+
+# For convenience in imports
+VERSION = get_version()
+BASE_VERSION = get_base_version()
+PIP_VERSION = get_pip_version()

ghtraf/cli.py

@@ -0,0 +1,172 @@
+"""Main CLI entry point for ghtraf.
+
+Implements a Docker-style two-pass argument parser:
+  1. First pass: extract global flags (--verbose, --no-color, --config)
+  2. Second pass: dispatch to subcommand with shared parent args
+
+Global flags can appear before OR after the subcommand:
+  ghtraf --verbose create --owner X      # works
+  ghtraf create --owner X --verbose      # also works
+
+Subcommands self-register via register(subparsers, parents) convention.
+"""
+
+import argparse
+import sys
+
+from ghtraf._version import BASE_VERSION, VERSION
+
+
+# ---------------------------------------------------------------------------
+# Global flags (Docker-style: can precede the subcommand)
+# ---------------------------------------------------------------------------
+GLOBAL_FLAGS = {
+    "--verbose": {"action": "store_true", "default": False,
+                  "help": "Enable verbose output"},
+    "--no-color": {"action": "store_true", "default": False,
+                   "help": "Disable colored output"},
+    "--config": {"metavar": "PATH", "default": None,
+                 "help": "Path to config file (default: ~/.ghtraf/config.json)"},
+}
+
+
+def _extract_global_flags(argv):
+    """Two-pass parse: pull global flags from anywhere in argv.
+
+    Returns (global_namespace, remaining_argv).
+    """
+    global_parser = argparse.ArgumentParser(add_help=False)
+    for flag, kwargs in GLOBAL_FLAGS.items():
+        global_parser.add_argument(flag, **kwargs)
+
+    global_args, remaining = global_parser.parse_known_args(argv)
+    return global_args, remaining
+
+
+# ---------------------------------------------------------------------------
+# Shared parent parser (inherited by all subcommands via parents=[])
+# ---------------------------------------------------------------------------
+def _build_common_parser():
+    """Build the shared argument parser for repo-scoped flags.
+
+    These are inherited by every subcommand — defined once, zero duplication.
+    """
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--owner", metavar="NAME",
+                        help="GitHub username or organization")
+    common.add_argument("--repo", metavar="NAME",
+                        help="Repository name")
+    common.add_argument("--repo-dir", metavar="PATH",
+                        help="Local repository directory")
+    common.add_argument("--dry-run", action="store_true", default=False,
+                        help="Preview changes without applying them")
+    common.add_argument("--non-interactive", action="store_true", default=False,
+                        help="Never prompt — fail on missing required values")
+    return common
+
+
+# ---------------------------------------------------------------------------
+# Subcommand discovery and registration
+# ---------------------------------------------------------------------------
+def _discover_commands():
+    """Import and return all command modules.
+
+    Each module in ghtraf.commands must export:
+      register(subparsers, parents) — add itself to the subparser
+      run(args, global_args) — execute the command
+    """
+    from ghtraf.commands import create
+    # Future commands added here:
+    # from ghtraf.commands import init, status, list_cmd, upgrade, verify
+    return [create]
+
+
+def _build_parser(commands, common_parser):
+    """Build the main argparse parser with subcommand dispatch."""
+    parser = argparse.ArgumentParser(
+        prog="ghtraf",
+        description="ghtraf — GitHub Traffic Tracker CLI",
+        epilog=(
+            "Run 'ghtraf <command> --help' for details on a specific command.\n"
+            "\n"
+            "Global flags (--verbose, --no-color, --config) can appear\n"
+            "before or after the subcommand."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"ghtraf {BASE_VERSION} ({VERSION})",
+    )
+
+    # Add global flags to main parser too (for --help display)
+    for flag, kwargs in GLOBAL_FLAGS.items():
+        parser.add_argument(flag, **kwargs)
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="commands",
+        metavar="<command>",
+    )
+
+    # Let each command register itself
+    for cmd_module in commands:
+        cmd_module.register(subparsers, parents=[common_parser])
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+def main(argv=None):
+    """Main entry point for ghtraf CLI.
+
+    Args:
+        argv: Command-line arguments. None means sys.argv[1:].
+              Accepts a list for DazzleCMD integration.
+
+    Returns:
+        Exit code (0 = success).
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Pass 1: extract global flags from anywhere in the arg list
+    global_args, remaining = _extract_global_flags(argv)
+
+    # Pass 2: parse subcommand + shared/specific args
+    common_parser = _build_common_parser()
+    commands = _discover_commands()
+    parser = _build_parser(commands, common_parser)
+
+    # If no args at all, print help
+    if not remaining:
+        parser.print_help()
+        return 0
+
+    args = parser.parse_args(remaining)
+
+    # If subcommand selected but no handler, print help
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+
+    # Merge global args into the namespace for convenience
+    for key, value in vars(global_args).items():
+        if key not in vars(args) or getattr(args, key) is None:
+            setattr(args, key, value)
+
+    # Dispatch
+    try:
+        return args.func(args) or 0
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        return 130
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ghtraf/commands/__init__.py

@@ -0,0 +1,6 @@
+"""ghtraf subcommands.
+
+Each command module exports:
+  register(subparsers, parents) — add the subcommand to argparse
+  run(args) — execute the command
+"""

ghtraf/commands/create.py

@@ -0,0 +1,392 @@
+"""ghtraf create — Create gists and configure repository for traffic tracking.
+
+This is the bootstrap command. It creates the badge and archive gists,
+sets repository variables/secrets, and optionally configures dashboard
+and workflow files with project-specific values.
+
+Equivalent to the standalone setup-gists.py script.
+"""
+
+import html as html_module
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+from ghtraf import gh, gist, configure
+from ghtraf.config import register_repo_globally, save_project_config
+from ghtraf.output import (
+    print_dry, print_ok, print_skip, print_step, print_warn, prompt,
+)
+
+
+def register(subparsers, parents):
+    """Register the 'create' subcommand."""
+    p = subparsers.add_parser(
+        "create",
+        parents=parents,
+        help="Create gists and set repository variables for traffic tracking",
+        description=(
+            "Create the public badge gist and unlisted archive gist needed\n"
+            "by the traffic-badges.yml workflow, then optionally configure\n"
+            "repository variables/secrets and update dashboard files."
+        ),
+        formatter_class=__import__("argparse").RawDescriptionHelpFormatter,
+    )
+
+    # create-specific args
+    p.add_argument("--created", metavar="DATE",
+                   help="Repository creation date (YYYY-MM-DD)")
+    p.add_argument("--display-name", metavar="NAME",
+                   help="Display name for dashboard title/banner")
+    p.add_argument("--ci-workflows", nargs="*", default=None,
+                   help="CI workflow names for workflow_run trigger "
+                        "(omit to comment out trigger)")
+    p.add_argument("--configure", action="store_true", dest="configure_files",
+                   help="Also update dashboard and workflow files with your values")
+    p.add_argument("--skip-variables", action="store_true",
+                   help="Skip setting repository variables/secrets")
+    p.add_argument("--gist-token-name", default="TRAFFIC_GIST_TOKEN",
+                   help="Name for the gist token secret "
+                        "(default: TRAFFIC_GIST_TOKEN)")
+
+    p.set_defaults(func=run)
+
+
+def _gather_config(args):
+    """Build config dict, prompting for any missing values."""
+    config = {}
+    non_interactive = args.non_interactive
+
+    # Owner
+    if args.owner:
+        config["owner"] = args.owner
+    elif non_interactive:
+        print("ERROR: --owner is required in non-interactive mode.")
+        sys.exit(1)
+    else:
+        config["owner"] = prompt("GitHub owner (username or org)")
+
+    # Repo
+    if args.repo:
+        config["repo"] = args.repo
+    elif non_interactive:
+        print("ERROR: --repo is required in non-interactive mode.")
+        sys.exit(1)
+    else:
+        config["repo"] = prompt("Repository name")
+
+    config["gh_repo"] = f"{config['owner']}/{config['repo']}"
+
+    # Created date — try auto-detect, fall back to today
+    if args.created:
+        config["created"] = args.created
+    else:
+        auto_date = gh.get_repo_created_date(config["gh_repo"])
+        if non_interactive:
+            config["created"] = auto_date or date.today().isoformat()
+        elif auto_date:
+            config["created"] = prompt(
+                "Repository creation date (YYYY-MM-DD)", default=auto_date)
+        else:
+            config["created"] = prompt(
+                "Repository creation date (YYYY-MM-DD)",
+                default=date.today().isoformat())
+
+    # Display name
+    if args.display_name:
+        config["display_name"] = args.display_name
+    elif non_interactive:
+        config["display_name"] = (config["repo"]
+                                  .replace("-", " ")
+                                  .replace("_", " ")
+                                  .title())
+    else:
+        default_name = (config["repo"]
+                        .replace("-", " ")
+                        .replace("_", " ")
+                        .title())
+        config["display_name"] = prompt(
+            "Display name for dashboard", default=default_name)
+
+    # CI workflows
+    if args.ci_workflows is not None:
+        config["ci_workflows"] = args.ci_workflows
+    elif non_interactive:
+        config["ci_workflows"] = []
+    else:
+        ci_input = input(
+            "  CI workflow names to trigger after "
+            "(comma-separated, Enter to skip): "
+        ).strip()
+        if ci_input:
+            config["ci_workflows"] = [
+                w.strip() for w in ci_input.split(",") if w.strip()
+            ]
+        else:
+            config["ci_workflows"] = []
+
+    config["display_name_html"] = html_module.escape(config["display_name"])
+
+    return config
+
+
+def _validate_config(config):
+    """Validate configuration values."""
+    if not re.match(r"^\d{4}-\d{2}-\d{2}$", config["created"]):
+        print(f"ERROR: Invalid date format '{config['created']}'. "
+              "Expected YYYY-MM-DD.")
+        sys.exit(1)
+
+    repo_exists = gh.check_repo_exists(config["gh_repo"])
+    if not repo_exists:
+        print_warn(f"Repository {config['gh_repo']} not found on GitHub.")
+        print("  This is OK if you haven't created it yet.")
+        print("  Repository variables/secrets will be set once it exists.")
+
+
+def _guide_token_setup(config, dry_run=False):
+    """Guide user through PAT creation and offer to set the secret."""
+    token_name = config.get("gist_token_name", "TRAFFIC_GIST_TOKEN")
+    gh_repo = config["gh_repo"]
+
+    print()
+    print("  The workflow needs a Personal Access Token (PAT) with 'gist' scope")
+    print("  to update your gists. This is SEPARATE from your gh CLI token.")
+    print()
+    print("  To create one:")
+    print(f"    1. Go to: https://github.com/settings/tokens/new")
+    print(f"    2. Name it: \"Traffic Tracker - {gh_repo}\"")
+    print("    3. Check ONLY the 'gist' scope")
+    print("    4. Set expiration (recommended: no expiration, or 1 year)")
+    print("    5. Click 'Generate token' and copy the value")
+    print()
+
+    if dry_run:
+        print_dry(f"Would prompt for PAT and set secret {token_name}")
+        return
+
+    if config.get("non_interactive"):
+        print(f"  Then run: gh secret set {token_name} -R {gh_repo}")
+        return
+
+    token = input("  Paste your PAT here (or press Enter to skip): ").strip()
+    if token:
+        success = gh.set_repo_secret(token_name, token, gh_repo)
+        if not success:
+            print_warn("Could not set secret.")
+            print(f"  Run manually: gh secret set {token_name} -R {gh_repo}")
+        else:
+            print_ok(f"Secret {token_name} set successfully")
+    else:
+        print_skip("PAT not provided")
+        print(f"  Remember to run: gh secret set {token_name} -R {gh_repo}")
+
+
+def run(args):
+    """Execute the create command."""
+    dry_run = args.dry_run
+
+    # Header
+    print()
+    print("GitHub Traffic Tracker Setup")
+    print("=" * 40)
+    if dry_run:
+        print("[DRY RUN MODE - no changes will be made]")
+
+    # Prerequisites
+    print("\nChecking prerequisites...")
+    version = gh.check_gh_installed()
+    print_ok(f"gh CLI found ({version})")
+
+    auth_output = gh.check_gh_authenticated()
+    # Extract login line for display
+    for line in auth_output.split("\n"):
+        if "Logged in to" in line and "account" in line:
+            print_ok(line.strip().lstrip("\u2713").strip())
+            break
+
+    has_gist_scope = gh.check_gh_scopes(auth_output)
+    if not has_gist_scope:
+        print_warn("Your gh CLI token may not have 'gist' scope.")
+        print("  Run: gh auth refresh -s gist")
+        if not args.non_interactive:
+            resp = input("  Continue anyway? (y/N): ").strip().lower()
+            if resp != "y":
+                sys.exit(1)
+    else:
+        print_ok("Token has gist access")
+
+    gh_username = gh.resolve_github_username()
+    print_ok(f"GitHub username: {gh_username}")
+
+    # Configuration
+    print("\nGathering configuration...")
+    config = _gather_config(args)
+    config["gh_username"] = gh_username
+    config["gist_token_name"] = args.gist_token_name
+    config["non_interactive"] = args.non_interactive
+
+    _validate_config(config)
+
+    total_steps = 3
+    if args.configure_files:
+        total_steps += 1
+    if not args.skip_variables:
+        total_steps += 1
+
+    print(f"\n  Owner:        {config['owner']}")
+    print(f"  Repository:   {config['repo']}")
+    print(f"  Created:      {config['created']}")
+    print(f"  Display Name: {config['display_name']}")
+    if config["ci_workflows"]:
+        print(f"  CI Workflows: {', '.join(config['ci_workflows'])}")
+    else:
+        print("  CI Workflows: (none)")
+    print(f"  Configure:    {'yes' if args.configure_files else 'no'}")
+
+    if not args.non_interactive and not dry_run:
+        print()
+        resp = input("  Proceed? (Y/n): ").strip().lower()
+        if resp == "n":
+            print("  Setup cancelled.")
+            return 0
+
+    # Step 1: Create badge gist
+    step = 1
+    print_step(step, total_steps, "Create badge gist (public)")
+    badge_gist_id = gist.create_badge_gist(config, dry_run=dry_run)
+    config["badge_gist_id"] = badge_gist_id
+
+    # Step 2: Create archive gist
+    step += 1
+    print_step(step, total_steps, "Create archive gist (unlisted)")
+    archive_gist_id = gist.create_archive_gist(config, dry_run=dry_run)
+    config["archive_gist_id"] = archive_gist_id
+
+    # Step 3: Set repository variables
+    if not args.skip_variables:
+        step += 1
+        print_step(step, total_steps, "Set repository variables")
+
+        success = gh.set_repo_variable(
+            "TRAFFIC_GIST_ID", badge_gist_id, config["gh_repo"], dry_run)
+        if dry_run:
+            print_dry(f"Would set variable TRAFFIC_GIST_ID = {badge_gist_id}")
+        elif success:
+            print_ok(f"TRAFFIC_GIST_ID = {badge_gist_id}")
+        else:
+            print_warn("Could not set TRAFFIC_GIST_ID")
+            print(f"  Run manually: gh variable set TRAFFIC_GIST_ID "
+                  f"--body \"{badge_gist_id}\" -R {config['gh_repo']}")
+
+        success = gh.set_repo_variable(
+            "TRAFFIC_ARCHIVE_GIST_ID", archive_gist_id,
+            config["gh_repo"], dry_run)
+        if dry_run:
+            print_dry(f"Would set variable TRAFFIC_ARCHIVE_GIST_ID = "
+                      f"{archive_gist_id}")
+        elif success:
+            print_ok(f"TRAFFIC_ARCHIVE_GIST_ID = {archive_gist_id}")
+        else:
+            print_warn("Could not set TRAFFIC_ARCHIVE_GIST_ID")
+            print(f"  Run manually: gh variable set TRAFFIC_ARCHIVE_GIST_ID "
+                  f"--body \"{archive_gist_id}\" -R {config['gh_repo']}")
+
+        # PAT guidance
+        step += 1
+        print_step(step, total_steps,
+                   f"Repository secret ({config['gist_token_name']})")
+        _guide_token_setup(config, dry_run=dry_run)
+
+    # Step 4: Configure files (optional)
+    if args.configure_files:
+        step += 1
+        print_step(step, total_steps, "Configure project files")
+
+        repo_dir = Path(args.repo_dir or ".").resolve()
+        dashboard_path = repo_dir / "docs" / "stats" / "index.html"
+        readme_path = repo_dir / "docs" / "stats" / "README.md"
+        workflow_path = repo_dir / ".github" / "workflows" / "traffic-badges.yml"
+
+        configure.configure_dashboard(config, dashboard_path, dry_run=dry_run)
+        configure.configure_readme(config, readme_path, dry_run=dry_run)
+        configure.configure_workflow(config, workflow_path, dry_run=dry_run)
+
+    # Write config files
+    if not dry_run:
+        repo_dir = Path(args.repo_dir or ".").resolve()
+        project_cfg = {
+            "owner": config["owner"],
+            "repo": config["repo"],
+            "created": config["created"],
+            "display_name": config["display_name"],
+            "badge_gist_id": badge_gist_id,
+            "archive_gist_id": archive_gist_id,
+            "dashboard_dir": "docs/stats",
+            "schema_version": 1,
+        }
+        if config["ci_workflows"]:
+            project_cfg["ci_workflows"] = config["ci_workflows"]
+
+        save_project_config(project_cfg, repo_dir)
+        register_repo_globally(
+            owner=config["owner"],
+            repo=config["repo"],
+            badge_gist_id=badge_gist_id,
+            archive_gist_id=archive_gist_id,
+            repo_dir=str(repo_dir),
+            display_name=config["display_name"],
+            created=config["created"],
+        )
+
+    # Summary
+    print()
+    print("=" * 40)
+    if dry_run:
+        print("Dry run complete! Re-run without --dry-run to apply.")
+    else:
+        print("Setup complete!")
+
+    print(f"\n  Badge Gist ID:   {badge_gist_id}")
+    print(f"  Archive Gist ID: {archive_gist_id}")
+
+    gist_base = (f"https://gist.githubusercontent.com/"
+                 f"{gh_username}/{badge_gist_id}/raw")
+    print(f"\nBadge URLs:")
+    print(f"  Installs:  https://img.shields.io/endpoint?url="
+          f"{gist_base}/installs.json")
+    print(f"  Downloads: https://img.shields.io/endpoint?url="
+          f"{gist_base}/downloads.json")
+    print(f"  Clones:    https://img.shields.io/endpoint?url="
+          f"{gist_base}/clones.json")
+    print(f"  Views:     https://img.shields.io/endpoint?url="
+          f"{gist_base}/views.json")
+
+    print(f"\nBadge Markdown (copy-paste for README):")
+    shield_base = "https://img.shields.io/endpoint?url=" + gist_base
+    owner_lower = config["owner"].lower()
+    stats_url = f"https://{owner_lower}.github.io/{config['repo']}/stats/"
+    print(f'  [![Installs]({shield_base}/installs.json)]({stats_url}#installs)')
+
+    print(f"\nNext steps:")
+    if args.skip_variables:
+        print(f"  1. Set repo variables:")
+        print(f"     gh variable set TRAFFIC_GIST_ID "
+              f"--body \"{badge_gist_id}\" -R {config['gh_repo']}")
+        print(f"     gh variable set TRAFFIC_ARCHIVE_GIST_ID "
+              f"--body \"{archive_gist_id}\" -R {config['gh_repo']}")
+        print(f"  2. Set repo secret with a PAT (gist scope):")
+        print(f"     gh secret set {config['gist_token_name']} "
+              f"-R {config['gh_repo']}")
+    if not args.configure_files:
+        print("  - Run again with --configure to update dashboard/workflow files")
+    print("  - Commit and push your changes")
+    print("  - Enable GitHub Pages (Settings > Pages > Deploy from branch "
+          "> main, /docs)")
+    print("  - Trigger the workflow manually or wait for the 3am UTC schedule:")
+    print(f"    gh workflow run \"Track Downloads & Clones\" "
+          f"-R {config['gh_repo']}")
+    print()
+
+    return 0