"""coding-agent-release-cadence.py - count how often three coding-agent CLIs ship, from the
registries' own publish timestamps, and check two published release promises against them:
Claude Code's stable channel ("typically about one week old") and Gemini CLI's weekly schedule
("Each Tuesday ~20:00 UTC").

Inputs, all public and keyless:
  https://registry.npmjs.org/@anthropic-ai/claude-code    every version and its publish time
  https://registry.npmjs.org/@openai/codex
  https://registry.npmjs.org/@google/gemini-cli
  https://downloads.claude.ai/claude-code/rpm/stable/repodata/repomd.xml, then the primary.xml.gz
      it names: Anthropic's stable-channel RPM repository. Each package carries <time file="...">,
      the file time the index records for it; this script uses that as the moment a version
      reached the stable channel.
  --crosscheck adds three independent records: Anthropic's latest-channel RPM repository, each
      project's GitHub releases, and the commit history of Homebrew's claude-code cask, which
      Anthropic's setup page says tracks the stable channel (GitHub API, unauthenticated,
      about ten requests).

What counts as what:
  release         a plain x.y.z version, the kind `npm install -g <package>` resolves through `latest`
  alpha, preview, nightly, rc, dev   pre-release builds, named by their version suffix
  platform build  Codex publishes each native binary as its own version (x.y.z-linux-x64 and so
                  on); these are packaging, not releases, and are left out of every count

Standard library only; Python 3.9 or later.
Run:
  python coding-agent-release-cadence.py                     # live data, window = Q3 2026
  python coding-agent-release-cadence.py --start 2026-07-01 --end 2026-10-01
  python coding-agent-release-cadence.py --cache saved/      # reuse saved responses, save new ones
  python coding-agent-release-cadence.py --after claude-code=2.1.274 --after codex=0.154.0
  python coding-agent-release-cadence.py --crosscheck --csv releases.csv
Window bounds are UTC dates; --end is exclusive.
"""
from __future__ import annotations

import argparse
import csv
import datetime as dt
import gzip
import json
import os
import re
import statistics
import sys
import urllib.request
from collections import Counter

UTC = dt.timezone.utc
UA = "coding-agent-release-cadence/1.0 (+https://vibecodetextbook.com)"
TOOLS = {  # tool: (npm package, GitHub repository, GitHub tag prefix)
    "claude-code": ("@anthropic-ai/claude-code", "anthropics/claude-code", "v"),
    "codex": ("@openai/codex", "openai/codex", "rust-v"),
    "gemini-cli": ("@google/gemini-cli", "google-gemini/gemini-cli", "v"),
}
CC_REPO = "https://downloads.claude.ai/claude-code/rpm/{channel}/"
CASK_COMMITS = ("https://api.github.com/repos/Homebrew/homebrew-cask/commits"
                "?path=Casks/c/claude-code.rb&since={since}T00:00:00Z&per_page=100")
PLATFORM = re.compile(r"-(linux|darwin|win32)-(x64|arm64)$")


def fetch(url: str, cache: str | None, name: str) -> bytes:
    """GET url, or read it from cache/name when present (and save it there when not)."""
    path = os.path.join(cache, name) if cache else None
    if path and os.path.exists(path):
        with open(path, "rb") as f:
            return f.read()
    headers = {"User-Agent": UA, "Accept": "application/json, */*"}
    with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=120) as r:
        raw = r.read()
    if path:
        os.makedirs(cache, exist_ok=True)
        with open(path, "wb") as f:
            f.write(raw)
    return raw


def ts(s: str) -> dt.datetime:
    return dt.datetime.fromisoformat(s.replace("Z", "+00:00"))


def days(a: dt.datetime, b: dt.datetime) -> float:
    return (b - a).total_seconds() / 86400


def kind(version: str) -> str:
    if PLATFORM.search(version):
        return "platform build"
    if re.fullmatch(r"\d+\.\d+\.\d+", version):
        return "release"
    m = re.search(r"-(alpha|preview|nightly|rc|dev)\b", version)
    return m.group(1) if m else "other"


