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.
  • 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__/.

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).