@zebeqo/vendy 0.3.0 → 0.4.0
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 +15 -13
- package/package.json +1 -1
package/dist/main.mjs
CHANGED
|
@@ -30220,11 +30220,7 @@ const inspectAtLocked = fnUntraced(function* (options, location) {
|
|
|
30220
30220
|
const fs = yield* FileSystem;
|
|
30221
30221
|
if ((yield* fs.exists(location.store)) && (yield* fs.exists(location.index))) return yield* gen(function* () {
|
|
30222
30222
|
yield* verifyStoreAt(location);
|
|
30223
|
-
|
|
30224
|
-
yield* mark(location.storeRoot, location.key.fileName);
|
|
30225
|
-
return { _tag: "Modified" };
|
|
30226
|
-
}
|
|
30227
|
-
const state = (yield* workTreeCleanAt(location)) ? { _tag: "Clean" } : { _tag: "Modified" };
|
|
30223
|
+
const state = !(yield* workTreeCleanAt(location)) ? { _tag: "Modified" } : (yield* matchesRepoAt(location, options.repo)) ? { _tag: "Clean" } : { _tag: "Stale" };
|
|
30228
30224
|
if (state._tag === "Clean") yield* recordMaterialized(location, options.repo.commit);
|
|
30229
30225
|
yield* mark(location.storeRoot, location.key.fileName);
|
|
30230
30226
|
return state;
|
|
@@ -37791,7 +37787,8 @@ const checkUpstream = fn("Status.checkUpstream")(function* (root, repo, log) {
|
|
|
37791
37787
|
}
|
|
37792
37788
|
}
|
|
37793
37789
|
});
|
|
37794
|
-
const isDirty = (status) => status.snapshot._tag !== "Clean" && !(status.mode === "shared" && status.snapshot._tag === "Missing");
|
|
37790
|
+
const isDirty = (status) => status.snapshot._tag !== "Clean" && status.snapshot._tag !== "Stale" && !(status.mode === "shared" && status.snapshot._tag === "Missing");
|
|
37791
|
+
const isStale = (status) => status.snapshot._tag === "Stale";
|
|
37795
37792
|
const check$1 = fn("Status.check")(function* (options = {}) {
|
|
37796
37793
|
const fs = yield* FileSystem;
|
|
37797
37794
|
const view = yield* read$2({
|
|
@@ -46030,6 +46027,7 @@ const upstreamLabel = (upstream) => {
|
|
|
46030
46027
|
};
|
|
46031
46028
|
const widestSnapshotState = [
|
|
46032
46029
|
"clean",
|
|
46030
|
+
"stale",
|
|
46033
46031
|
"modified",
|
|
46034
46032
|
"missing",
|
|
46035
46033
|
"unverified"
|
|
@@ -46037,6 +46035,7 @@ const widestSnapshotState = [
|
|
|
46037
46035
|
const snapshotState = (snapshot) => {
|
|
46038
46036
|
switch (snapshot._tag) {
|
|
46039
46037
|
case "Clean": return "clean";
|
|
46038
|
+
case "Stale": return "stale";
|
|
46040
46039
|
case "Modified": return "modified";
|
|
46041
46040
|
case "Missing": return "missing";
|
|
46042
46041
|
case "Unverified": return "unverified";
|
|
@@ -46186,7 +46185,7 @@ const skills$1 = {
|
|
|
46186
46185
|
},
|
|
46187
46186
|
"core": {
|
|
46188
46187
|
description: "The vendy model and its reference — repos, snapshots, modes, the `uses` schema that makes up the map, what `vendy check` verifies, and the inventory verbs the other workflows leave out (inspect, sync, remove, cache cleanup, recovery).",
|
|
46189
|
-
content: "---\nname: core\ndescription: The vendy model and its reference — repos, snapshots, modes, the `uses` schema that makes up the map, what `vendy check` verifies, and the inventory verbs the other workflows leave out (inspect, sync, remove, cache cleanup, recovery).\n---\n\n# vendy core\n\nvendy keeps pinned snapshots of external repositories at `.vendy/<name>`, and a map of what this project uses each one for.\n\n- Treat `.vendy/` as read-only reference material: never edit it or import from it.\n- Edit only the `uses` of `vendy.json` by hand, then run `vendy check`. Every other field moves through a verb. Never edit vendy's managed block in `AGENTS.md`.\n\n## Repos and modes\n\n| Mode | Pin | Snapshot bytes | A fresh clone gets |\n| -------- | ------------------------- | -------------- | ----------------------------------- |\n| `shared` | committed in `vendy.json` | git-ignored | the pin; run `vendy sync` for bytes |\n| `local` | `vendy.local.json` | git-excluded | nothing |\n\nA repo is a **library repo** when a package its snapshot publishes is a dependency of a project package its scope covers, and a **reference repo** otherwise. The difference decides what it tracks:\n\n- **Library repos track release tags.** The project runs the published package, so the snapshot must be the same release: reading unreleased code on a branch produces calls the installed version does not have. \"Newest\" means the newest published release, and the dependency moves with the tag.\n- **Reference repos track branches** — projects imitated, documentation read. Nothing installed has to match them, except the version of a tool the project pins when the snapshot is that tool's documentation.\n\nNot every dependency is a repo: the vendor workflow's \"Is it worth a repo?\" says which ones are.\n\n### Matching a dependency to its snapshot\n\n- **Snapshot ahead:** set the dependency to the snapshot's own version, keeping the range operator already there (`^1.4.0` → `^1.5.0`). Never `latest`: it drifts out of step with the pin the moment upstream publishes again. A pnpm dependency written as `catalog:` takes its version from `pnpm-workspace.yaml`; change it there, not in `package.json`.\n- **Dependency ahead:** move the snapshot instead — `vendy track <name> <tag-of-that-release>`.\n- **No `package.json`, or no dependency on it:** a reference repo; nothing to align — unless it documents a tool the project pins, such as a package manager's docs and `packageManager` in `package.json`. Set that pin to the tool's newest stable release whenever the snapshot moves, and treat what the docs mark as added in a later version as not yet available.\n\n### Two releases of one library\n\nWhen part of the project has to run another release — a plugin pinned to the version its host was built with — one snapshot cannot describe both. Take that part out of the use's scope with a `!` glob (`\"scope\": [\"**/*.ts\", \"!packages/plugin/**\"]`): the snapshot then answers for the rest, and `vendy check` compares it only with the dependencies of the packages its scope covers. When that part's code needs evidence of its own, also vendor the same upstream under a second name at the release it runs (`vendy add <url> --name <name>-plugin --ref <tag>`), with a use scoped to it.\n\n## The map\n\nEach shared repo carries `uses`: one per role the snapshot plays in this project.\n\n```json\n{\n \"name\": \"opencode\",\n \"url\": \"https://github.com/anomalyco/opencode.git\",\n \"ref\": \"v2.0.22\",\n \"commit\": \"…\",\n \"uses\": [\n {\n \"for\": \"Writing vendy's OpenCode plugin\",\n \"scope\": [\"packages/opencode/**\"],\n \"read\": [\"services/www/src/docs/content/build/plugins/\"]\n },\n {\n \"for\": \"Self-update and distribution, modeled on opencode's\",\n \"scope\": [\"packages/vendy/src/upgrade/**\", \"install.sh\"],\n \"read\": [\"packages/cli/src/services/updater.ts\", \"install\"],\n \"guide\": \"docs/guides/self-update.md\"\n }\n ]\n}\n```\n\n| Field | Relative to | Meaning | Absent means |\n| ------- | ----------------- | ----------------------------------------------------------------------------------------------- | ---------------------- |\n| `for` | — | The role, in the user's words. One clause, at most 120 characters, without `[`, `]`, `→` or `·` | (required) |\n| `scope` | the project root | Globs for the project files this use governs; `!` globs exclude | the use is provisional |\n| `read` | the snapshot root | Files or directories where the evidence lives: docs, examples, tests, source | the use is provisional |\n| `guide` | the project root | This use's guide, one file | no guide |\n\n`scope` globs are [picomatch](https://github.com/micromatch/picomatch) patterns that also match dot paths, so `**/*.ts` covers `.github/`. As in tinyglobby and fast-glob, a `!` glob subtracts from what every other glob matches, whatever their order, and no later glob adds a file back. `read` and `guide` are plain paths, never globs: a `read` directory covers everything under it.\n\nA use scoped to all the code a snapshot shapes is **project-wide**: a framework like Effect governs every TypeScript file, so it has one use, scoped to `**/*.ts` (`**` only when every file is, docs and config included), `\"for\": \"Effect 4 APIs and Node platform behavior\"`, and never one per module it touches. A use with no `scope` or no `read` is **provisional**: written at vendoring time, before where it applies and its evidence are located, and completed by align.\n\nA local repo's uses live in `vendy.local.json` the same way, and its guides stay out of Git with it: that is how a project draws on a repository without its history naming it. `vendy check` reports a local guide that is committed or not excluded.\n\nThe catalog renders every use as one line, into every session. Keep `for` to the role and let `read` and the guide carry the detail. A role says what reading the snapshot settles: \"Effect is the application framework\" only restates the project's imports, while the use above names what it settles.\n\n`scope` shares that line, so write it in as few globs as name the feature exactly: `dir/**` for a directory the feature owns, one brace glob for sibling files (`scripts/{release.mts,distribution.ts}`, `.github/workflows/{publish,release-*}.yml`), never one glob per file. Shorter must not mean wider: every file a scope matches costs a read of its evidence before any change there.\n\n## Check\n\n```bash\nvendy check # every finding across the map; exits non-zero on any\nvendy check <name> # one repo's uses\n```\n\nEach finding is decidable without judgment:\n\n- a `uses` field with the wrong shape, or a `for` over budget or containing `[`, `]`, `→` or `·`\n- a `scope` glob, or one of its brace alternatives, that matches or excludes no file — the feature it covered is gone\n- a `read` path the snapshot does not contain — upstream moved or deleted it\n- a `guide` that does not exist\n- a provisional use\n- a session catalog over the hook's 10,000-character limit even with only each use's `for` and scope; only when no repo is named\n- a library repo whose dependency, in a package its scope covers, is behind its snapshot, or ahead of it\n- a project file importing a vendored package that no use's scope covers or excludes\n\nWhether the code inside a scope actually follows its evidence takes judgment, and belongs to the health workflow.\n\n## Inspect\n\n```bash\nvendy list # all repos, including local ones; offline\nvendy show <name> # source, ref, pin, paths, mode, dependencies, uses\nvendy status # local integrity and upstream changes\nvendy status --log # also count and list the upstream commits touching each behind repo\nvendy catalog # the map as agents receive it\nvendy catalog <name>... # only these repos, with where to read\nvendy diff <name> # pinned snapshot versus local bytes\nvendy diff <name> <from>..<to> # revision range, filtered to repo paths\nvendy diff <name> <from>..<to> --read # only the paths the uses read; --stat for a diffstat\nvendy diff <name> <from>..<to> --dirstat # where upstream changed, by directory\nvendy diff <name> <from>..<to> <path>... # only these paths in the snapshot\nvendy diff <name> <from>..<to> --log # the upstream commits in the range, one per line\nvendy git <name> show <from>:<path>\n```\n\nSnapshots have no `.git`; read upstream history with `vendy diff`, and use `vendy git <name> <args>` for any other Git operation — everything after the name goes to git.\n\n`list`, `show`, `status`, and `check` take `--json` to print the same report as one JSON document, with the same exit code.\n\n`status` exits non-zero for modified, unexpectedly missing, or `unverified` snapshots. Behind or unreachable upstreams do not fail it. `unverified` means local integrity cannot be established, commonly after clearing the cache; run `vendy sync <name>`.\n\n## Maintain\n\n```bash\nvendy sync [<name>...] # restore bytes to existing pins\nvendy sync --prune # also delete what no repo owns: snapshot dirs, store views, indexes\nvendy mode <mode> <name>... # move repos between shared and local\nvendy local pull [<name>...] # copy the main worktree's local repos into this one\nvendy remove <name>... # remove repos, their uses, and their worktree state\nvendy store list # the shared cache: each upstream, its size, when it was last used\nvendy store gc --dry-run # preview cache cleanup; default age is 90 days\nvendy store gc --max-age 30d # reclaim eligible cache data\n```\n\n`sync` keeps pins fixed; moving them is the update workflow. A new worktree starts with no local repos, and `vendy local pull` never overwrites a copy that differs.\n\nThe store is a rebuildable cache shared across projects. `remove` and `sync --prune` leave it intact; `store gc` reclaims it, skipping busy or recently used stores. Commands that fetch also run it on their own, at most once a day (`VENDY_STORE_AUTO_CLEAN_FREQUENCY`: `never`, `always`, or a duration such as `12h`). `store gc --repack` also compacts retained stores.\n\n## Recover\n\n- **Modified snapshot:** inspect with `vendy diff <name>`. Before `sync` or `update` overwrites edits, it saves a rescue.\n- **Missing snapshot:** run `vendy sync <name>`.\n- **Failed operation:** do not delete internal locks or migration data as a generic repair.\n\nRescues belong to the current worktree and survive shared-cache cleanup. Removing a repo or pruning its orphan store view deletes its rescues too; recover anything needed first.\n"
|
|
46188
|
+
content: "---\nname: core\ndescription: The vendy model and its reference — repos, snapshots, modes, the `uses` schema that makes up the map, what `vendy check` verifies, and the inventory verbs the other workflows leave out (inspect, sync, remove, cache cleanup, recovery).\n---\n\n# vendy core\n\nvendy keeps pinned snapshots of external repositories at `.vendy/<name>`, and a map of what this project uses each one for.\n\n- Treat `.vendy/` as read-only reference material: never edit it or import from it.\n- Edit only the `uses` of `vendy.json` by hand, then run `vendy check`. Every other field moves through a verb. Never edit vendy's managed block in `AGENTS.md`.\n\n## Repos and modes\n\n| Mode | Pin | Snapshot bytes | A fresh clone gets |\n| -------- | ------------------------- | -------------- | ----------------------------------- |\n| `shared` | committed in `vendy.json` | git-ignored | the pin; run `vendy sync` for bytes |\n| `local` | `vendy.local.json` | git-excluded | nothing |\n\nA repo is a **library repo** when a package its snapshot publishes is a dependency of a project package its scope covers, and a **reference repo** otherwise. The difference decides what it tracks:\n\n- **Library repos track release tags.** The project runs the published package, so the snapshot must be the same release: reading unreleased code on a branch produces calls the installed version does not have. \"Newest\" means the newest published release, and the dependency moves with the tag.\n- **Reference repos track branches** — projects imitated, documentation read. Nothing installed has to match them, except the version of a tool the project pins when the snapshot is that tool's documentation.\n\nNot every dependency is a repo: the vendor workflow's \"Is it worth a repo?\" says which ones are.\n\n### Matching a dependency to its snapshot\n\n- **Snapshot ahead:** set the dependency to the snapshot's own version, keeping the range operator already there (`^1.4.0` → `^1.5.0`). Never `latest`: it drifts out of step with the pin the moment upstream publishes again. A pnpm dependency written as `catalog:` takes its version from `pnpm-workspace.yaml`; change it there, not in `package.json`.\n- **Dependency ahead:** move the snapshot instead — `vendy track <name> <tag-of-that-release>`.\n- **No `package.json`, or no dependency on it:** a reference repo; nothing to align — unless it documents a tool the project pins, such as a package manager's docs and `packageManager` in `package.json`. Set that pin to the tool's newest stable release whenever the snapshot moves, and treat what the docs mark as added in a later version as not yet available.\n\n### Two releases of one library\n\nWhen part of the project has to run another release — a plugin pinned to the version its host was built with — one snapshot cannot describe both. Take that part out of the use's scope with a `!` glob (`\"scope\": [\"**/*.ts\", \"!packages/plugin/**\"]`): the snapshot then answers for the rest, and `vendy check` compares it only with the dependencies of the packages its scope covers. When that part's code needs evidence of its own, also vendor the same upstream under a second name at the release it runs (`vendy add <url> --name <name>-plugin --ref <tag>`), with a use scoped to it.\n\n## The map\n\nEach shared repo carries `uses`: one per role the snapshot plays in this project.\n\n```json\n{\n \"name\": \"opencode\",\n \"url\": \"https://github.com/anomalyco/opencode.git\",\n \"ref\": \"v2.0.22\",\n \"commit\": \"…\",\n \"uses\": [\n {\n \"for\": \"Writing vendy's OpenCode plugin\",\n \"scope\": [\"packages/opencode/**\"],\n \"read\": [\"services/www/src/docs/content/build/plugins/\"]\n },\n {\n \"for\": \"Self-update and distribution, modeled on opencode's\",\n \"scope\": [\"packages/vendy/src/upgrade/**\", \"install.sh\"],\n \"read\": [\"packages/cli/src/services/updater.ts\", \"install\"],\n \"guide\": \"docs/guides/self-update.md\"\n }\n ]\n}\n```\n\n| Field | Relative to | Meaning | Absent means |\n| ------- | ----------------- | ----------------------------------------------------------------------------------------------- | ---------------------- |\n| `for` | — | The role, in the user's words. One clause, at most 120 characters, without `[`, `]`, `→` or `·` | (required) |\n| `scope` | the project root | Globs for the project files this use governs; `!` globs exclude | the use is provisional |\n| `read` | the snapshot root | Files or directories where the evidence lives: docs, examples, tests, source | the use is provisional |\n| `guide` | the project root | This use's guide, one file | no guide |\n\n`scope` globs are [picomatch](https://github.com/micromatch/picomatch) patterns that also match dot paths, so `**/*.ts` covers `.github/`. As in tinyglobby and fast-glob, a `!` glob subtracts from what every other glob matches, whatever their order, and no later glob adds a file back. `read` and `guide` are plain paths, never globs: a `read` directory covers everything under it.\n\nA use scoped to all the code a snapshot shapes is **project-wide**: a framework like Effect governs every TypeScript file, so it has one use, scoped to `**/*.ts` (`**` only when every file is, docs and config included), `\"for\": \"Effect 4 APIs and Node platform behavior\"`, and never one per module it touches. A use with no `scope` or no `read` is **provisional**: written at vendoring time, before where it applies and its evidence are located, and completed by align.\n\nA local repo's uses live in `vendy.local.json` the same way, and its guides stay out of Git with it: that is how a project draws on a repository without its history naming it. `vendy check` reports a local guide that is committed or not excluded.\n\nThe catalog renders every use as one line, into every session. Keep `for` to the role and let `read` and the guide carry the detail. A role says what reading the snapshot settles: \"Effect is the application framework\" only restates the project's imports, while the use above names what it settles.\n\n`scope` shares that line, so write it in as few globs as name the feature exactly: `dir/**` for a directory the feature owns, one brace glob for sibling files (`scripts/{release.mts,distribution.ts}`, `.github/workflows/{publish,release-*}.yml`), never one glob per file. Shorter must not mean wider: every file a scope matches costs a read of its evidence before any change there.\n\n## Check\n\n```bash\nvendy check # every finding across the map; exits non-zero on any\nvendy check <name> # one repo's uses\n```\n\nEach finding is decidable without judgment:\n\n- a `uses` field with the wrong shape, or a `for` over budget or containing `[`, `]`, `→` or `·`\n- a `scope` glob, or one of its brace alternatives, that matches or excludes no file — the feature it covered is gone\n- a `read` path the snapshot does not contain — upstream moved or deleted it\n- a `guide` that does not exist\n- a provisional use\n- a session catalog over the hook's 10,000-character limit even with only each use's `for` and scope; only when no repo is named\n- a library repo whose dependency, in a package its scope covers, is behind its snapshot, or ahead of it\n- a project file importing a vendored package that no use's scope covers or excludes\n\nWhether the code inside a scope actually follows its evidence takes judgment, and belongs to the health workflow.\n\n## Inspect\n\n```bash\nvendy list # all repos, including local ones; offline\nvendy show <name> # source, ref, pin, paths, mode, dependencies, uses\nvendy status # local integrity and upstream changes\nvendy status --log # also count and list the upstream commits touching each behind repo\nvendy catalog # the map as agents receive it\nvendy catalog <name>... # only these repos, with where to read\nvendy diff <name> # pinned snapshot versus local bytes\nvendy diff <name> <from>..<to> # revision range, filtered to repo paths\nvendy diff <name> <from>..<to> --read # only the paths the uses read; --stat for a diffstat\nvendy diff <name> <from>..<to> --dirstat # where upstream changed, by directory\nvendy diff <name> <from>..<to> <path>... # only these paths in the snapshot\nvendy diff <name> <from>..<to> --log # the upstream commits in the range, one per line\nvendy git <name> show <from>:<path>\n```\n\nSnapshots have no `.git`; read upstream history with `vendy diff`, and use `vendy git <name> <args>` for any other Git operation — everything after the name goes to git.\n\n`list`, `show`, `status`, and `check` take `--json` to print the same report as one JSON document, with the same exit code.\n\n`status` exits non-zero for stale, modified, unexpectedly missing, or `unverified` snapshots. Behind or unreachable upstreams do not fail it. `stale` means the pin or `paths` moved, as in a pull or a cherry-pick, and the snapshot did not; run the `vendy sync <name>...` it names. `unverified` means local integrity cannot be established, commonly after clearing the cache; run `vendy sync <name>`.\n\n## Maintain\n\n```bash\nvendy sync [<name>...] # restore bytes to existing pins\nvendy sync --prune # also delete what no repo owns: snapshot dirs, store views, indexes\nvendy mode <mode> <name>... # move repos between shared and local\nvendy local pull [<name>...] # copy the main worktree's local repos into this one\nvendy remove <name>... # remove repos, their uses, and their worktree state\nvendy store list # the shared cache: each upstream, its size, when it was last used\nvendy store gc --dry-run # preview cache cleanup; default age is 90 days\nvendy store gc --max-age 30d # reclaim eligible cache data\n```\n\n`sync` keeps pins fixed; moving them is the update workflow. A new worktree starts with no local repos, and `vendy local pull` never overwrites a copy that differs.\n\nThe store is a rebuildable cache shared across projects. `remove` and `sync --prune` leave it intact; `store gc` reclaims it, skipping busy or recently used stores. Commands that fetch also run it on their own, at most once a day (`VENDY_STORE_AUTO_CLEAN_FREQUENCY`: `never`, `always`, or a duration such as `12h`). `store gc --repack` also compacts retained stores.\n\n## Recover\n\n- **Modified snapshot:** inspect with `vendy diff <name>`. Before `sync` or `update` overwrites edits, it saves a rescue.\n- **Stale or missing snapshot:** run `vendy sync <name>`.\n- **Failed operation:** do not delete internal locks or migration data as a generic repair.\n\nRescues belong to the current worktree and survive shared-cache cleanup. Removing a repo or pruning its orphan store view deletes its rescues too; recover anything needed first.\n"
|
|
46190
46189
|
},
|
|
46191
46190
|
"health": {
|
|
46192
46191
|
description: "Audit the whole map, or only the repos named — run vendy status and vendy check, let the user choose whether to bring any repo that is behind up to date first through the update workflow, then judge use by use whether the code in each scope follows its evidence, whether the map still describes the project, and whether each guide still holds. Fixes every finding, each citing both sides, commits the fixes, and reports what changed.",
|
|
@@ -46206,7 +46205,7 @@ const skills$1 = {
|
|
|
46206
46205
|
},
|
|
46207
46206
|
"update": {
|
|
46208
46207
|
description: "Move snapshots to their newest upstream — 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, take up new upstream features the map has a use for, commit each repo, and report what changed. Also covers updating a dependency that is not a repo, through a temporary local repo or its changelog alone.",
|
|
46209
|
-
content: "---\nname: update\ndescription: Move snapshots to their newest upstream — 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, take up new upstream features the map has a use for, commit each repo, and report what changed. 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. The steps below take one repo, or one group of repos whose dependencies move together, from its pin to a commit.\n\nTake the repos named, or every repo in `vendy catalog`. Of those, the ones with work are what `vendy status` shows behind, what `vendy check` reports as a dependency and snapshot that disagree, and any library repo still on a branch. A package named that is no repo follows \"Updating a dependency that is not a repo\".\n\nWhen several repos have work, give each repo or group its own subagent, in its own worktree of the current commit. A group is repos whose dependencies move together, such as packages released from one monorepo. Brief each with exactly this, filling in its names; the workflow and the catalog give it everything else:\n\n```text\nRun vendy's update workflow (`vendy skills get update`) for <names>. Commit on this worktree's branch; do not push. Report as its step 5 says.\n```\n\nBring their commits in one at a time. Where both sides of a conflict changed only their own repos' lines, as in a shared version list, keep each side's change to its own lines. When a commit touches the lockfile, conflicted or not, regenerate it through the package manager rather than editing it, and keep the result in that same commit.
|
|
46208
|
+
content: "---\nname: update\ndescription: Move snapshots to their newest upstream — 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, take up new upstream features the map has a use for, commit each repo, and report what changed. 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. The steps below take one repo, or one group of repos whose dependencies move together, from its pin to a commit.\n\nTake the repos named, or every repo in `vendy catalog`. Of those, the ones with work are what `vendy status` shows behind, what `vendy check` reports as a dependency and snapshot that disagree, and any library repo still on a branch. A package named that is no repo follows \"Updating a dependency that is not a repo\".\n\nWhen several repos have work, give each repo or group its own subagent, in its own worktree of the current commit. A group is repos whose dependencies move together, such as packages released from one monorepo. Brief each with exactly this, filling in its names; the workflow and the catalog give it everything else:\n\n```text\nRun vendy's update workflow (`vendy skills get update`) for <names>. Commit on this worktree's branch; do not push. Report as its step 5 says.\n```\n\nBring their commits in one at a time. Where both sides of a conflict changed only their own repos' lines, as in a shared version list, keep each side's change to its own lines. When a commit touches the lockfile, conflicted or not, regenerate it through the package manager rather than editing it, and keep the result in that same commit. Once a subagent's commit is in, or it committed nothing, remove its worktree and branch: `git worktree remove <path>`, then `git branch -D <branch>`. With every commit in, run `vendy sync <names>` for the repos they moved — a cherry-pick moves pins, not snapshots — then `vendy check` and the project's full checks and tests, once. Then report once, as step 5 says, for all of them.\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\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 diff <name> <from>..<to> --log` and the diffstat `vendy update` printed; for a large update, `vendy diff <name> <from>..<to> --dirstat` shows it by directory, and `vendy diff <name> <from>..<to> <path>...` shows how the files a feature touches changed.\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 alone, or the pin and its dependency.\n\nAnything affected → carry it forward without asking, the recommended features as well as the required changes: change the code, update the `read` paths and guides, and commit — one commit per repo or group, holding its pins, its dependencies, and the code and guides that followed it.\n\nEither way, in the project's commit style, the subject names each repo and the range `vendy update` printed, as in `Update effect to 4.0.5 (e17ecdb..7f524e2)` for a release or `Update cargo to 0892e1e (3960fa6..0892e1e)` for a branch, and the body says what changed and which upstream change each part follows.\n\nBefore committing, verify what the commit changes, and no more:\n\n- **Pins only**, no dependency or code: `vendy check` alone. The project's tests run nothing a pin moves.\n- **A dependency or code**: `vendy check`, then the project's checks and the tests that cover what changed. A subagent stops there; the orchestrator, or an update run without subagents, runs the full checks and tests once, after every commit is in.\n\nWhen the project's commit hook already runs its checks or tests, let the commit run them rather than running them first.\n\nWhen a repo or group cannot be carried forward cleanly — a migration too large for this pass, tests that will not go green — put it back where it was: `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## 5. Report what changed\n\nFor each repo: from and to, its commit, what changed in the code, the map, and the guides, and the upstream features it took up. Then each repo put back, and why.\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, vendor it at the release now installed by that workflow's \"Vendoring an installed dependency\", and say so in the report.\n"
|
|
46210
46209
|
},
|
|
46211
46210
|
"vendor": {
|
|
46212
46211
|
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.",
|
|
@@ -46722,10 +46721,13 @@ const setup = make("setup", {
|
|
|
46722
46721
|
if (agents.length === 0) yield* error("no session hook installed; `vendy catalog` will not be injected automatically");
|
|
46723
46722
|
yield* note$1(render$2(yield* devDependencyGap(preview.root)));
|
|
46724
46723
|
}, reportErrors)).pipe(withDescription("Install or repair vendy's project guidance and agent hooks"));
|
|
46725
|
-
const statusVerdict = (statuses)
|
|
46724
|
+
const statusVerdict = fnUntraced(function* (statuses) {
|
|
46726
46725
|
const dirty = statuses.filter(isDirty).length;
|
|
46727
|
-
|
|
46728
|
-
}
|
|
46726
|
+
const stale = statuses.filter(isStale).map((status) => status.name);
|
|
46727
|
+
const of = `of ${statuses.length} ${statuses.length === 1 ? "repo" : "repos"}`;
|
|
46728
|
+
const findings = [...dirty === 0 ? [] : [`${dirty} ${of} locally modified or missing`], ...stale.length === 0 ? [] : [`${stale.length} ${dirty === 0 ? `${of} ` : ""}stale, not materialized from ${stale.length === 1 ? "its pin" : "their pins"}; run \`${yield* command$1("sync", ...stale)}\``]];
|
|
46729
|
+
if (findings.length > 0) return yield* new StatusDirty({ message: findings.join("; ") });
|
|
46730
|
+
});
|
|
46729
46731
|
const status = make("status", {
|
|
46730
46732
|
names: String$2("name").pipe(withDescription$2("Repos to show; omit to show every repo"), variadic()),
|
|
46731
46733
|
log: Boolean$1("log").pipe(withDefault(false), withDescription$1("Count and preview the upstream commits touching each repo that is behind")),
|
|
@@ -46761,7 +46763,7 @@ const status = make("status", {
|
|
|
46761
46763
|
if (statuses.length === 0 && localCopies.pullable.length === 0) yield* emptyInventoryHint;
|
|
46762
46764
|
if (storeFinding !== void 0) yield* error(`shared store cache is missing; run \`${command$2(runner$1, "sync")}\` to rebuild it`);
|
|
46763
46765
|
return yield* statusVerdict(statuses);
|
|
46764
|
-
}, reportErrors)).pipe(withDescription("Show each repo against upstream and on disk: behind, modified, or missing"));
|
|
46766
|
+
}, reportErrors)).pipe(withDescription("Show each repo against upstream and on disk: behind, stale, modified, or missing"));
|
|
46765
46767
|
const printWorkflows = fn("Cli.printWorkflows")(function* () {
|
|
46766
46768
|
yield* printLines(list$1);
|
|
46767
46769
|
});
|
|
@@ -46830,7 +46832,7 @@ const withGitSeparator = (args) => {
|
|
|
46830
46832
|
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));
|
|
46831
46833
|
//#endregion
|
|
46832
46834
|
//#region src/main.ts
|
|
46833
|
-
const version = "0.
|
|
46835
|
+
const version = "0.4.0";
|
|
46834
46836
|
const isSqliteExperimentalWarning = (warning) => warning.name === "ExperimentalWarning" && warning.message.startsWith("SQLite ");
|
|
46835
46837
|
for (const printWarning of process.listeners("warning")) {
|
|
46836
46838
|
process.off("warning", printWarning);
|
package/package.json
CHANGED