ghtraffic 0.0.2__tar.gz

ghtraffic-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

ghtraffic-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+node_modules/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

ghtraffic-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghtraffic-0.0.2/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: ghtraffic
+Version: 0.0.2
+Summary: Collect, accumulate and explore GitHub traffic and insights (views, clones, referrers, paths, stars) across all your repos and orgs, with a GitHub Action and a static dashboard.
+Project-URL: Homepage, https://github.com/thorwhalen/ghtraffic
+Project-URL: Repository, https://github.com/thorwhalen/ghtraffic
+Project-URL: Dashboard, https://thorwhalen.github.io/ghtraffic/
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,dashboard,github,github-actions,insights,traffic
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# ghtraffic
+
+Keep your GitHub traffic for longer than 14 days, across all your repos and orgs, and explore it in a dashboard.
+
+GitHub shows a repo's views, clones, referrers and popular pages for the last 14 days only, one repo at a time. `ghtraffic` collects them for every repo you can push to, on a schedule, and merges each run into a growing history of small CSV files in a git repository you own. Star, fork and watcher counts come along, and star history is rebuilt back to each repo's creation. A static dashboard reads that history.
+
+**Dashboard (demo data):** https://thorwhalen.github.io/ghtraffic/
+
+## Quick start: collect with a GitHub Action
+
+1. Create a **private** repository for the data (it will hold the traffic of your private repos too), and add the workflow and config to it:
+
+   ```bash
+   pip install ghtraffic
+   gh repo create my-traffic-data --private --clone && cd my-traffic-data
+   ghtraffic init . --owner @me          # or: --owner me --owner my-org ...
+   git add -A && git commit -m "ghtraffic" && git push -u origin main
+   ```
+
+   `ghtraffic init` writes two files: `ghtraffic.toml` (what to collect) and `.github/workflows/ghtraffic.yml`, which is all the workflow needs:
+
+   ```yaml
+   - uses: actions/checkout@v4
+   - uses: thorwhalen/ghtraffic@0.0.2   # the release you installed; pin it
+     with:
+       token: ${{ secrets.GHTRAFFIC_TOKEN }}
+   ```
+
+   The Action is pinned to a release tag (or pin a commit SHA): the token it receives can read every repo it covers, so it should run code you chose, not whatever lands on `main` later. It refuses to commit private repos' data into a public repository (input `allow-public: true` overrides).
+
+   `"@me"` means you **and every organization you belong to**, including client or employer organizations whose repo names and traffic may not be yours to copy. List owners explicitly, or use `exclude = ["client-org/*"]`, when that matters.
+
+2. Create a token with push access to the repos you want: a [classic token with the `repo` and `read:org` scopes](https://github.com/settings/tokens/new?scopes=repo,read:org&description=ghtraffic) covers every owner you can push to (a fine-grained token is limited to one owner). Save it as the data repo's `GHTRAFFIC_TOKEN` secret:
+
+   ```bash
+   gh secret set GHTRAFFIC_TOKEN
+   ```
+
+3. Run it once by hand (`gh workflow run ghtraffic.yml`), and it will run on its own on Mondays and Thursdays from then on. The first run is the cold start: it takes the 14 days GitHub still has, plus each repo's star history. Every later run merges into what is there; re-running is always safe.
+
+## Look at it
+
+Open the dashboard at https://thorwhalen.github.io/ghtraffic/ and point it at your data repo, or use `#repo=<owner>/<data-repo>` in the URL. Paste a [fine-grained token](https://github.com/settings/personal-access-tokens/new) that can only **read the contents of that one repo**. Your browser fetches the data straight from the GitHub API with it. The page itself is public, holds no data, talks to no host but GitHub, and refuses to run inside a frame. The token stays in memory unless you tick "remember"; a remembered token is readable by any page on the same `<user>.github.io` origin, which is one more reason to give it read access to the data repo only. `?data=<url>` reads a public data directory from `raw.githubusercontent.com` instead.
+
+It shows totals and growth over any time range, by owner and repo, views or clones, totals or uniques, a sortable leaderboard with sparklines, top referrers and pages, and stars and forks over time.
+
+## Collect from your own computer
+
+```bash
+ghtraffic collect --owner @me                  # into ~/.local/share/ghtraffic/data
+ghtraffic collect --data-dir ./my-traffic-data # into a checkout of your data repo
+```
+
+The token comes from `GHTRAFFIC_TOKEN`, `GH_TOKEN` or `GITHUB_TOKEN`, or from the GitHub CLI (`gh auth login`).
+
+From Python:
+
+```python
+from ghtraffic import collect, load_settings, Files
+
+report = collect(load_settings(owners=["@me"], exclude=["my-org/sandbox-*"]), store=Files("~/traffic"))
+print(report.summary())
+```
+
+`store` is any `MutableMapping[str, str]` (relative path to text): a folder by default, or any [dol](https://github.com/i2mint/dol) store (S3, a database, ...). `rest=` and `graphql=` replace the HTTP transport.
+
+## Configuration
+
+`ghtraffic.toml`, at the data directory's root. Every key is optional.
+
+| key | default | meaning |
+|---|---|---|
+| `owners` | `["@me"]` | user and org logins; `"@me"` is you and every org you belong to |
+| `exclude` | `[]` | `owner/repo` glob patterns to skip (`"my-org/*"` skips an owner) |
+| `include_forks` | `true` | collect forks too |
+| `include_archived` | `true` | collect archived repos too |
+| `snapshot_every_days` | `14` | days between snapshots of referrers, paths and 14-day totals |
+| `backfill_stars` | `true` | rebuild a repo's star history the first time it is seen |
+| `max_workers` | `8` | concurrent requests |
+
+Unknown keys are refused (a typo never silently falls back to a default). Every key is also a `ghtraffic collect` flag (`--no-include-forks`, `--snapshot-every-days 7`, ...).
+
+Repos you cannot push to have no readable traffic: they are counted and listed in `last_run.json`, never an error. An organization policy refusing the token (SAML SSO, a ban on classic tokens) is an error, listed with the repo, so a whole org never silently reads as zero traffic. The Action log carries counts only; names and messages go to `last_run.json`.
+
+## Data layout
+
+Plain CSV, one table per kind, split by year, sorted by date so each run adds lines at the end of the current year's file. `manifest.json` lists every file and its columns.
+
+| file | rows |
+|---|---|
+| `views/YYYY.csv`, `clones/YYYY.csv` | `date,repo,count,uniques`: one per repo and day with any traffic (no row means zero) |
+| `windows/YYYY.csv` | `fetched,repo,kind,count,uniques`: 14-day totals at each snapshot, the only true 14-day unique counts |
+| `referrers/YYYY.csv`, `paths/YYYY.csv` | the top 10 over the 14 days before `fetched`; snapshots are 14 days apart, so they never overlap |
+| `stars.csv` | `date,repo,stars,forks,watchers`: a row only when something changed |
+| `repos.csv` | current metadata of every repo seen |
+| `backfills.csv` | when each repo's star history was rebuilt (a failed backfill is retried next run) |
+| `runs.csv`, `last_run.json` | one row per run; the last run's details (repos without access, errors) |
+
+A day seen by several runs keeps the largest value of each field, so overlapping windows, re-runs and partial days all merge to the same result. Why this layout, and the alternatives: [docs/adr/0001-storage.md](docs/adr/0001-storage.md).
+
+## Cost
+
+One job per run, about 1 minute (a few minutes for the cold start with star history). At two runs a week that is about 10 to 20 Actions minutes a month on a private repository, and two missed runs in a row still lose nothing. Data grows by a few MB a year for a few hundred repos.
+
+## Limits
+
+- GitHub keeps traffic for 14 days. Nothing earlier can be recovered, except star history.
+- Star history counts current stargazers by the date they starred; unstars are invisible.
+- Referrers and paths are GitHub's top 10 per repo only. Snapshots are 14 days apart so they can be added up; a missed snapshot run loses the referrer and path data of the days it slipped by (daily views and clones are unaffected).
+- One token for every owner means a classic token (fine-grained tokens are per owner).

ghtraffic-0.0.2/README.md

@@ -0,0 +1,110 @@
+# ghtraffic
+
+Keep your GitHub traffic for longer than 14 days, across all your repos and orgs, and explore it in a dashboard.
+
+GitHub shows a repo's views, clones, referrers and popular pages for the last 14 days only, one repo at a time. `ghtraffic` collects them for every repo you can push to, on a schedule, and merges each run into a growing history of small CSV files in a git repository you own. Star, fork and watcher counts come along, and star history is rebuilt back to each repo's creation. A static dashboard reads that history.
+
+**Dashboard (demo data):** https://thorwhalen.github.io/ghtraffic/
+
+## Quick start: collect with a GitHub Action
+
+1. Create a **private** repository for the data (it will hold the traffic of your private repos too), and add the workflow and config to it:
+
+   ```bash
+   pip install ghtraffic
+   gh repo create my-traffic-data --private --clone && cd my-traffic-data
+   ghtraffic init . --owner @me          # or: --owner me --owner my-org ...
+   git add -A && git commit -m "ghtraffic" && git push -u origin main
+   ```
+
+   `ghtraffic init` writes two files: `ghtraffic.toml` (what to collect) and `.github/workflows/ghtraffic.yml`, which is all the workflow needs:
+
+   ```yaml
+   - uses: actions/checkout@v4
+   - uses: thorwhalen/ghtraffic@0.0.2   # the release you installed; pin it
+     with:
+       token: ${{ secrets.GHTRAFFIC_TOKEN }}
+   ```
+
+   The Action is pinned to a release tag (or pin a commit SHA): the token it receives can read every repo it covers, so it should run code you chose, not whatever lands on `main` later. It refuses to commit private repos' data into a public repository (input `allow-public: true` overrides).
+
+   `"@me"` means you **and every organization you belong to**, including client or employer organizations whose repo names and traffic may not be yours to copy. List owners explicitly, or use `exclude = ["client-org/*"]`, when that matters.
+
+2. Create a token with push access to the repos you want: a [classic token with the `repo` and `read:org` scopes](https://github.com/settings/tokens/new?scopes=repo,read:org&description=ghtraffic) covers every owner you can push to (a fine-grained token is limited to one owner). Save it as the data repo's `GHTRAFFIC_TOKEN` secret:
+
+   ```bash
+   gh secret set GHTRAFFIC_TOKEN
+   ```
+
+3. Run it once by hand (`gh workflow run ghtraffic.yml`), and it will run on its own on Mondays and Thursdays from then on. The first run is the cold start: it takes the 14 days GitHub still has, plus each repo's star history. Every later run merges into what is there; re-running is always safe.
+
+## Look at it
+
+Open the dashboard at https://thorwhalen.github.io/ghtraffic/ and point it at your data repo, or use `#repo=<owner>/<data-repo>` in the URL. Paste a [fine-grained token](https://github.com/settings/personal-access-tokens/new) that can only **read the contents of that one repo**. Your browser fetches the data straight from the GitHub API with it. The page itself is public, holds no data, talks to no host but GitHub, and refuses to run inside a frame. The token stays in memory unless you tick "remember"; a remembered token is readable by any page on the same `<user>.github.io` origin, which is one more reason to give it read access to the data repo only. `?data=<url>` reads a public data directory from `raw.githubusercontent.com` instead.
+
+It shows totals and growth over any time range, by owner and repo, views or clones, totals or uniques, a sortable leaderboard with sparklines, top referrers and pages, and stars and forks over time.
+
+## Collect from your own computer
+
+```bash
+ghtraffic collect --owner @me                  # into ~/.local/share/ghtraffic/data
+ghtraffic collect --data-dir ./my-traffic-data # into a checkout of your data repo
+```
+
+The token comes from `GHTRAFFIC_TOKEN`, `GH_TOKEN` or `GITHUB_TOKEN`, or from the GitHub CLI (`gh auth login`).
+
+From Python:
+
+```python
+from ghtraffic import collect, load_settings, Files
+
+report = collect(load_settings(owners=["@me"], exclude=["my-org/sandbox-*"]), store=Files("~/traffic"))
+print(report.summary())
+```
+
+`store` is any `MutableMapping[str, str]` (relative path to text): a folder by default, or any [dol](https://github.com/i2mint/dol) store (S3, a database, ...). `rest=` and `graphql=` replace the HTTP transport.
+
+## Configuration
+
+`ghtraffic.toml`, at the data directory's root. Every key is optional.
+
+| key | default | meaning |
+|---|---|---|
+| `owners` | `["@me"]` | user and org logins; `"@me"` is you and every org you belong to |
+| `exclude` | `[]` | `owner/repo` glob patterns to skip (`"my-org/*"` skips an owner) |
+| `include_forks` | `true` | collect forks too |
+| `include_archived` | `true` | collect archived repos too |
+| `snapshot_every_days` | `14` | days between snapshots of referrers, paths and 14-day totals |
+| `backfill_stars` | `true` | rebuild a repo's star history the first time it is seen |
+| `max_workers` | `8` | concurrent requests |
+
+Unknown keys are refused (a typo never silently falls back to a default). Every key is also a `ghtraffic collect` flag (`--no-include-forks`, `--snapshot-every-days 7`, ...).
+
+Repos you cannot push to have no readable traffic: they are counted and listed in `last_run.json`, never an error. An organization policy refusing the token (SAML SSO, a ban on classic tokens) is an error, listed with the repo, so a whole org never silently reads as zero traffic. The Action log carries counts only; names and messages go to `last_run.json`.
+
+## Data layout
+
+Plain CSV, one table per kind, split by year, sorted by date so each run adds lines at the end of the current year's file. `manifest.json` lists every file and its columns.
+
+| file | rows |
+|---|---|
+| `views/YYYY.csv`, `clones/YYYY.csv` | `date,repo,count,uniques`: one per repo and day with any traffic (no row means zero) |
+| `windows/YYYY.csv` | `fetched,repo,kind,count,uniques`: 14-day totals at each snapshot, the only true 14-day unique counts |
+| `referrers/YYYY.csv`, `paths/YYYY.csv` | the top 10 over the 14 days before `fetched`; snapshots are 14 days apart, so they never overlap |
+| `stars.csv` | `date,repo,stars,forks,watchers`: a row only when something changed |
+| `repos.csv` | current metadata of every repo seen |
+| `backfills.csv` | when each repo's star history was rebuilt (a failed backfill is retried next run) |
+| `runs.csv`, `last_run.json` | one row per run; the last run's details (repos without access, errors) |
+
+A day seen by several runs keeps the largest value of each field, so overlapping windows, re-runs and partial days all merge to the same result. Why this layout, and the alternatives: [docs/adr/0001-storage.md](docs/adr/0001-storage.md).
+
+## Cost
+
+One job per run, about 1 minute (a few minutes for the cold start with star history). At two runs a week that is about 10 to 20 Actions minutes a month on a private repository, and two missed runs in a row still lose nothing. Data grows by a few MB a year for a few hundred repos.
+
+## Limits
+
+- GitHub keeps traffic for 14 days. Nothing earlier can be recovered, except star history.
+- Star history counts current stargazers by the date they starred; unstars are invisible.
+- Referrers and paths are GitHub's top 10 per repo only. Snapshots are 14 days apart so they can be added up; a missed snapshot run loses the referrer and path data of the days it slipped by (daily views and clones are unaffected).
+- One token for every owner means a classic token (fine-grained tokens are per owner).

ghtraffic-0.0.2/action.yml

@@ -0,0 +1,72 @@
+name: ghtraffic
+description: Collect GitHub traffic (views, clones, referrers, paths, stars) across your repos and orgs, and commit the accumulated history.
+branding:
+  icon: bar-chart-2
+  color: blue
+inputs:
+  token:
+    description: A token with push access to the repos to collect (classic, scopes `repo` + `read:org`, for several owners).
+    required: true
+  data-dir:
+    description: Where the history lives in the checked-out repository.
+    default: "."
+  config:
+    description: Path to ghtraffic.toml (default <data-dir>/ghtraffic.toml).
+    default: ""
+  commit:
+    description: Commit and push the updated history.
+    default: "true"
+  allow-public:
+    description: Allow committing private repos' data into a PUBLIC data repository (refused by default).
+    default: "false"
+  fail-on-errors:
+    description: Fail the job when some repo or owner errored (never for missing access).
+    default: "false"
+runs:
+  using: composite
+  steps:
+    - name: Collect and commit
+      shell: bash
+      env:
+        GHTRAFFIC_TOKEN: ${{ inputs.token }}
+        PYTHONPATH: ${{ github.action_path }}
+        DATA_DIR: ${{ inputs.data-dir }}
+        CONFIG: ${{ inputs.config }}
+        COMMIT: ${{ inputs.commit }}
+        ALLOW_PUBLIC: ${{ inputs.allow-public }}
+        FAIL_ON_ERRORS: ${{ inputs.fail-on-errors }}
+      run: |
+        set -euo pipefail
+        # ghtraffic needs only the standard library, but Python 3.11+ (tomllib).
+        python3 -c 'import sys; sys.exit(sys.version_info < (3, 11))' || {
+          echo "::error::ghtraffic needs Python 3.11+; add actions/setup-python before this step."; exit 1; }
+
+        args=(collect --data-dir "$DATA_DIR")
+        [ -n "$CONFIG" ] && args+=(--config "$CONFIG")
+        [ "$FAIL_ON_ERRORS" = "true" ] && args+=(--fail-on-errors)
+        status=0
+        python3 -m ghtraffic "${args[@]}" || status=$?
+        [ "$COMMIT" = "true" ] || exit $status
+
+        # Never put private repos' data into a public repository.
+        if [ "$ALLOW_PUBLIC" != "true" ]; then
+          python3 -m ghtraffic guard --data-dir "$DATA_DIR" --repo "$GITHUB_REPOSITORY"
+        fi
+
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        commit() {
+          git add -A "$DATA_DIR"
+          git diff --cached --quiet || git commit -q -m "ghtraffic: collect $(date -u +%F)"
+        }
+        commit
+        # On a push race, start from the remote and collect again: merges are
+        # idempotent, so re-collecting loses nothing and never conflicts.
+        for attempt in 1 2 3; do
+          git push -q && exit $status
+          git fetch -q origin "$GITHUB_REF_NAME"
+          git reset -q --hard "origin/$GITHUB_REF_NAME"
+          python3 -m ghtraffic "${args[@]}" || status=$?
+          commit
+        done
+        echo "::error::could not push after 3 attempts"; exit 1

ghtraffic-0.0.2/ghtraffic/__init__.py

@@ -0,0 +1,41 @@
+"""Accumulate GitHub traffic and insights across all your repos and orgs.
+
+GitHub keeps repository traffic (views, clones, referrers, popular paths) for
+14 days only. ``ghtraffic`` collects it on a schedule and merges it into a
+growing, git-friendly history of CSV files, together with star, fork and
+watcher counts, and ships a static dashboard to explore it.
+
+>>> from ghtraffic import collect, load_settings, Files   # doctest: +SKIP
+>>> collect(load_settings(owners=["@me"]), store=Files("~/traffic"))  # doctest: +SKIP
+
+Main pieces:
+
+- :func:`collect`: one idempotent run (cold start and update are the same call).
+- :func:`load_settings` / :class:`Settings`: which owners and repos.
+- :data:`TABLES`: the on-disk schema; :class:`Files`: the default store.
+- :func:`init_data_repo`: write the workflow + config into a data repository.
+"""
+
+from ghtraffic.collect import RunReport, collect, write_manifest
+from ghtraffic.config import Settings, load_settings
+from ghtraffic.github import GitHubError, make_graphql, make_rest, resolve_token
+from ghtraffic.scaffold import init_data_repo
+from ghtraffic.tables import TABLES, Files, TableSpec, merge_rows, read_table
+
+__all__ = [
+    "Files",
+    "GitHubError",
+    "RunReport",
+    "Settings",
+    "TABLES",
+    "TableSpec",
+    "collect",
+    "init_data_repo",
+    "load_settings",
+    "make_graphql",
+    "make_rest",
+    "merge_rows",
+    "read_table",
+    "resolve_token",
+    "write_manifest",
+]

ghtraffic-0.0.2/ghtraffic/__main__.py

@@ -0,0 +1,134 @@
+"""Command line: ``ghtraffic collect | init | guard | demo | manifest``.
+
+``python -m ghtraffic collect --data-dir .`` is what the GitHub Action runs.
+Without ``--data-dir``, data goes to ``~/.local/share/ghtraffic/data`` (never
+the current directory, so a local run cannot end up committed by accident).
+Every :class:`~ghtraffic.config.Settings` field is also a ``collect`` flag.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import typing
+from dataclasses import fields
+from pathlib import Path
+
+from ghtraffic.collect import collect, has_private_data, write_manifest
+from ghtraffic.config import (
+    DFLT_CONFIG_FILENAME,
+    DFLT_DATA_DIR,
+    Settings,
+    load_settings,
+)
+from ghtraffic.scaffold import DFLT_CRON, default_action_ref, init_data_repo
+from ghtraffic.tables import Files
+
+
+def _add_settings_flags(parser: argparse.ArgumentParser) -> None:
+    """One flag per Settings field, so a new setting needs no CLI edit."""
+    hints = typing.get_type_hints(Settings)
+    for f in fields(Settings):
+        flag = "--" + f.name.replace("_", "-")
+        kind = hints[f.name]
+        if kind is bool:
+            parser.add_argument(flag, action=argparse.BooleanOptionalAction)
+        elif typing.get_origin(kind) is tuple:
+            parser.add_argument(flag, action="append", help="repeatable")
+        else:
+            parser.add_argument(flag, type=kind)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="ghtraffic", description=__doc__.splitlines()[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("collect", help="fetch traffic and merge it into the data dir")
+    c.add_argument("--data-dir", default=str(DFLT_DATA_DIR))
+    c.add_argument("--config", help=f"default: <data-dir>/{DFLT_CONFIG_FILENAME}")
+    c.add_argument(
+        "--fail-on-errors",
+        action="store_true",
+        help="exit 1 when some repo or owner failed (never for missing access)",
+    )
+    _add_settings_flags(c)
+
+    i = sub.add_parser("init", help="write the workflow and config into a data repo")
+    i.add_argument("dir", nargs="?", default=".")
+    i.add_argument("--owner", action="append", dest="owners")
+    i.add_argument("--cron", default=DFLT_CRON)
+    i.add_argument("--action-ref", help="default: this ghtraffic's release tag")
+    i.add_argument("--overwrite", action="store_true")
+
+    g = sub.add_parser(
+        "guard", help="exit 1 if private data would be committed to a public repo"
+    )
+    g.add_argument("--data-dir", default=".")
+    g.add_argument("--repo", required=True, help="owner/name of the data repo")
+
+    d = sub.add_parser(
+        "demo", help="write a synthetic data dir (for the demo dashboard)"
+    )
+    d.add_argument("--data-dir", required=True)
+    d.add_argument("--days", type=int, default=420)
+
+    m = sub.add_parser("manifest", help="rewrite manifest.json from the files present")
+    m.add_argument("--data-dir", default=str(DFLT_DATA_DIR))
+    return p
+
+
+def _guard(data_dir: str, repo: str) -> int:
+    from ghtraffic.github import make_rest
+
+    if not make_rest()(f"/repos/{repo}").get("private", False) and has_private_data(
+        Files(data_dir)
+    ):
+        print(
+            f"ghtraffic: REFUSING to commit: {repo} is public and the history "
+            "holds private repos. Make the data repo private, or exclude private "
+            "repos, or set the action input allow-public: true.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+def main(argv=None) -> int:
+    """Entry point of the ``ghtraffic`` command."""
+    args = _parser().parse_args(argv)
+    if args.cmd == "collect":
+        data_dir = Path(args.data_dir)
+        overrides = {f.name: getattr(args, f.name) for f in fields(Settings)}
+        settings = load_settings(
+            args.config or data_dir / DFLT_CONFIG_FILENAME, **overrides
+        )
+        report = collect(settings, store=Files(data_dir), log=print)
+        failed = report.errors or report.owner_errors
+        return 1 if (args.fail_on_errors and failed) else 0
+    if args.cmd == "init":
+        written = init_data_repo(
+            args.dir,
+            owners=args.owners or ("@me",),
+            cron=args.cron,
+            action_ref=args.action_ref or default_action_ref(),
+            overwrite=args.overwrite,
+        )
+        print("\n".join(written) or "nothing written (files exist; --overwrite)")
+        return 0
+    if args.cmd == "guard":
+        return _guard(args.data_dir, args.repo)
+    if args.cmd == "demo":
+        from ghtraffic.demo import make_demo_data
+
+        make_demo_data(Files(args.data_dir), n_days=args.days)
+        return 0
+    if args.cmd == "manifest":
+        from datetime import date
+
+        write_manifest(Files(args.data_dir), updated=date.today().isoformat())
+        return 0
+    return 2  # pragma: no cover
+
+
+if __name__ == "__main__":
+    sys.exit(main())