def npm_versions(tool: str, cache: str | None) -> tuple[dict, dict]:
    """version -> publish time for every version still listed, plus the dist-tags."""
    pkg = TOOLS[tool][0]
    name = "npm_" + pkg.replace("@", "").replace("/", "__") + ".json"
    doc = json.loads(fetch("https://registry.npmjs.org/" + pkg.replace("/", "%2F"), cache, name))
    listed = set(doc["versions"])   # the time map also keeps versions that were unpublished
    times = {v: ts(t) for v, t in doc["time"].items() if v in listed}
    return times, doc.get("dist-tags", {})


def rpm_index(channel: str, cache: str | None) -> tuple[dict, dt.datetime]:
    """Claude Code version -> file time recorded in that channel's RPM index (earliest arch)."""
    base = CC_REPO.format(channel=channel)
    repomd = fetch(base + "repodata/repomd.xml", cache, f"cc_rpm_{channel}_repomd.xml").decode()
    primary = re.search(r'<data type="primary">(.*?)</data>', repomd, re.S).group(1)
    href = re.search(r'<location href="([^"]+)"', primary).group(1)
    stamp = int(re.search(r"<timestamp>(\d+)</timestamp>", primary).group(1))
    xml = gzip.decompress(fetch(base + href, cache, f"cc_rpm_{channel}_primary.xml.gz")).decode()
    out = {}
    for pkg in re.findall(r'<package type="rpm">(.*?)</package>', xml, re.S):
        ver = re.search(r'<version epoch="\d+" ver="([^"]+)"', pkg).group(1)
        when = dt.datetime.fromtimestamp(int(re.search(r'<time file="(\d+)"', pkg).group(1)), UTC)
        out[ver] = min(out.get(ver, when), when)
    return out, dt.datetime.fromtimestamp(stamp, UTC)


def github_releases(tool: str, cache: str | None, since: dt.datetime) -> dict:
    """tag-stripped version -> GitHub release publish time, paging newest-first back to `since`."""
    repo, prefix = TOOLS[tool][1], TOOLS[tool][2]
    out, page = {}, 1
    while page <= 12:
        url = f"https://api.github.com/repos/{repo}/releases?per_page=100&page={page}"
        rels = json.loads(fetch(url, cache, f"gh_{tool}_releases_p{page}.json"))
        dated = [ts(r["published_at"]) for r in rels if r["published_at"]]
        for r in rels:
            if not r["draft"] and r["tag_name"].startswith(prefix) and r["published_at"]:
                out[r["tag_name"][len(prefix):]] = ts(r["published_at"])
        if not dated or min(dated) < since:
            break
        page += 1
    return out


def cask_history(cache: str | None, since: dt.date) -> dict:
    """Claude Code version -> first commit time of Homebrew's stable claude-code cask at it."""
    commits = json.loads(fetch(CASK_COMMITS.format(since=since.isoformat()), cache, "homebrew_cask_stable.json"))
    out = {}
    for c in commits:
        m = re.fullmatch(r"claude-code (\d+\.\d+\.\d+)", c["commit"]["message"].splitlines()[0])
        if m:
            when = ts(c["commit"]["committer"]["date"])
            out[m.group(1)] = min(out.get(m.group(1), when), when)
    return out


