GitHub - fbosch/docs-cache: 🗃️ Deterministic local caching of external documentation for agents and developers

Deterministic local caching of external documentation for agents and developers

Purpose

Provides agents and developers with local access to external documentation without committing it to the repository.

Documentation is cached in a gitignored location, exposed to agent and tool targets via links or copies, and updated through sync commands or postinstall hooks.

Features

Local only: Cache lives in the directory .docs (or a custom location) and can be gitignored.
Deterministic: docs-lock.json pins commits and file metadata.
Fast: Local cache avoids network roundtrips after sync.
Flexible: Cache full repos or just the subdirectories you need.

Note: Sources are downloaded to a local cache. If you provide a targetDir, docs-cache creates a symlink or copy from the cache to that target directory.

Usage

# Initialize (optional)
npx docs-cache init

# Add source(s)
npx docs-cache add github:owner/repo#main

# Sync and lock
npx docs-cache sync
npx docs-cache sync --frozen

# Refresh tracked refs (write lock/materialized output)
npx docs-cache update <source-id>
npx docs-cache update --all --dry-run

# Optional: pin config ref(s) to commit SHA
npx docs-cache pin <source-id>

# Inspect / maintain
npx docs-cache verify
npx docs-cache status
npx docs-cache remove <source-id>
npx docs-cache clean

for more options: npx docs-cache --help

Recommended Workflow

Use this flow to keep behavior predictable (similar to package manager manifest + lock workflows):

Keep source intent in config (ref: "main", ref: "v1", or a commit SHA).
Run npx docs-cache update <id...> (or --all) to refresh selected sources and lock data.
Use npx docs-cache sync --frozen in CI to fail fast when lock data drifts.
Use npx docs-cache pin <id...> only when you explicitly want to rewrite config refs to commit SHAs.

Configuration

docs.config.json at project root (or a docs-cache field in package.json):

Options

Top-level

Field	Details	Required
`cacheDir`	Directory for cache. Default: `.docs`.	Optional
`defaults`	Default settings for all sources.	Optional
`sources`	List of repositories to sync.	Required

Show default and source options

Default options

These fields can be set in defaults and are inherited by every source unless overridden per-source.

Field	Details
`ref`	Branch, tag, or commit. Default: `"HEAD"`.
`mode`	Cache mode. Default: `"materialize"`.
`include`	Glob patterns to copy. Default: `["*/.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"]`.
`exclude`	Glob patterns to skip. Default: `[]`.
`targetMode`	How to link or copy from the cache to the destination. Default: `"symlink"` on Unix, `"copy"` on Windows.
`required`	Whether missing sources should fail. Default: `true`.
`maxBytes`	Maximum total bytes to materialize. Default: `200000000` (200 MB).
`maxFiles`	Maximum total files to materialize.
`ignoreHidden`	Skip hidden files and directories (dotfiles). Default: `false`.
`allowHosts`	Allowed Git hosts. Default: `["github.com", "gitlab.com", "visualstudio.com"]`.
`toc`	Generate per-source `TOC.md`. Default: `true`. Supports `true`, `false`, or a format: `"tree"` (human readable), `"compressed"`
`unwrapSingleRootDir`	If the materialized output is nested under a single directory, unwrap it (recursively). Default: `true`.

Brace expansion in include supports comma-separated lists (including multiple groups) like **/*.{md,mdx} and is capped at 500 expanded patterns per include entry. It does not support nested braces or numeric ranges.

Source options

Required

Field	Details
`repo`	Git URL.
`id`	Unique identifier for the source.

Optional (source-only)

Field	Details
`targetDir`	Path where files should be symlinked/copied to, outside `.docs`.

Note: Sources are always downloaded to .docs/<id>/. If you provide a targetDir; docs-cache will create a symlink or copy pointing from the cache to that target directory.

NPM Integration

Use postinstall to ensure documentation is available locally immediately after installation:

{
  "scripts": {
    "postinstall": "npx docs-cache sync --prune"
  }
}

License

MIT