@vibe-agent-toolkit/cli 0.2.0-rc.2 → 0.2.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/dist/bin/vat +66 -15
  2. package/dist/bin/vat.js +66 -15
  3. package/dist/bin/vat.js.map +1 -1
  4. package/dist/bin.js +155 -36
  5. package/dist/bin.js.map +1 -1
  6. package/dist/command-loaders.d.ts +44 -0
  7. package/dist/command-loaders.d.ts.map +1 -0
  8. package/dist/command-loaders.js +58 -0
  9. package/dist/command-loaders.js.map +1 -0
  10. package/dist/commands/agent/index.js +1 -1
  11. package/dist/commands/agent/install.d.ts.map +1 -1
  12. package/dist/commands/agent/install.js +46 -5
  13. package/dist/commands/agent/install.js.map +1 -1
  14. package/dist/commands/audit/distributed-tree.d.ts +1 -1
  15. package/dist/commands/audit/distributed-tree.d.ts.map +1 -1
  16. package/dist/commands/audit/distributed-tree.js.map +1 -1
  17. package/dist/commands/audit/hierarchical-output.d.ts +1 -1
  18. package/dist/commands/audit/hierarchical-output.d.ts.map +1 -1
  19. package/dist/commands/audit/hierarchical-output.js +1 -1
  20. package/dist/commands/audit/hierarchical-output.js.map +1 -1
  21. package/dist/commands/audit.d.ts +22 -1
  22. package/dist/commands/audit.d.ts.map +1 -1
  23. package/dist/commands/audit.js +223 -24
  24. package/dist/commands/audit.js.map +1 -1
  25. package/dist/commands/build.d.ts +1 -1
  26. package/dist/commands/build.d.ts.map +1 -1
  27. package/dist/commands/build.js +1 -1
  28. package/dist/commands/build.js.map +1 -1
  29. package/dist/commands/cache/cache-control.d.ts +73 -0
  30. package/dist/commands/cache/cache-control.d.ts.map +1 -0
  31. package/dist/commands/cache/cache-control.js +77 -0
  32. package/dist/commands/cache/cache-control.js.map +1 -0
  33. package/dist/commands/cache/clear.d.ts +17 -3
  34. package/dist/commands/cache/clear.d.ts.map +1 -1
  35. package/dist/commands/cache/clear.js +68 -3
  36. package/dist/commands/cache/clear.js.map +1 -1
  37. package/dist/commands/cache/index.d.ts +13 -63
  38. package/dist/commands/cache/index.d.ts.map +1 -1
  39. package/dist/commands/cache/index.js +38 -79
  40. package/dist/commands/cache/index.js.map +1 -1
  41. package/dist/commands/claude/budget.d.ts +157 -0
  42. package/dist/commands/claude/budget.d.ts.map +1 -0
  43. package/dist/commands/claude/budget.js +412 -0
  44. package/dist/commands/claude/budget.js.map +1 -0
  45. package/dist/commands/claude/context.d.ts +211 -0
  46. package/dist/commands/claude/context.d.ts.map +1 -0
  47. package/dist/commands/claude/context.js +709 -0
  48. package/dist/commands/claude/context.js.map +1 -0
  49. package/dist/commands/claude/index.d.ts +13 -0
  50. package/dist/commands/claude/index.d.ts.map +1 -1
  51. package/dist/commands/claude/index.js +24 -2
  52. package/dist/commands/claude/index.js.map +1 -1
  53. package/dist/commands/claude/marketplace/git-publish.d.ts.map +1 -1
  54. package/dist/commands/claude/marketplace/git-publish.js +18 -20
  55. package/dist/commands/claude/marketplace/git-publish.js.map +1 -1
  56. package/dist/commands/claude/marketplace/validate.d.ts +1 -1
  57. package/dist/commands/claude/marketplace/validate.d.ts.map +1 -1
  58. package/dist/commands/claude/marketplace/validate.js +1 -1
  59. package/dist/commands/claude/marketplace/validate.js.map +1 -1
  60. package/dist/commands/claude/plugin/build.d.ts +1 -1
  61. package/dist/commands/claude/plugin/build.d.ts.map +1 -1
  62. package/dist/commands/claude/plugin/build.js +10 -2
  63. package/dist/commands/claude/plugin/build.js.map +1 -1
  64. package/dist/commands/claude/plugin/install.d.ts.map +1 -1
  65. package/dist/commands/claude/plugin/install.js +22 -2
  66. package/dist/commands/claude/plugin/install.js.map +1 -1
  67. package/dist/commands/consistency-check.d.ts.map +1 -1
  68. package/dist/commands/consistency-check.js +3 -3
  69. package/dist/commands/consistency-check.js.map +1 -1
  70. package/dist/commands/corpus/report.d.ts +1 -1
  71. package/dist/commands/corpus/report.d.ts.map +1 -1
  72. package/dist/commands/corpus/runner.js +1 -1
  73. package/dist/commands/corpus/runner.js.map +1 -1
  74. package/dist/commands/corpus/scan.d.ts.map +1 -1
  75. package/dist/commands/corpus/scan.js +17 -8
  76. package/dist/commands/corpus/scan.js.map +1 -1
  77. package/dist/commands/doctor.d.ts +36 -0
  78. package/dist/commands/doctor.d.ts.map +1 -1
  79. package/dist/commands/doctor.js +96 -0
  80. package/dist/commands/doctor.js.map +1 -1
  81. package/dist/commands/inventory.d.ts +13 -1
  82. package/dist/commands/inventory.d.ts.map +1 -1
  83. package/dist/commands/inventory.js +118 -13
  84. package/dist/commands/inventory.js.map +1 -1
  85. package/dist/commands/mcp/collections.d.ts +1 -1
  86. package/dist/commands/mcp/collections.d.ts.map +1 -1
  87. package/dist/commands/phase-utils.d.ts +1 -1
  88. package/dist/commands/phase-utils.d.ts.map +1 -1
  89. package/dist/commands/rag/index-command.d.ts +39 -0
  90. package/dist/commands/rag/index-command.d.ts.map +1 -1
  91. package/dist/commands/rag/index-command.js +28 -2
  92. package/dist/commands/rag/index-command.js.map +1 -1
  93. package/dist/commands/rag/index.d.ts.map +1 -1
  94. package/dist/commands/rag/index.js +21 -10
  95. package/dist/commands/rag/index.js.map +1 -1
  96. package/dist/commands/resources/index.d.ts.map +1 -1
  97. package/dist/commands/resources/index.js +10 -2
  98. package/dist/commands/resources/index.js.map +1 -1
  99. package/dist/commands/resources/scan.d.ts +24 -0
  100. package/dist/commands/resources/scan.d.ts.map +1 -1
  101. package/dist/commands/resources/scan.js +18 -5
  102. package/dist/commands/resources/scan.js.map +1 -1
  103. package/dist/commands/resources/validate.d.ts +1 -1
  104. package/dist/commands/resources/validate.d.ts.map +1 -1
  105. package/dist/commands/resources/validate.js +6 -3
  106. package/dist/commands/resources/validate.js.map +1 -1
  107. package/dist/commands/skill/review-checklist.d.ts.map +1 -1
  108. package/dist/commands/skill/review-checklist.js +1 -0
  109. package/dist/commands/skill/review-checklist.js.map +1 -1
  110. package/dist/commands/skill/review.js +2 -2
  111. package/dist/commands/skill/review.js.map +1 -1
  112. package/dist/commands/skill/test/configure.d.ts +19 -0
  113. package/dist/commands/skill/test/configure.d.ts.map +1 -1
  114. package/dist/commands/skill/test/configure.js +18 -3
  115. package/dist/commands/skill/test/configure.js.map +1 -1
  116. package/dist/commands/skill/test/run.d.ts +51 -4
  117. package/dist/commands/skill/test/run.d.ts.map +1 -1
  118. package/dist/commands/skill/test/run.js +112 -10
  119. package/dist/commands/skill/test/run.js.map +1 -1
  120. package/dist/commands/skills/build.d.ts +1 -1
  121. package/dist/commands/skills/build.d.ts.map +1 -1
  122. package/dist/commands/skills/build.js +72 -37
  123. package/dist/commands/skills/build.js.map +1 -1
  124. package/dist/commands/skills/package.d.ts +1 -1
  125. package/dist/commands/skills/package.d.ts.map +1 -1
  126. package/dist/commands/skills/package.js.map +1 -1
  127. package/dist/commands/skills/validate.d.ts +1 -1
  128. package/dist/commands/skills/validate.d.ts.map +1 -1
  129. package/dist/commands/skills/validate.js +37 -19
  130. package/dist/commands/skills/validate.js.map +1 -1
  131. package/dist/commands/verify.d.ts +2 -2
  132. package/dist/commands/verify.d.ts.map +1 -1
  133. package/dist/commands/verify.js +3 -3
  134. package/dist/commands/verify.js.map +1 -1
  135. package/dist/utils/command-error.d.ts +1 -1
  136. package/dist/utils/command-error.d.ts.map +1 -1
  137. package/dist/utils/command-error.js +1 -1
  138. package/dist/utils/command-error.js.map +1 -1
  139. package/dist/utils/config-loader.d.ts.map +1 -1
  140. package/dist/utils/config-loader.js +7 -1
  141. package/dist/utils/config-loader.js.map +1 -1
  142. package/dist/utils/context-budget-issues.d.ts +108 -0
  143. package/dist/utils/context-budget-issues.d.ts.map +1 -0
  144. package/dist/utils/context-budget-issues.js +280 -0
  145. package/dist/utils/context-budget-issues.js.map +1 -0
  146. package/dist/utils/corpus-target.d.ts +48 -0
  147. package/dist/utils/corpus-target.d.ts.map +1 -0
  148. package/dist/utils/corpus-target.js +61 -0
  149. package/dist/utils/corpus-target.js.map +1 -0
  150. package/dist/utils/issue-anchor.d.ts +2 -2
  151. package/dist/utils/issue-anchor.d.ts.map +1 -1
  152. package/dist/utils/issue-anchor.js +1 -1
  153. package/dist/utils/issue-rendering.d.ts +1 -1
  154. package/dist/utils/issue-rendering.d.ts.map +1 -1
  155. package/dist/utils/issue-rendering.js +1 -1
  156. package/dist/utils/issue-rendering.js.map +1 -1
  157. package/dist/utils/issue-severity.d.ts +1 -1
  158. package/dist/utils/issue-severity.d.ts.map +1 -1
  159. package/dist/utils/issue-severity.js +1 -1
  160. package/dist/utils/issue-severity.js.map +1 -1
  161. package/dist/utils/optional-backend.d.ts +77 -0
  162. package/dist/utils/optional-backend.d.ts.map +1 -0
  163. package/dist/utils/optional-backend.js +115 -0
  164. package/dist/utils/optional-backend.js.map +1 -0
  165. package/dist/utils/output.d.ts +17 -0
  166. package/dist/utils/output.d.ts.map +1 -1
  167. package/dist/utils/output.js +19 -0
  168. package/dist/utils/output.js.map +1 -1
  169. package/dist/utils/population-wiring.d.ts +59 -0
  170. package/dist/utils/population-wiring.d.ts.map +1 -0
  171. package/dist/utils/population-wiring.js +55 -0
  172. package/dist/utils/population-wiring.js.map +1 -0
  173. package/dist/utils/projection-store.d.ts +186 -0
  174. package/dist/utils/projection-store.d.ts.map +1 -0
  175. package/dist/utils/projection-store.js +255 -0
  176. package/dist/utils/projection-store.js.map +1 -0
  177. package/dist/utils/resource-loader.d.ts +127 -1
  178. package/dist/utils/resource-loader.d.ts.map +1 -1
  179. package/dist/utils/resource-loader.js +224 -7
  180. package/dist/utils/resource-loader.js.map +1 -1
  181. package/dist/utils/verdict-helpers.d.ts +1 -1
  182. package/dist/utils/verdict-helpers.d.ts.map +1 -1
  183. package/dist/utils/verdict-helpers.js +1 -1
  184. package/dist/utils/verdict-helpers.js.map +1 -1
  185. package/docs/agent.md +2 -2
  186. package/docs/mcp.md +2 -2
  187. package/docs/resources.md +8 -1
  188. package/package.json +15 -12
