@zebeqo/vendy 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/main.mjs +7 -7
- package/package.json +1 -1
package/dist/main.mjs
CHANGED
|
@@ -45600,20 +45600,20 @@ const skills$1 = {
|
|
|
45600
45600
|
content: "---\nname: research\ndescription: Before building a feature, find what it should be built on or modeled after — what the map already covers, then three to five current, credible open-source candidates laid out with the data to choose between them. Ends when the user picks one and the vendor workflow takes over.\n---\n\n# research a feature\n\nDo not write the feature yet. Find what it should stand on, so nothing is reinvented and nothing is guessed.\n\n## 1. Pin down the feature\n\nOne sentence: what it does for the user of this project, and what it touches. If the request leaves that open, ask before searching — candidates are only comparable against a stated need.\n\n## 2. Look in the map first\n\n```bash\nvendy catalog\n```\n\nA repo already here may cover it. A framework the project is built on often ships the feature itself — a local database on an Effect project means Effect's own SQL modules before any new library — and a project already imitated may already solve the same problem. Read the relevant snapshot far enough to say yes or no.\n\nIf the map covers it, say so, name the evidence (`.vendy/<name>/<path>`), and offer to go straight to building. Research continues only if the user wants alternatives.\n\n## 3. Find candidates\n\nTwo kinds, and say which each one is:\n\n- **Library** — the project would depend on it.\n- **Reference** — a project that already ships this feature well, to imitate its implementation and its UX.\n\nSources: `gh search repos <terms> --sort stars --limit 20`, web search for recent comparisons and announcements, and the dependencies and choices of the high-quality projects already vendored. Prefer what is actively developed: the user favors newer tools with cleaner designs over incumbents, so a young project with momentum is a real candidate, not a risk to filter out.\n\n## 4. Gather the facts\n\nFor each candidate:\n\n```bash\ngh repo view <owner>/<repo> --json stargazerCount,pushedAt,licenseInfo,latestRelease,description\ngh release list --repo <owner>/<repo> --limit 5\ngh api 'repos/<owner>/<repo>/git/trees/HEAD?recursive=1' \\\n --jq '[.tree[] | select(.type == \"blob\")] as $b | {truncated, files: ($b | length), bytes: ($b | map(.size) | add)}'\n```\n\nThe last one sizes the snapshot: the files at the default branch's tip, which is what vendoring puts on disk. Not `diskUsage` from `gh repo view`, which counts the whole history and overstates a large repository several times over. `truncated: true` means the tree is too large for one response; report it as very large.\n\nRead its README and enough of its docs or source to judge fit with this project's stack — whether it is native to the framework the project already uses, its runtime, its module format.\n\n## 5. Present the options\n\nThree to five candidates in one table, then a recommendation:\n\n| Candidate | Kind | Stars | Last release | Last push | License | Snapshot | Fit with this project | Why it stands out |\n| --------- | ---- | ----: | ------------ | --------- | ------- | -------: | --------------------- | ----------------- |\n\nWrite the snapshot as files and megabytes (`2,628 files, 41 MB`). No hard thresholds: show the numbers and let the user weigh them. A large snapshot is not a reason to drop a candidate; it is a reason to vendor only the paths the use needs (vendor workflow), so say which ones when it is. The recommendation names one candidate and the reason, citing what you read.\n\n## 6. Hand off\n\nWhen the user picks, load `vendy skills get vendor` and vendor it with the feature as the purpose — unless it fails that workflow's \"Is it worth a repo?\", in which case it becomes a dependency without a repo. A pick of \"none\" ends here with nothing vendored.\n"
|
|
45601
45601
|
},
|
|
45602
45602
|
"review": {
|
|
45603
|
-
description: "Review the current branch's changes against the map — the health check narrowed to the files the branch touched
|
|
45604
|
-
content: "---\nname: review\ndescription: Review the current branch's changes against the map — the health check narrowed to the files the branch touched
|
|
45603
|
+
description: "Review the current branch's changes against the map — the health check narrowed to the files the branch touched. Does the new code follow the evidence of the uses it falls under, did it bring in vendored packages or imitated mechanisms the map does not record, and do the guides it affects still hold? Vendor alignment only; general bugs belong to a code review.",
|
|
45604
|
+
content: "---\nname: review\ndescription: Review the current branch's changes against the map — the health check narrowed to the files the branch touched. Does the new code follow the evidence of the uses it falls under, did it bring in vendored packages or imitated mechanisms the map does not record, and do the guides it affects still hold? Vendor alignment only; general bugs belong to a code review.\n---\n\n# review the branch\n\nThe health check, narrowed to what this branch changed. Load `vendy skills get health` for the judgments; this workflow says only what is different.\n\n## 1. The changes\n\nEvery file changed since the merge-base with the base branch — main unless the user says otherwise — committed or not.\n\n## 2. The uses they fall under\n\nRun `vendy check`, then match every changed file against the map: every project-wide use applies to all of them, and a scoped use applies to the files its globs match and its `!` globs do not. A changed file under no use is still read — it is where unmapped findings come from.\n\n## 3. Judge the changed lines\n\nHealth's step 3, on the changed lines and what they call, not the whole scope:\n\n- **Deviation** — the new code against its uses' evidence.\n- **Unmapped** — a new import of a vendored package outside every scope, or new code imitating a reference repo with no use recording it.\n- **Not worth a repo** — the branch vendored a library that health would flag as not worth one.\n- **Stale map** — the branch moved or deleted what a scope covered, or changed a feature's role without changing its use.\n- **Guide** — a guide whose use the branch changed, now out of date.\n\nThe fix for an unmapped or stale finding is usually an align the branch skipped: say so.\n\n## 4. Report, then fix\n\nReport as health's step 4 does, findings only for this branch. Fix what the user picks.\n"
|
|
45605
45605
|
},
|
|
45606
45606
|
"setup": {
|
|
45607
45607
|
description: "Bring vendy into a project and decide how it behaves — which agents get session hooks, and editor exclusions. Also covers what setup writes into AGENTS.md, and changing any of it later.",
|
|
45608
45608
|
content: "---\nname: setup\ndescription: Bring vendy into a project and decide how it behaves — which agents get session hooks, and editor exclusions. Also covers what setup writes into AGENTS.md, and changing any of it later.\n---\n\n# vendy setup\n\n```bash\nvendy setup # inspect, preview every write, confirm\nvendy setup --dry-run # list the files setup would change; write nothing\nvendy setup --agent claude # session hooks: claude, codex, cursor, opencode; --no-agent for none\nvendy setup --no-vscode # remove the editor exclusions\n```\n\nIn a terminal, the command previews everything it will write and asks before applying. Without one, as when an agent runs it, nobody is asked: a choice left off the command line keeps what is installed, and on a first run installs hooks and editor exclusions for the agent and editor directories the repository already has. Only an explicit choice removes anything — `--no-agent`, `--no-vscode`, or an `--agent` list that leaves out an installed agent.\n\n## What setup installs\n\n- **The managed block in `AGENTS.md`** — the rules every session starts with. Its commands go through the project's package manager (`pnpm exec vendy …`), so after switching package managers, run setup again.\n- **Session hooks** for Claude, Codex, and Cursor that put the catalog into each session, and the published plugin entry in `.opencode/opencode.jsonc` for OpenCode. Each hook runs a generated script beside the agent's config (`.claude/hooks/vendy-claude-gate.mjs` and its siblings) that finds the vendy the project or machine installed and never downloads one; Claude Code and Codex also get an edit gate that blocks edits until the session has seen the catalog.\n- **`.vscode/settings.json` exclusions**, so `.vendy/` stays out of search, file watching, and auto-imports.\n\nSetup does not write `.vendy/.gitignore`, which ignores everything in `.vendy/`, itself included: vendy writes it with the first repo and removes it with the last.\n\nSetup ends with numbered next steps it cannot do for you; do them, or ask the user to.\n\nRe-run setup any time, with new flags; it only offers what is stale or absent.\n"
|
|
45609
45609
|
},
|
|
45610
45610
|
"update": {
|
|
45611
|
-
description: "Move snapshots to their newest upstream one repo at a time — libraries to their newest release with the dependency alongside, references to their branch tip — then trace what changed to the uses it affects, carry the project's code and guides forward, and recommend new upstream features the map has a use for.",
|
|
45612
|
-
content: "---\nname: update\ndescription: Move snapshots to their newest upstream one repo at a time — libraries to their newest release with the dependency alongside, references to their branch tip — then trace what changed to the uses it affects, carry the project's code and guides forward, and recommend new upstream features the map has a use for.\n---\n\n# update snapshots\n\nThe project always runs on the newest upstream. One repo at a time, each finished before the next starts: move it, trace the change to the map, carry the project forward, commit.\n\nWith no repo named, take every repo in `vendy catalog`. Start from `vendy status` to see which have anything new.\n\n## 1. Move the pin\n\n```bash\nvendy update <name> # prints: updated <name> <from>..<to>, then a diffstat of the whole snapshot\nvendy update <name> --patch # the full patch instead\n```\n\n`<from>..<to>` is the range every command below takes. Name revisions by SHA: the store fetches no upstream tags.\n\nA reference repo follows its branch to the tip. A library repo on a release tag moves to the newest release with the same tag pattern — prereleases only on the line it is already on (alpha → beta → rc; a nightly or canary channel only from that channel) — and never backward. Then bring the dependency along — for a reference repo, the tool pin its documentation describes: `vendy skills get core`, \"Matching a dependency to its snapshot\".\n\nA library repo still on a branch gets onto releases first:\n\n```bash\nvendy track <name> --release # the repository's own releases: v<version>, or <repo>@<version>\nvendy track <name> --release --package <pkg> # a monorepo's <pkg>@<version> tags\n```\n\nIf the project installs a newer release than the newest tag vendy finds — a prerelease line the snapshot is not on — track that release's tag by name instead: `vendy track <name> <tag>`.\n\nNothing new upstream → next repo.\n\n## 2. Find what changed\n\nTwo questions, read at different breadths.\n\n### What the project must follow\n\nNarrow: only the uses' evidence decides what the project's code depends on. Stop at the first layer that answers it:\n\n1. **The changelog.** `gh release view <tag> --repo <owner>/<repo>` for each release crossed, or the `CHANGELOG.md`, `.changeset/`, or release notes inside the snapshot. Breaking changes and deprecations, at the highest signal per line.\n2. **The diff in the `read` paths.**\n\n ```bash\n vendy diff <name> <from>..<to> --read --stat # which evidence changed\n vendy diff <name> <from>..<to> --read # how\n ```\n\n3. **Fresh read.** When the update crosses a major version, or a `read` path was moved or deleted, read the affected use's evidence again from scratch, as if vendoring it, and decide what the best practice is now.\n\n### What is new\n\nWide: never narrowed to the `read` paths, because a feature a use could take up often lands where the map does not read yet. Weigh each new thing against what each use is `for`, not where it reads.\n\n1. **The changelog** for every release crossed. When it names each feature and what it is for, it is enough: open a feature's code only once you are about to recommend it, to cite its evidence.\n2. **Where upstream changed**, when there is no changelog or it is too thin to judge from — a reference repo usually has none. Start from `vendy git <name> log --oneline <from>..<to>` and the diffstat `vendy update` printed; for a large update, `vendy diff <name> <from>..<to> --dirstat` shows it by directory.\n\n## 3. Trace it to the map\n\nFor every use of the repo, decide:\n\n- **Unaffected** — nothing in its evidence changed in a way its code depends on.\n- **Code must follow** — a breaking change, a deprecation, or a new recommended way of doing what this use's code does. List the files in its scope and what changes, citing the upstream evidence for each.\n- **Map must follow** — a `read` path moved, the evidence now lives elsewhere, or a recommended feature's evidence lies outside the use's `read` paths.\n- **Guide must follow** — a runbook step or an explained mechanism no longer matches.\n\nThen **recommend new features** from \"What is new\": anything one of the repo's uses could take up — a simpler API for what the code does by hand, a capability the scope's feature is missing. Only what the map has a use for; new features the project has no use for are noise.\n\n## 4. Carry the project forward\n\nEverything unaffected → commit the pin (and dependency) alone and move on.\n\nAnything affected → show the user the plan from step 3, with the recommendations kept separate from the required changes, and wait. On approval: change the code, update the `read` paths and guides, run `vendy check` and the project's own checks and tests, and commit — one commit per repo, holding its pin, its dependency, and the code and guides that followed it.\n\nWhen a repo cannot be carried forward cleanly — a migration too large for this pass, tests that will not go green — stop at that repo and report. Do not continue to the next on top of a broken one. Put the repo back where it was while the user decides — `vendy pin <name> <from>` for a reference repo, `vendy track <name> <old-tag>` and the old dependency for a library — so the snapshot never describes code the project does not run.\n"
|
|
45611
|
+
description: "Move snapshots to their newest upstream one repo at a time — libraries to their newest release with the dependency alongside, references to their branch tip — then trace what changed to the uses it affects, carry the project's code and guides forward, and recommend new upstream features the map has a use for. Also covers updating a dependency that is not a repo, through a temporary local repo or its changelog alone.",
|
|
45612
|
+
content: "---\nname: update\ndescription: Move snapshots to their newest upstream one repo at a time — libraries to their newest release with the dependency alongside, references to their branch tip — then trace what changed to the uses it affects, carry the project's code and guides forward, and recommend new upstream features the map has a use for. Also covers updating a dependency that is not a repo, through a temporary local repo or its changelog alone.\n---\n\n# update snapshots\n\nThe project always runs on the newest upstream. One repo at a time, each finished before the next starts: move it, trace the change to the map, carry the project forward, commit.\n\nWith no repo named, take every repo in `vendy catalog`. Start from `vendy status` to see which have anything new. A package named that is no repo follows \"Updating a dependency that is not a repo\".\n\n## 1. Move the pin\n\n```bash\nvendy update <name> # prints: updated <name> <from>..<to>, then a diffstat of the whole snapshot\nvendy update <name> --patch # the full patch instead\n```\n\n`<from>..<to>` is the range every command below takes. Name revisions by SHA: the store fetches no upstream tags.\n\nA reference repo follows its branch to the tip. A library repo on a release tag moves to the newest release with the same tag pattern — prereleases only on the line it is already on (alpha → beta → rc; a nightly or canary channel only from that channel) — and never backward. Then bring the dependency along — for a reference repo, the tool pin its documentation describes: `vendy skills get core`, \"Matching a dependency to its snapshot\".\n\nA library repo still on a branch gets onto releases first:\n\n```bash\nvendy track <name> --release # the repository's own releases: v<version>, or <repo>@<version>\nvendy track <name> --release --package <pkg> # a monorepo's <pkg>@<version> tags\n```\n\nIf the project installs a newer release than the newest tag vendy finds — a prerelease line the snapshot is not on — track that release's tag by name instead: `vendy track <name> <tag>`.\n\nNothing new upstream → next repo.\n\n## 2. Find what changed\n\nTwo questions, read at different breadths.\n\n### What the project must follow\n\nNarrow: only the uses' evidence decides what the project's code depends on. Stop at the first layer that answers it:\n\n1. **The changelog.** `gh release view <tag> --repo <owner>/<repo>` for each release crossed, or the `CHANGELOG.md`, `.changeset/`, or release notes inside the snapshot. Breaking changes and deprecations, at the highest signal per line.\n2. **The diff in the `read` paths.**\n\n ```bash\n vendy diff <name> <from>..<to> --read --stat # which evidence changed\n vendy diff <name> <from>..<to> --read # how\n ```\n\n3. **Fresh read.** When the update crosses a major version, or a `read` path was moved or deleted, read the affected use's evidence again from scratch, as if vendoring it, and decide what the best practice is now.\n\n### What is new\n\nWide: never narrowed to the `read` paths, because a feature a use could take up often lands where the map does not read yet. Weigh each new thing against what each use is `for`, not where it reads.\n\n1. **The changelog** for every release crossed. When it names each feature and what it is for, it is enough: open a feature's code only once you are about to recommend it, to cite its evidence.\n2. **Where upstream changed**, when there is no changelog or it is too thin to judge from — a reference repo usually has none. Start from `vendy git <name> log --oneline <from>..<to>` and the diffstat `vendy update` printed; for a large update, `vendy diff <name> <from>..<to> --dirstat` shows it by directory.\n\n## 3. Trace it to the map\n\nFor every use of the repo, decide:\n\n- **Unaffected** — nothing in its evidence changed in a way its code depends on.\n- **Code must follow** — a breaking change, a deprecation, or a new recommended way of doing what this use's code does. List the files in its scope and what changes, citing the upstream evidence for each.\n- **Map must follow** — a `read` path moved, the evidence now lives elsewhere, or a recommended feature's evidence lies outside the use's `read` paths.\n- **Guide must follow** — a runbook step or an explained mechanism no longer matches.\n\nThen **recommend new features** from \"What is new\": anything one of the repo's uses could take up — a simpler API for what the code does by hand, a capability the scope's feature is missing. Only what the map has a use for; new features the project has no use for are noise.\n\n## 4. Carry the project forward\n\nEverything unaffected → commit the pin (and dependency) alone and move on.\n\nAnything affected → show the user the plan from step 3, with the recommendations kept separate from the required changes, and wait. On approval: change the code, update the `read` paths and guides, run `vendy check` and the project's own checks and tests, and commit — one commit per repo, holding its pin, its dependency, and the code and guides that followed it.\n\nWhen a repo cannot be carried forward cleanly — a migration too large for this pass, tests that will not go green — stop at that repo and report. Do not continue to the next on top of a broken one. Put the repo back where it was while the user decides — `vendy pin <name> <from>` for a reference repo, `vendy track <name> <old-tag>` and the old dependency for a library — so the snapshot never describes code the project does not run.\n\n## Updating a dependency that is not a repo\n\nThe same move, trace, and carry forward, with nothing added to the map: the target is the newest release by step 1's rule, and the evidence comes from the changelog or a temporary local repo.\n\n1. **Changelog first**, for every release crossed (step 2, \"What the project must follow\"). When it names each breaking change and deprecation precisely enough to find the calls they affect, skip to 3 without a snapshot.\n2. **Otherwise, a temporary local repo** at the installed release, moved forward:\n\n ```bash\n vendy add <url> --ref <tag-of-installed-version> --mode local\n vendy update <name>\n ```\n\n The repo has no uses, so `--read` narrows to nothing: read the diff in the paths behind the APIs the project calls.\n\n3. **Trace it to the importing files** in place of uses: for each file that imports the package, unaffected or code must follow, citing the evidence. Recommend new features only where that code could take them up.\n4. **Carry the project forward** as step 4 says, with two differences: run the project's own checks and tests but not `vendy check`, which reports the temporary repo's importers as unmapped; and the commit holds the dependency and the code, no pin. When it cannot be carried forward cleanly, put the dependency back at its old version.\n5. **Remove the temporary repo**, unasked: `vendy remove <name>`. When it passed \"Is it worth a repo?\" in the vendor workflow, say so in the report; on the user's word, vendor it at the new release by that workflow's \"Vendoring an installed dependency\".\n"
|
|
45613
45613
|
},
|
|
45614
45614
|
"vendor": {
|
|
45615
|
-
description: "Vendor an external repository and build with it — resolving the URL, pinning a library to its newest release and moving the dependency alongside, recording a provisional use for what the user wants from it, building the feature from its evidence, and finishing with align. Also covers vendoring a package on your own instead of reading node_modules.",
|
|
45616
|
-
content: "---\nname: vendor\ndescription: Vendor an external repository and build with it — resolving the URL, pinning a library to its newest release and moving the dependency alongside, recording a provisional use for what the user wants from it, building the feature from its evidence, and finishing with align. Also covers vendoring a package on your own instead of reading node_modules.\n---\n\n# vendor a repository\n\nThe usual request is \"vendor `<url>`, then build `<feature>`\". The URL says what to read; the feature says why, and the why becomes the use.\n\n## Is it worth a repo?\n\nA repo pays for itself with evidence you would otherwise get wrong. Its cost is fixed: a line in every session's catalog, and a required read before every change inside its scope, whether or not that change touches the library.\n\nVendor when the snapshot tells you what memory does not:\n\n- an API that is new or recently changed — a framework's new major, a pre-1.0 library\n- a project too niche to be well known\n- an implementation the project imitates\n- documentation the project's configuration follows\n\nDo not vendor a long-stable, widely used library when the project calls a narrow, familiar slice of it — `semver.compare`, one `picomatch` matcher. Depending on a package is not a reason to vendor it. When an edge case of such a library needs settling, add it with `--mode local`, read the answer, `vendy remove` it, and pin the behavior the project relies on in a test.\n\nA repository the user names to vendor is their call; when it fails this test, say so once, then follow their decision.\n\n## 1. Add it, local\n\nStart every vendoring with `--mode local`: reading and deciding touch no git, and a repo that turns out not to help leaves no trace.\n\n```bash\nvendy add https://github.com/Effect-TS/effect --mode local # repo URL, default branch\nvendy add effect-ts/effect --mode local # owner/repo shorthand\nvendy add effect-ts/effect#next --mode local # #ref on shorthand\nvendy add <url> --ref effect@3.19.9 --mode local # a tag or SHA\nvendy add <url> --name effect-src --mode local # override the repo name\n```\n\nAny plain git URL works, including private remotes using existing git credentials. Pasted browser URLs are sugar: GitHub commit pages become SHA pins, and GitHub and GitLab directory pages become subset repos. Subdirectories are positional arguments, and upstream's layout is preserved:\n\n```bash\nvendy add electron/electron docs --mode local\n```\n\nThe catalog marks such a repo `only docs/`. Something missing outside those paths says nothing about upstream; the subset left it out. The paths are fixed at `add`, so widening them means removing and re-adding the repo: ask the user rather than doing it yourself.\n\n**A library gets its newest release, not its default branch.** If the project will depend on a package this repository publishes, add it at its newest release tag:\n\n```bash\nvendy add <url> --release --mode local # the repository's own releases: v<version>, or <repo>@<version>\nvendy add <url> --release --package <pkg> --mode local # a monorepo's <pkg>@<version> tags\n```\n\nNewest is by semver, stable releases first. A monorepo whose tags name only other packages (`<pkg>@<version>`) fails with the package names; pick the one the project will install. When the project is already on a prerelease line of that package (on `4.0.0-rc.*`), add that line's newest tag by name with `--ref` instead. A repository with no release tags stays on its branch.\n\n## 2. Read it with the purpose in hand\n\nRead `.vendy/<name>` against what the user wants: which part of it answers the feature. Note the paths as you go — they become the use's `read`.\n\nWhen the user gave only a URL and no purpose, introduce the repository from what you read — what it is, what stands out — and ask what they want from it. Never record a use for a purpose you do not have.\n\n## 3. Land it, with a provisional use\n\n```bash\nvendy mode shared <name>\n```\n\nThen add the use to the repo in `vendy.json` — the role, in the user's words, and nothing else yet. When the user wants the borrowing kept private, skip the mode change and add the use in `vendy.local.json` instead:\n\n```json\n\"uses\": [{ \"for\": \"Release versioning and changelogs\" }]\n```\n\nBefore adding a new use, check the map for the same role: if this snapshot, or another, already plays it, widen that use instead (the align workflow explains the rule). Then:\n\n```bash\nvendy check <name>\n```\n\nFor a library repo, bring the dependency to the snapshot's release now — for a reference repo, the tool pin its documentation describes — as \"Matching a dependency to its snapshot\" in `vendy skills get core` describes.\n\n## 4. Build from the evidence\n\nBuild the feature from what step 2 found, not from memory. When a choice comes up that the evidence does not settle, go back to the snapshot before guessing.\n\n## 5. Align\n\nWhen the feature works, load `vendy skills get align`.\n\n## Vendoring on your own\n\nWhen you find yourself reading a package's source in `node_modules` — compiled, flattened, stripped of comments — vendor it instead:\n\n```bash\nvendy add <repo> --mode local\n```\n\nNo need to ask: a local repo stays in this worktree and out of git. Pin it like a library (step 1) when the project depends on it. Before the task ends, `vendy remove <name>` it unasked if it is not worth a repo (above). Otherwise ask the user once whether to keep it; on yes, continue from step 3, and on no, remove it.\n"
|
|
45615
|
+
description: "Vendor an external repository and build with it — resolving the URL, pinning a library to its newest release and moving the dependency alongside, recording a provisional use for what the user wants from it, building the feature from its evidence, and finishing with align. Also covers vendoring a dependency the project already installs, at its installed release, and vendoring a package on your own instead of reading node_modules.",
|
|
45616
|
+
content: "---\nname: vendor\ndescription: Vendor an external repository and build with it — resolving the URL, pinning a library to its newest release and moving the dependency alongside, recording a provisional use for what the user wants from it, building the feature from its evidence, and finishing with align. Also covers vendoring a dependency the project already installs, at its installed release, and vendoring a package on your own instead of reading node_modules.\n---\n\n# vendor a repository\n\nThe usual request is \"vendor `<url>`, then build `<feature>`\". The URL says what to read; the feature says why, and the why becomes the use.\n\n## Is it worth a repo?\n\nA repo pays for itself with evidence you would otherwise get wrong. Its cost is fixed: a line in every session's catalog, and a required read before every change inside its scope, whether or not that change touches the library.\n\nVendor when the snapshot tells you what memory does not:\n\n- an API that is new or recently changed — a framework's new major, a pre-1.0 library\n- a project too niche to be well known\n- an implementation the project imitates\n- documentation the project's configuration follows\n\nDo not vendor a long-stable, widely used library when the project calls a narrow, familiar slice of it — `semver.compare`, one `picomatch` matcher. Depending on a package is not a reason to vendor it. When an edge case of such a library needs settling, add it with `--mode local`, read the answer, `vendy remove` it, and pin the behavior the project relies on in a test.\n\nA repository the user names to vendor is their call; when it fails this test, say so once, then follow their decision.\n\n## 1. Add it, local\n\nStart every vendoring with `--mode local`: reading and deciding touch no git, and a repo that turns out not to help leaves no trace.\n\n```bash\nvendy add https://github.com/Effect-TS/effect --mode local # repo URL, default branch\nvendy add effect-ts/effect --mode local # owner/repo shorthand\nvendy add effect-ts/effect#next --mode local # #ref on shorthand\nvendy add <url> --ref effect@3.19.9 --mode local # a tag or SHA\nvendy add <url> --name effect-src --mode local # override the repo name\n```\n\nAny plain git URL works, including private remotes using existing git credentials. Pasted browser URLs are sugar: GitHub commit pages become SHA pins, and GitHub and GitLab directory pages become subset repos. Subdirectories are positional arguments, and upstream's layout is preserved:\n\n```bash\nvendy add electron/electron docs --mode local\n```\n\nThe catalog marks such a repo `only docs/`. Something missing outside those paths says nothing about upstream; the subset left it out. The paths are fixed at `add`, so widening them means removing and re-adding the repo: ask the user rather than doing it yourself.\n\n**A library gets its newest release, not its default branch.** If the project will depend on a package this repository publishes, add it at its newest release tag:\n\n```bash\nvendy add <url> --release --mode local # the repository's own releases: v<version>, or <repo>@<version>\nvendy add <url> --release --package <pkg> --mode local # a monorepo's <pkg>@<version> tags\n```\n\nWhen the project already installs the package, follow \"Vendoring an installed dependency\" instead.\n\nNewest is by semver, stable releases first. A monorepo whose tags name only other packages (`<pkg>@<version>`) fails with the package names; pick the one the project will install. When the project is already on a prerelease line of that package (on `4.0.0-rc.*`), add that line's newest tag by name with `--ref` instead. A repository with no release tags stays on its branch.\n\n## 2. Read it with the purpose in hand\n\nRead `.vendy/<name>` against what the user wants: which part of it answers the feature. Note the paths as you go — they become the use's `read`.\n\nWhen the user gave only a URL and no purpose, introduce the repository from what you read — what it is, what stands out — and ask what they want from it. Never record a use for a purpose you do not have.\n\n## 3. Land it, with a provisional use\n\n```bash\nvendy mode shared <name>\n```\n\nThen add the use to the repo in `vendy.json` — the role, in the user's words, and nothing else yet. When the user wants the borrowing kept private, skip the mode change and add the use in `vendy.local.json` instead:\n\n```json\n\"uses\": [{ \"for\": \"Release versioning and changelogs\" }]\n```\n\nBefore adding a new use, check the map for the same role: if this snapshot, or another, already plays it, widen that use instead (the align workflow explains the rule). Then:\n\n```bash\nvendy check <name>\n```\n\nFor a library repo, bring the dependency to the snapshot's release now — for a reference repo, the tool pin its documentation describes — as \"Matching a dependency to its snapshot\" in `vendy skills get core` describes.\n\n## 4. Build from the evidence\n\nBuild the feature from what step 2 found, not from memory. When a choice comes up that the evidence does not settle, go back to the snapshot before guessing.\n\n## 5. Align\n\nWhen the feature works, load `vendy skills get align`.\n\n## Vendoring on your own\n\nWhen you find yourself reading a package's source in `node_modules` — compiled, flattened, stripped of comments — vendor it instead:\n\n```bash\nvendy add <repo> --mode local\n```\n\nNo need to ask: a local repo stays in this worktree and out of git. Pin it like a library (step 1) when the project depends on it. Before the task ends, `vendy remove <name>` it unasked if it is not worth a repo (above). Otherwise ask the user once whether to keep it; on yes, continue from step 3, and on no, remove it.\n\n## Vendoring an installed dependency\n\nWhen the user wants a package the project already installs vendored — to update it through the update workflow, or to read its source and docs — the code is already written, so there is no feature to build and nothing to align afterwards. The vendoring commit stays separate from any update, so an update can be reverted alone.\n\n1. **Find the upstream** in the `repository` field of the installed package's `package.json`.\n2. **Pin the installed release**, not the newest: `vendy add <url> --ref <tag> --mode local`, where `<tag>` is the installed version's release tag (`v<version>`, or `<pkg>@<version>` in a monorepo). Never move the dependency here: moving forward belongs to the update workflow, with its changelog trace and the user's approval.\n3. **Weigh it** against \"Is it worth a repo?\".\n4. **Map the code that is there.** The role is what the existing code draws on the package for; ask the user when the code does not make it clear. `vendy mode shared <name>`, then write the use complete, not provisional: `scope` covers the files that import the package — `vendy check <name>` lists them — collapsed into as few globs as core's \"The map\" allows, and `read` points at the docs and examples that answer how the project calls it.\n5. `vendy check <name>`, and fix every finding.\n6. **Offer the update.** `vendy status <name>` shows whether a newer release is out. When it is, report how far behind the project is and offer the update workflow; when the user vendored it in order to update, go straight on to it.\n"
|
|
45617
45617
|
}
|
|
45618
45618
|
};
|
|
45619
45619
|
//#endregion
|
|
@@ -46212,7 +46212,7 @@ const withGitSeparator = (args) => {
|
|
|
46212
46212
|
const run = (args, config) => runWith(vendy, config)(withGitSeparator(args)).pipe(provideService(Blocking, (description) => error(`waiting for file lock on ${description}`)), provideService(runner, invocation(process.cwd())), provideService(CliConfig, cliConfig), provideService(Formatter, formatter));
|
|
46213
46213
|
//#endregion
|
|
46214
46214
|
//#region src/main.ts
|
|
46215
|
-
const version = "0.1.
|
|
46215
|
+
const version = "0.1.3";
|
|
46216
46216
|
const isSqliteExperimentalWarning = (warning) => warning.name === "ExperimentalWarning" && warning.message.startsWith("SQLite ");
|
|
46217
46217
|
for (const printWarning of process.listeners("warning")) {
|
|
46218
46218
|
process.off("warning", printWarning);
|
package/package.json
CHANGED