@kody/lineage
Interactive commit-level lines of kody, minus generated noise, as an offline-ready chart.
Files
@kody/lineage — agent notes
Human setup and intent live in README.md. This file is for
agents: imports, smoke checks, snippets, and edge cases. Secrets by name
only — never paste secret values. Do not disable live webhooks or jobs.
Secrets / surfaces
| Name | Kind | Notes |
|---|---|---|
| (package-owned HMAC) | webhook record | github-push verifies x-hub-signature-256 with the HMAC Kody stores on the minted webhook URL; no user secret |
- Job:
backfill-missing(cron*/30 * * * *, timezone America/Denver) — catch-up only; keep enabled. - Webhook:
github-push→./handle-github-webhook(responseMode: ack). - Hosted app:
https://lineage--kody.kody.run/ - Dependency:
@kody/github(public, same org). Lineage inherits its onegithubcredential slot. The job and webhook need a default credential mapping forgithubon@kody/lineage(read-only GitHub connection). - Owner-specific values:
src/config.ts(lineageConfig) andsrc/annotations.ts(primitiveStories). Defaults are Kent's live values; changing them changes what his app shows, so don't edit them on his copy.
Import paths
| Export | Import |
|---|---|
| overview | kody:@kody/lineage |
| status | kody:@kody/lineage/status |
| series | kody:@kody/lineage/series |
| settings | kody:@kody/lineage/settings |
| backfill | kody:@kody/lineage/backfill |
| backfill-continue | kody:@kody/lineage/backfill-continue |
| ingest-missing | kody:@kody/lineage/ingest-missing |
| handle-github-webhook | kody:@kody/lineage/handle-github-webhook |
| commentary | kody:@kody/lineage/commentary |
| inspect-commit | kody:@kody/lineage/inspect-commit |
| reset-ingest | kody:@kody/lineage/reset-ingest |
| seed-highlights | kody:@kody/lineage/seed-highlights |
| seed-primitive-story | kody:@kody/lineage/seed-primitive-story |
| record-version | kody:@kody/lineage/record-version |
Prefer static kody:@kody/lineage/... imports from execute. Do not lead
with packages.invoke.
Smoke test (read-only)
import status from 'kody:@kody/lineage/status'
export default async function main() {
return await status()
// => { repo, ingest, commentaryCount, recentIngest }
}Optional series read (same numbers the UI graphs):
import getSeries from 'kody:@kody/lineage/series'
export default async function main() {
return await getSeries({ mode: 'cumulative' })
}Common snippets
Backfill a batch (writes storage; safe catch-up):
import backfill from 'kody:@kody/lineage/backfill'
export default async function main() {
return await backfill({ limit: 50 })
// Transient GitHub/CF failures may return { deferred: true }
// Slow listings stop early with { listingComplete: false, done: false }
}Inspect one commit's file classification:
import inspectCommit from 'kody:@kody/lineage/inspect-commit'
export default async function main() {
return await inspectCommit({
sha: '35878a47ef4aa3567eb6f6b5ea4d3d2c753934b5',
})
}Attach commentary:
import commentary from 'kody:@kody/lineage/commentary'
export default async function main() {
return await commentary({
sha: 'abc123',
label: 'Worker split',
narrative:
'The monolith was carved into the first dedicated worker package.',
})
}Edge cases
- Tracked repo is
kody-hq/kody(application source), notuse-kody. - Only first-parent history of the tracked branch is stored. Points sit at the
commit's committer date, which for merge / squash / rebase-merge commits is
when the change landed. Commits brought in by a merge are never their own
points; the merge commit carries the PR's whole diff.
backfillprunes any stored off-mainline commits (pruned), and the webhook walks first parents back from the pushedafterinstead of ingestingpayload.commits. - Commit files are paged (300 per page, GitHub caps at 3000), so big merges are counted in full. A one-time migration re-fetches rows stored before paging.
- Generated / Linguist-generated /
@generated/DO NOT EDITpaths are skipped even when committed — use./inspect-committo debug empty buckets. - Prefer the
github-pushwebhook for new main commits; keepbackfill-missingenabled as coarse catch-up. Do not disable the webhook or job. backfill/ingest-missingmay returndeferred: trueon transient GitHub/Cloudflare failures instead of throwing — retry on the next tick. On the webhook path (explicit SHAs) any per-commit fetch failure is listed inerrorsand left forbackfill-missing, so the delivery still succeeds../reset-ingestwipes stored commit buckets so a recount can run after ignore-rule changes — confirm before calling../seed-highlightsand./seed-primitive-storyare safe to re-run; existing SHAs keep current commentary../record-versionafter publish with the published commit for the About view.- Never paste the webhook URL or its signing secret into chat or logs.
Dependency note
Uses @kody/github 1.x, which reads auth from one declared github credential
slot. account, secretName, and integrationName were removed and throw.
Run read-only snippets with --credential github=<name> (CLI) or
credentials: { github: "<name>" } (MCP execute).
UI URL params
?labels=off(alsofalse,0,hide,no) hides chart annotation markers and text. Any other value or no param shows them (default). The Labels toggle writes/removes the param withhistory.replaceState; it is not persisted to localStorage. Logic lives insrc/ui/labels-toggle.ts(tested inlabels-toggle.node.test.ts). The story list below the chart is not affected.?xaxis=date(alsotime,linear) switches the x axis from even per-commit spacing (default, no param) to a linear date scale. The X axis control writes/removes the param withhistory.replaceState; logic lives insrc/ui/x-axis.ts(tested inx-axis.node.test.ts).- Chart mode and range are UI state only (mode persists in localStorage); the
from/to/modeparams belong to/api/series, not the page URL.
Fork / adapt
Kent's copy must keep its current defaults. For a fork:
communityForkboth@kody/lineageand@kody/github(imports never cross orgs). In the fork, rewritekody:@kody/github/requestinsrc/github.tsandkody.dependenciesinpackage.jsonto the forker's scope, and renamepackage.json#name.- Edit
src/config.ts:defaultRepo—{ owner, repo, branch }to chartbranding— app name, description, colours (art lives insrc/ui/art/)fallbackHostedOrigin/fallbackAppBasePath— only whenpackageContextlacks theminspectDefaultSha— any commit in the new repo
- Replace or empty
primitiveStoriesinsrc/annotations.ts(prefixes are kody-hq/kody SHAs and will not match another repo). - Rewrite
kody:@kody/lineage/...imports in docs/JSDoc to the fork. - Mint the webhook URL for
github-push(webhookUrlMint; package-owned HMAC, no user secret) and register a GitHub push hook withwebhookUrlApply({{webhookUrl}}inconfig.url,{{webhookSecret}}inconfig.secret). The webhook's first turn-on needs the owner's Approve click. - Publish, then backfill.
Runtime repo switch without republishing (persists in package storage and
wins over defaultRepo; run reset-ingest first if the old repo's commits
are stored — confirm with the owner):
import settings from 'kody:@kody/lineage/settings'
export default async function main() {
return await settings({ owner: 'your-org', repo: 'your-repo', branch: 'main' })
}Public surface (audit notes)
- The hosted app's routes are read-only:
/,/api/series,/api/status,/api/version, the manifest, service worker, and art. None call GitHub, write storage (beyond idempotentCREATE TABLE IF NOT EXISTS), or spend. - They expose commit SHAs, first-line messages, GitHub URLs, line counts, and commentaries for the tracked repo. Author names are stored but never served. Only point an internet-visible copy at a repo whose history is public.
- Writes happen only through exports (owner-only), the
backfill-missingjob, and the HMAC-verifiedgithub-pushwebhook.