@@ -1,68 +1,18 @@
1
1
  /**
2
- * Cache command group, plus the root-level `--no-cache` control surface.
3
- *
4
- * Both live here so the flag and the command that cleans up after it stay in one
5
- * place: `--no-cache` decides whether this run *writes* to the caches, `vat cache
6
- * clear` decides whether the caches *survive*.
2
+ * Cache command group.
3
+ *
4
+ * The paired `--no-cache` control surface lives in `./cache-control.js`:
5
+ * `--no-cache` decides whether this run *writes* to the caches, `vat cache
6
+ * clear` decides whether the caches *survive*. They are separate modules only
7
+ * because `bin.ts` registers the flag on every invocation and must not pay for
8
+ * this command's imports to do it.
9
+ *
10
+ * ⛔ Do NOT re-export `cache-control.js` from here for convenience. Importing it
11
+ * through this module pulls `./clear.js` and the whole resources package behind
12
+ * it — the exact ~1.2s that splitting the file removed — so a re-export leaves
13
+ * the expensive path one identical-looking import away, with nothing pinning
14
+ * the cheap one. Import from `./cache-control.js` directly.
7
15
  */
8
16
  import { Command } from 'commander';
9
- /**
10
- * Root options this module reads. Commander represents `--no-cache` as the
11
- * POSITIVE key `cache` — `true` by default, `false` only when the negated flag
12
- * is passed. It NEVER produces `noCache`; reading that key is the exact bug that
13
- * made three flags in this package silent no-ops (see
14
- * `test/commands/commander-option-keys.test.ts`).
15
- */
16
- export interface CacheControlOptions {
17
- cache?: boolean;
18
- }
19
- /**
20
- * Register the root-level `--no-cache` flag and the hook that gives it effect.
21
- *
22
- * ## Why this sets an environment variable instead of plumbing a flag
23
- *
24
- * `vat validate`, `vat verify` and `vat build` enumerate nothing in their own
25
- * process: each `spawnSync`s the vat binary once per phase, and the child is
26
- * what parses the corpus. A flag parsed in the parent therefore never reaches
27
- * the process whose caching it is supposed to control, whereas `process.env` is
28
- * inherited by every child for free. `bin.ts` already leans on exactly that for
29
- * `VAT_CONTEXT` / `VAT_CONTEXT_PATH`.
30
- *
31
- * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
32
- * per construction, never at module load, so setting it from a `preAction` hook
33
- * — after Commander has parsed, before any command body runs — is observed.
34
- *
35
- * ## The collision with `vat resources validate --no-cache`
36
- *
37
- * This root program does NOT use `enablePositionalOptions()`, so Commander scans
38
- * the WHOLE argv for root options, including everything after the subcommand
39
- * name. That is the same mechanism that let a root `-v` shadow the subcommands'
40
- * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
41
- * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
42
- * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
43
- * identically-named flag is swallowed before it ever sees it, which would have
44
- * silently re-enabled the external-URL cache the flag exists to bypass.
45
- *
46
- * Rather than break a shipped flag, the hook hands the value back down to
47
- * whichever action command declares a `cache` option of its own. `--no-cache` is
48
- * a superset — every cache off — so the handoff is a strengthening, never a
49
- * reversal.
50
- *
51
- * @param program - The root program to register the flag and hook on
52
- */
53
- export declare function registerCacheControl(program: Command): void;
54
- /**
55
- * Apply the root `--no-cache` decision: export it to child processes, and hand
56
- * it down to an action command that declares its own `cache` option.
57
- *
58
- * Exported so a test can drive it from real parsed options rather than from a
59
- * hand-built bag. Deliberately does nothing when the flag was not passed — a
60
- * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
61
- * one that is always on.
62
- *
63
- * @param rootOptions - Options bag from the ROOT program
64
- * @param actionCommand - The command whose action is about to run
65
- */
66
- export declare function applyCacheControl(rootOptions: CacheControlOptions, actionCommand: Command): void;
67
17
  export declare function createCacheCommand(): Command;
