toolmenu 0.12.0 → 0.13.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 (58) hide show
  1. package/README.md +76 -20
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +53 -17
  6. package/dist/auto.d.ts +70 -6
  7. package/dist/auto.js +248 -17
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +62 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +80 -170
  13. package/dist/config.d.ts +5 -1
  14. package/dist/config.js +14 -0
  15. package/dist/connect.d.ts +4 -0
  16. package/dist/connect.js +132 -11
  17. package/dist/diff.d.ts +23 -1
  18. package/dist/diff.js +526 -114
  19. package/dist/difference.d.ts +2 -0
  20. package/dist/difference.js +13 -12
  21. package/dist/explain.d.ts +103 -0
  22. package/dist/explain.js +434 -0
  23. package/dist/failures.d.ts +9 -0
  24. package/dist/failures.js +17 -0
  25. package/dist/help.d.ts +9 -0
  26. package/dist/help.js +198 -0
  27. package/dist/history.d.ts +13 -0
  28. package/dist/history.js +86 -6
  29. package/dist/init.d.ts +92 -2
  30. package/dist/init.js +507 -20
  31. package/dist/menu.js +10 -2
  32. package/dist/options.d.ts +135 -0
  33. package/dist/options.js +48 -0
  34. package/dist/report.d.ts +1 -1
  35. package/dist/report.js +229 -99
  36. package/dist/rules/description.d.ts +7 -2
  37. package/dist/rules/description.js +85 -42
  38. package/dist/rules/determinism.d.ts +3 -1
  39. package/dist/rules/determinism.js +145 -11
  40. package/dist/rules/ids.d.ts +1 -1
  41. package/dist/rules/ids.js +9 -4
  42. package/dist/rules/index.d.ts +6 -0
  43. package/dist/rules/index.js +12 -4
  44. package/dist/rules/naming.d.ts +1 -1
  45. package/dist/rules/naming.js +66 -19
  46. package/dist/rules/rule.d.ts +18 -0
  47. package/dist/rules/rule.js +25 -1
  48. package/dist/rules/spec.js +33 -9
  49. package/dist/rules/write.d.ts +1 -1
  50. package/dist/rules/write.js +42 -10
  51. package/dist/session.d.ts +18 -8
  52. package/dist/session.js +484 -92
  53. package/dist/snapshot.d.ts +2 -2
  54. package/dist/snapshot.js +17 -2
  55. package/dist/types.d.ts +14 -0
  56. package/dist/words.d.ts +5 -0
  57. package/dist/words.js +14 -0
  58. package/package.json +1 -1
package/dist/report.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { stepLabel } from './session.js';
2
- import { breakdown, breakdownLines } from './breakdown.js';
2
+ import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
3
+ import { autoSummary } from './auto.js';
3
4
  const LABEL = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
