# @kody/lineage — agent notes Human setup and intent live in [`README.md`](./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 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 | 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) ```js 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): ```js 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): ```js 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: ```js import inspectCommit from 'kody:@kody/lineage/inspect-commit' export default async function main() { return await inspectCommit({ sha: '35878a47ef4aa3567eb6f6b5ea4d3d2c753934b5', }) } ``` Attach commentary: ```js 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=` (CLI) or `credentials: { github: "" }` (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): ```js 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.