68
18
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI,CAWhG;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CA6D5C"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,kBAAkB,IAAI,OAAO,CA2E5C"}
@@ -1,75 +1,20 @@
1
1
  /**
2
- * Cache command group, plus the root-level `--no-cache` control surface.
2
+ * Cache command group.
3
3
  *
4
- * Both live here so the flag and the command that cleans up after it stay in one
5
- * place: `--no-cache` decides whether this run *writes* to the caches, `vat cache
6
- * clear` decides whether the caches *survive*.
4
+ * The paired `--no-cache` control surface lives in `./cache-control.js`:
5
+ * `--no-cache` decides whether this run *writes* to the caches, `vat cache
6
+ * clear` decides whether the caches *survive*. They are separate modules only
7
+ * because `bin.ts` registers the flag on every invocation and must not pay for
8
+ * this command's imports to do it.
9
+ *
10
+ * ⛔ Do NOT re-export `cache-control.js` from here for convenience. Importing it
11
+ * through this module pulls `./clear.js` and the whole resources package behind
12
+ * it — the exact ~1.2s that splitting the file removed — so a re-export leaves
13
+ * the expensive path one identical-looking import away, with nothing pinning
14
+ * the cheap one. Import from `./cache-control.js` directly.
7
15
  */
8
16
  import { Command } from 'commander';
