Skip to content
← Public packages

@kody/lineage

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

FollowForkOpen app

Files

AGENTS.md

203 lines · 8.2 KB · Markdown

@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

NameKindNotes
(package-owned HMAC)webhook recordgithub-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 one github credential slot. The job and webhook need a default credential mapping for github on @kody/lineage (read-only GitHub connection).
  • Owner-specific values: src/config.ts (lineageConfig) and src/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

ExportImport
overviewkody:@kody/lineage
statuskody:@kody/lineage/status
serieskody:@kody/lineage/series
settingskody:@kody/lineage/settings
backfillkody:@kody/lineage/backfill
backfill-continuekody:@kody/lineage/backfill-continue
ingest-missingkody:@kody/lineage/ingest-missing
handle-github-webhookkody:@kody/lineage/handle-github-webhook
commentarykody:@kody/lineage/commentary
inspect-commitkody:@kody/lineage/inspect-commit
reset-ingestkody:@kody/lineage/reset-ingest
seed-highlightskody:@kody/lineage/seed-highlights
seed-primitive-storykody:@kody/lineage/seed-primitive-story
record-versionkody:@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), not use-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. backfill prunes any stored off-mainline commits (pruned), and the webhook walks first parents back from the pushed after instead of ingesting payload.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 EDIT paths are skipped even when committed — use ./inspect-commit to debug empty buckets.
  • Prefer the github-push webhook for new main commits; keep backfill-missing enabled as coarse catch-up. Do not disable the webhook or job.
  • backfill / ingest-missing may return deferred: true on 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 in errors and left for backfill-missing, so the delivery still succeeds.
  • ./reset-ingest wipes stored commit buckets so a recount can run after ignore-rule changes — confirm before calling.
  • ./seed-highlights and ./seed-primitive-story are safe to re-run; existing SHAs keep current commentary.
  • ./record-version after 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 (also false, 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 with history.replaceState; it is not persisted to localStorage. Logic lives in src/ui/labels-toggle.ts (tested in labels-toggle.node.test.ts). The story list below the chart is not affected.
  • ?xaxis=date (also time, 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 with history.replaceState; logic lives in src/ui/x-axis.ts (tested in x-axis.node.test.ts).
  • Chart mode and range are UI state only (mode persists in localStorage); the from / to / mode params belong to /api/series, not the page URL.

Fork / adapt

Kent's copy must keep its current defaults. For a fork:

  1. communityFork both @kody/lineage and @kody/github (imports never cross orgs). In the fork, rewrite kody:@kody/github/request in src/github.ts and kody.dependencies in package.json to the forker's scope, and rename package.json#name.
  2. Edit src/config.ts:
    • defaultRepo — { owner, repo, branch } to chart
    • branding — app name, description, colours (art lives in src/ui/art/)
    • fallbackHostedOrigin / fallbackAppBasePath — only when packageContext lacks them
    • inspectDefaultSha — any commit in the new repo
  3. Replace or empty primitiveStories in src/annotations.ts (prefixes are kody-hq/kody SHAs and will not match another repo).
  4. Rewrite kody:@kody/lineage/... imports in docs/JSDoc to the fork.
  5. Mint the webhook URL for github-push (webhookUrlMint; package-owned HMAC, no user secret) and register a GitHub push hook with webhookUrlApply ({{webhookUrl}} in config.url, {{webhookSecret}} in config.secret). The webhook's first turn-on needs the owner's Approve click.
  6. 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 idempotent CREATE 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-missing job, and the HMAC-verified github-push webhook.