@vibe-agent-toolkit/cli 0.1.41-rc.6 → 0.1.41-rc.8

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 (199) hide show
  1. package/README.md +4 -3
  2. package/dist/bin/vat +25 -2
  3. package/dist/bin/vat.js +25 -2
  4. package/dist/bin/vat.js.map +1 -1
  5. package/dist/bin.js +12 -1
  6. package/dist/bin.js.map +1 -1
  7. package/dist/commands/agent/list.d.ts +11 -0
  8. package/dist/commands/agent/list.d.ts.map +1 -1
  9. package/dist/commands/agent/list.js +30 -11
  10. package/dist/commands/agent/list.js.map +1 -1
  11. package/dist/commands/audit/hierarchical-output.d.ts +6 -2
  12. package/dist/commands/audit/hierarchical-output.d.ts.map +1 -1
  13. package/dist/commands/audit/hierarchical-output.js +93 -50
  14. package/dist/commands/audit/hierarchical-output.js.map +1 -1
  15. package/dist/commands/audit-settings.d.ts +35 -0
  16. package/dist/commands/audit-settings.d.ts.map +1 -1
  17. package/dist/commands/audit-settings.js +121 -51
  18. package/dist/commands/audit-settings.js.map +1 -1
  19. package/dist/commands/audit.d.ts +97 -2
  20. package/dist/commands/audit.d.ts.map +1 -1
  21. package/dist/commands/audit.js +505 -231
  22. package/dist/commands/audit.js.map +1 -1
  23. package/dist/commands/build.d.ts +14 -0
  24. package/dist/commands/build.d.ts.map +1 -1
  25. package/dist/commands/build.js +126 -32
  26. package/dist/commands/build.js.map +1 -1
  27. package/dist/commands/claude/marketplace/license-utils.d.ts +39 -2
  28. package/dist/commands/claude/marketplace/license-utils.d.ts.map +1 -1
  29. package/dist/commands/claude/marketplace/license-utils.js +114 -68
  30. package/dist/commands/claude/marketplace/license-utils.js.map +1 -1
  31. package/dist/commands/claude/marketplace/publish.js +5 -4
  32. package/dist/commands/claude/marketplace/publish.js.map +1 -1
  33. package/dist/commands/claude/marketplace/validate.d.ts +97 -0
  34. package/dist/commands/claude/marketplace/validate.d.ts.map +1 -1
  35. package/dist/commands/claude/marketplace/validate.js +157 -49
  36. package/dist/commands/claude/marketplace/validate.js.map +1 -1
  37. package/dist/commands/claude/org/skills.d.ts +11 -3
  38. package/dist/commands/claude/org/skills.d.ts.map +1 -1
  39. package/dist/commands/claude/org/skills.js +70 -20
  40. package/dist/commands/claude/org/skills.js.map +1 -1
  41. package/dist/commands/claude/org/stubs.d.ts +9 -1
  42. package/dist/commands/claude/org/stubs.d.ts.map +1 -1
  43. package/dist/commands/claude/org/stubs.js +11 -3
  44. package/dist/commands/claude/org/stubs.js.map +1 -1
  45. package/dist/commands/claude/plugin/build.d.ts +116 -0
  46. package/dist/commands/claude/plugin/build.d.ts.map +1 -1
  47. package/dist/commands/claude/plugin/build.js +173 -40
  48. package/dist/commands/claude/plugin/build.js.map +1 -1
  49. package/dist/commands/claude/plugin/marketplace-json.d.ts +36 -0
  50. package/dist/commands/claude/plugin/marketplace-json.d.ts.map +1 -0
  51. package/dist/commands/claude/plugin/marketplace-json.js +34 -0
  52. package/dist/commands/claude/plugin/marketplace-json.js.map +1 -0
  53. package/dist/commands/claude/plugin/plugin-json-merge.d.ts +30 -1
  54. package/dist/commands/claude/plugin/plugin-json-merge.d.ts.map +1 -1
  55. package/dist/commands/claude/plugin/plugin-json-merge.js +107 -14
  56. package/dist/commands/claude/plugin/plugin-json-merge.js.map +1 -1
  57. package/dist/commands/claude/plugin/tree-copy.d.ts.map +1 -1
  58. package/dist/commands/claude/plugin/tree-copy.js +0 -1
  59. package/dist/commands/claude/plugin/tree-copy.js.map +1 -1
  60. package/dist/commands/corpus/report.d.ts +22 -4
  61. package/dist/commands/corpus/report.d.ts.map +1 -1
  62. package/dist/commands/corpus/report.js +1 -0
  63. package/dist/commands/corpus/report.js.map +1 -1
  64. package/dist/commands/corpus/runner.d.ts +16 -1
  65. package/dist/commands/corpus/runner.d.ts.map +1 -1
  66. package/dist/commands/corpus/runner.js +55 -48
  67. package/dist/commands/corpus/runner.js.map +1 -1
  68. package/dist/commands/doctor.d.ts +57 -8
  69. package/dist/commands/doctor.d.ts.map +1 -1
  70. package/dist/commands/doctor.js +142 -67
  71. package/dist/commands/doctor.js.map +1 -1
  72. package/dist/commands/inventory.d.ts +2 -0
  73. package/dist/commands/inventory.d.ts.map +1 -1
  74. package/dist/commands/inventory.js +45 -4
  75. package/dist/commands/inventory.js.map +1 -1
  76. package/dist/commands/phase-utils.d.ts +240 -11
  77. package/dist/commands/phase-utils.d.ts.map +1 -1
  78. package/dist/commands/phase-utils.js +352 -15
  79. package/dist/commands/phase-utils.js.map +1 -1
  80. package/dist/commands/rag/query-command.d.ts +40 -0
  81. package/dist/commands/rag/query-command.d.ts.map +1 -1
  82. package/dist/commands/rag/query-command.js +47 -20
  83. package/dist/commands/rag/query-command.js.map +1 -1
  84. package/dist/commands/resources/index.d.ts.map +1 -1
  85. package/dist/commands/resources/index.js +38 -13
  86. package/dist/commands/resources/index.js.map +1 -1
  87. package/dist/commands/resources/scan.d.ts +37 -0
  88. package/dist/commands/resources/scan.d.ts.map +1 -1
  89. package/dist/commands/resources/scan.js +47 -32
  90. package/dist/commands/resources/scan.js.map +1 -1
  91. package/dist/commands/resources/validate.d.ts +136 -1
  92. package/dist/commands/resources/validate.d.ts.map +1 -1
  93. package/dist/commands/resources/validate.js +121 -68
  94. package/dist/commands/resources/validate.js.map +1 -1
  95. package/dist/commands/skill/review.d.ts.map +1 -1
  96. package/dist/commands/skill/review.js +40 -23
  97. package/dist/commands/skill/review.js.map +1 -1
  98. package/dist/commands/skill/test/run.d.ts +1 -1
  99. package/dist/commands/skill/test/run.d.ts.map +1 -1
  100. package/dist/commands/skill/test/run.js +8 -6
  101. package/dist/commands/skill/test/run.js.map +1 -1
  102. package/dist/commands/skills/build.d.ts +140 -0
  103. package/dist/commands/skills/build.d.ts.map +1 -1
  104. package/dist/commands/skills/build.js +348 -94
  105. package/dist/commands/skills/build.js.map +1 -1
  106. package/dist/commands/skills/command-helpers.d.ts +6 -10
  107. package/dist/commands/skills/command-helpers.d.ts.map +1 -1
  108. package/dist/commands/skills/command-helpers.js +6 -22
  109. package/dist/commands/skills/command-helpers.js.map +1 -1
  110. package/dist/commands/skills/list.d.ts +18 -0
  111. package/dist/commands/skills/list.d.ts.map +1 -1
  112. package/dist/commands/skills/list.js +41 -15
  113. package/dist/commands/skills/list.js.map +1 -1
  114. package/dist/commands/skills/package.d.ts +17 -0
  115. package/dist/commands/skills/package.d.ts.map +1 -1
  116. package/dist/commands/skills/package.js +72 -43
  117. package/dist/commands/skills/package.js.map +1 -1
  118. package/dist/commands/skills/skill-discovery.d.ts.map +1 -1
  119. package/dist/commands/skills/skill-discovery.js +9 -1
  120. package/dist/commands/skills/skill-discovery.js.map +1 -1
  121. package/dist/commands/skills/validate-command.d.ts.map +1 -1
  122. package/dist/commands/skills/validate-command.js +22 -6
  123. package/dist/commands/skills/validate-command.js.map +1 -1
  124. package/dist/commands/skills/validate.d.ts +79 -0
  125. package/dist/commands/skills/validate.d.ts.map +1 -1
  126. package/dist/commands/skills/validate.js +268 -79
  127. package/dist/commands/skills/validate.js.map +1 -1
  128. package/dist/commands/validate.d.ts +18 -0
  129. package/dist/commands/validate.d.ts.map +1 -1
  130. package/dist/commands/validate.js +79 -66
  131. package/dist/commands/validate.js.map +1 -1
  132. package/dist/commands/verify.d.ts +38 -1
  133. package/dist/commands/verify.d.ts.map +1 -1
  134. package/dist/commands/verify.js +247 -84
  135. package/dist/commands/verify.js.map +1 -1
  136. package/dist/index.d.ts +1 -1
  137. package/dist/index.d.ts.map +1 -1
  138. package/dist/index.js +7 -1
  139. package/dist/index.js.map +1 -1
  140. package/dist/skill-resolution/index.d.ts +1 -1
  141. package/dist/skill-resolution/index.d.ts.map +1 -1
  142. package/dist/skill-resolution/index.js +1 -1
  143. package/dist/skill-resolution/index.js.map +1 -1
  144. package/dist/skill-resolution/packaging-config.d.ts +15 -2
  145. package/dist/skill-resolution/packaging-config.d.ts.map +1 -1
  146. package/dist/skill-resolution/packaging-config.js +39 -2
  147. package/dist/skill-resolution/packaging-config.js.map +1 -1
  148. package/dist/utils/command-error.d.ts +34 -1
  149. package/dist/utils/command-error.d.ts.map +1 -1
  150. package/dist/utils/command-error.js +32 -1
  151. package/dist/utils/command-error.js.map +1 -1
  152. package/dist/utils/config-loader.d.ts.map +1 -1
  153. package/dist/utils/config-loader.js +0 -2
  154. package/dist/utils/config-loader.js.map +1 -1
  155. package/dist/utils/help-loader.d.ts +6 -2
  156. package/dist/utils/help-loader.d.ts.map +1 -1
  157. package/dist/utils/help-loader.js +9 -16
  158. package/dist/utils/help-loader.js.map +1 -1
  159. package/dist/utils/issue-anchor.d.ts +26 -0
  160. package/dist/utils/issue-anchor.d.ts.map +1 -0
  161. package/dist/utils/issue-anchor.js +39 -0
  162. package/dist/utils/issue-anchor.js.map +1 -0
  163. package/dist/utils/issue-rendering.d.ts +149 -0
  164. package/dist/utils/issue-rendering.d.ts.map +1 -0
  165. package/dist/utils/issue-rendering.js +229 -0
  166. package/dist/utils/issue-rendering.js.map +1 -0
  167. package/dist/utils/output.d.ts +80 -9
  168. package/dist/utils/output.d.ts.map +1 -1
  169. package/dist/utils/output.js +138 -23
  170. package/dist/utils/output.js.map +1 -1
  171. package/dist/utils/project-root-policy.d.ts +2 -2
  172. package/dist/utils/project-root-policy.js +2 -2
  173. package/dist/utils/relativize-paths.d.ts +45 -0
  174. package/dist/utils/relativize-paths.d.ts.map +1 -0
  175. package/dist/utils/relativize-paths.js +67 -0
  176. package/dist/utils/relativize-paths.js.map +1 -0
  177. package/dist/utils/resource-loader.d.ts +21 -2
  178. package/dist/utils/resource-loader.d.ts.map +1 -1
  179. package/dist/utils/resource-loader.js +85 -11
  180. package/dist/utils/resource-loader.js.map +1 -1
  181. package/dist/utils/skill-packaging-config.d.ts +22 -1
  182. package/dist/utils/skill-packaging-config.d.ts.map +1 -1
  183. package/dist/utils/skill-packaging-config.js +26 -0
  184. package/dist/utils/skill-packaging-config.js.map +1 -1
  185. package/dist/utils/validate-help-files.d.ts +3 -2
  186. package/dist/utils/validate-help-files.d.ts.map +1 -1
  187. package/dist/utils/validate-help-files.js +48 -5
  188. package/dist/utils/validate-help-files.js.map +1 -1
  189. package/dist/utils/verdict-helpers.d.ts +14 -5
  190. package/dist/utils/verdict-helpers.d.ts.map +1 -1
  191. package/dist/utils/verdict-helpers.js +19 -16
  192. package/dist/utils/verdict-helpers.js.map +1 -1
  193. package/docs/audit.md +40 -14
  194. package/docs/doctor.md +46 -10
  195. package/docs/index.md +1 -1
  196. package/docs/rag.md +9 -4
  197. package/docs/resources.md +54 -22
  198. package/docs/skills.md +11 -7
  199. package/package.json +12 -12
