AGENTS.md

1# src/hooks/auto-update-checker/ -- npm Update Detection
2 
3**Generated:** 2026-05-18
4 
5## OVERVIEW
6 
727 files. Session Tier hook on `session.created`. Checks the npm registry for newer plugin versions, compares against the installed version, and surfaces update availability via startup toasts. Caches results to avoid repeated registry fetches. Throttled per channel (`latest`, `next`, `beta`). Skips CLI run mode and subagent sessions.
8 
9## FILE CATALOG
10 
11| File | Purpose |
12|------|---------|
13| `index.ts` | Barrel exports: hook factory, checker, cache invalidation, channel helpers |
14| `hook.ts` | `createAutoUpdateCheckerHook()` -- event handler, orchestrates startup toasts and background check |
15| `checker.ts` | Barrel for `checker/` subdir -- version resolution, local dev detection, package entry finding |
16| `cache.ts` | `invalidatePackage()` -- removes package from bun.lock, node_modules, and specifier cache |
17| `version-channel.ts` | `extractChannel()` -- resolves dist-tags and prerelease versions to npm channels |
18| `types.ts` | `UpdateCheckResult`, `AutoUpdateCheckerOptions`, `NpmDistTags` |
19| `constants.ts` | Registry URL, timeouts, cache paths, accepted package names |
20 
21## SUBDIRECTORIES
22 
23- `checker/` -- 11 files. Core version checking logic: `check-for-update.ts`, `latest-version.ts`, `local-dev-version.ts`, `plugin-entry.ts`, `cached-version.ts`, `pinned-version-updater.ts`, `sync-package-json.ts`, plus helpers.
24- `hook/` -- 9 files. Startup UX: `background-update-check.ts`, `deferred-startup-check.ts`, `startup-toasts.ts`, `update-toasts.ts`, `spinner-toast.ts`, `config-errors-toast.ts`, `connected-providers-status.ts`, `model-capabilities-status.ts`, `model-cache-warning.ts`.
25 
26## CACHE
27 
28File-based deduplication via `VERSION_FILE` in the OpenCode cache directory (`getOpenCodeCacheDir()`). Prevents excessive npm registry calls. `invalidatePackage()` forces a fresh check by purging the package from Bun's lockfile, node_modules, and specifier cache.
29 
30## VERSION CHANNELS
31 
32`extractChannel()` maps:
33- Dist-tags (`next`, `beta`) → channel name directly
34- Prerelease versions (`1.0.0-beta.1`) → channel from prerelease prefix (`alpha`, `beta`, `rc`, `canary`, `next`)
35- Stable versions → `latest`
36 
37## INTEGRATION
38 
39Registered in `create-session-hooks.ts` as `autoUpdateChecker`. Part of the Session Tier hook composition.
40 
41## RELATED
42 
43Three `zauc-mocks-*` directories in `src/hooks/` exist specifically to test this hook with mocked dependencies:
44- `zauc-mocks-cache/` -- tests cache invalidation paths
45- `zauc-mocks-hook/` -- tests hook orchestration with mocked submodules
46- `zauc-mocks-bg/` -- tests background check scheduling
47 
48## CROSS-REFERENCES
49 
50- Parent: [`src/hooks/AGENTS.md`](../AGENTS.md) -- Session Tier hook list
51- [`src/cli/AGENTS.md`](../../cli/AGENTS.md) -- CLI uses the same npm dist-tag helpers
52