@kentcdodds/lineage

@kentcdodds/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

• Job: backfill-missing (cron */30 * * * *, timezone America/Denver) — catch-up only; keep enabled.
• Webhook: github-push → ./handle-github-webhook (responseMode: ack).
• Hosted app: https://kentcdodds.kody.run/packages/lineage
• Dependency: @kentcdodds/github

Import paths

Prefer static kody:@kentcdodds/lineage/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

import status from 'kody:@kentcdodds/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:@kentcdodds/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:@kentcdodds/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:@kentcdodds/lineage/inspect-commit'

export default async function main() {
	return await inspectCommit({
		sha: '35878a47ef4aa3567eb6f6b5ea4d3d2c753934b5',
	})
}

Attach commentary:

import commentary from 'kody:@kentcdodds/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 kentcdodds/kody (application source), not use-kody.
• 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 githubLocWebhookSecret values into chat or logs.

Dependency note

Uses @kentcdodds/github, which authenticates via createAuthenticatedFetch on the github-bot / github-kent OAuth integrations (not mirrored github-*AccessToken user secrets).