@@ -0,0 +1,229 @@
1
+ /**
2
+ * Rendering for SETS of `ValidationIssue`s — the severity label, the set's
3
+ * heading, and the per-issue block.
4
+ *
5
+ * `issue-anchor.ts` answers "where is this issue?"; this module answers "what
6
+ * severity is it, and what is in this set?". Both exist because the answer has
7
+ * to be spelled identically by every command: two renderers that each invent
8
+ * their own severity prefix is exactly how `info` findings came to be printed
9
+ * as `[WARNING]` in `vat skills build` AND `vat claude plugin build`, and how a
10
+ * mixed set came to be labelled "post-build error(s)" wholesale.
11
+ *
12
+ * The failure mode these helpers exist to prevent is directional: every
13
+ * hand-rolled severity collapse in this codebase mapped the case it could not
14
+ * represent onto the REASSURING one (info ⇒ "warning", warnings ⇒ "all
15
+ * passed"). That is why none of it was ever reported — it produces silence, not
16
+ * a false alarm.
17
+ */
18
+ import { countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
19
+ import { formatIssueAnchor } from './issue-anchor.js';
20
+ /**
21
+ * Uppercase label for a resolved severity.
22
+ *
23
+ * A total map, not an `=== 'error' ? … : …` ternary: the ternary is what
24
+ * rendered every non-error severity — `info` included — as `WARNING`.
25
+ */
26
+ const SEVERITY_LABELS = {
27
+ error: 'ERROR',
28
+ warning: 'WARNING',
29
+ info: 'INFO',
30
+ ignore: 'IGNORED',
31
+ };
32
+ /** Render an issue's own severity as itself. */
33
+ export function severityLabel(severity) {
34
+ return SEVERITY_LABELS[severity];
35
+ }
36
+ /**
37
+ * The severity distribution in prose: `1 error, 2 warnings, 3 info`.
38
+ *
39
+ * Zero buckets are omitted so the phrase names only what is present. An
40
+ * all-zero set returns `no findings` rather than an empty string, because an
41
+ * empty string silently disappears into whatever sentence embeds it.
42
+ */
43
+ export function formatSeverityBreakdown(counts) {
44
+ const parts = [];
45
+ if (counts.errors > 0) {
46
+ parts.push(`${counts.errors} error${counts.errors === 1 ? '' : 's'}`);
47
+ }
48
+ if (counts.warnings > 0) {
49
+ parts.push(`${counts.warnings} warning${counts.warnings === 1 ? '' : 's'}`);
50
+ }
51
+ if (counts.info > 0) {
52
+ parts.push(`${counts.info} info`);
53
+ }
54
+ return parts.length === 0 ? 'no findings' : parts.join(', ');
55
+ }
56
+ /**
57
+ * Heading for a set of issues: `3 post-build issues (1 error, 2 info)`.
58
+ *
59
+ * The breakdown is not decoration — it is the only part of the heading that
60
+ * cannot be wrong about a mixed set. `noun` qualifies the set ("post-build"),
61
+ * and is omitted entirely when empty.
62
+ */
63
+ export function formatIssueSetHeading(issues, noun) {
64
+ const qualifier = noun === undefined || noun === '' ? '' : `${noun} `;
65
+ const total = issues.length;
66
+ const breakdown = formatSeverityBreakdown(countBySeverity(issues));
67
+ return `${total} ${qualifier}issue${total === 1 ? '' : 's'} (${breakdown})`;
68
+ }
69
+ /**
70
+ * Render one issue as its own lines, each prefixed with `indent`.
71
+ *
72
+ * Returns an array rather than writing, so a caller can pick its own stream and
73
+ * a unit test can assert over every line without capturing output.
74
+ */
75
+ export function formatIssueLines(issue, indent = '') {
76
+ const lines = [
77
+ `${indent}[${severityLabel(issue.severity)}] [${String(issue.code)}] ${String(issue.message)}`,
78
+ ];
79
+ const anchor = formatIssueAnchor(issue);
80
+ if (anchor !== undefined) {
81
+ lines.push(`${indent} Location: ${anchor}`);
82
+ }
83
+ if (issue.fix) {
84
+ lines.push(`${indent} Fix: ${String(issue.fix)}`);
85
+ }
86
+ return lines;
87
+ }
88
+ /**
89
+ * Render the run-level findings section — findings that belong to the whole
90
+ * invocation rather than to any one skill (ALLOW_UNUSED is the only producer).
91
+ *
92
+ * Shared by `vat skills validate` and `vat skills build` so the two commands
93
+ * name the same concept the same way. Attributing these to a skill is the
94
+ * misreading the heading exists to prevent: `validation.allow` is declared once
95
+ * for the package, so an entry that matched nothing is a fact about the run.
96
+ *
97
+ * Returns `[]` for an empty set; callers own their surrounding blank lines.
98
+ */
99
+ export function formatRunIssueLines(runIssues) {
100
+ if (runIssues.length === 0)
101
+ return [];
102
+ const lines = [
103
+ 'Run-level (project config, not any one skill):',
104
+ ` ${formatIssueSetHeading(runIssues)}:`,
105
+ ];
106
+ for (const issue of runIssues) {
107
+ lines.push(...formatIssueLines(issue, ' '));
108
+ }
109
+ return lines;
110
+ }
111
+ /** Identity of an issue for de-duplication across the two post-build channels. */
112
+ function issueIdentity(issue) {
113
+ return [
114
+ issue.code,
115
+ issue.severity,
116
+ issue.location ?? '',
117
+ issue.line === undefined ? '' : String(issue.line),
118
+ issue.field ?? '',
119
+ issue.message,
120
+ ].join('\0');
121
+ }
122
+ /**
123
+ * Every post-build finding a `PackageSkillResult` carries, from BOTH channels.
124
+ *
125
+ * `hasErrors` is the OR of two independent sets — the packager's own framework
126
+ * run (`postBuildIssues`: link exclusions, unreferenced files, broken packaged
127
+ * links) and the full validation of the built tree (`postBuildValidation`). A
128
+ * renderer that walks only `postBuildIssues` therefore prints NOTHING for a
129
+ * build that failed purely on `postBuildValidation`: the user is told the build
130
+ * failed and shown no reason. Reading both is the whole point of this helper.
131
+ *
132
+ * `postBuildValidation.allErrors` is the full emitted set including `info`
133
+ * (see its doc comment — the name lies), so info findings survive here.
134
+ */
135
+ export function collectPostBuildIssues(result) {
136
+ const seen = new Set();
137
+ const merged = [];
138
+ for (const issue of [
139
+ ...(result.postBuildIssues ?? []),
140
+ ...(result.postBuildValidation?.allErrors ?? []),
141
+ ]) {
142
+ const identity = issueIdentity(issue);
143
+ if (seen.has(identity))
144
+ continue;
145
+ seen.add(identity);
146
+ merged.push(issue);
147
+ }
148
+ return merged;
149
+ }
150
+ /**
151
+ * Project a set of issues onto its counts: severity buckets plus a per-code tally.
152
+ *
153
+ * Severity counting delegates to `countBySeverity` — there must be exactly one
154
+ * severity collapse in this codebase (see this module's header). That delegation
155
+ * carries its rule with it: `ignore` findings land in NO severity bucket, because
156
+ * the adopter's `validation.allow` config silenced them.
157
+ *
158
+ * They do still appear in `codes`, because they were emitted — a code the adopter
159
+ * allow-listed would otherwise be invisible in every summary, which is the one
160
+ * place a reviewer would look to notice an allow-list that has quietly grown.
161
+ *
162
+ * `codes` is ordered descending by count, ties broken by code name ascending.
163
+ * Insertion order is the YAML serialization order, so the ordering is the feature:
164
+ * the first row names the dominant finding without the reader tallying anything.
165
+ */
166
+ export function summarizeFindings(issues) {
167
+ const counts = countBySeverity(issues);
168
+ const tally = new Map();
169
+ for (const issue of issues) {
170
+ const code = String(issue.code);
171
+ tally.set(code, (tally.get(code) ?? 0) + 1);
172
+ }
173
+ // `Object.fromEntries` over a sorted array, rather than keyed assignment into a
174
+ // record: it preserves the sort as insertion order without a dynamic index write.
175
+ const codes = Object.fromEntries([...tally.entries()].sort(([codeA, countA], [codeB, countB]) => countB - countA || codeA.localeCompare(codeB)));
176
+ return {
177
+ ...(counts.errors > 0 ? { errors: counts.errors } : {}),
178
+ ...(counts.warnings > 0 ? { warnings: counts.warnings } : {}),
179
+ ...(counts.info > 0 ? { info: counts.info } : {}),
180
+ codes,
181
+ };
182
+ }
183
+ /**
184
+ * The findings a human-facing report renders IN FULL at a given verbosity.
185
+ *
186
+ * One policy, spelled once, because the three verbs that report findings —
187
+ * `vat skills validate`, `vat skills build`, `vat audit` — each grew their own
188
+ * answer and landed on three different ones: validate collapsed every severity
189
+ * into a per-skill count line, while build and audit printed every occurrence.
190
+ * On a 90-skill adopter that read as 804 lines against 6,552 and 26,480, for
191
+ * the same corpus.
192
+ *
193
+ * The rule is asymmetric on purpose, and the asymmetry is the whole point:
194
+ *
195
+ * - **`error` is always rendered in full**, at every verbosity. An error is what
196
+ * failed the run, there are few of them, and every one is actionable. Collapsing
197
+ * an error into a count means the reader must re-run with a flag to learn what
198
+ * broke — which is strictly worse than the verbosity it was meant to fix. This
199
+ * is the direction the module header warns about: a collapse that hides the
200
+ * thing you needed produces silence, not a false alarm.
201
+ * - **`warning` and `info` collapse into the caller's summary line** unless
202
+ * `verbose`. These are the high-cardinality findings (one adopter skill carries
203
+ * 348 `LINK_DROPPED_BY_DEPTH` warnings alone), and a count plus a per-code tally
204
+ * answers "what is going on here?" without the reader scrolling past 348 near-
205
+ * identical blocks.
206
+ * - **`ignore` never renders**, at any verbosity: the adopter's `validation.allow`
207
+ * config silenced it deliberately. It stays visible in `summarizeFindings`'
208
+ * `codes` tally, which is where a quietly-growing allow-list is noticed.
209
+ *
210
+ * This decides only WHICH findings are rendered, never HOW. Each lane keeps its
211
+ * own heading and summary line — those legitimately differ — so this can be shared
212
+ * without forcing one layout onto three commands.
213
+ *
214
+ * The machine-readable document is NOT filtered by this. `vat audit`'s YAML and
215
+ * `vat skills build`'s `issueCounts` carry every finding at every verbosity;
216
+ * anything else would silently break consumers that parse them.
217
+ */
218
+ export function issuesToRenderAtVerbosity(issues, verbose) {
219
+ return issues.filter((issue) => issue.severity !== 'ignore' && (verbose || issue.severity === 'error'));
220
+ }
221
+ /** Sum severity counts across lanes (per-skill → per-plugin → per-run). */
222
+ export function sumSeverityCounts(counts) {
223
+ return counts.reduce((acc, c) => ({
224
+ errors: acc.errors + c.errors,
225
+ warnings: acc.warnings + c.warnings,
226
+ info: acc.info + c.info,
227
+ }), { errors: 0, warnings: 0, info: 0 });
228
+ }
229
+ //# sourceMappingURL=issue-rendering.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"issue-rendering.js","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"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"}
@@ -3,18 +3,89 @@
3
3
  * YAML output on stdout, logs on stderr
4
4
  */
5
5
  /**
6
- * Write YAML output to stdout with document markers
7
- * @param data - Data to serialize as YAML
6
+ * Write `content` to stdout SYNCHRONOUSLY, in a loop until every byte is handed
7
+ * over.
8
+ *
9
+ * `process.stdout.write` is asynchronous whenever stdout is a PIPE, and every
10
+ * command in this CLI calls `process.exit()` the moment it has written its
11
+ * summary. `process.exit` does not drain a pending write, so everything past the
12
+ * first pipe buffer (64 KB on Linux/macOS) was silently discarded — with exit
13
+ * code 0, so nothing signalled the loss. An interactive TTY is unbuffered and
14
+ * looked perfect, which is why this survived: it only bites the piped consumer
15
+ * this CLI's own docs recommend (`vat command | jq .status`).
16
+ *
17
+ * `writeSync` cannot return before the bytes reach the pipe, so `process.exit`
18
+ * has nothing left to lose. The loop is required because a single `writeSync`
19
+ * may accept fewer bytes than offered.
20
+ *
21
+ * This is the same fix `help-loader.ts` applied to `--help --verbose`; it lives
22
+ * here so both callers share one implementation rather than two copies of a
23
+ * subtle loop.
8
24
  */
9
- export declare function writeYamlOutput(data: unknown): void;
25
+ export declare function writeStdoutSync(content: string): void;
26
+ /**
27
+ * A synchronous write primitive: `(buffer, offset, length) => bytesWritten`.
28
+ *
29
+ * Matches `fs.writeSync`'s shape so the real one drops straight in, while a test
30
+ * can supply one that returns short counts or throws EAGAIN on demand.
31
+ */
32
+ export type SyncWriter = (buffer: Buffer, offset: number, length: number) => number;
33
+ export interface WriteAllSyncOptions {
34
+ /** Override {@link MAX_CONSECUTIVE_EAGAIN_RETRIES}. Tests use a tiny budget. */
35
+ maxConsecutiveRetries?: number;
36
+ /** Override the backoff. Tests pass a no-op to drive the bound instantly. */
37
+ waitBetweenRetries?: (consecutiveRetries: number) => void;
38
+ }
10
39
  /**
11
- * Flush stdout before writing to stderr
12
- * Prevents output corruption when streams are merged
40
+ * Drive `write` until every byte of `buffer` has been accepted.
41
+ *
42
+ * Split out from {@link writeStdoutSync} because the things that make this loop
43
+ * necessary — a short write, and an EAGAIN retry on a momentarily-full
44
+ * non-blocking pipe — are both hard to provoke on a real fd and trivial to state
45
+ * against an injected writer. The fd-1 wiring stays a one-liner above, so the
46
+ * only part with branching logic is the part that can be unit tested.
47
+ *
48
+ * The EAGAIN retry is BOUNDED. A reader that stops draining without closing the
49
+ * pipe (`vat … | consumer-that-wanders-off`) leaves it permanently full, so
50
+ * every retry raises EAGAIN forever; an unbounded loop turns that into a hang
51
+ * with no output and no error — strictly worse than the truncation this replaced.
52
+ * Exhausting the budget throws, so the failure is visible and the exit code is
53
+ * non-zero, rather than the bytes quietly going missing.
54
+ *
55
+ * @throws the underlying error for any failure other than EAGAIN; an `Error`
56
+ * naming the unwritten remainder when the retry budget is exhausted.
13
57
  */
14
- export declare function flushStdout(): Promise<void>;
58
+ export declare function writeAllSync(write: SyncWriter, buffer: Buffer, options?: WriteAllSyncOptions): void;
59
+ /**
60
+ * Write a single YAML document to stdout, opened with `---`.
61
+ *
62
+ * There is deliberately NO trailing marker. `---` OPENS a document in YAML; the
63
+ * end-of-document marker is `...`. Emitting `---` at the end therefore opened a
64
+ * second, empty document, so every command's stdout was a two-document stream and
65
+ * a plain `YAML.parse()` threw `Source contains multiple documents` — on output
66
+ * this CLI documents as "YAML summary → stdout (for programmatic parsing)".
67
+ *
68
+ * The repo's own test helper had already been written around it: `executeCli…`
69
+ * calls `parseAllDocuments(...)` and takes `docs[0]`, with a comment saying "to
70
+ * handle document markers". That workaround is what kept the defect invisible —
71
+ * every consumer that did the obvious thing instead got an exception.
72
+ *
73
+ * Dropping the trailer also makes this agree with the seven hand-rolled emit
74
+ * sites elsewhere in the CLI, none of which ever wrote one.
75
+ *
76
+ * @param data - Data to serialize as YAML
77
+ */
78
+ export declare function writeYamlOutput(data: unknown): void;
15
79
  /**
16
- * Write test-format error to stderr
17
- * Format: file:line:column: message
80
+ * Write a test-format finding to stderr.
81
+ *
82
+ * Format: `file:line:column: severity: message` — the GCC/ESLint-compact
83
+ * convention, which every editor and CI log scraper already parses.
84
+ *
85
+ * The severity is not decoration. Only `error` findings fail the run, so a
86
+ * reader who cannot see the severity cannot tell which lines of a long report
87
+ * they have to act on. Omitting it made an info-severity note byte-identical in
88
+ * shape to a build-breaking error.
18
89
  */
19
- export declare function writeTestFormatError(file: string, line: number, column: number, message: string): void;
90
+ export declare function writeTestFormatError(file: string, line: number, column: number, severity: string, message: string): void;
20
91
  //# sourceMappingURL=output.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAQnD;AAED;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAQjD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}
1
+ {"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAoCpF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+BN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAWnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}
@@ -2,39 +2,154 @@
2
2
  * Output utilities for structured data
3
3
  * YAML output on stdout, logs on stderr
4
4
  */
5
+ import { writeSync } from 'node:fs';
5
6
  import * as yaml from 'yaml';
6
7
  /**
7
- * Write YAML output to stdout with document markers
8
- * @param data - Data to serialize as YAML
8
+ * Write `content` to stdout SYNCHRONOUSLY, in a loop until every byte is handed
9
+ * over.
10
+ *
11
+ * `process.stdout.write` is asynchronous whenever stdout is a PIPE, and every
12
+ * command in this CLI calls `process.exit()` the moment it has written its
13
+ * summary. `process.exit` does not drain a pending write, so everything past the
14
+ * first pipe buffer (64 KB on Linux/macOS) was silently discarded — with exit
15
+ * code 0, so nothing signalled the loss. An interactive TTY is unbuffered and
16
+ * looked perfect, which is why this survived: it only bites the piped consumer
17
+ * this CLI's own docs recommend (`vat command | jq .status`).
18
+ *
19
+ * `writeSync` cannot return before the bytes reach the pipe, so `process.exit`
20
+ * has nothing left to lose. The loop is required because a single `writeSync`
21
+ * may accept fewer bytes than offered.
22
+ *
23
+ * This is the same fix `help-loader.ts` applied to `--help --verbose`; it lives
24
+ * here so both callers share one implementation rather than two copies of a
25
+ * subtle loop.
9
26
  */
10
- export function writeYamlOutput(data) {
11
- process.stdout.write('---\n');
12
- process.stdout.write(yaml.stringify(data, {
13
- indent: 2,
14
- lineWidth: 120,
15
- aliasDuplicateObjects: false,
16
- }));
17
- process.stdout.write('---\n');
27
+ export function writeStdoutSync(content) {
28
+ writeAllSync((buffer, offset, length) => writeSync(1, buffer, offset, length), Buffer.from(content, 'utf8'));
18
29
  }
19
30
  /**
20
- * Flush stdout before writing to stderr
21
- * Prevents output corruption when streams are merged
31
+ * How many CONSECUTIVE EAGAIN retries — retries during which the writer accepted
32
+ * zero bytes — are tolerated before the write is declared stalled.
33
+ *
34
+ * Consecutive, not cumulative: a large payload to a slow reader legitimately
35
+ * EAGAINs thousands of times in total, and every one of those is followed by
36
+ * progress. What is never legitimate is the pipe staying full while the process
37
+ * on the other end takes nothing at all. Combined with the wait below, the
38
+ * budget is roughly ten seconds of a completely stalled reader.
22
39
  */
23
- export async function flushStdout() {
24
- return new Promise((resolve) => {
25
- if (process.stdout.writableNeedDrain) {
26
- process.stdout.once('drain', resolve);
40
+ const MAX_CONSECUTIVE_EAGAIN_RETRIES = 10_000;
41
+ /** Consecutive retries to spin on before sleeping between attempts. */
42
+ const EAGAIN_SPIN_RETRIES = 16;
43
+ /**
44
+ * Sleep synchronously. Required because this whole path exists to run to
45
+ * completion before `process.exit`, so it cannot yield to the event loop; a
46
+ * timer would never fire. `Atomics.wait` on a never-notified buffer is the one
47
+ * primitive that blocks the thread without burning CPU.
48
+ */
49
+ function sleepSync(ms) {
50
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
51
+ }
52
+ /**
53
+ * Spin for the first few retries — a draining pipe frees space in microseconds,
54
+ * and paying a millisecond for that would be absurd — then back off to a real
55
+ * sleep so a genuinely stalled reader is waited out rather than spun on.
56
+ */
57
+ function defaultWaitBetweenRetries(consecutiveRetries) {
58
+ if (consecutiveRetries > EAGAIN_SPIN_RETRIES)
59
+ sleepSync(1);
60
+ }
61
+ /**
62
+ * Drive `write` until every byte of `buffer` has been accepted.
63
+ *
64
+ * Split out from {@link writeStdoutSync} because the things that make this loop
65
+ * necessary — a short write, and an EAGAIN retry on a momentarily-full
66
+ * non-blocking pipe — are both hard to provoke on a real fd and trivial to state
67
+ * against an injected writer. The fd-1 wiring stays a one-liner above, so the
68
+ * only part with branching logic is the part that can be unit tested.
69
+ *
70
+ * The EAGAIN retry is BOUNDED. A reader that stops draining without closing the
71
+ * pipe (`vat … | consumer-that-wanders-off`) leaves it permanently full, so
72
+ * every retry raises EAGAIN forever; an unbounded loop turns that into a hang
73
+ * with no output and no error — strictly worse than the truncation this replaced.
74
+ * Exhausting the budget throws, so the failure is visible and the exit code is
75
+ * non-zero, rather than the bytes quietly going missing.
76
+ *
77
+ * @throws the underlying error for any failure other than EAGAIN; an `Error`
78
+ * naming the unwritten remainder when the retry budget is exhausted.
79
+ */
80
+ export function writeAllSync(write, buffer, options = {}) {
81
+ const maxRetries = options.maxConsecutiveRetries ?? MAX_CONSECUTIVE_EAGAIN_RETRIES;
82
+ const wait = options.waitBetweenRetries ?? defaultWaitBetweenRetries;
83
+ let written = 0;
84
+ let consecutiveRetries = 0;
85
+ while (written < buffer.length) {
86
+ try {
87
+ const n = write(buffer, written, buffer.length - written);
88
+ // A writer that reports no progress would spin forever. Treat it as a
89
+ // failure rather than hang the CLI.
90
+ if (n <= 0) {
91
+ throw new Error(`Refusing to loop forever: writer accepted ${n} bytes of ${buffer.length - written} remaining`);
92
+ }
93
+ written += n;
94
+ consecutiveRetries = 0;
27
95
  }
28
- else {
29
- resolve();
96
+ catch (error) {
97
+ // A non-blocking pipe whose buffer is momentarily full raises EAGAIN; a
98
+ // reader that is draining will free space, so retry. Anything else is a
99
+ // genuine write failure.
100
+ if (error.code !== 'EAGAIN')
101
+ throw error;
102
+ consecutiveRetries++;
103
+ if (consecutiveRetries > maxRetries) {
104
+ throw new Error(`Write stalled: ${maxRetries} consecutive EAGAIN retries with no progress after ${written} of ${buffer.length} bytes. The reader is not draining the pipe.`);
105
+ }
106
+ wait(consecutiveRetries);
30
107
  }
31
- });
108
+ }
109
+ }
110
+ /**
111
+ * Write a single YAML document to stdout, opened with `---`.
112
+ *
113
+ * There is deliberately NO trailing marker. `---` OPENS a document in YAML; the
114
+ * end-of-document marker is `...`. Emitting `---` at the end therefore opened a
115
+ * second, empty document, so every command's stdout was a two-document stream and
116
+ * a plain `YAML.parse()` threw `Source contains multiple documents` — on output
117
+ * this CLI documents as "YAML summary → stdout (for programmatic parsing)".
118
+ *
119
+ * The repo's own test helper had already been written around it: `executeCli…`
120
+ * calls `parseAllDocuments(...)` and takes `docs[0]`, with a comment saying "to
121
+ * handle document markers". That workaround is what kept the defect invisible —
122
+ * every consumer that did the obvious thing instead got an exception.
123
+ *
124
+ * Dropping the trailer also makes this agree with the seven hand-rolled emit
125
+ * sites elsewhere in the CLI, none of which ever wrote one.
126
+ *
127
+ * @param data - Data to serialize as YAML
128
+ */
129
+ export function writeYamlOutput(data) {
130
+ // Deliberately the ordinary stream write, NOT writeStdoutSync: this summary
131
+ // follows human-readable progress output written via console.log, and a
132
+ // synchronous fd-1 write would jump ahead of anything still buffered there.
133
+ // Completeness is guaranteed instead by makeStdioBlocking() at startup, which
134
+ // makes BOTH channels synchronous and keeps them in order.
135
+ process.stdout.write(`---\n${yaml.stringify(data, {
136
+ indent: 2,
137
+ lineWidth: 120,
138
+ aliasDuplicateObjects: false,
139
+ })}`);
32
140
  }
33
141
  /**
34
- * Write test-format error to stderr
35
- * Format: file:line:column: message
142
+ * Write a test-format finding to stderr.
143
+ *
144
+ * Format: `file:line:column: severity: message` — the GCC/ESLint-compact
145
+ * convention, which every editor and CI log scraper already parses.
146
+ *
147
+ * The severity is not decoration. Only `error` findings fail the run, so a
148
+ * reader who cannot see the severity cannot tell which lines of a long report
149
+ * they have to act on. Omitting it made an info-severity note byte-identical in
150
+ * shape to a build-breaking error.
36
151
  */
37
- export function writeTestFormatError(file, line, column, message) {
38
- process.stderr.write(`${file}:${line}:${column}: ${message}\n`);
152
+ export function writeTestFormatError(file, line, column, severity, message) {
153
+ process.stderr.write(`${file}:${line}:${column}: ${severity}: ${message}\n`);
39
154
  }
40
155
  //# sourceMappingURL=output.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;QACxC,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,GAAG;QACd,qBAAqB,EAAE,KAAK;KAC7B,CAAC,CAAC,CAAC;IACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,IAAY,EACZ,MAAc,EACd,OAAe;IAEf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC;AAClE,CAAC"}
1
+ {"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"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"}
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CLI-boundary policy helpers for projectRoot resolution.
3
3
  *
4
- * Per docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §7,
5
- * each command picks one of these to fulfill its declared policy:
4
+ * Root discovery belongs at the CLI boundary, not inside libraries. Each command
5
+ * picks exactly one of these to fulfill its declared policy:
6
6
  *
7
7
  * - `required` → {@link requireProjectRoot} — fails fast with a clear message.
8
8
  * - `loud-cwd` → {@link projectRootOrLoudCwd} — falls back to cwd with a stderr warning.
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CLI-boundary policy helpers for projectRoot resolution.
3
3
  *
4
- * Per docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §7,
5
- * each command picks one of these to fulfill its declared policy:
4
+ * Root discovery belongs at the CLI boundary, not inside libraries. Each command
5
+ * picks exactly one of these to fulfill its declared policy:
6
6
  *
7
7
  * - `required` → {@link requireProjectRoot} — fails fast with a clear message.
8
8
  * - `loud-cwd` → {@link projectRootOrLoudCwd} — falls back to cwd with a stderr warning.
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Re-basing report `path` values onto the run's single stated root.
3
+ *
4
+ * A report states its coordinate system ONCE — `root:` — and every `path`
5
+ * beneath it is relative to that. Producers keep absolute paths internally on
6
+ * purpose: an absolute path is the identity every internal map keys on (compat
7
+ * results, visited-path de-duplication, registry caches), and unlike a
8
+ * `location` it is trivially recoverable, since an absolute path plus a known
9
+ * root yields the relative form. Re-basing therefore happens once, at the
10
+ * document boundary, and this module is that one place.
11
+ *
12
+ * Deliberately NOT a deep walk over every `path`-named property: re-basing is
13
+ * not idempotent (`relative(root, someRelativeValue)` resolves the value
14
+ * against the process cwd and produces nonsense), so a helper that guesses
15
+ * which values are absolute would silently corrupt an already-relative one.
16
+ * The caller names the nested carriers it owns instead.
17
+ */
18
+ /** The minimum shape this module re-bases: anything carrying a `path`. */
19
+ export interface PathEntry {
20
+ path: string;
21
+ }
22
+ /**
23
+ * Re-base one absolute path onto `root`, as a forward-slashed relative path.
24
+ *
25
+ * Pointing a report AT a single resource makes that resource the root, which
26
+ * relativizes to the empty string. That is spelled `.` — the POSIX name for
27
+ * "the root itself" — so no consumer has to special-case a blank value, and
28
+ * `join(root, path)` still resolves.
29
+ */
30
+ export declare function relativizePath(absolutePath: string, root: string): string;
31
+ /**
32
+ * Re-base the `path` of every entry — and of every entry inside the nested
33
+ * carriers named by `nestedKeys`, at any depth — onto `root`.
34
+ *
35
+ * Returns new objects; the input is never mutated.
36
+ *
37
+ * @param entries - Report entries carrying absolute `path` values.
38
+ * @param root - The single root the document states.
39
+ * @param nestedKeys - Names of array-valued properties whose elements also
40
+ * carry an absolute `path` (audit passes `['linkedFiles']`). Omitting a
41
+ * carrier leaves its paths absolute, which is how a document ends up in two
42
+ * coordinate systems — so a producer that adds a carrier must name it here.
43
+ */
44
+ export declare function relativizePathEntries<T extends PathEntry>(entries: readonly T[], root: string, nestedKeys?: readonly string[]): T[];
45
+ //# sourceMappingURL=relativize-paths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"relativize-paths.d.ts","sourceRoot":"","sources":["../../src/utils/relativize-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AA+BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,SAAS,EACvD,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,CAAC,EAAE,CAEL"}