def cadence(rows: list) -> dict:
    """rows = [(version, time)] sorted by time: count, active days, median and longest gap."""
    gaps = [(days(a[1], b[1]), a[0], b[0]) for a, b in zip(rows, rows[1:])]
    return {"n": len(rows), "days": len({t.date() for _, t in rows}),
            "median_gap": statistics.median(g for g, _, _ in gaps) if gaps else 0.0,
            "longest": max(gaps) if gaps else (0.0, "-", "-"),
            "first": rows[0][0] if rows else "-", "last": rows[-1][0] if rows else "-"}


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    ap.add_argument("--start", default="2026-07-01")
    ap.add_argument("--end", default="2026-10-01")
    ap.add_argument("--cache", help="directory for saved responses (read if present, written if not)")
    ap.add_argument("--after", action="append", default=[], metavar="TOOL=VERSION",
                    help="also count releases published after this version (repeatable)")
    ap.add_argument("--crosscheck", action="store_true",
                    help="compare with the latest RPM repository, GitHub releases and the Homebrew cask")
    ap.add_argument("--csv", help="write one row per non-platform version published since --start "
                                  "(plus Claude Code versions promoted to stable since --start)")
    a = ap.parse_args()
    sys.stdout.reconfigure(encoding="utf-8")
    start = dt.datetime.fromisoformat(a.start).replace(tzinfo=UTC)
    end = dt.datetime.fromisoformat(a.end).replace(tzinfo=UTC)
    span = (end - start).days

    def inside(t):
        return start <= t < end

    data = {tool: npm_versions(tool, a.cache) for tool in TOOLS}
    print(f"Window {a.start} to {(end - dt.timedelta(days=1)).date()} UTC ({span} days); "
          "a release is a plain x.y.z version on npm\n")
    print(f"{'tool':<12}{'releases':>9}{'days':>6}{'median gap':>12}{'longest gap':>13}   first -> last")
    rel = {}
    for tool, (times, _) in data.items():
        rel[tool] = sorted(((v, t) for v, t in times.items() if kind(v) == "release" and inside(t)),
                           key=lambda r: r[1])
        c = cadence(rel[tool])
        print(f"{tool:<12}{c['n']:>9}{c['days']:>6}{c['median_gap']:>10.2f} d{c['longest'][0]:>11.2f} d"
              f"   {c['first']} -> {c['last']}")
    print()
    for tool, (times, tags) in data.items():
        c = cadence(rel[tool])
        other = Counter(kind(v) for v, t in times.items() if inside(t) and kind(v) != "release")
        other_txt = ", ".join(f"{k} {n}" for k, n in sorted(other.items())) or "none"
        tag_txt = ", ".join(f"{n} {tags[n]}" for n in ("latest", "stable", "preview", "nightly", "alpha") if n in tags)
        print(f"{tool}: longest gap {c['longest'][1]} -> {c['longest'][2]}; "
              f"other builds in window: {other_txt}; dist-tags today: {tag_txt}")

    # Claude Code: the stable channel, measured from Anthropic's stable RPM repository
    promo, index_time = rpm_index("stable", a.cache)
    cc = data["claude-code"][0]
    win = sorted((t, v) for v, t in promo.items() if inside(t) and v in cc)
    ages = [days(cc[v], t) for t, v in win]
    reached = [v for v, _ in rel["claude-code"] if v in promo]
    wait = max((days(p[0], q[0]), p[1], q[1]) for p, q in zip(win, win[1:]))
    print(f"\nClaude Code stable channel (stable RPM index dated {index_time:%Y-%m-%d %H:%M} UTC)")
    print(f"  promotions in window: {len(win)}; age at promotion: median {statistics.median(ages):.2f} d, "
          f"min {min(ages):.2f} d, max {max(ages):.2f} d, {sum(1 for x in ages if 6 <= x <= 10)} of {len(ages)} "
          "between 6 and 10 d")
    print(f"  window releases that reached stable: {len(reached)} of {len(rel['claude-code'])}; "
          f"longest wait between promotions {wait[0]:.2f} d ({wait[1]} -> {wait[2]})")
    for t, v in win:
        if not 6 <= days(cc[v], t) <= 10:
            print(f"    {v:<8} released {cc[v]:%d %b %H:%M}, promoted {t:%d %b %H:%M}, {days(cc[v], t):5.2f} d")

    # Gemini CLI: the stated weekly schedule against the publish times
    gem = data["gemini-cli"][0]
    first_of_line = {}
    for v, t in sorted(((v, t) for v, t in gem.items() if kind(v) == "release"), key=lambda r: r[1]):
        first_of_line.setdefault(v.rsplit(".", 1)[0], (v, t))
    lines = sorted((t, v) for v, t in first_of_line.values() if inside(t))
    print(f"\nGemini CLI: {len(lines)} minor lines first reached stable in window, "
          f"{sum(1 for t, _ in lines if t.weekday() == 1)} of them on a Tuesday (UTC)")
    for t, v in lines:
        pre = gem.get(v + "-preview.0")
        note = f"{days(pre, t):5.2f} d after {v}-preview.0" if pre else "no -preview.0 published"
        print(f"  {v:<8}{t:%a %d %b %H:%M}   {note}")
    nightly = [t for v, t in gem.items() if kind(v) == "nightly" and inside(t)]
    hours = ", ".join(f"{h:02d}h {n}" for h, n in sorted(Counter(t.hour for t in nightly).items()))
    print(f"  nightly builds: {len(nightly)} on {len({t.date() for t in nightly})} of {span} days; "
          f"publish hour UTC: {hours}")

    if a.after:
        print()
    for spec in a.after:   # releases after a named version, e.g. the one an article was written against
        tool, ver = spec.split("=", 1)
        times = data[tool][0]
        later = sorted((t, v) for v, t in times.items() if kind(v) == "release" and t > times[ver])
        print(f"{tool} after {ver} (published {times[ver]:%Y-%m-%d}): "
              f"{len(later)} releases, newest {later[-1][1] if later else '-'}")

    gh, cask = {}, {}
    if a.crosscheck:
        print("\nCross-checks")
        latest_repo, _ = rpm_index("latest", a.cache)
        mine = [v for v, _ in rel["claude-code"]]
        print(f"  claude-code: {sum(1 for v in mine if v in latest_repo)} of {len(mine)} releases are in the "
              f"latest-channel RPM repository (absent: {', '.join(v for v in mine if v not in latest_repo) or 'none'})")
        for tool in TOOLS:
            gh[tool] = github_releases(tool, a.cache, start)
            mine = [v for v, _ in rel[tool]]
            missing = [v for v in mine if v not in gh[tool]]
            lag = [(gh[tool][v] - data[tool][0][v]).total_seconds() / 60 for v in mine if v in gh[tool]]
            print(f"  {tool}: {len(mine) - len(missing)} of {len(mine)} releases have a GitHub release "
                  f"(absent: {', '.join(missing) or 'none'}); GitHub minus npm, median {statistics.median(lag):.1f} min")
        cask = cask_history(a.cache, (start - dt.timedelta(days=30)).date())
        both = [v for t, v in win if v in cask]
        hrs = {v: (cask[v] - promo[v]).total_seconds() / 3600 for v in both}
        print(f"  Homebrew claude-code cask: moved through {len(both)} of the {len(win)} promoted versions "
              f"(same set: {set(both) == {v for _, v in win}}); {sum(1 for h in hrs.values() if 0 <= h <= 6)} "
              "moves came 0 to 6 h after the RPM file time")
        for v in both:
            if not 0 <= hrs[v] <= 6:
                print(f"    {v:<8} cask {cask[v]:%d %b %H:%M}, RPM file {promo[v]:%d %b %H:%M} ({hrs[v]:+.1f} h); "
                      f"age by the cask {days(cc[v], cask[v]):.2f} d")

    if a.csv:
        with open(a.csv, "w", newline="", encoding="utf-8") as f:
            w = csv.writer(f, lineterminator="\n")
            w.writerow(["tool", "version", "kind", "npm_published_utc", "github_release_utc",
                        "stable_repo_utc", "homebrew_stable_cask_utc"])

            def fmt(t):
                return t.strftime("%Y-%m-%dT%H:%M:%SZ") if t else ""
            for tool, (times, _) in data.items():
                cc_row = tool == "claude-code"
                for v, t in sorted(times.items(), key=lambda r: r[1]):
                    promoted_in_range = cc_row and v in promo and promo[v] >= start
                    if (t >= start or promoted_in_range) and kind(v) != "platform build":
                        w.writerow([tool, v, kind(v), fmt(t), fmt(gh.get(tool, {}).get(v)),
                                    fmt(promo.get(v)) if cc_row else "", fmt(cask.get(v)) if cc_row else ""])
        print(f"\nwrote {a.csv}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())