9
17
  import { cacheClearCommand } from './clear.js';
10
- /**
11
- * Register the root-level `--no-cache` flag and the hook that gives it effect.
12
- *
13
- * ## Why this sets an environment variable instead of plumbing a flag
14
- *
15
- * `vat validate`, `vat verify` and `vat build` enumerate nothing in their own
16
- * process: each `spawnSync`s the vat binary once per phase, and the child is
17
- * what parses the corpus. A flag parsed in the parent therefore never reaches
18
- * the process whose caching it is supposed to control, whereas `process.env` is
19
- * inherited by every child for free. `bin.ts` already leans on exactly that for
20
- * `VAT_CONTEXT` / `VAT_CONTEXT_PATH`.
21
- *
22
- * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
23
- * per construction, never at module load, so setting it from a `preAction` hook
24
- * — after Commander has parsed, before any command body runs — is observed.
25
- *
26
- * ## The collision with `vat resources validate --no-cache`
27
- *
28
- * This root program does NOT use `enablePositionalOptions()`, so Commander scans
29
- * the WHOLE argv for root options, including everything after the subcommand
30
- * name. That is the same mechanism that let a root `-v` shadow the subcommands'
31
- * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
32
- * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
33
- * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
34
- * identically-named flag is swallowed before it ever sees it, which would have
35
- * silently re-enabled the external-URL cache the flag exists to bypass.
36
- *
37
- * Rather than break a shipped flag, the hook hands the value back down to
38
- * whichever action command declares a `cache` option of its own. `--no-cache` is
39
- * a superset — every cache off — so the handoff is a strengthening, never a
40
- * reversal.
41
- *
42
- * @param program - The root program to register the flag and hook on
43
- */
44
- export function registerCacheControl(program) {
45
- program.option('--no-cache', "Disable VAT's disk caches for this run (also applies to spawned phases)");
46
- program.hook('preAction', (_thisCommand, actionCommand) => {
47
- applyCacheControl(program.opts(), actionCommand);
48
- });
49
- }
50
- /**
51
- * Apply the root `--no-cache` decision: export it to child processes, and hand
52
- * it down to an action command that declares its own `cache` option.
53
- *
54
- * Exported so a test can drive it from real parsed options rather than from a
55
- * hand-built bag. Deliberately does nothing when the flag was not passed — a
56
- * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
57
- * one that is always on.
58
- *
59
- * @param rootOptions - Options bag from the ROOT program
60
- * @param actionCommand - The command whose action is about to run
61
- */
62
- export function applyCacheControl(rootOptions, actionCommand) {
63
- if (rootOptions.cache !== false)
64
- return;
65
- process.env['VAT_CACHE'] = '0';
66
- // `attributeName()`, not `name()`: for `--no-cache` the latter returns
67
- // 'no-cache', so a check written against it never matches and the handoff
68
- // above becomes a no-op that looks like it works.
69
- if (actionCommand.options.some((option) => option.attributeName() === 'cache')) {
70
- actionCommand.setOptionValue('cache', false);
71
- }
72
- }
73
18
  export function createCacheCommand() {
74
19
  const cache = new Command('cache');
75
20
  cache
@@ -77,13 +22,20 @@ export function createCacheCommand() {
77
22
  .helpCommand(false)
78
23
  .addHelpText('after', `
79
24
  Description:
80
- VAT keeps three disposable caches under <tmpdir>/.vat-cache: parse facts
81
- keyed by file content, external-URL validation results, and per-OS-user
82
- authenticated-link content. None of them is durable — recovery is always
83
- "rescan", and the OS temp purge is the eviction policy.
25
+ VAT keeps four disposable caches under <tmpdir>/.vat-cache: parse facts
26
+ keyed by file content, external-URL validation results, per-OS-user
27
+ authenticated-link content, and the projection store — a SQLite database
28
+ holding one whole scanned tree per entry, and by far the largest of the
29
+ four. None of them is durable — recovery is always "rescan".
30
+
31
+ Only the projection store evicts anything on its own: it keeps the few most
32
+ recently written trees per root and drops the rest as it writes. The other
33
+ three rely on the OS temp purge, and every one of them is reclaimed in full
34
+ by vat cache clear.
84
35
 
85
36
  To run WITHOUT the caches rather than remove them, use --no-cache on any
86
- command (or VAT_CACHE=0), which also applies to spawned phases.
37
+ command (or VAT_CACHE=0), which also applies to spawned phases and to the
38
+ projection store.
87
39
 
88
40
  Example:
89
41
  $ vat cache clear # Reclaim the temp-directory cache tree
@@ -97,9 +49,11 @@ Example:
97
49
  .addHelpText('after', `
98
50
  Description:
99
51
  Removes <tmpdir>/.vat-cache in its entirety — the parse cache, the
100
- external-URL validation cache, and the per-OS-user authenticated-link cache.
101
- Every one of them is disposable by design: the next run repopulates what it
102
- needs, so the only cost of clearing is one cold pass.
52
+ external-URL validation cache, the per-OS-user authenticated-link cache, and
53
+ the projection store (<namespace>/projection-<shape>/projection.db), which is
54
+ usually most of the bytes this reclaims. Every one of them is disposable by
55
+ design: the next run repopulates what it needs, so the only cost of clearing
56
+ is one cold pass.
103
57
 
104
58
  Runs regardless of --no-cache / VAT_CACHE=0. Turning caching off must not
105
59
  disarm the one command that reclaims the space.
@@ -107,16 +61,21 @@ Description:
107
61
  A cache directory that does not exist is not an error — nothing to remove is
108
62
  a successful clear.
109
63
 
64
+ The tree is shared by every VAT on the machine, so another run writing into
65
+ it can make the delete stop part-way. That is reported as status: partial,
66
+ naming what went and what stayed, rather than failing with no account of it.
67
+
110
68
  Output:
111
69
  - cacheDir: absolute path that was targeted
112
70
  - existed: whether the directory was there at all
113
- - removed: top-level entries that were deleted
114
- - entriesRemoved / bytesRemoved: file count and total size, measured before
115
- deletion
71
+ - removed: top-level entries that are now gone
72
+ - remaining / reason: what survived a partial clear, and why (partial only)
73
+ - entriesRemoved / bytesRemoved: file count and total size actually removed
116
74
 
117
75
  Exit Codes:
118
76
  0 - Cache cleared (or already absent)
119
- 2 - Could not remove the cache (permissions, busy file)
77
+ 1 - Cleared only in part, because something else is using the tree
78
+ 2 - Could not read or target the cache at all (permissions, unexpected layout)
120
79
 
121
80
  Example:
122
81
  $ vat cache clear # Reclaim the temp-directory cache tree
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AAavE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,yEAAyE,CAAC,CAAC;IAExG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,EAAE;QACxD,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAuB,EAAE,aAAa,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAgC,EAAE,aAAsB;IACxF,IAAI,WAAW,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO;IAExC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IAE/B,uEAAuE;IACvE,0EAA0E;IAC1E,kDAAkD;IAClD,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC;QAC/E,aAAa,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC,KAAK;SACF,WAAW,CAAC,iEAAiE,CAAC;SAC9E,WAAW,CAAC,KAAK,CAAC;SAClB,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;CAYL,CACI,CAAC;IAEJ,KAAK;SACF,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,KAAK;QACX,MAAM,iBAAiB,CAAC,IAAI,CAAC,eAAe,EAAuB,CAAC,CAAC;IACvE,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BL,CACI,CAAC;IAEJ,OAAO,KAAK,CAAC;AACf,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AAGvE,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC,KAAK;SACF,WAAW,CAAC,iEAAiE,CAAC;SAC9E,WAAW,CAAC,KAAK,CAAC;SAClB,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;CAmBL,CACI,CAAC;IAEJ,KAAK;SACF,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,KAAK;QACX,MAAM,iBAAiB,CAAC,IAAI,CAAC,eAAe,EAAuB,CAAC,CAAC;IACvE,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCL,CACI,CAAC;IAEJ,OAAO,KAAK,CAAC;AACf,CAAC"}
@@ -0,0 +1,157 @@
1
+ /**
2
+ * `vat claude budget [paths...]` — is the always-loaded context at a working
3
+ * location over its budget?
4
+ *
5
+ * ## Why this is a command and not a check inside `vat resources validate`
6
+ *
7
+ * It used to be one: default-on, with a `--no-context-budget` opt-out. That is
8
+ * gone, in both directions — `vat resources validate` has no knowledge of the
9
+ * budget at all any more, not a flag, not a default. The ruling behind the move
10
+ * is short: *a validation run must not emit findings nobody asked for.* An
11
+ * `info` finding attached to a lane people run for link and anchor errors is a
12
+ * finding they scroll past, and a check people scroll past is a check they
13
+ * eventually silence.
14
+ *
15
+ * ## The sibling split: `context` QUERIES, `budget` CHECKS
16
+ *
17
+ * `vat claude context` answers a question and
18
+ * never gates — totals, admissions, the declared limits, no verdict, always
19
+ * exit 0. This command is the other half of that pair: it applies a THRESHOLD,
20
+ * produces findings with severities an adopter can configure, and lets an
21
+ * adopter who promotes the code to `error` fail their build with it. Two verbs
22
+ * because they are two acts, and folding a verdict into the query would make
23
+ * the query's number a number people learn to stop reading.
24
+ *
25
+ * ## Everything below is orchestration — deliberately
26
+ *
27
+ * Which directories exist, what each pays, and whether that is over budget are
28
+ * all decided in `@vibe-agent-toolkit/resources` (`buildClaudeContextPopulation`
29
+ * and `sweepAlwaysLoadedBudgets`); the wording and grouping of the findings in
30
+ * `utils/context-budget-issues.ts`; severity resolution in the two shared
31
+ * filters every other lane runs. This module populates one tree, calls them in
32
+ * order, and renders. It decides nothing about context loading of its own,
33
+ * which is the CLI-stays-dumb rule applied to the lane where the temptation is
34
+ * strongest.
35
+ *
36
+ * ⛔ The threshold is never re-spelled here. It is a MEASURED quantity that
37
+ * lives beside the detector (`DEFAULT_ALWAYS_LOADED_CONTEXT_TOKENS`), and a
38
+ * literal in this package would be a second source of truth that nothing
39
+ * compares.
40
+ *
41
+ * ## The stated bounds ride ONCE on the REPORT, in every format
42
+ *
43
+ * The sibling query publishes 23 stated limits; this command applies a threshold
44
+ * to the same measurement, so it publishes {@link ALWAYS_LOADED_BUDGET_LIMITS}
45
+ * and {@link CLAUDE_CONTEXT_BOUNDS_STATEMENT} beside its verdict — the half that
46
+ * GATES is the half whose bounds a reader most needs. Both are imported, never
47
+ * restated: the sentence is domain content owned beside the list it frames.
48
+ *
49
+ * ⛔ They belong to the REPORT, never to a finding. A per-finding copy is the
50
+ * defect this lane already shipped once on the query side, and it is invisible to
51
+ * any assertion that checks presence rather than counting occurrences.
52
+ */
53
+ import { type BudgetSweep, type StatedLimit } from '@vibe-agent-toolkit/resources';
54
+ import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/schema';
55
+ import { Command } from 'commander';
56
+ /** How the report is rendered. `text` is for a person; the other two are for a program. */
57
+ export type BudgetOutputFormat = 'text' | 'yaml' | 'json';
58
+ /** Flags `vat claude budget` accepts. */
59
+ export interface ClaudeBudgetOptions {
60
+ format?: BudgetOutputFormat;
61
+ debug?: boolean;
62
+ }
63
+ /**
64
+ * The report one run emits.
65
+ *
66
+ * The three sweep counters ride beside the findings and describe the WHOLE
67
+ * tree, not the scope: a scope narrows what is reported, never what was
68
+ * measured. Publishing them is what keeps an empty `findings` legible — "9
69
+ * chains checked, none over budget" and "nothing was checked" are different
70
+ * answers and must not render identically.
71
+ */
72
+ export interface BudgetReport {
73
+ readonly root: string;
74
+ /** The budget every chain was measured against, in tokens. */
75
+ readonly threshold: number;
76
+ /** The root-relative directories asked about. `''` is the whole tree. */
77
+ readonly scope: readonly string[];
78
+ /** Requested paths that named no working location — see `scopeSweepToPaths`. */
79
+ readonly unmatchedScope: readonly string[];
80
+ readonly status: 'success' | 'warning' | 'error';
81
+ readonly issueCounts: SeverityCounts;
82
+ /** Working locations the sweep evaluated, across the whole tree. */
83
+ readonly workingLocations: number;
84
+ /** Distinct instruction chains among them — the queries the sweep really issued. */
85
+ readonly distinctChains: number;
86
+ /** Locations whose representative the projection never realized. Counted, never zeroed. */
87
+ readonly skippedUnknownLocations: number;
88
+ readonly findings: readonly ValidationIssue[];
89
+ /**
90
+ * What this verdict does not settle, in either direction. Stated ONCE.
91
+ *
92
+ * ⛔ On the report beside `threshold`, never on a finding. These bound the
93
+ * MEASUREMENT METHOD, not any one chain — a finding carrying its own copy
94
+ * reads as though that chain had caveats of its own, and repeated across a
95
+ * sweep it is pure byte-identical duplication.
96
+ */
97
+ readonly boundsStatement: string;
98
+ /** The signed over/under-report bounds on the method. Stated ONCE. */
99
+ readonly limits: readonly StatedLimit[];
100
+ }
101
+ /**
102
+ * Create the `vat claude budget [paths...]` command.
103
+ *
104
+ * @returns The configured Commander command
105
+ */
106
+ export declare function createBudgetCommand(): Command;
107
+ /**
108
+ * Action handler for `vat claude budget [paths...]`.
109
+ *
110
+ * @param pathArgs - Directories to check; empty means the whole tree
111
+ * @param options - The command's flags
112
+ */
113
+ export declare function claudeBudgetCommand(pathArgs: readonly string[], options: ClaudeBudgetOptions): Promise<void>;
114
+ /** Everything {@link buildReport} needs, bundled past the lint gate's parameter ceiling. */
115
+ export interface ReportInput {
116
+ readonly root: string;
117
+ readonly threshold: number;
118
+ readonly scope: readonly string[];
119
+ readonly sweep: BudgetSweep;
120
+ readonly scoped: {
121
+ readonly unmatchedScope: readonly string[];
122
+ };
123
+ readonly findings: readonly ValidationIssue[];
124
+ }
125
+ /**
126
+ * Assemble the report from the run's parts.
127
+ *
128
+ * ⛔ The counters come from the UNSCOPED sweep. They answer "what was measured",
129
+ * and a scope changes only what is reported — sourcing them from the narrowed
130
+ * view would let `vat claude budget docs` claim the tree has one chain.
131
+ *
132
+ * ⛔ This is the ONE place the stated bounds enter the machine-readable output,
133
+ * and keeping it a single assignment is what makes "stated once" structural
134
+ * rather than a habit: there is no per-finding site left where a copy could be
135
+ * reintroduced. They are attached unconditionally — a run that flagged nothing
136
+ * used the same method, and a reader acting on "within budget" needs them most.
137
+ *
138
+ * ⛔ Exported so it can be TESTED. What has to be pinned is a COUNT — that the
139
+ * block appears exactly once across a MULTI-finding report — and a presence
140
+ * check passes identically with a copy per finding.
141
+ *
142
+ * @param input - The run's parts
143
+ * @returns The report, ready to serialize
144
+ */
145
+ export declare function buildReport(input: ReportInput): BudgetReport;
146
+ /**
147
+ * Render the report for a person.
148
+ *
149
+ * ⛔ Exported so the "stated once" property can be pinned in TEXT as well as in
150
+ * json. The two renderings are separate code paths and this lane has already
151
+ * shipped a defect where they disagreed while each looked right alone.
152
+ *
153
+ * @param report - The report
154
+ * @returns The text rendering, newline-terminated
155
+ */
156
+ export declare function renderReportText(report: BudgetReport): string;
157
+ //# sourceMappingURL=budget.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../../src/commands/claude/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAmB5C,2FAA2F;AAC3F,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAmE7C;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAgB5D;AAkFD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAa7D"}