vendor-src
v0.16.0
Published
Vendor dependency source into your repo with git subtree, pinned to the installed version, for coding agents.
Maintainers
Readme
vendor-src
Vendor dependency source into your repo with git subtree, pinned to the installed package version, so coding agents can read real library code instead of guessing from docs.
Inspired by The One Weird Git Trick That Makes Coding Agents More Effect-ive.
Why
Coding agents are better at exploring source than reading documentation. node_modules is usually compiled or ignored, so vendor-src checks out the upstream git repo under .repos/ at the same version you have installed, and keeps it there as you upgrade.
Install
pnpm add -D vendor-src # workspaces: -Dw; catalogs: bump the catalog entry
pnpm exec vendor-src init
pnpm exec vendor-src add effectinit writes vendor-src.json, the AGENTS.md files, and a postinstall hook, then prints what else to set up: keeping .repos/ out of your formatter, linter, and editor. vendor-src doesn't touch those configs itself because it can't know which tools you use. Commit before add, which needs a clean working tree. add commits the checkout; commit the rest yourself.
Quick start (copy/paste for agents)
Set up vendor-src in this repo:
1. Install vendor-src as a root devDependency and run `vendor-src init`.
2. Exclude `.repos/` from the formatters, linters, and editor settings this
repo uses, then commit.
3. Suggest a few dependencies worth vendoring: the frameworks and libraries
this code leans on most, especially new or fast-moving ones. Say why for
each, and ask me which to add.
4. Run `vendor-src add <package>` for each one I pick, committing after each.Staying in sync
init sets "postinstall": "vendor-src check". After each install it compares vendor-src.json with the installed versions, offline and without touching git, and warns when a vendored repo is out of date. It never fails the install.
When it warns, run vendor-src sync. It re-vendors the matching tags and commits only the checkouts, so you can commit vendor-src.json and the AGENTS.md files together with the upgrade. In CI, vendor-src check --strict fails on stale sources.
If package.json already has a postinstall, init leaves it alone and prints a combined script to use instead.
Commands
Run them with pnpm exec vendor-src (or npx vendor-src) from anywhere in the project. Every command except init needs a vendor-src.json. add and remove need a clean working tree; sync only needs the checkouts it touches to be clean.
vendor-src init
Set up vendor-src: create vendor-src.json, the AGENTS.md files, and the postinstall hook, then print what else to configure (safe to re-run).
--dir <value>: Directory for vendored checkouts (default: .repos).--root-agents-md: Maintain a managed section in the root AGENTS.md (default: on; pass --no-root-agents-md to opt out).
# Use the defaults (vendor dir .repos, root AGENTS.md section on)
vendor-src init
# Pick another folder and leave the root AGENTS.md alone
vendor-src init --dir vendor --no-root-agents-mdvendor-src add <package>
Vendor a dependency's source into the vendor dir at the installed version's git tag.
<package>: npm package name or git URL to vendor.--name <value>: Directory name under the vendor dir.--ref <value>: Git ref/tag to vendor (skips version/tag lookup).--ignore <value>: Glob matched against paths inside the vendored repo (repeatable).
# Vendor an installed package
vendor-src add effect
# Prune paths you never want agents to read
vendor-src add effect --ignore 'scratchpad/**' --ignore '**/.github/**'
# Vendor a git repository directly (git-only when the package is not installed)
vendor-src add https://github.com/org/repo.git --ref v1.2.3vendor-src check
Offline check that vendored repos match installed package versions (what the postinstall hook runs).
--strict: Exit 1 when vendored versions drift from installed.
# Fail CI when vendored sources are stale
vendor-src check --strictvendor-src sync [name...]
Pull vendored repos to the git tags matching installed package versions, and git-only repos to their newest upstream tag or commit.
[name...]: Vendored repo names to sync (default: all).
# Sync every vendored repo after upgrading dependencies
vendor-src sync
# Sync one checkout
vendor-src sync effectvendor-src list
List vendored repositories and drift status. Alias: ls.
vendor-src remove <name>
Remove a vendored checkout, or stop tracking a package that shares one. Alias: rm.
<name>: Checkout name under the vendor dir, or a vendored package name.
Ignore patterns
To keep paths out of a checkout, list globs under the repo's ignore in vendor-src.json (or pass --ignore to add). They are matched against paths inside that repo and deleted after every add and sync. Nothing is ignored by default.
"ignore": ["scratchpad/**", "**/.github/**", "**/.changeset/**"]Git-only checkouts
vendor-src add https://github.com/org/repo.git --ref v1.2.3 is always git-only unless you pass --name <installed-package>. Git-only checkouts use an empty packages array, set version to the ref, and are ignored by check. AGENTS.md lists them by directory name and ref.
sync moves git-only checkouts to the newest upstream ref:
- A versioned tag moves to the highest tag with the same prefix:
[email protected]followsorpc@*tags,v1.2.3followsv*. Prereleases are only picked when the current tag is a prerelease. - A commit SHA moves to the default branch's
HEAD. - Other refs (branch names, unversioned tags) make
syncfail before it touches any checkout. Pass--name effectonly when you want the checkout pinned to the installedeffectversion.
Several packages from one repo
Packages published from the same monorepo share one checkout. add @tanstack/react-start checks out .repos/router; a later add @tanstack/react-router is recorded in the same entry without a second clone. The first package in packages decides the version. remove <package> stops tracking one package; remove <checkout> deletes the checkout.
"router": {
"packages": ["@tanstack/react-start", "@tanstack/react-router"],
"url": "https://github.com/TanStack/router.git",
"version": "1.168.60",
"ref": "@tanstack/[email protected]"
}Manifest
{
"$schema": "./node_modules/vendor-src/schema/vendor-src.schema.json",
"dir": ".repos",
"rootAgentsMd": true,
"repos": {
"effect": {
"packages": ["effect"],
"url": "https://github.com/Effect-TS/effect.git",
"version": "4.0.1",
"ref": "[email protected]"
}
}
}dir: where checkouts live. If you change it by hand, move the checkouts and re-runinit.rootAgentsMd: set tofalseto keep vendor-src out of your rootAGENTS.md.{dir}/AGENTS.mdis always written.
Installed versions are read from the project root and every workspace package; when several are installed, the highest wins.
Development
See .github/DEVELOPMENT.md. The published package lives in packages/vendor-src; this repo dogfoods it by vendoring effect under .repos/effect. The command reference above is generated from the CLI with pnpm readme.
