Skip to content
← Public packages

@kody/lineage

Interactive commit-level lines of kody, minus generated noise, as an offline-ready chart.

FollowForkOpen app

Files

README.md

100 lines · 4.6 KB · Markdown

@kody/lineage

Intent

Give Kent (and anyone who forks it) an interactive, commit-level look at countable lines in a GitHub repo — by default kody-hq/kody, not use-kody, which has no application source. The app should ignore generated output even when that output is committed (Wrangler types, lockfiles, generated/ trees, Linguist-generated paths, and @generated / DO NOT EDIT headers), store the series in this package's storage, and stay useful offline as an installable PWA. Success is a graph you can slice by time, language, and type (source / tests / docs), with linked commits and short labels that open a longer narrative.

What it does

  • Hosted chart app with cumulative, added/removed, and net-per-commit modes
  • Backfill and ingest helpers write commit buckets into packageStorage()
  • GitHub push webhook fills new main commits as they land
  • Commentary helpers attach short labels and longer narratives to commits
  • Status / series / inspect helpers for agents and the UI to share the same numbers

Prerequisites / setup

  1. Tracked repo defaults to kody-hq/kody on main (override via ./settings without republishing).
  2. The github-push webhook uses package-owned HMAC (x-hub-signature-256): Kody stores the signing secret on the minted webhook URL, and webhookUrlApply writes it into the GitHub hook. No user secret to create.
  3. Depends on @kody/github for GitHub API access used by ingest / backfill.
  4. Prefer event-driven webhook ingest; the backfill-missing cron (every 30m, America/Denver) is catch-up only — do not disable live webhooks or jobs.
  5. Hosted app: https://lineage--kody.kody.run/
  6. Agents: see AGENTS.md for import paths and smoke checks.

Commits or dates on the x axis

The X axis control under the chart switches between Commits (the default: every commit gets the same width) and Date (a linear time scale, so busy days spread out and quiet stretches show as gaps). Link the date view with ?xaxis=date, e.g. https://lineage--kody.kody.run/?xaxis=date. It combines with ?labels=off.

Hiding the labels

The Labels toggle under the chart hides the story markers and their text (the chart data stays the same). Labels are on by default. To link or screenshot the chart without them, add ?labels=off to the app URL, e.g. https://lineage--kody.kody.run/?labels=off.

Make it yours (forking)

Lineage works for any GitHub repository the GitHub connection can read. Kent's copy keeps charting kody-hq/kody; a fork changes a few settings.

What to change — everything owner-specific is in one file, src/config.ts:

  • Repository — defaultRepo (owner, repo, branch). You can also switch repos later without republishing by calling the settings export; a stored setting always wins over the default.
  • GitHub account — @kody/github has one github credential slot. Map it to a read-only GitHub connection (a bot account is enough) with a default credential mapping on this package.
  • Branding — app name, description, and theme colours under branding. The icons and preview image live in src/ui/art/.
  • Hosted address fallback — fallbackHostedOrigin / fallbackAppBasePath, only used if Kody does not provide them.
  • Story annotations — src/annotations.ts holds the labelled kody milestones. They only match commits in kody-hq/kody, so empty or replace the list for your repo, or add your own labels later with commentary.

Credentials you need

  • A GitHub connection (OAuth) through your own fork of the public @kody/github package. Read-only access to the repo is enough. Kody packages can't import across accounts, so fork that package too and point Lineage's import and kody.dependencies at your copy.
  • No webhook secret to create: the github-push webhook uses package-owned HMAC that Kody stores when you mint the webhook URL.

Point it at your repo

  1. Fork this package (and @kody/github if you are outside the kody org), then edit src/config.ts.
  2. Publish your fork and mint its github-push webhook URL.
  3. In your GitHub repo, add a webhook for push events pointing at your fork's github-push webhook URL with its signing secret (webhookUrlApply does both without showing either), then click Approve to turn it on.
  4. Run a backfill once (or wait for the 30-minute catch-up job) and open your fork's hosted app.

Done when

  • Hosted app loads and shows a countable series for the tracked repo (kody-hq/kody for Kent)
  • ./status reports stored commits; webhook or backfill fills gaps
  • Generated files stay out of countable totals; commentaries open from chart labels