agent-docs

kevin-wiki / scripts/lib

Purpose

The reusable core behind scripts/. CLIs stay thin; the real logic — state tracking, source absorption, integration persistence, auth, agent-config symlinking, and the bookmark-enrichment pipeline — lives here as pure, unit-tested modules.

Mental model & key files

  • update-state.ts — single writer for state.json (freshness source of truth).
  • absorb-log.ts — tracks which raw/ sources became which wiki pages.
  • integration-db.ts — PGlite state shared by calendar/email/meeting syncs.
  • google-auth.ts — OAuth for Google integrations.
  • voice-call-import.ts — consent-gated, content-addressed private export freezing.
  • circleback-import.ts — complete meeting/detail/transcript revision assembly and private receipts.
  • slack-read.ts — exact-scope Slack collection, thread revisions, attachment freezing, and run receipts.
  • agent-config-links.ts / agent-config-sync.ts — the 7 canonical ~/.cursor/ ~/.claude symlinks (bootstrap). Covered by __tests__/agent-config-sync.test.ts.
  • enrich/ — bookmark/article enrichment: fetchers/ (article, github, youtube), pool.ts, thread.ts, with __tests__/.
  • agent-session-analysis-migration.ts — deterministic contract-v4 migration from shared trace IDs to one session snapshot plus one source per message.
  • source-review-unit-audit.ts — pure message-class/topic/cohort classification and final-disposition rules for exact source-review units.
  • source-review-batch.ts, review-batch-planner.ts, and source-review-unit-audit.ts preserve exact review-unit digests and treat held as a final reviewed state while blocked remains pending.
  • source-audit-freshness.ts lets freshness defer to a complete exact X artifact audit instead of emitting a raw-mtime false positive.

Patterns to follow / invariants

  • Pure where possible; side effects (fs, network) isolated and injectable.
  • One writer per resource — e.g. all state.json writes go through update-state.ts.
  • Parallelize independent async (fetchers) and reuse clients rather than re-initializing per call.
  • Tests live in __tests__/ and run via node --import tsx --test.

Common tasks → first action

  • Add a helper → create the module here, export pure functions, add a __tests__ test, call it from the relevant scripts/*.ts.
  • Add a source fetcher → extend the enrich/fetchers/ pattern (base-fetcher + registry).

Gotchas

  • integration-db.ts historically used ~/.my-wiki/; the canonical path is ~/.kevin-wiki/ — symlink legacy installs.
  • Don't import these from a CLI's function body — import at module top (ESM).