4
5
  export function counts(findings) {
5
6
  const c = { error: 0, warn: 0, info: 0 };
@@ -53,31 +54,32 @@ export function formatSnapshot(menu, findings, format, outPath) {
53
54
  return lines.join('\n');
54
55
  }
55
56
  function mdBreakdown(menu) {
56
- const where = breakdownLines(breakdown(menu), menu.tools.length);
57
- if (!where.length)
58
- return [];
59
- return ['', `<details><summary>${where[0]}</summary>`, '', '```', ...where.slice(1).map((l) => l.trimStart()), '```', '', '</details>'];
57
+ return breakdownMarkdown(breakdown(menu), menu.tools.length);
60
58
  }
61
59
  function findingLines(findings) {
62
60
  const lines = [];
63
61
  for (const f of findings) {
64
- lines.push(`${LABEL[f.severity]} ${f.rule}`);
62
+ lines.push(`${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
65
63
  lines.push(` ${f.message}`);
66
64
  for (const d of f.detail ?? [])
67
65
  lines.push(` ${d}`);
66
+ if (f.fix)
67
+ lines.push(` → Next: ${f.fix}`);
68
68
  }
69
69
  lines.push(findings.length ? '' : 'No findings.');
70
70
  return lines;
71
71
  }
72
+ /** The last line of every report: ✗ with errors, ! with warnings, ✓ otherwise. */
72
73
  function summaryLine(findings) {
73
74
  const c = counts(findings);
74
- return `${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`;
75
+ const mark = c.error ? '✗' : c.warn ? '!' : '✓';
76
+ return `${mark} ${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`;
75
77
  }
76
78
  function githubLines(findings) {
77
79
  return findings.map((f) => {
78
80
  const level = f.severity === 'error' ? 'error' : f.severity === 'warn' ? 'warning' : 'notice';
79
- const body = [f.message, ...(f.detail ?? [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
80
- return `::${level} title=toolmenu ${f.rule}::${body}`;
81
+ const body = [f.message, ...(f.detail ?? []), ...(f.fix ? [`→ Next: ${f.fix}`] : [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
82
+ return `::${level} title=toolmenu ${f.rule}${unsureMark(f)}::${body}`;
81
83
  });
82
84
  }
83
85
  function signed(n) {
@@ -91,49 +93,54 @@ function tokenSentence(d) {
91
93
  return `this release saves ~${n} tokens in every conversation that loads the menu`;
92
94
  return 'no change in menu size';
93
95
  }
96
+ /** "3 breaking (25 tools) · 2 minor (2 tools) · 11 notice (10 tools)": changes, and the tools they touch. */
97
+ function classLine(d) {
98
+ const part = (c) => {
99
+ const { changes, tools } = d.classes[c];
100
+ return `${changes} ${c}${changes && tools ? ` (${plural(tools, 'tool')})` : ''}`;
101
+ };
102
+ return `${part('breaking')} · ${part('minor')} · ${part('notice')}`;
103
+ }
104
+ /**
105
+ * The version verdict: the bump these changes suggest, then whether the release's
106
+ * bump is enough (and what to release instead), or why it wasn't checked.
107
+ */
108
+ function bumpVerdict(d, md = false) {
109
+ const b = (s) => (md ? `**${s}**` : s);
110
+ const suggested = `suggested bump: ${b(d.suggestedBump)}`;
111
+ if (!d.actualBump || !d.release)
112
+ return { line: `${suggested} · not checked (${d.bumpNotChecked ?? 'pass --release old..new'})`, short: false };
113
+ const pair = `${d.release.before} → ${d.release.after} is a ${d.actualBump} bump`;
114
+ const required = d.requiredBump ?? d.suggestedBump;
115
+ const below1 = required !== d.suggestedBump ? ` (under 1.0.0 ${required === 'none' ? 'anything goes' : `a ${required} is enough`})` : '';
116
+ const rank = { none: 0, patch: 1, minor: 2, major: 3 };
117
+ if (rank[d.actualBump] >= rank[required])
118
+ return { line: `${suggested} · ${pair}: enough${below1}`, short: false };
119
+ return { line: `${suggested} · ${pair}: ${b(`too small, release ${d.releaseAs ?? `a ${required}`}`)}${below1}`, short: true };
120
+ }
121
+ function releasePair(d) {
122
+ // Name the release versions when there are some; otherwise say whose version this is.
123
+ return d.release?.source === 'release' ? `${d.release.before} → ${d.release.after}` : `${d.before.version ?? '?'} → ${d.after.version ?? '?'} (server-reported)`;
124
+ }
94
125
  export function formatDiff(d, beforeTools, afterTools, format) {
95
126
  if (format === 'json') {
96
127
  return JSON.stringify({ command: 'diff', ...d, counts: counts(d.findings) }, null, 2);
97
128
  }
98
- const classes = { breaking: 0, minor: 0, notice: 0 };
99
- for (const f of d.findings)
100
- if (f.class)
101
- classes[f.class]++;
102
- // Name the release versions when there are some; otherwise say whose version this is.
103
- const pair = d.release?.source === 'release'
104
- ? `${d.release.before} → ${d.release.after}`
105
- : `${d.before.version ?? '?'} → ${d.after.version ?? '?'} (server-reported)`;
106
- const actual = d.actualBump ?? `not checked (${d.bumpNotChecked ?? 'pass --release'})`;
107
- const headline = `${d.after.name ?? d.before.name ?? 'server'} ${pair}`;
108
- const tokenLine = `~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')} tokens (${signed(d.tokens.delta)}, estimate): ${tokenSentence(d)}`;
109
- const bumpLine = `suggested bump: ${d.suggestedBump} · actual: ${actual}`;
129
+ const name = d.after.name ?? d.before.name ?? 'server';
130
+ const pair = releasePair(d);
131
+ const verdict = bumpVerdict(d);
132
+ const tokenLine = `~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')} (${signed(d.tokens.delta)}, estimate): ${tokenSentence(d)}`;
110
133
  if (format === 'github') {
111
- return [...githubLines(d.findings), `::notice title=toolmenu diff::${headline}. ${tokenLine}. ${bumpLine}.`].join('\n');
112
- }
113
- if (format === 'markdown') {
114
- const lines = [
115
- `### toolmenu diff: \`${d.after.name ?? d.before.name ?? 'server'}\` ${pair}`,
116
- '',
117
- `**${signed(d.tokens.delta)} tokens** (~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')}, estimate): ${tokenSentence(d)}.`,
118
- '',
119
- `**${classes.breaking} breaking** · ${classes.minor} minor · ${classes.notice} notice · suggested bump: **${d.suggestedBump}** (actual: ${actual}) · ${beforeTools} → ${afterTools} tools`,
120
- '',
121
- ...mdFindings(d.findings),
122
- ];
123
- if (d.tokens.tools.length) {
124
- lines.push('', '<details><summary>Token change by tool (estimate)</summary>', '', '| Tool | Before | After | Change |', '|---|---:|---:|---:|');
125
- for (const t of d.tokens.tools.slice(0, 30))
126
- lines.push(`| \`${t.name}\` | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
127
- if (d.tokens.tools.length > 30)
128
- lines.push(`| …and ${d.tokens.tools.length - 30} more | | | |`);
129
- lines.push('', '</details>');
130
- }
131
- return lines.join('\n');
134
+ return [...githubLines(d.findings), `::notice title=toolmenu diff::${name} ${pair}. Changes: ${classLine(d)}. Tokens: ${tokenLine}. Version: ${verdict.line}.`].join('\n');
132
135
  }
136
+ if (format === 'markdown')
137
+ return mdDiff(d, beforeTools, afterTools);
133
138
  const lines = [
134
- `toolmenu diff ${headline}`,
135
- ` ${beforeTools} → ${afterTools} tools · ${tokenLine}`,
136
- ` ${classes.breaking} breaking · ${classes.minor} minor · ${classes.notice} notice · ${bumpLine}`,
139
+ `toolmenu diff ${name} ${pair}`,
140
+ ` changes ${classLine(d)}`,
141
+ ` version ${verdict.line}`,
142
+ ` tokens ${tokenLine}`,
143
+ ` tools ${beforeTools} → ${afterTools}`,
137
144
  '',
138
145
  ...findingLines(d.findings),
139
146
  ];
@@ -148,66 +155,189 @@ export function formatDiff(d, beforeTools, afterTools, format) {
148
155
  lines.push(summaryLine(d.findings));
149
156
  return lines.join('\n');
150
157
  }
151
- export function formatHistory(h, format, outDir) {
158
+ /** The diff as a PR comment: the verdict first, then the changes by class, notices folded. */
159
+ function mdDiff(d, beforeTools, afterTools) {
160
+ const name = d.after.name ?? d.before.name ?? 'server';
161
+ const verdict = bumpVerdict(d, true);
162
+ const c = d.classes;
163
+ const headline = [
164
+ c.breaking.changes ? `**${plural(c.breaking.changes, 'breaking change')}** in ${plural(c.breaking.tools, 'tool')}` : 'No breaking changes',
165
+ `${c.minor.changes} minor`,
166
+ `${c.notice.changes} notice${c.notice.changes === 1 ? '' : 's'}`,
167
+ `**${signed(d.tokens.delta)} tokens** (~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')}, estimate)`,
168
+ `${beforeTools} → ${afterTools} tools`,
169
+ ].join(' · ');
170
+ const lines = [`### toolmenu diff: \`${name}\` ${releasePair(d)}`, '', headline, '', `> **Version:** ${verdict.line}`, ''];
171
+ if (d.tokens.delta !== 0)
172
+ lines.splice(lines.length - 1, 0, '>', `> **Tokens:** ${tokenSentence(d)}.`);
173
+ const table = (findings) => ['| | Rule | Change |', '|---|---|---|', ...findings.map(mdDiffRow)];
174
+ // Sections follow the severity the user's rules set, not only the class: a
175
+ // notice raised to error fails CI, so it's shown, never folded; a breaking
176
+ // rule lowered to info is folded with the notices.
177
+ const loud = (f) => f.severity !== 'info';
178
+ const breaking = d.findings.filter((f) => f.class === 'breaking' && loud(f));
179
+ const checks = d.findings.filter((f) => f.class !== 'breaking' && f.class !== 'minor' && loud(f));
180
+ const minor = d.findings.filter((f) => f.class === 'minor');
181
+ const quiet = d.findings.filter((f) => f.class !== 'minor' && !loud(f));
182
+ if (breaking.length)
183
+ lines.push(`#### Breaking (${breaking.length})`, '', ...table(breaking), '');
184
+ if (checks.length)
185
+ lines.push(`#### To check (${checks.length})`, '', ...table(checks), '');
186
+ if (minor.length)
187
+ lines.push(`#### New (${minor.length}, minor)`, '', ...table(minor), '');
188
+ if (quiet.length)
189
+ lines.push(`<details><summary>Notices (${quiet.length})</summary>`, '', ...table(quiet), '', '</details>', '');
190
+ if (!d.findings.length)
191
+ lines.push('No findings.', '');
192
+ if (d.tokens.tools.length) {
193
+ lines.push('<details><summary>Token change by tool (estimate)</summary>', '', '| Tool | Before | After | Change |', '|---|---:|---:|---:|');
194
+ for (const t of d.tokens.tools.slice(0, 30))
195
+ lines.push(`| \`${t.name}\` | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
196
+ if (d.tokens.tools.length > 30)
197
+ lines.push(`| …and ${d.tokens.tools.length - 30} more | | | |`);
198
+ lines.push('', '</details>', '');
199
+ }
200
+ lines.push(summaryLine(d.findings));
201
+ return lines.join('\n');
202
+ }
203
+ /** One diff finding as a table row: a long tool list folds, a text change shows as -/+ lines. */
204
+ function mdDiffRow(f) {
205
+ const detail = (f.detail ?? []).map((line) => {
206
+ const list = /^(tools|operations|moved): (.*)$/.exec(line);
207
+ if (list)
208
+ return `<details><summary>all ${list[2].split(', ').length} ${list[1] === 'moved' ? 'moved tools' : list[1]}</summary>${mdCell(list[2])}</details>`;
209
+ return `<br><sub>${mdCell(line).replace(/</g, '&lt;')}</sub>`;
210
+ });
211
+ const sev = f.severity === 'error' ? '**error**' : f.severity;
212
+ return `| ${sev} | \`${f.rule}\`${f.confidence === 'unsure' ? ' · _unsure_' : ''} | ${mdCell(f.message)}${detail.join('')}${f.fix ? `<br>**→ Next:** ${mdCell(f.fix)}` : ''} |`;
213
+ }
214
+ export function formatHistory(h, format, outDir, csvPath) {
152
215
  if (format === 'json')
153
- return JSON.stringify({ command: 'history', ...h }, null, 2);
216
+ return JSON.stringify({ command: 'history', ...h, written: { dir: outDir, csv: csvPath ?? null } }, null, 2);
154
217
  const ok = h.rows.filter((r) => r.status === 'ok');
155
218
  const failed = h.rows.filter((r) => r.status === 'failed');
219
+ const breaking = h.rows.filter((r) => r.diff?.breakingChanges.length);
156
220
  const reasons = {};
157
221
  for (const r of failed)
158
222
  reasons[r.reason ?? 'crashed'] = (reasons[r.reason ?? 'crashed'] ?? 0) + 1;
159
- const failSummary = failed.length ? ` (${Object.entries(reasons).map(([k, n]) => `${k} ${n}`).join(', ')})` : '';
223
+ const reasonList = Object.entries(reasons).map(([k, n]) => `${n} ${k}`).join(', ');
224
+ const mark = ok.length === 0 && h.rows.length ? '✗' : failed.length || breaking.length ? '!' : '✓';
225
+ const summary = [
226
+ `${mark} ${ok.length} of ${plural(h.rows.length, 'version')} inspected`,
227
+ ...(failed.length ? [`${failed.length} failed (${reasonList})`] : []),
228
+ // "No breaking changes" only when there was something to compare.
229
+ ...(breaking.length ? [`${plural(breaking.length, 'release')} with breaking changes`] : ok.length > 1 ? ['no breaking changes'] : []),
230
+ ].join(' · ');
231
+ const scope = `the last ${h.rows.length} of ${h.totalVersions} published versions, installed ${h.installedAt.slice(0, 10)}: dependencies resolve as of that day, not as shipped`;
232
+ const saved = `menus and history.json in ${outDir}${csvPath ? ` · CSV in ${csvPath}` : ''}`;
233
+ const failure = (r) => r.message ?? `${r.reason}: ${(r.error ?? '').split('\n')[0].slice(0, 160)}`;
160
234
  if (format === 'github') {
161
235
  const lines = h.rows.flatMap((r) => r.status === 'failed'
162
- ? [`::warning title=toolmenu history ${r.version}::failed: ${r.reason}`]
163
- : (r.diff?.breakingChanges ?? []).map((m) => `::error title=toolmenu history ${r.version}::${m}`));
164
- return [...lines, `::notice title=toolmenu history::${h.package}: ${ok.length} of ${h.rows.length} versions inspected${failSummary}`].join('\n');
236
+ ? [`::warning title=toolmenu history ${r.version} (${r.reason}${r.confidence === 'unsure' ? ' · unsure' : ''})::${ghEscape([failure(r), ...(r.fix ? [`→ Next: ${r.fix}`] : [])].join('\n'))}`]
237
+ : (r.diff?.breakingChanges ?? []).map((m) => `::error title=toolmenu history ${r.version}::${ghEscape(`${m} (vs ${r.diff.from})`)}`));
238
+ return [...lines, `::notice title=toolmenu history::${ghEscape(`${h.package}: ${summary.slice(2)}. ${saved}.`)}`].join('\n');
165
239
  }
166
240
  const sdkOf = (r) => (r.resolved?.['@modelcontextprotocol/sdk'] ?? r.resolved?.['@modelcontextprotocol/server'] ?? []).join('+') || '-';
167
- const table = [
168
- ['version', 'published', 'protocol', 'tools', 'tokens', 'sdk', 'zod', 'findings', 'vs previous'],
169
- ...h.rows.map((r) => r.status === 'failed'
170
- ? [r.version, r.published?.slice(0, 10) ?? '', `failed: ${r.reason}`, '', '', sdkOf(r), (r.resolved?.zod ?? []).join('+') || '-', '', '']
171
- : [
172
- r.version,
173
- r.published?.slice(0, 10) ?? '',
174
- r.protocolVersion ?? '?',
175
- String(r.tools ?? ''),
176
- `~${(r.tokens ?? 0).toLocaleString('en-US')}`,
177
- sdkOf(r),
178
- (r.resolved?.zod ?? []).join('+') || '-',
179
- [r.counts?.error ? `${r.counts.error} err` : '', r.counts?.warn ? `${r.counts.warn} warn` : ''].filter(Boolean).join(' ') || 'clean',
180
- r.diff
181
- ? `${signed(r.diff.tokenDelta)} tokens · ${[r.diff.breaking && `${r.diff.breaking} breaking`, r.diff.minor && `${r.diff.minor} minor`, r.diff.notice && `${r.diff.notice} notice`].filter(Boolean).join(' · ') || 'no changes'}`
182
- : '—',
183
- ]),
184
- ];
241
+ const zodOf = (r) => (r.resolved?.zod ?? []).join('+') || '-';
242
+ const findingsOf = (r) => [r.counts?.error ? `${r.counts.error} err` : '', r.counts?.warn ? `${r.counts.warn} warn` : ''].filter(Boolean).join(' ') || 'clean';
243
+ const versus = (r) => {
244
+ if (!r.diff)
245
+ return '—';
246
+ const d = r.diff;
247
+ const changes = [d.breaking && `${d.breaking} breaking`, d.minor && `${d.minor} minor`, d.notice && `${d.notice} notice`].filter(Boolean).join(' · ') || 'no changes';
248
+ return `${signed(d.tokenDelta)} tokens · ${changes}${d.bumpTooSmall ? ` · bump too small (${d.actualBump ?? '?'}, needs ${d.suggestedBump})` : ''}`;
249
+ };
250
+ const head = ['version', 'published', 'protocol', 'tools', 'tokens', 'sdk', 'zod', 'findings', 'vs previous'];
251
+ const cells = (r) => r.status === 'failed'
252
+ ? [r.version, r.published?.slice(0, 10) ?? '', `failed: ${r.reason}`, '', '', sdkOf(r), zodOf(r), '', '']
253
+ : [r.version, r.published?.slice(0, 10) ?? '', r.protocolVersion ?? '?', String(r.tools ?? ''), `~${(r.tokens ?? 0).toLocaleString('en-US')}`, sdkOf(r), zodOf(r), findingsOf(r), versus(r)];
254
+ if (format === 'markdown') {
255
+ const lines = [
256
+ `### toolmenu history: \`${h.package}\``,
257
+ '',
258
+ `${scope.charAt(0).toUpperCase()}${scope.slice(1)}.`,
259
+ '',
260
+ `| ${head.join(' | ')} |`,
261
+ `|${head.map((_, i) => (i >= 3 && i <= 4 ? '---:' : '---')).join('|')}|`,
262
+ ...h.rows.map((r) => `| ${cells(r).map((c, i) => (i === 2 && r.status === 'failed' ? `**${mdCell(c)}**` : mdCell(c))).join(' | ')} |`),
263
+ ];
264
+ if (breaking.length) {
265
+ lines.push('', '**Breaking changes**', '');
266
+ for (const r of breaking) {
267
+ for (const m of r.diff.breakingChanges.slice(0, BREAKING_SHOWN))
268
+ lines.push(`- \`${r.version}\` (vs ${r.diff.from}): ${mdCell(m)}`);
269
+ if (r.diff.breakingChanges.length > BREAKING_SHOWN)
270
+ lines.push(`- \`${r.version}\`: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
271
+ }
272
+ }
273
+ if (failed.length) {
274
+ lines.push('', `**Failed** (${failed.length} of ${h.rows.length})`, '');
275
+ for (const g of failureGroups(failed, failure))
276
+ lines.push(`- \`${g.versions}\` · ${g.row.reason}${g.row.confidence === 'unsure' ? ' · _unsure_' : ''}: ${mdCell(g.message)}${g.fix ? `<br>**→ Next:** ${mdCell(g.fix)}` : ''}`);
277
+ }
278
+ lines.push('', `**${summary}**`, '', `<sub>${saved.charAt(0).toUpperCase()}${saved.slice(1)}.</sub>`);
279
+ return lines.join('\n');
280
+ }
281
+ const table = [head, ...h.rows.map(cells)];
185
282
  const widths = table[0].map((_, c) => Math.max(...table.map((row) => row[c].length)));
186
283
  const lines = [
187
284
  `toolmenu history ${h.package}`,
188
- ` last ${h.rows.length} of ${h.totalVersions} published versions · installed ${h.installedAt.slice(0, 10)}`,
189
- ` (each version was installed today: dependencies resolve as of today, not as shipped)`,
285
+ ` ${scope}`,
190
286
  '',
191
287
  ...table.map((row) => ' ' + row.map((cell, c) => cell.padEnd(widths[c])).join(' ').trimEnd()),
192
288
  '',
193
289
  ];
194
- const breaking = h.rows.filter((r) => r.diff?.breakingChanges.length);
195
290
  if (breaking.length) {
196
291
  lines.push('Breaking changes:');
197
- for (const r of breaking)
198
- for (const m of r.diff.breakingChanges)
292
+ for (const r of breaking) {
293
+ for (const m of r.diff.breakingChanges.slice(0, BREAKING_SHOWN))
199
294
  lines.push(` ${r.version} (vs ${r.diff.from}): ${m}`);
295
+ if (r.diff.breakingChanges.length > BREAKING_SHOWN)
296
+ lines.push(` ${r.version}: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
297
+ }
200
298
  lines.push('');
201
299
  }
202
300
  if (failed.length) {
203
- lines.push('Failed:');
204
- for (const r of failed)
205
- lines.push(` ${r.version}: ${r.reason}. ${(r.error ?? '').split('\n')[0].slice(0, 160)}`);
301
+ lines.push(`Failed (${failed.length} of ${h.rows.length}):`);
302
+ for (const g of failureGroups(failed, failure)) {
303
+ lines.push(` ${g.versions} ${g.row.reason}${g.row.confidence === 'unsure' ? ' · unsure' : ''}`);
304
+ lines.push(` ${g.message}`);
305
+ if (g.fix)
306
+ lines.push(` → Next: ${g.fix}`);
307
+ }
206
308
  lines.push('');
207
309
  }
208
- lines.push(`${h.rows.length} inspected · ${ok.length} ok · ${failed.length} failed${failSummary} · wrote ${outDir}`);
310
+ lines.push(summary, ` ${saved}`);
209
311
  return lines.join('\n');
210
312
  }
313
+ /** Breaking changes listed per release in history's text and markdown; the rest are in history.json. */
314
+ const BREAKING_SHOWN = 5;
315
+ /**
316
+ * Failed versions with the same words and next step, as one entry naming them: "0.2.0, 0.3.0 … 0.4.0 (6 versions)".
317
+ * The words name the version (npm couldn't install pkg@0.2.0), so they're compared, and a
318
+ * group of several shown, with "@<version>" in its place.
319
+ */
320
+ function failureGroups(failed, failure) {
321
+ const bare = (text, version) => text.split(`@${version}`).join('@<version>');
322
+ const groups = new Map();
323
+ for (const r of failed) {
324
+ const key = `${r.reason}\n${bare(failure(r), r.version)}\n${bare(r.fix ?? '', r.version)}`;
325
+ groups.set(key, [...(groups.get(key) ?? []), r]);
326
+ }
327
+ return [...groups.values()].map((rows) => {
328
+ const row = rows[0];
329
+ const shown = (text) => (rows.length === 1 ? text : bare(text, row.version));
330
+ return {
331
+ row,
332
+ message: shown(failure(row)),
333
+ fix: row.fix === undefined ? undefined : shown(row.fix),
334
+ versions: rows.length === 1 ? row.version : rows.length <= 3 ? rows.map((r) => r.version).join(', ') : `${rows[0].version}, ${rows[1].version} … ${rows[rows.length - 1].version} (${rows.length} versions)`,
335
+ };
336
+ });
337
+ }
338
+ function ghEscape(text) {
339
+ return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
340
+ }
211
341
  export function formatSession(s, format) {
212
342
  if (format === 'json') {
213
343
  // The union menu itself goes to --union-out; the report says how big it is.
@@ -215,7 +345,7 @@ export function formatSession(s, format) {
215
345
  return JSON.stringify({ command: 'session', ...rest, union: { tools: union.tools.length, totalTokens: union.totalTokens }, counts: counts(s.findings) }, null, 2);
216
346
  }
217
347
  if (format === 'github') {
218
- return githubLines(s.findings.map((f) => ({ ...f, message: f.step ? `step ${f.step} (${s.steps[f.step - 1]?.label}): ${f.message}` : f.message }))).join('\n');
348
+ return githubLines(s.findings.map((f) => ({ ...f, message: stepPrefix(f, `step ${f.step} (${s.steps[(f.step ?? 1) - 1]?.label}): `) }))).join('\n');
219
349
  }
220
350
  if (format === 'markdown') {
221
351
  const lines = [
@@ -223,12 +353,12 @@ export function formatSession(s, format) {
223
353
  '',
224
354
  `\`${s.server.name ?? 'server'}\` ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport} · ${s.baseline.tools} → ${s.final.tools} tools · ~${s.baseline.tokens.toLocaleString('en-US')} → ~${s.final.tokens.toLocaleString('en-US')} tokens (estimate)`,
225
355
  '',
226
- ...(autoLine(s) ? [autoLine(s), ''] : []),
356
+ ...(s.auto ? [...autoSummary(s.auto).map((l, i) => (i === 0 ? `**${l.replace(/^auto: /, 'auto:** ')}` : `- ${l.trim()}`)), ''] : []),
227
357
  '| Step | Menu | list_changed | Scope |',
228
358
  '|---|---|---|---|',
229
359
  ...s.steps.map((st) => `| ${st.index}. ${mdCell(st.label)} | ${st.status !== 'ok' ? st.status : st.changed ? `changed (${st.tools} tools)` : 'no change'} | ${st.changed ? (st.listChanged ? 'received' : '**missing**') : ''} | ${st.scope ?? ''} |`),
230
360
  '',
231
- ...mdFindings(s.findings.map((f) => ({ ...f, message: f.step ? `Step ${f.step}: ${f.message}` : f.message }))),
361
+ ...mdFindings(s.findings.map((f) => ({ ...f, message: stepPrefix(f, `Step ${f.step}: `) }))),
232
362
  ];
233
363
  return lines.join('\n');
234
364
  }
@@ -237,26 +367,31 @@ export function formatSession(s, format) {
237
367
  `toolmenu session ${s.scenario}`,
238
368
  ` ${s.server.name ?? 'server'} ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport}`,
239
369
  ` baseline: ${plural(s.baseline.tools, 'tool')} · ${tok(s.baseline.tokens)} tokens (estimate) · listening for list_changed: ${s.listening ? 'yes' : 'no'}`,
240
- ...(autoLine(s) ? [` ${autoLine(s)}`] : []),
370
+ ...(s.auto ? autoSummary(s.auto).map((l, i) => (i === 0 ? ` ${l}` : ` ${l}`)) : []),
241
371
  ` fresh-${s.transport === 'stdio' ? 'process' : 'connection'} check: ${s.connectionCheck === undefined ? 'not checked' : s.connectionCheck === 'same' ? 'the same menu' : 'a DIFFERENT menu'}`,
242
372
  '',
243
373
  ];
244
374
  const at = (step) => s.findings.filter((f) => f.step === step);
245
375
  const block = (findings) => {
246
376
  for (const f of findings) {
247
- lines.push(` ${LABEL[f.severity]} ${f.rule}`);
377
+ lines.push(` ${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
248
378
  lines.push(` ${f.message}`);
249
379
  for (const d of f.detail ?? [])
250
380
  lines.push(` ${d}`);
381
+ if (f.fix)
382
+ lines.push(` → Next: ${f.fix}`);
251
383
  }
252
384
  };
253
385
  block(at(0));
254
386
  if (at(0).length)
255
387
  lines.push('');
388
+ let before = s.baseline.tools;
256
389
  for (const step of s.steps) {
390
+ const delta = step.tools - before;
391
+ before = step.tools;
257
392
  const facts = [
258
393
  step.status !== 'ok' ? step.status : '',
259
- step.changed ? 'menu changed' : step.status === 'ok' ? 'no change' : '',
394
+ step.changed ? `menu changed${delta ? ` · ${delta > 0 ? '+' : '−'}${plural(Math.abs(delta), 'tool')}` : ''}` : step.status === 'ok' ? 'no change' : '',
260
395
  step.changed ? (step.listChanged ? 'list_changed received' : 'no list_changed') : '',
261
396
  step.scope ? `scope: ${step.scope}` : '',
262
397
  step.note ?? '',
@@ -281,20 +416,15 @@ export function formatPlan(scenario, name) {
281
416
  lines.push('', 'After every step the menu is listed and compared with the one before. Nothing was run.');
282
417
  return lines.join('\n');
283
418
  }
284
- /** One line on what --auto called and what it left out, and how to reach more. */
285
- function autoLine(s) {
286
- if (!s.auto)
287
- return undefined;
288
- const by = (r) => s.auto.skipped.filter((x) => x.reason === r);
289
- const needs = by('needs values');
290
- const params = [...new Set(needs.flatMap((x) => x.missing ?? []))];
291
- const parts = [
292
- by('not read-only').length && `${by('not read-only').length} not read-only`,
293
- by('open world').length && `${by('open world').length} marked openWorldHint: true (--open-world to call them)`,
294
- needs.length && `${needs.length} need values the schema doesn't give (${params.slice(0, 6).join(', ')}${params.length > 6 ? ', …' : ''}: write a scenario, or --save-scenario and fill them in)`,
295
- by('over the call budget').length && `${by('over the call budget').length} over --max-calls`,
296
- ].filter(Boolean);
297
- return `auto: called ${s.auto.called.length} tool${s.auto.called.length === 1 ? '' : 's'}${parts.length ? ` · skipped ${parts.join(', ')}` : ''}`;
419
+ /** " · unsure" after the rule, for findings that are a heuristic or an inference. */
420
+ function unsureMark(f) {
421
+ return f.confidence === 'unsure' ? ' · unsure' : '';
422
+ }
423
+ /** The step a session finding belongs to, unless its message already names its steps. */
424
+ function stepPrefix(f, prefix) {
425
+ if (!f.step || /^steps? \d/i.test(f.message))
426
+ return f.message;
427
+ return prefix + f.message;
298
428
  }
299
429
  function mdCell(text) {
300
430
  return text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
@@ -302,7 +432,7 @@ function mdCell(text) {
302
432
  function mdFindings(findings) {
303
433
  if (findings.length === 0)
304
434
  return ['No findings.'];
305
- const row = (f) => `| ${f.severity === 'error' ? '**error**' : f.severity} | \`${f.rule}\` | ${mdCell([f.message, ...(f.detail ?? [])].join(' · '))} |`;
435
+ const row = (f) => `| ${f.severity === 'error' ? '**error**' : f.severity} | \`${f.rule}\`${f.confidence === 'unsure' ? ' · _unsure_' : ''} | ${mdCell([f.message, ...(f.detail ?? [])].join(' · '))}${f.fix ? `<br>**→ Next:** ${mdCell(f.fix)}` : ''} |`;
306
436
  const head = ['| | Rule | Finding |', '|---|---|---|'];
307
437
  const loud = findings.filter((f) => f.severity !== 'info');
308
438
  const quiet = findings.filter((f) => f.severity === 'info');
@@ -1,11 +1,15 @@
1
1
  import type { MenuTool } from '../types.js';
2
- import type { Rule } from './rule.js';
2
+ import { type Rule } from './rule.js';
3
3
  export declare const CLIENT_LIMITS: Record<string, number>;
4
4
  export declare const DEFAULT_CLIENT = "claude-code";
5
- /** The cut in characters, and how to name it in a message. */
5
+ /**
6
+ * The cut in characters, the client to name in a message ("Claude Code", "your
7
+ * client"), and whether it's toolmenu's assumption rather than the user's setting.
8
+ */
6
9
  export declare function resolveLimit(setting: number | string | undefined): {
7
10
  limit: number;
8
11
  who: string;
12
+ assumed: boolean;
9
13
  };
10
14
  interface Instruction {
11
15
  at: number;
@@ -25,4 +29,5 @@ export declare function pastTheCut(text: string, otherTools: string[], limit: nu
25
29
  export declare function sentInFull(tool: MenuTool, patterns: string[] | undefined): boolean;
26
30
  export declare const buried: Rule;
27
31
  export declare const cut: Rule;
32
+ export declare const lateInstruction: Rule;
28
33
  export {};