GITPULSE

A GitHub profile is a scroll. It gives you a follower count and a green calendar and leaves you to assemble everything else across a dozen tabs. The terminal tools that try to fix this mostly inherit a subtler problem: they are built on the public Events API, which returns at most 300 events over a variable and often short period, and then print a fixed "last 90 days" header over whatever they happened to get. The number on screen and the label above it describe different things, on a page about a real person.

A TypeScript CLI that reads three public REST endpoints — user, repositories, public events — and computes everything else locally, rendering one screen: profile, statistics, language share, ranked repositories, a code-activity heatmap, commit patterns by day and hour, coding streaks, and a 0–100 score with a letter grade. The rule the whole thing is built on is that when the label and the data would disagree, the label changes and the data does not: the activity span is derived from the oldest event the feed actually returned and printed next to the number, and a streak carries "measured within the 30-day event window above, not all-time". The score's methodology, inputs and weights ship inside the package as SCORING.md, so the number is checkable rather than asserted.

GitHub's own profile page will tell you a follower count and show you a green calendar, then leave you to assemble everything else across a dozen tabs. gitpulse renders the same public data as one screen in the terminal: profile, statistics, language share, ranked repositories, a code-activity heatmap, commit patterns by day and hour, coding streaks, and a 0–100 score with a letter grade.

What separates it from the other terminal GitHub tools is not the rendering, it is the labelling. The public Events API returns at most 300 events and reaches back a limited and variable period — often far less than 90 days for an active account. Most tools built on it print a fixed "last 90 days" header over whatever they got. gitpulse derives the window from the oldest event the feed actually returned and prints that window beside the number, so a heatmap says `last 30 days of public code events 2026-07-16 → 2026-08-14` and a streak says `measured within the 30-day event window above, not all-time`. When the label and the data would disagree, the label changes.

The output is the product, so the output is what CI enforces. Committed snapshots pin what every renderer emits byte for byte, the demo is rendered on every push, and the piped output is scanned for emoji and stray ANSI escapes so scripts get clean text. The score is the part that needed a caveat rather than a feature bullet, so it has one: it reads public metadata only, never opens a line of anyone's code, and SCORING.md ships inside the package documenting every input and weight — and what the number cannot see — before it gives any formula.

TypeScript, ESM, strict mode, Node 20+. Three runtime dependencies: chalk for colour, commander for the flag surface, ora for the spinner.

One network surface, `src/api/github.ts`, reading three REST endpoints — `/users/:name`, `/users/:name/repos` (owner-type, capped at 200) and `/users/:name/events/public` (capped at 300, tolerant of the endpoint's known flakiness). Nothing else touches the wire. Results cache for 30 minutes under `~/.gitpulse/cache`, evicting at 50 profiles.

The pipeline is deliberately cut in the middle: `buildProfile()` is split out of `fetchUserProfile()`, so the network path and the bundled `--demo` fixture converge on the same derivation. `src/utils/scoring.ts` computes language share, the contribution window, streaks, commit patterns and the five score components from that single structure. Nine renderers in `src/ui/` turn it into text; `src/utils/anim.ts` stages the reveal.

The animation contract is carried by the type signature: every animated renderer takes `progress: number = 1`, and at `progress === 1` returns exactly the string the static path returns. The last frame is the real output, so the animated and unanimated paths cannot drift.

CI runs on every push to every branch across Node 20, 22 and 24: lint, typecheck of source and tests, build, the suite, an assertion that `dist/__tests__` does not exist, a real render of the demo, a render with `fetch` stubbed to throw, a scan of the piped output for emoji and ANSI escapes, and `npm pack --dry-run`.

The work did not start from a feature list. It started from a measured audit (RESEARCH-CONTEXT.md, committed to the public repo) whose verdict was uncomfortable: the tool worked, looked finished, and its own documented first command did not run. `gitpulse torvalds` with no token hit GitHub's 60-requests-per-hour unauthenticated cap, because only the `--token` flag was honoured and most machines have already spent that per-IP budget on something else. A first-time user ran the command printed in the README, got an error, and concluded the tool was broken. Everything else in the backlog was worth less than that.

The first-run fix was roughly twenty lines: read GITHUB_TOKEN and GH_TOKEN from the environment, split the single 403 branch into primary rate limit, secondary rate limit and bad credentials so the message names the actual problem, and add `--demo` so the output is reachable with no setup at all.

Then the numbers were made to agree with their labels. `generateContributions` had been counting every public event type as a "contribution" under a hardcoded `Last 90 days:` header, while reporting an active-day count derived from a third window — three windows, one label, on a screen about a real person. The rewrite counts only code events and derives the span from real coverage. Its own first implementation then widened the window to GitHub's nominal 90-day retention whenever the 300-event cap was not hit, which rendered torvalds as a 90-day grid containing 60 days of fabricated inactivity for a feed that only reaches back 30. The sprint's acceptance gate caught it before it shipped, which is the single most useful thing that happened in this project.

Four more defects surfaced the same way — by rendering real profiles and reading the result rather than by trusting a green suite. `src/__tests__/cache.test.ts` was asserting an inline expression and importing no product code at all, so two of the then-33 passing tests verified nothing; it was replaced with tests against the real module. Test helpers were compiling into `dist/` and would have shipped inside the packed tarball, so CI now fails if `dist/__tests__` reappears. `boxen` and `node-fetch` were declared as runtime dependencies and imported nowhere, worth 24 packages in the install tree of a project whose first rule is no runtime bloat — removing them left three. And three separate renderers stamped wall-clock time into their output, so the same profile produced different bytes on every run.

A second independent re-audit at the end, run against a live render rather than against the draft, found seven further defects inside gates that had already been marked passed. That pass is written up in masterplan.md, which is committed, so the failures are readable by anyone who wants to check the account.

Matrix CI on Node 20, 22 and 24 earned its place on the first run by failing on all three. The failure was real rather than flaky: Math.sin, cos, sqrt and log2 are not required to be bit-identical across platforms and are not, so the Three.js scene export produced x = 4.044661788320042 on macOS and …043 on Linux. A scene that differs between machines cannot be diffed or cached, which defeats the point of a contract another tool consumes, so every derived float is now quantised to six decimal places (src/ui/export.ts) with a regression test behind it.

Writing the scoring methodology meant checking the weights instead of describing them, which produced the most interesting correction in the project. The star sub-item is `Math.min(8, log2(stars + 1) * 1.5)`, which saturates at 40 stars — not the ~215 the first draft of the document claimed. Above 40 stars that input stops discriminating entirely, so a 250,000-star repository scores identically to a 40-star one. SCORING.md now says so, because it materially changes how the number should be read.

`--no-anim` was verified byte-identical to the staged render by replaying the animated stream through a minimal ANSI interpreter and diffing the result, rather than by asserting that it ought to be.