@kody/lineage
Interactive commit-level lines of kody, minus generated noise, as an offline-ready chart.
Files
@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
maincommits 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
- Tracked repo defaults to
kody-hq/kodyonmain(override via./settingswithout republishing). - The
github-pushwebhook uses package-owned HMAC (x-hub-signature-256): Kody stores the signing secret on the minted webhook URL, andwebhookUrlApplywrites it into the GitHub hook. No user secret to create. - Depends on
@kody/githubfor GitHub API access used by ingest / backfill. - Prefer event-driven webhook ingest; the
backfill-missingcron (every 30m, America/Denver) is catch-up only — do not disable live webhooks or jobs. - Hosted app: https://lineage--kody.kody.run/
- Agents: see
AGENTS.mdfor 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 thesettingsexport; a stored setting always wins over the default. - GitHub account —
@kody/githubhas onegithubcredential 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 insrc/ui/art/. - Hosted address fallback —
fallbackHostedOrigin/fallbackAppBasePath, only used if Kody does not provide them. - Story annotations —
src/annotations.tsholds the labelled kody milestones. They only match commits inkody-hq/kody, so empty or replace the list for your repo, or add your own labels later withcommentary.
Credentials you need
- A GitHub connection (OAuth) through your own fork of the public
@kody/githubpackage. 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 andkody.dependenciesat your copy. - No webhook secret to create: the
github-pushwebhook uses package-owned HMAC that Kody stores when you mint the webhook URL.
Point it at your repo
- Fork this package (and
@kody/githubif you are outside the kody org), then editsrc/config.ts. - Publish your fork and mint its
github-pushwebhook URL. - In your GitHub repo, add a webhook for push events pointing at your
fork's
github-pushwebhook URL with its signing secret (webhookUrlApplydoes both without showing either), then click Approve to turn it on. - 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/kodyfor Kent) ./statusreports stored commits; webhook or backfill fills gaps- Generated files stay out of countable totals; commentaries open from chart labels