@zebeqo/vendy 0.2.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.
Files changed (2) hide show
  1. package/dist/main.mjs +194 -122
  2. package/package.json +1 -1
package/dist/main.mjs CHANGED
@@ -26761,6 +26761,12 @@ const Use = Struct({
26761
26761
  read: optionalKey(Lines),
26762
26762
  guide: optionalKey(Line)
26763
26763
  });
26764
+ const lineDelimiters = [
26765
+ "[",
26766
+ "]",
26767
+ "→",
26768
+ "·"
26769
+ ];
26764
26770
  const normalizePath = (path) => path.replace(/^\.\//, "").replace(/\/+$/, "");
26765
26771
  const scopeAlternatives = (glob) => {
26766
26772
  for (let open = 0; open < glob.length; open++) {
@@ -26799,13 +26805,14 @@ const partitionScope = (scope) => ({
26799
26805
  });
26800
26806
  const unlocated = (use) => ["scope", "read"].filter((key) => use[key] === void 0);
26801
26807
  const isProvisional = (use) => unlocated(use).length > 0;
26808
+ const scopeText = (use) => use.scope === void 0 ? "" : ` [${use.scope.join(", ")}]`;
26809
+ const provisionalText = (use) => isProvisional(use) ? " (provisional)" : "";
26802
26810
  const line = (use) => {
26803
- const scope = use.scope === void 0 ? "" : ` [${use.scope.join(", ")}]`;
26804
26811
  const read = use.read === void 0 ? "" : ` → ${use.read.join(", ")}`;
26805
- const provisional = isProvisional(use) ? " (provisional)" : "";
26806
26812
  const guide = use.guide === void 0 ? "" : ` · guide ${use.guide}`;
26807
- return `${use.for}${scope}${read}${provisional}${guide}`;
26813
+ return `${use.for}${scopeText(use)}${read}${provisionalText(use)}${guide}`;
26808
26814
  };
26815
+ const scopeLine = (use) => `${use.for}${scopeText(use)}${provisionalText(use)}`;
26809
26816
  const sameLines = (left, right) => left?.join("\0") === right?.join("\0");
26810
26817
  const same = (left, right) => left.for === right.for && sameLines(left.scope, right.scope) && sameLines(left.read, right.read) && left.guide === right.guide;
26811
26818
  const sameUses = (left, right) => left.length === right.length && left.every((use, index) => {
@@ -27188,7 +27195,7 @@ const failUnknownNames = fnUntraced(function* (names) {
27188
27195
  recovery: yield* render$9({ _tag: "UnknownNames" })
27189
27196
  });
27190
27197
  });
27191
- const select$1 = fn("Inventory.select")(function* (inventory, names) {
27198
+ const select$2 = fn("Inventory.select")(function* (inventory, names) {
27192
27199
  const { selected, unknown } = selectNamed(inventory, names, ({ repo }) => repo.name);
27193
27200
  if (unknown.length > 0) return yield* failUnknownNames(unknown);
27194
27201
  return selected;
@@ -30213,11 +30220,7 @@ const inspectAtLocked = fnUntraced(function* (options, location) {
30213
30220
  const fs = yield* FileSystem;
30214
30221
  if ((yield* fs.exists(location.store)) && (yield* fs.exists(location.index))) return yield* gen(function* () {
30215
30222
  yield* verifyStoreAt(location);
30216
- if (!(yield* matchesRepoAt(location, options.repo))) {
30217
- yield* mark(location.storeRoot, location.key.fileName);
30218
- return { _tag: "Modified" };
30219
- }
30220
- 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" };
30221
30224
  if (state._tag === "Clean") yield* recordMaterialized(location, options.repo.commit);
30222
30225
  yield* mark(location.storeRoot, location.key.fileName);
30223
30226
  return state;
@@ -34336,6 +34339,7 @@ const render$5 = (current, install) => {
34336
34339
  const events = ["SessionStart", "SubagentStart"];
34337
34340
  const cursorEvents = ["sessionStart"];
34338
34341
  const hookEvents = [...events, ...cursorEvents];
34342
+ const contextLimit = 1e4;
34339
34343
  const agents = [
34340
34344
  "claude",
34341
34345
  "codex",
@@ -34632,6 +34636,13 @@ const withSnapshot = fnUntraced(function* (root, git, item) {
34632
34636
  snapshot: recorded?.trim() === item.repo.commit ? "Current" : "Stale"
34633
34637
  };
34634
34638
  });
34639
+ const select$1 = fn("Catalog.select")(function* (loaded, names) {
34640
+ if (names.length === 0) return loaded;
34641
+ return {
34642
+ items: yield* select$2(loaded.items, names),
34643
+ pullable: 0
34644
+ };
34645
+ });
34635
34646
  const load = fn("Catalog.load")(function* (cwd) {
34636
34647
  const pathService = yield* Path$1;
34637
34648
  const root = yield* findRoot(cwd);
@@ -34652,6 +34663,86 @@ const load = fn("Catalog.load")(function* (cwd) {
34652
34663
  pullable: mainLocal?.manifest.repos.filter((repo) => !here.has(repo.name)).length ?? 0
34653
34664
  };
34654
34665
  });
34666
+ const header = (runner) => `Vendored repos in this worktree (\`${runner} catalog\`), each at ${vendorDir}/<name>.`;
34667
+ const legend = "Each use: what this project draws on it for [the project files it governs] → where in the snapshot to read · its guide, a file in this project. Before changing a file a use governs, read those paths and the guide.";
34668
+ const scopesLegend = (runner) => `Each use: what this project draws on it for [the project files it governs]. Before changing a file a use governs, run \`${runner} catalog <name>\`: it prints that repo's uses in full, adding → where in the snapshot to read · its guide, a file in this project. Then read those paths and the guide.`;
34669
+ const empty = `No repos are vendored under ${vendorDir}/ in this worktree.`;
34670
+ const unreadable = (detail) => [
34671
+ `No vendored catalog is available this session: ${manifestFileName} could not be read.`,
34672
+ "",
34673
+ detail,
34674
+ "",
34675
+ "Report this to the user. Fix a use by hand; repair anything else with the vendy verbs."
34676
+ ];
34677
+ const parenthetical = (item) => {
34678
+ const { ref } = item.repo;
34679
+ const parts = [`at ${isCommitSha(ref) ? shortSha(ref) : ref}`];
34680
+ if (item.local) parts.push("local");
34681
+ if (item.snapshot !== "Current") parts.push(item.snapshot === "Missing" ? "missing" : "stale");
34682
+ if (item.repo.paths !== void 0) parts.push(`only ${item.repo.paths.map((path) => `${path}/`).join(", ")}`);
34683
+ return ` (${parts.join("; ")})`;
34684
+ };
34685
+ const repoLines = (item, useLine) => [`- ${item.repo.name}${parenthetical(item)}`, ...(item.repo.uses ?? []).map((use) => ` - ${useLine(use)}`)];
34686
+ const missingLine = (count, runner) => `${count} ${count === 1 ? "snapshot is" : "snapshots are"} missing: run \`${runner} sync <name>\` before reading ${count === 1 ? "it" : "them"}, not another worktree's copy, which may be at another pin.`;
34687
+ const staleLine = (count, runner) => `${count} ${count === 1 ? "snapshot is" : "snapshots are"} stale, not materialized from ${count === 1 ? "its pin" : "their pins"}: run \`${runner} sync <name>\` before reading ${count === 1 ? "it" : "them"}.`;
34688
+ const provisionalLine = (count, runner) => `${count} ${count === 1 ? "use is" : "uses are"} provisional: the scope or evidence is not recorded yet. Find the evidence in the snapshot before building on it, then record both (\`${runner} skills get align\`).`;
34689
+ const pullLine = (count, runner) => `${count} local ${count === 1 ? "repo" : "repos"} in the main worktree ${count === 1 ? "is" : "are"} not in this one: run \`${runner} local pull\` to copy ${count === 1 ? "it" : "them"} here.`;
34690
+ const entries = ({ items, pullable }, runner, useLine) => {
34691
+ const missing = items.filter((item) => item.snapshot === "Missing").length;
34692
+ const stale = items.filter((item) => item.snapshot === "Stale").length;
34693
+ const provisional = items.flatMap((item) => item.repo.uses ?? []).filter(isProvisional).length;
34694
+ const footer = [
34695
+ ...missing === 0 ? [] : [missingLine(missing, runner)],
34696
+ ...stale === 0 ? [] : [staleLine(stale, runner)],
34697
+ ...provisional === 0 ? [] : [provisionalLine(provisional, runner)],
34698
+ ...pullable === 0 ? [] : [pullLine(pullable, runner)]
34699
+ ];
34700
+ return [...items.flatMap((item) => repoLines(item, useLine)), ...footer.length === 0 ? [] : ["", ...footer]];
34701
+ };
34702
+ const listing = (loaded, runner, form) => {
34703
+ const hasUses = loaded.items.some((item) => (item.repo.uses ?? []).length > 0);
34704
+ return [
34705
+ header(runner),
34706
+ ...hasUses ? [form.legend] : [],
34707
+ "",
34708
+ ...entries(loaded, runner, form.useLine)
34709
+ ];
34710
+ };
34711
+ const text = (lines) => lines.join("\n");
34712
+ const render$4 = (loaded, runner) => {
34713
+ if (loaded.items.length === 0) return loaded.pullable === 0 ? [empty] : [
34714
+ empty,
34715
+ "",
34716
+ pullLine(loaded.pullable, runner)
34717
+ ];
34718
+ return listing(loaded, runner, {
34719
+ legend,
34720
+ useLine: line
34721
+ });
34722
+ };
34723
+ const renderNamed = (loaded, runner) => entries(loaded, runner, line);
34724
+ /** The whole catalog when it fits in `limit` characters; otherwise each use with only its `for` and scope. */
34725
+ const renderWithin = (loaded, runner, limit) => {
34726
+ const full = render$4(loaded, runner);
34727
+ return text(full).length <= limit ? full : listing(loaded, runner, {
34728
+ legend: scopesLegend(runner),
34729
+ useLine: scopeLine
34730
+ });
34731
+ };
34732
+ const inFreshWorktree = (inventory) => ({
34733
+ items: inventory.map((item) => ({
34734
+ ...item,
34735
+ snapshot: "Missing"
34736
+ })),
34737
+ pullable: 0
34738
+ });
34739
+ const hookOutput = (event, lines) => {
34740
+ const additionalContext = text(lines);
34741
+ return event === "sessionStart" ? JSON.stringify({ additional_context: additionalContext }) : JSON.stringify({ hookSpecificOutput: {
34742
+ hookEventName: event,
34743
+ additionalContext
34744
+ } });
34745
+ };
34655
34746
  //#endregion
34656
34747
  //#region ../../node_modules/.pnpm/picomatch@4.0.7/node_modules/picomatch/lib/constants.js
34657
34748
  var require_constants = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -36612,11 +36703,25 @@ const specifierPattern = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*im
36612
36703
  const specifiers = (source) => new Set([...source.matchAll(specifierPattern)].map((match) => match[1] ?? ""));
36613
36704
  const loads = (specifier, name) => specifier === name || specifier.startsWith(`${name}/`);
36614
36705
  //#endregion
36706
+ //#region ../core/src/Runner.ts
36707
+ const io = {
36708
+ existsSync,
36709
+ readFileSync,
36710
+ join,
36711
+ dirname
36712
+ };
36713
+ const packageManager = (root) => detectPackageManager(root, io);
36714
+ const commands = (packageManager) => runnerCommands(packageManager, packageName$1, executable);
36715
+ const command = (packageManager) => commands(packageManager)[0] ?? "vendy";
36716
+ const invocation = (root) => findLocalCli(root, "@zebeqo/vendy", "vendy", io) === void 0 ? executable : command(packageManager(root));
36717
+ //#endregion
36615
36718
  //#region ../core/src/Check.ts
36616
36719
  const quote = (text) => `"${text.length > 48 ? `${text.slice(0, 47)}…` : text}"`;
36617
36720
  const describe = (finding, runner) => {
36618
36721
  switch (finding._tag) {
36722
+ case "CatalogOverLimit": return `the session catalog is ${finding.length} characters with only each use's \`for\` and scope, over the ${finding.limit} Claude Code injects; shorten \`for\`s and scopes, or remove repos the project no longer draws on`;
36619
36723
  case "ForOverBudget": return `use ${quote(finding.for)} has a ${finding.for.length}-character \`for\`; keep it to the role in 120, and let \`read\` and the guide carry the rest`;
36724
+ case "ForHasDelimiter": return `use ${quote(finding.for)}: \`for\` contains ${finding.delimiters.map((delimiter) => `"${delimiter}"`).join(", ")}, which the catalog writes between a use's parts; reword it`;
36620
36725
  case "Provisional": return `use ${quote(finding.for)} is provisional: it has no ${finding.missing.map((key) => `\`${key}\``).join(" or ")} yet`;
36621
36726
  case "ScopeMatchesNothing": {
36622
36727
  const verb = isExclusion(finding.glob) ? "excludes" : "matches";
@@ -36638,7 +36743,17 @@ const describe = (finding, runner) => {
36638
36743
  }
36639
36744
  }
36640
36745
  };
36641
- const message = (finding, runner) => `${finding.name}: ${describe(finding, runner)}`;
36746
+ const message = (finding, runner) => finding._tag === "CatalogOverLimit" ? describe(finding, runner) : `${finding.name}: ${describe(finding, runner)}`;
36747
+ const catalogFindings = (root, inventory) => {
36748
+ const limit = contextLimit;
36749
+ const lines = renderWithin(inFreshWorktree(inventory), command(packageManager(root)), limit);
36750
+ const { length } = text(lines);
36751
+ return length > limit ? [{
36752
+ _tag: "CatalogOverLimit",
36753
+ length,
36754
+ limit
36755
+ }] : [];
36756
+ };
36642
36757
  const listFiles = fnUntraced(function* (root, args) {
36643
36758
  return (yield* run$17([
36644
36759
  "ls-files",
@@ -36701,26 +36816,35 @@ const scopeFindings = (name, purpose, glob, files) => {
36701
36816
  alternative
36702
36817
  }));
36703
36818
  };
36704
- const useFindings = (name, use, files, guides) => [
36705
- ...use.for.length > 120 ? [{
36706
- _tag: "ForOverBudget",
36707
- name,
36708
- for: use.for
36709
- }] : [],
36710
- ...isProvisional(use) ? [{
36711
- _tag: "Provisional",
36712
- name,
36713
- for: use.for,
36714
- missing: unlocated(use)
36715
- }] : [],
36716
- ...(use.scope ?? []).flatMap((glob) => scopeFindings(name, use.for, glob, files)),
36717
- ...use.guide === void 0 || guides.has(normalize(use.guide)) ? [] : [{
36718
- _tag: "GuideMissing",
36719
- name,
36720
- for: use.for,
36721
- guide: use.guide
36722
- }]
36723
- ];
36819
+ const useFindings = (name, use, files, guides) => {
36820
+ const delimiters = lineDelimiters.filter((delimiter) => use.for.includes(delimiter));
36821
+ return [
36822
+ ...use.for.length > 120 ? [{
36823
+ _tag: "ForOverBudget",
36824
+ name,
36825
+ for: use.for
36826
+ }] : [],
36827
+ ...delimiters.length === 0 ? [] : [{
36828
+ _tag: "ForHasDelimiter",
36829
+ name,
36830
+ for: use.for,
36831
+ delimiters
36832
+ }],
36833
+ ...isProvisional(use) ? [{
36834
+ _tag: "Provisional",
36835
+ name,
36836
+ for: use.for,
36837
+ missing: unlocated(use)
36838
+ }] : [],
36839
+ ...(use.scope ?? []).flatMap((glob) => scopeFindings(name, use.for, glob, files)),
36840
+ ...use.guide === void 0 || guides.has(normalize(use.guide)) ? [] : [{
36841
+ _tag: "GuideMissing",
36842
+ name,
36843
+ for: use.for,
36844
+ guide: use.guide
36845
+ }]
36846
+ ];
36847
+ };
36724
36848
  const localGuideFindings = (name, use, project) => {
36725
36849
  if (use.guide === void 0) return [];
36726
36850
  const guide = normalize(use.guide);
@@ -36837,7 +36961,7 @@ const inspect$4 = fn("Check.inspect")(function* (options) {
36837
36961
  });
36838
36962
  const { root } = view;
36839
36963
  const inventory = view.items;
36840
- const selected = yield* select$1(inventory, options.names);
36964
+ const selected = yield* select$2(inventory, options.names);
36841
36965
  const listed = yield* projectFiles(root);
36842
36966
  const files = listed.files;
36843
36967
  const guides = /* @__PURE__ */ new Set();
@@ -36897,6 +37021,7 @@ const inspect$4 = fn("Check.inspect")(function* (options) {
36897
37021
  findings.push(...report.findings);
36898
37022
  dependencies.push(...report.dependencies);
36899
37023
  }
37024
+ if (options.names === void 0 || options.names.length === 0) findings.push(...catalogFindings(root, inventory));
36900
37025
  return {
36901
37026
  findings,
36902
37027
  dependencies
@@ -37028,7 +37153,7 @@ const run$10 = fn("LocalPull.run")(function* (options = {}) {
37028
37153
  });
37029
37154
  const state = view.local;
37030
37155
  const source = yield* findSource(state, options.from, options.cwd ?? process.cwd());
37031
- const selected = yield* select$1(repos(empty$1, source.manifest), options.names);
37156
+ const selected = yield* select$2(repos(empty$1, source.manifest), options.names);
37032
37157
  const outcomes = yield* forEach$1(selected, fnUntraced(function* ({ repo }) {
37033
37158
  const here = state.current.manifest.repos.find((existing) => existing.name === repo.name);
37034
37159
  const outcome = here !== void 0 ? {
@@ -37144,18 +37269,6 @@ const run$8 = fn("Remove.run")(function* (options) {
37144
37269
  };
37145
37270
  });
37146
37271
  //#endregion
37147
- //#region ../core/src/Runner.ts
37148
- const io = {
37149
- existsSync,
37150
- readFileSync,
37151
- join,
37152
- dirname
37153
- };
37154
- const packageManager = (root) => detectPackageManager(root, io);
37155
- const commands = (packageManager) => runnerCommands(packageManager, packageName$1, executable);
37156
- const command = (packageManager) => commands(packageManager)[0] ?? "vendy";
37157
- const invocation = (root) => findLocalCli(root, "@zebeqo/vendy", "vendy", io) === void 0 ? executable : command(packageManager(root));
37158
- //#endregion
37159
37272
  //#region ../core/src/AgentsFile.ts
37160
37273
  const targetNames = agentsFileNames;
37161
37274
  var UnusableAgentsFile = class extends TaggedError()("UnusableAgentsFile", {
@@ -37294,7 +37407,7 @@ const ownedEntry = (settings) => {
37294
37407
  };
37295
37408
  const ownedIndices = (autoImports) => (autoImports?.children ?? []).flatMap((pattern, index) => pattern.type === "string" && pattern.value === vendoredPattern ? [index] : []);
37296
37409
  /** Parses before editing: jsonc-parser's editor tolerates faults that setup must skip. */
37297
- const render$4 = (current, install) => {
37410
+ const render$3 = (current, install) => {
37298
37411
  if (!install && current === void 0) return succeed$7(void 0);
37299
37412
  const source = current ?? "{}\n";
37300
37413
  const errors = [];
@@ -37357,7 +37470,7 @@ const render$4 = (current, install) => {
37357
37470
  return next;
37358
37471
  });
37359
37472
  };
37360
- const inspect$2 = (current) => flatMap$3(render$4(current, false), (without) => without === current ? succeed$7("Absent") : map$10(render$4(current, true), (installed) => installed === current ? "Current" : "Stale"));
37473
+ const inspect$2 = (current) => flatMap$3(render$3(current, false), (without) => without === current ? succeed$7("Absent") : map$10(render$3(current, true), (installed) => installed === current ? "Current" : "Stale"));
37361
37474
  //#endregion
37362
37475
  //#region ../core/src/Setup.ts
37363
37476
  const inspectVSCodeSettings = fnUntraced(function* (root) {
@@ -37460,7 +37573,7 @@ const planVSCodeBody = fnUntraced(function* (file, install) {
37460
37573
  if (yield* isSymbolicLink(pathService.dirname(file.absolute))) return skippedFile(file, "its parent directory is a symbolic link, and vendy will not write through it");
37461
37574
  if (yield* isSymbolicLink(file.absolute)) return skippedFile(file, "it is a symbolic link, and vendy will not replace the link");
37462
37575
  const current = yield* readFileStringOptional(file.absolute);
37463
- const rendered = render$4(current, install);
37576
+ const rendered = render$3(current, install);
37464
37577
  if (isFailure$1(rendered)) return skippedFile(file, rendered.failure.detail);
37465
37578
  return filePlan(file, current, rendered.success);
37466
37579
  });
@@ -37562,7 +37675,7 @@ const devDependencyGap = fn("Setup.devDependencyGap")(function* (root) {
37562
37675
  const contents = yield* readFileStringOptional(pathService.join(root, "package.json"));
37563
37676
  return contents !== void 0 && declarations(/* @__PURE__ */ new Map([["package.json", contents]])).some((declaration) => declaration.name === "@zebeqo/vendy") ? void 0 : packageManager(root);
37564
37677
  });
37565
- const render$3 = (devDependency) => `Next steps:\n${[
37678
+ const render$2 = (devDependency) => `Next steps:\n${[
37566
37679
  ...devDependency === void 0 ? [] : [devDependencyPointer(devDependency)],
37567
37680
  skillPointer,
37568
37681
  formatterReminder
@@ -37674,7 +37787,8 @@ const checkUpstream = fn("Status.checkUpstream")(function* (root, repo, log) {
37674
37787
  }
37675
37788
  }
37676
37789
  });
37677
- 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";
37678
37792
  const check$1 = fn("Status.check")(function* (options = {}) {
37679
37793
  const fs = yield* FileSystem;
37680
37794
  const view = yield* read$2({
@@ -37682,7 +37796,7 @@ const check$1 = fn("Status.check")(function* (options = {}) {
37682
37796
  cwd: options.cwd
37683
37797
  });
37684
37798
  const root = view.root;
37685
- const selected = yield* select$1(view.items, options.names);
37799
+ const selected = yield* select$2(view.items, options.names);
37686
37800
  const inspect = fnUntraced(function* (item) {
37687
37801
  const { repo } = item;
37688
37802
  const [upstream, snapshot] = yield* all([checkUpstream(root, repo, options.log === true), inspect$6({
@@ -38458,7 +38572,7 @@ const run$4 = fn("Sync.run")(function* (options = {}) {
38458
38572
  const root = view.root;
38459
38573
  yield* ensureDirectoryBoundary(root, vendorDir);
38460
38574
  const inventory = view.items;
38461
- const selected = yield* select$1(inventory, options.names);
38575
+ const selected = yield* select$2(inventory, options.names);
38462
38576
  yield* repair(root);
38463
38577
  const inspections = yield* forEach$1(selected, fnUntraced(function* (item) {
38464
38578
  const result$3 = yield* result(inspect$6({
@@ -38723,7 +38837,7 @@ const run$3 = fn("Update.run")(function* (options) {
38723
38837
  verb: "update",
38724
38838
  cwd: options.cwd
38725
38839
  });
38726
- const selected = yield* select$1(view.items, options.names);
38840
+ const selected = yield* select$2(view.items, options.names);
38727
38841
  if (selected.some((item) => !item.local) || selected.length === 0) yield* ensure$1(view.root, [manifestPath]);
38728
38842
  yield* repair(view.root);
38729
38843
  if (selected.length === 0) return [];
@@ -45780,62 +45894,6 @@ const runWith = (command, config) => {
45780
45894
  }, catchFilter((error) => isCliError(error) && error._tag === "ShowHelp" ? succeed$7(error) : fail$5(error), (error) => andThen(showHelp(command, error, config.renderErrors !== false), fail$1(error))), catchFilter((error) => config.renderErrors !== false && isCliError(error) && error._tag === "UserError" ? succeed$7(error) : fail$5(error), (error) => andThen(showUserError(error), fail$1(error))), catchFilter((e) => isQuitError(e) ? succeed$7(e) : fail$5(e), (_) => interrupt$1));
45781
45895
  };
45782
45896
  //#endregion
45783
- //#region src/cli/Catalog.ts
45784
- const header = (runner) => `Vendored repos in this worktree (\`${runner} catalog\`), each at ${vendorDir}/<name>.`;
45785
- const legend = "Each use: what this project draws on it for [the project files it governs] → where in the snapshot to read · its guide. Before changing a file a use governs, read those paths and the guide.";
45786
- const empty = `No repos are vendored under ${vendorDir}/ in this worktree.`;
45787
- const unreadable = (detail) => [
45788
- `No vendored catalog is available this session: ${manifestFileName} could not be read.`,
45789
- "",
45790
- detail,
45791
- "",
45792
- "Report this to the user. Fix a use by hand; repair anything else with the vendy verbs."
45793
- ];
45794
- const parenthetical = (item) => {
45795
- const { ref } = item.repo;
45796
- const parts = [`at ${isCommitSha(ref) ? shortSha(ref) : ref}`];
45797
- if (item.local) parts.push("local");
45798
- if (item.snapshot !== "Current") parts.push(item.snapshot === "Missing" ? "missing" : "stale");
45799
- if (item.repo.paths !== void 0) parts.push(`only ${item.repo.paths.map((path) => `${path}/`).join(", ")}`);
45800
- return ` (${parts.join(", ")})`;
45801
- };
45802
- const repoLines = (item) => [`- ${item.repo.name}${parenthetical(item)}`, ...(item.repo.uses ?? []).map((use) => ` - ${line(use)}`)];
45803
- const missingLine = (count, runner) => `${count} ${count === 1 ? "snapshot is" : "snapshots are"} missing: run \`${runner} sync <name>\` before reading ${count === 1 ? "it" : "them"}, not another worktree's copy, which may be at another pin.`;
45804
- const staleLine = (count, runner) => `${count} ${count === 1 ? "snapshot is" : "snapshots are"} stale, not materialized from ${count === 1 ? "its pin" : "their pins"}: run \`${runner} sync <name>\` before reading ${count === 1 ? "it" : "them"}.`;
45805
- const provisionalLine = (count, runner) => `${count} ${count === 1 ? "use is" : "uses are"} provisional: the scope or evidence is not recorded yet. Find the evidence in the snapshot before building on it, then record both (\`${runner} skills get align\`).`;
45806
- const pullLine = (count, runner) => `${count} local ${count === 1 ? "repo" : "repos"} in the main worktree ${count === 1 ? "is" : "are"} not in this one: run \`${runner} local pull\` to copy ${count === 1 ? "it" : "them"} here.`;
45807
- const render$2 = ({ items, pullable }, runner) => {
45808
- if (items.length === 0) return pullable === 0 ? [empty] : [
45809
- empty,
45810
- "",
45811
- pullLine(pullable, runner)
45812
- ];
45813
- const missing = items.filter((item) => item.snapshot === "Missing").length;
45814
- const stale = items.filter((item) => item.snapshot === "Stale").length;
45815
- const uses = items.flatMap((item) => item.repo.uses ?? []);
45816
- const provisional = uses.filter(isProvisional).length;
45817
- const footer = [
45818
- ...missing === 0 ? [] : [missingLine(missing, runner)],
45819
- ...stale === 0 ? [] : [staleLine(stale, runner)],
45820
- ...provisional === 0 ? [] : [provisionalLine(provisional, runner)],
45821
- ...pullable === 0 ? [] : [pullLine(pullable, runner)]
45822
- ];
45823
- return [
45824
- header(runner),
45825
- ...uses.length === 0 ? [] : [legend],
45826
- "",
45827
- ...items.flatMap(repoLines),
45828
- ...footer.length === 0 ? [] : ["", ...footer]
45829
- ];
45830
- };
45831
- const hookOutput = (event, lines) => {
45832
- const additionalContext = lines.join("\n");
45833
- return event === "sessionStart" ? JSON.stringify({ additional_context: additionalContext }) : JSON.stringify({ hookSpecificOutput: {
45834
- hookEventName: event,
45835
- additionalContext
45836
- } });
45837
- };
45838
- //#endregion
45839
45897
  //#region src/cli/Check.ts
45840
45898
  const code = (tag) => tag.replaceAll(/(?<!^)[A-Z]/gu, (letter) => `-${letter}`).toLowerCase();
45841
45899
  const json$2 = (findings, runner) => findings.map((finding) => {
@@ -45969,6 +46027,7 @@ const upstreamLabel = (upstream) => {
45969
46027
  };
45970
46028
  const widestSnapshotState = [
45971
46029
  "clean",
46030
+ "stale",
45972
46031
  "modified",
45973
46032
  "missing",
45974
46033
  "unverified"
@@ -45976,6 +46035,7 @@ const widestSnapshotState = [
45976
46035
  const snapshotState = (snapshot) => {
45977
46036
  switch (snapshot._tag) {
45978
46037
  case "Clean": return "clean";
46038
+ case "Stale": return "stale";
45979
46039
  case "Modified": return "modified";
45980
46040
  case "Missing": return "missing";
45981
46041
  case "Unverified": return "unverified";
@@ -46125,7 +46185,7 @@ const skills$1 = {
46125
46185
  },
46126
46186
  "core": {
46127
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).",
46128
- 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 | (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 | Where the evidence lives: docs, examples, tests, source | the use is provisional |\n| `guide` | the project root | This use's guide | no guide |\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\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 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 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"
46129
46189
  },
46130
46190
  "health": {
46131
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.",
@@ -46145,7 +46205,7 @@ const skills$1 = {
46145
46205
  },
46146
46206
  "update": {
46147
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.",
46148
- 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. Run the project's checks and tests after each commit that changes more than pins. 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>`. 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 once the project's own checks and tests pass.\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, run `vendy check` and the project's own checks and tests, 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\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"
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"
46149
46209
  },
46150
46210
  "vendor": {
46151
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.",
@@ -46568,17 +46628,26 @@ const list = make("list", { json: jsonFlag }, fn("Cli.list")(function* (config)
46568
46628
  if (lines.length === 0) return yield* emptyInventoryHint;
46569
46629
  return yield* printLines(lines);
46570
46630
  }, reportErrors)).pipe(withAlias("ls"), withDescription("List every repo, local ones included"));
46571
- const catalogLines = fn("Cli.catalogLines")(function* (cwd) {
46631
+ const catalogLines = fn("Cli.catalogLines")(function* (cwd, names, render) {
46572
46632
  const loaded = yield* result(load(cwd));
46573
- if (isSuccess$1(loaded)) return render$2(loaded.success, command(packageManager(cwd)));
46633
+ if (isSuccess$1(loaded)) return render(yield* select$1(loaded.success, names), command(packageManager(cwd)));
46574
46634
  const failure = loaded.failure;
46575
46635
  return failure._tag === "ManifestParseError" || failure._tag === "ManifestValidationError" ? unreadable(failure.message) : yield* failure;
46576
46636
  });
46577
- const catalog = make("catalog", { hook: Literals("hook", hookEvents).pipe(optional, withMetavar("event"), withDescription$1("Emit the payload as hook JSON for this lifecycle event instead of plain text"), withHidden) }, fn("Cli.catalog")(function* (config) {
46637
+ const renderHookCatalog = (loaded, runner) => renderWithin(loaded, runner, contextLimit);
46638
+ const catalogRenderer = (named, event) => {
46639
+ if (named) return renderNamed;
46640
+ return event === void 0 ? render$4 : renderHookCatalog;
46641
+ };
46642
+ const catalog = make("catalog", {
46643
+ names: String$2("name").pipe(withDescription$2("Repos to show; omit for every repo"), variadic()),
46644
+ hook: Literals("hook", hookEvents).pipe(optional, withMetavar("event"), withDescription$1("Emit the payload as hook JSON for this lifecycle event instead of plain text"), withHidden)
46645
+ }, fn("Cli.catalog")(function* (config) {
46578
46646
  const event = getOrUndefined$1(config.hook);
46579
- const lines = yield* catalogLines(process.cwd());
46580
- yield* event === void 0 ? printLines(lines) : log(hookOutput(event, lines));
46581
- }, ignoreCause())).pipe(withDescription("Print what agents receive at session start: every repo, one line per use"));
46647
+ const named = config.names.length > 0;
46648
+ const printed = catalogLines(process.cwd(), config.names, catalogRenderer(named, event)).pipe(flatMap$1((lines) => event === void 0 ? printLines(lines) : log(hookOutput(event, lines))));
46649
+ return yield* named ? reportErrors(printed) : printed.pipe(ignoreCause());
46650
+ })).pipe(withDescription("Print every repo, or the named ones, with one line per use and where to read for it"));
46582
46651
  const setupAgents = Literals("agent", agents).pipe(atLeast(1), optional, withMetavar("claude|codex|cursor|opencode"), withDescription$1("Install hooks for an agent; repeat to select several. Agents not named lose vendy's hooks"));
46583
46652
  const setupNoAgent = Boolean$1("no-agent").pipe(withDefault(false), withDescription$1("Install no session hooks, and uninstall any vendy installed before"));
46584
46653
  const resolveSetupAgents = fn("Cli.resolveSetupAgents")(function* (flag, none, interactive, inspection) {
@@ -46650,12 +46719,15 @@ const setup = make("setup", {
46650
46719
  yield* reportSkipped(newSkipped);
46651
46720
  yield* printLines(result.changed.map(planLine));
46652
46721
  if (agents.length === 0) yield* error("no session hook installed; `vendy catalog` will not be injected automatically");
46653
- yield* note$1(render$3(yield* devDependencyGap(preview.root)));
46722
+ yield* note$1(render$2(yield* devDependencyGap(preview.root)));
46654
46723
  }, reportErrors)).pipe(withDescription("Install or repair vendy's project guidance and agent hooks"));
46655
- const statusVerdict = (statuses) => {
46724
+ const statusVerdict = fnUntraced(function* (statuses) {
46656
46725
  const dirty = statuses.filter(isDirty).length;
46657
- return dirty > 0 ? fail$1(new StatusDirty({ message: `${dirty} of ${statuses.length} ${statuses.length === 1 ? "repo" : "repos"} locally modified or missing` })) : void_;
46658
- };
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
+ });
46659
46731
  const status = make("status", {
46660
46732
  names: String$2("name").pipe(withDescription$2("Repos to show; omit to show every repo"), variadic()),
46661
46733
  log: Boolean$1("log").pipe(withDefault(false), withDescription$1("Count and preview the upstream commits touching each repo that is behind")),
@@ -46691,7 +46763,7 @@ const status = make("status", {
46691
46763
  if (statuses.length === 0 && localCopies.pullable.length === 0) yield* emptyInventoryHint;
46692
46764
  if (storeFinding !== void 0) yield* error(`shared store cache is missing; run \`${command$2(runner$1, "sync")}\` to rebuild it`);
46693
46765
  return yield* statusVerdict(statuses);
46694
- }, 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"));
46695
46767
  const printWorkflows = fn("Cli.printWorkflows")(function* () {
46696
46768
  yield* printLines(list$1);
46697
46769
  });
@@ -46760,7 +46832,7 @@ const withGitSeparator = (args) => {
46760
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));
46761
46833
  //#endregion
46762
46834
  //#region src/main.ts
46763
- const version = "0.2.0";
46835
+ const version = "0.4.0";
46764
46836
  const isSqliteExperimentalWarning = (warning) => warning.name === "ExperimentalWarning" && warning.message.startsWith("SQLite ");
46765
46837
  for (const printWarning of process.listeners("warning")) {
46766
46838
  process.off("warning", printWarning);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zebeqo/vendy",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Let your coding agent choose, build with, and maintain vendored repos, and keep your code in step as upstream moves",
5
5
  "license": "MIT",
6
6
  "repository": {