toolmenu 0.25.2 → 0.27.1

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 (60) hide show
  1. package/README.md +170 -683
  2. package/dist/args.d.ts +14 -2
  3. package/dist/args.js +44 -1
  4. package/dist/auth-check.d.ts +27 -0
  5. package/dist/auth-check.js +177 -0
  6. package/dist/auth.d.ts +7 -0
  7. package/dist/auth.js +29 -1
  8. package/dist/auto.d.ts +8 -0
  9. package/dist/auto.js +9 -2
  10. package/dist/breakdown.js +14 -10
  11. package/dist/cli.js +151 -49
  12. package/dist/clients.d.ts +13 -2
  13. package/dist/clients.js +65 -11
  14. package/dist/config.js +6 -0
  15. package/dist/diff.d.ts +35 -1
  16. package/dist/diff.js +57 -12
  17. package/dist/failures.js +4 -3
  18. package/dist/help.d.ts +1 -1
  19. package/dist/help.js +45 -18
  20. package/dist/history.js +5 -0
  21. package/dist/html.d.ts +29 -0
  22. package/dist/html.js +360 -0
  23. package/dist/index.d.ts +3 -2
  24. package/dist/index.js +3 -2
  25. package/dist/init.d.ts +14 -0
  26. package/dist/init.js +20 -6
  27. package/dist/junit.d.ts +6 -1
  28. package/dist/junit.js +12 -3
  29. package/dist/mcp-env.d.ts +6 -0
  30. package/dist/mcp-env.js +6 -0
  31. package/dist/mcp.d.ts +11 -1
  32. package/dist/mcp.js +123 -22
  33. package/dist/menu.d.ts +6 -0
  34. package/dist/menu.js +12 -1
  35. package/dist/options.d.ts +10 -0
  36. package/dist/options.js +3 -0
  37. package/dist/report.d.ts +14 -0
  38. package/dist/report.js +57 -51
  39. package/dist/review.d.ts +48 -0
  40. package/dist/review.js +212 -0
  41. package/dist/rule-docs.json +49 -4
  42. package/dist/rules/clients.d.ts +11 -0
  43. package/dist/rules/clients.js +65 -2
  44. package/dist/rules/determinism.d.ts +3 -0
  45. package/dist/rules/determinism.js +44 -7
  46. package/dist/rules/ids.js +5 -1
  47. package/dist/rules/index.js +5 -2
  48. package/dist/rules/output.d.ts +21 -0
  49. package/dist/rules/output.js +49 -0
  50. package/dist/rules/search.js +1 -1
  51. package/dist/rules/spec.d.ts +19 -0
  52. package/dist/rules/spec.js +86 -1
  53. package/dist/sanitize.d.ts +42 -0
  54. package/dist/sanitize.js +142 -0
  55. package/dist/scan.d.ts +9 -2
  56. package/dist/scan.js +46 -24
  57. package/dist/session.d.ts +17 -0
  58. package/dist/session.js +119 -13
  59. package/dist/snapshot.js +2 -1
  60. package/package.json +5 -3
package/dist/cli.js CHANGED
@@ -7,9 +7,12 @@ import { CLIENT_NAMES, CLIENTS } from './clients.js';
7
7
  import { LIST_WORDS } from './lists.js';
8
8
  import { loadConfig } from './config.js';
9
9
  import { ELICITATIONS, PROTOCOLS } from './connect.js';
10
- import { diffMenus } from './diff.js';
10
+ import { comparedTools, diffMenus } from './diff.js';
11
+ import { formatReview, reviewMenus } from './review.js';
12
+ import { authCheck } from './auth-check.js';
11
13
  import { loadMenu } from './menu.js';
12
14
  import { history, historyCsv } from './history.js';
15
+ import { findingLines } from './report.js';
13
16
  import { counts, formatDiff, formatHistory, formatPlan, formatSession, formatSnapshot } from './report.js';
14
17
  import { loadScenario, session, starterScenario, unlockListers, valuesFromListing } from './session.js';
15
18
  import { listTools, quietExclusions } from './connect.js';
@@ -25,9 +28,11 @@ import { existingMessage, initReport, planInit, shellWord, writeInit } from './i
25
28
  import { SEVERITY_RANK } from './types.js';
26
29
  import { toSarif } from './sarif.js';
27
30
  import { toJunit } from './junit.js';
31
+ import { diffHtml, sessionHtml, snapshotHtml } from './html.js';
28
32
  import { badge, badgeMarkdown } from './badge.js';
29
33
  import { VERSION } from './version.js';
30
- import { SECRET_ARGS_ENV } from './mcp-env.js';
34
+ import { ARGS_ENV, SECRET_ARGS_ENV } from './mcp-env.js';
35
+ import { guardStream, plain, terminalSafe, writeUnguarded } from './sanitize.js';
31
36
  import { CLI_OPTIONS } from './options.js';
32
37
  import { editDistance } from './words.js';
33
38
  import { formatScan, ListError, loadList, scan, scanExit } from './scan.js';
@@ -95,11 +100,19 @@ export async function main(given) {
95
100
  throw new UsageError('SARIF needs findings: --plan and --init run nothing.');
96
101
  if (sub === 'session' && (values.plan || values.init) && (asked === 'junit' || values.junit !== undefined))
97
102
  throw new UsageError('JUnit needs findings: --plan and --init run nothing.');
103
+ if (values.html !== undefined && !fileCommands.includes(sub))
104
+ throw new UsageError(`The HTML report (--html) goes with snapshot, diff or session; ${sub} has none.`);
105
+ if (sub === 'session' && (values.plan || values.init) && values.html !== undefined)
106
+ throw new UsageError('The HTML report needs a run: --plan and --init run nothing.');
98
107
  const sarifToStdout = asked === 'sarif';
99
108
  const junitToStdout = asked === 'junit';
100
109
  const format = (sarifToStdout || junitToStdout ? 'text' : asked);
101
- /** Print the report, or the SARIF / JUnit file with --format sarif|junit; write --sarif's and --junit's files too. */
102
- const emit = async (report, findings, command, menuPath) => {
110
+ /** session --html: the menu after each step, for the page only. */
111
+ const stepMenus = new Map();
112
+ /** Print the report, or the SARIF / JUnit file with --format sarif|junit; write --sarif's, --junit's and --html's files too. */
113
+ const emit = async (report, findings, command, menuPath, html) => {
114
+ if (values.html !== undefined && html)
115
+ await writeFile(values.html, html());
103
116
  const menu = values['sarif-menu'] ?? menuPath;
104
117
  const sarif = values.sarif !== undefined || sarifToStdout ? toSarif(findings, { command, menuPath: menu }) + '\n' : undefined;
105
118
  // session's menuPath is where SARIF points, not what it checked (a live server): no target there.
@@ -110,23 +123,28 @@ export async function main(given) {
110
123
  await writeFile(values.junit, junit);
111
124
  if (sarifToStdout)
112
125
  process.stdout.write(sarif);
126
+ // JUnit is XML, escaped its own way; the report is already safe, its colour toolmenu's.
113
127
  else if (junitToStdout)
114
- process.stdout.write(junit);
128
+ writeUnguarded(process.stdout, junit);
115
129
  else if (report)
116
- process.stdout.write(show(report) + '\n');
130
+ writeUnguarded(process.stdout, show(report) + '\n');
117
131
  };
118
132
  // Colour for a report read in a terminal (colour.ts); piped, CI and other formats stay plain.
119
- const show = (report) => (format === 'text' && colourFor(process.stdout) ? colourise(report) : report);
133
+ // terminalSafe first: a control character a server's text still carries is shown, never acted on. JSON escapes its own.
134
+ const show = (report) => {
135
+ // JSON too: JSON.stringify leaves bidi and other format characters raw, and the
136
+ // escapes terminalSafe writes read back as the same characters.
137
+ const safe = terminalSafe(report);
138
+ if (format === 'json')
139
+ return safe;
140
+ return format === 'text' && colourFor(process.stdout) ? colourise(safe) : safe;
141
+ };
120
142
  const failOn = (values['fail-on'] ?? 'error');
121
143
  if (!(failOn in SEVERITY_RANK))
122
144
  throw new UsageError(`--fail-on must be error, warn or info`);
123
145
  const timeoutMs = values.timeout ? Number(values.timeout) : 30_000;
124
146
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
125
147
  throw new UsageError(`--timeout must be a positive number of milliseconds`);
126
- if (sub === 'auth')
127
- return authCommand(rest, values);
128
- if (sub === 'explain')
129
- return explainCommand(rest, command, format);
130
148
  if (sub === 'mcp') {
131
149
  if (command || rest.length)
132
150
  throw new UsageError('mcp takes no server: it is one. Add it to a client as: npx -y toolmenu mcp');
@@ -135,6 +153,38 @@ export async function main(given) {
135
153
  await serveMcp();
136
154
  return 0;
137
155
  }
156
+ // Every command's output, whatever writes it: a server's text that reaches a line
157
+ // some report forgot is shown as escapes, never acted on by the terminal. Not toolmenu
158
+ // mcp's stdout above: that's the protocol.
159
+ guardStream(process.stdout);
160
+ guardStream(process.stderr);
161
+ if (sub === 'auth' && rest[0] === 'check') {
162
+ if (rest.length !== 2)
163
+ throw new UsageError('auth check needs one server URL: toolmenu auth check https://example.com/mcp');
164
+ if (!/^https:\/\//.test(rest[1]))
165
+ throw new UsageError(`"${rest[1]}" isn't an https URL.`);
166
+ const checked = await authCheck(rest[1], timeoutMs);
167
+ if (format === 'json')
168
+ writeUnguarded(process.stdout, show(JSON.stringify({ command: 'auth check', ...checked }, null, 2)) + '\n');
169
+ else {
170
+ const lines = [
171
+ `toolmenu auth check ${plain(checked.url)}`,
172
+ ` without credentials HTTP ${checked.status ?? '?'}${checked.wwwAuthenticate ? ` · WWW-Authenticate: ${plain(checked.wwwAuthenticate).slice(0, 120)}` : ''}`,
173
+ ...(checked.metadataUrl ? [` resource metadata ${plain(checked.metadataUrl)} (${checked.foundBy})`] : []),
174
+ ...(checked.authorizationServers?.length ? [` authorization ${checked.authorizationServers.map(plain).join(', ')}`] : []),
175
+ ...(checked.serverMetadataUrl ? [` server metadata ${plain(checked.serverMetadataUrl)} · PKCE ${checked.pkce?.join(', ') ?? 'not listed'} · registration ${checked.registration}`] : []),
176
+ '',
177
+ ...findingLines(checked.findings),
178
+ checked.findings.some((f) => f.severity !== 'info') ? '' : '✓ discovery works the way the spec says',
179
+ ];
180
+ writeUnguarded(process.stdout, show(lines.filter((l, i, a) => l !== '' || a[i - 1] !== '').join('\n')) + '\n');
181
+ }
182
+ return checked.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
183
+ }
184
+ if (sub === 'auth')
185
+ return authCommand(rest, values);
186
+ if (sub === 'explain')
187
+ return explainCommand(rest, command, format);
138
188
  // The invocation up to the server, for examples in messages: a session example
139
189
  // without --auto or --scenario wouldn't run.
140
190
  const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
@@ -176,9 +226,14 @@ export async function main(given) {
176
226
  const concurrency = values.concurrency !== undefined ? Number(values.concurrency) : 4;
177
227
  if (!Number.isInteger(concurrency) || concurrency < 1)
178
228
  throw new UsageError('--concurrency must be a whole number, 1 or more');
229
+ const names = (values['allow-env'] ?? []).flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean);
230
+ const bad = names.find((n) => n !== '*' && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(n));
231
+ if (bad)
232
+ throw new UsageError(`--allow-env takes environment variable names, comma-separated, or '*' for all; "${bad}" isn't one.`);
233
+ const allow = names.includes('*') ? '*' : new Set(names);
179
234
  let entries;
180
235
  try {
181
- entries = await loadList(rest[0]);
236
+ entries = await loadList(rest[0], allow);
182
237
  }
183
238
  catch (error) {
184
239
  if (error instanceof ListError)
@@ -208,16 +263,16 @@ export async function main(given) {
208
263
  ...(config.offlineCheck ? { offlineCheck: true } : {}),
209
264
  onDone: (row, done, total) => {
210
265
  if (tty)
211
- process.stderr.write(`\r\x1b[K ${done}/${total} ${row.name}`);
266
+ writeUnguarded(process.stderr, `\r\x1b[K ${done}/${total} ${plain(row.name)}`);
212
267
  },
213
268
  });
214
269
  if (tty)
215
- process.stderr.write('\r\x1b[K');
270
+ writeUnguarded(process.stderr, '\r\x1b[K');
216
271
  if (outDir)
217
272
  for (const r of rows)
218
273
  if (r.menu)
219
274
  await writeFile(join(outDir, `${r.name.replace(/[^\w.@-]+/g, '_')}.json`), JSON.stringify(r.menu, null, 2) + '\n');
220
- process.stdout.write(show(formatScan(rows, format, rest[0])) + '\n');
275
+ writeUnguarded(process.stdout, show(formatScan(rows, format, rest[0])) + '\n');
221
276
  return scanExit(rows, failOn);
222
277
  }
223
278
  if (sub === 'diff') {
@@ -234,9 +289,28 @@ export async function main(given) {
234
289
  release,
235
290
  serverVersionIsRelease: values['server-version-is-release'] ?? config.serverVersionIsRelease,
236
291
  });
237
- await emit(formatDiff(result, before.tools.length, after.tools.length, format), result.findings, 'diff', rest[1]);
292
+ await emit(formatDiff(result, before.tools.length, after.tools.length, format), result.findings, 'diff', rest[1], () => diffHtml(result, comparedTools(before, after, config.ignore), { paths: [rest[0], rest[1]] }));
238
293
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
239
294
  }
295
+ if (sub === 'review') {
296
+ if (command)
297
+ throw new UsageError("review compares two menu files; it doesn't start a server. Run snapshot first.");
298
+ if (rest.length !== 2)
299
+ throw new UsageError('review needs the baseline and the new menu file: toolmenu review <baseline.json> <new.json>');
300
+ if (format === 'github')
301
+ throw new UsageError('review prints text, markdown or json.');
302
+ const [before, after] = await Promise.all(rest.map((path) => loadMenu(path)));
303
+ const result = reviewMenus(before, after, {
304
+ rules: config.rules,
305
+ ignore: config.ignore,
306
+ tokenBudget: config.tokenBudget,
307
+ release: values.release ? parseRelease(values.release) : undefined,
308
+ serverVersionIsRelease: values['server-version-is-release'] ?? config.serverVersionIsRelease,
309
+ failOn,
310
+ });
311
+ writeUnguarded(process.stdout, show(formatReview(result, [rest[0], rest[1]], format, failOn)) + '\n');
312
+ return result.accept ? 0 : 1;
313
+ }
240
314
  if (sub === 'history') {
241
315
  if (command)
242
316
  throw new UsageError('history takes an npm package name, not a command. Use --cmd for unusual entry points.');
@@ -267,7 +341,7 @@ export async function main(given) {
267
341
  });
268
342
  if (values.csv)
269
343
  await writeFile(values.csv, historyCsv(result));
270
- process.stdout.write(show(formatHistory(result, format, outDir, values.csv)) + '\n');
344
+ writeUnguarded(process.stdout, show(formatHistory(result, format, outDir, values.csv)) + '\n');
271
345
  return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
272
346
  }
273
347
  if (sub === 'session' && values.init) {
@@ -289,7 +363,7 @@ export async function main(given) {
289
363
  const found = result.isError ? [] : valuesFromListing(result);
290
364
  if (found.length) {
291
365
  unlockValues[unlock] = found;
292
- read.push(`${found.length} values for ${unlock} from ${lister}`);
366
+ read.push(`${found.length} values for ${plain(unlock)} from ${plain(lister)}`);
293
367
  }
294
368
  }
295
369
  catch {
@@ -311,7 +385,7 @@ export async function main(given) {
311
385
  throw new UsageError(existingMessage(plan));
312
386
  const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions, ...(config.offlineCheck && target.kind === 'stdio' ? { offlineCheck: true } : {}) });
313
387
  await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
314
- process.stdout.write(initReport(plan, { server: menu.server.name, version: menu.server.version, tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
388
+ process.stdout.write(initReport(plan, { server: menu.server.name === undefined ? undefined : plain(menu.server.name), version: menu.server.version === undefined ? undefined : plain(menu.server.version), tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
315
389
  return 0;
316
390
  }
317
391
  if (sub === 'session' && values.auto) {
@@ -342,26 +416,32 @@ export async function main(given) {
342
416
  throw new UsageError(error instanceof Error ? error.message : String(error));
343
417
  }
344
418
  const autoTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
419
+ // Every tool, writes included: only where nothing real can be changed. A hosted
420
+ // server's tools act on someone's real account or system.
421
+ if (values['call-everything'] && autoTarget.kind !== 'stdio') {
422
+ throw new UsageError('--call-everything calls every tool, writes included, so it only runs a local stdio server (in a sandbox with nothing to lose: no credentials, no network). Over HTTP, --auto calls the read-only tools.');
423
+ }
345
424
  const waited = { ms: 0 };
346
425
  const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
347
426
  throw refusedForTooMany(error, waited.ms);
348
427
  });
349
- const options = { openWorld: values['open-world'], createHandles: values['create-handles'], values: given, assumeReadOnly };
350
- let plan = autoScenario(menu, { ...options, maxCalls: givenMax ?? 20 });
428
+ const everything = values['call-everything'] === true;
429
+ const options = { openWorld: values['open-world'], createHandles: values['create-handles'], values: given, assumeReadOnly, everything };
430
+ let plan = autoScenario(menu, { ...options, maxCalls: givenMax ?? (everything ? Infinity : 20) });
351
431
  // Each unlock value gets its own budget for the tools it brings, so the first
352
432
  // toolsets can't use up the calls the last ones need. --max-calls, when given,
353
433
  // caps every call, and the starting menu leaves up to half of it for the unlocks.
354
434
  const reserve = givenMax === undefined ? 0 : Math.min(perUnlock * plan.unlockValues, Math.floor(givenMax / 2));
355
435
  if (reserve)
356
436
  plan = autoScenario(menu, { ...options, maxCalls: givenMax - reserve });
357
- const maxCalls = givenMax ?? 20 + perUnlock * plan.unlockValues;
437
+ const maxCalls = givenMax ?? (everything ? Infinity : 20 + perUnlock * plan.unlockValues);
358
438
  if (savePath)
359
439
  await writeFile(savePath, scenarioYaml(plan, menu.server.name));
360
440
  if (values.plan) {
361
441
  process.stdout.write(formatPlan(plan.scenario, 'auto') + '\n');
362
442
  return 0;
363
443
  }
364
- const auto = { called: plan.called, skipped: plan.skipped, assumed: plan.assumed, withValues: plan.withValues, ignored: plan.ignored, maxCalls, maxCallsPerUnlock: perUnlock };
444
+ const auto = { called: plan.called, skipped: plan.skipped, assumed: plan.assumed, withValues: plan.withValues, ignored: plan.ignored, maxCalls, maxCallsPerUnlock: perUnlock, ...(everything ? { everything } : {}) };
365
445
  // Tools that appear mid-session (behind an unlock) are planned when they appear,
366
446
  // under the same rules and what's left of --max-calls. Each tool once.
367
447
  const planned = new Set([...plan.called, ...plan.skipped.map((s) => s.tool)]);
@@ -373,7 +453,7 @@ export async function main(given) {
373
453
  if (!fresh.length)
374
454
  return [];
375
455
  const left = maxCalls - spent;
376
- const more = autoScenario({ ...menu, tools: fresh }, { ...options, maxCalls: Math.min(perUnlock, left), callsOnly: true });
456
+ const more = autoScenario({ ...menu, tools: fresh }, { ...options, maxCalls: everything ? left : Math.min(perUnlock, left), callsOnly: true });
377
457
  // Left out by this unlock's own budget, not by the total: say which, for the right flag.
378
458
  if (perUnlock < left)
379
459
  for (const s of more.skipped)
@@ -388,21 +468,21 @@ export async function main(given) {
388
468
  plan.scenario.assumeReadOnly = [...(plan.scenario.assumeReadOnly ?? []), ...more.assumed];
389
469
  return more.scenario.steps;
390
470
  };
391
- const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto, replan });
471
+ const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto, replan, onStepMenu: values.html !== undefined ? (step, menu) => stepMenus.set(step, menu) : undefined });
392
472
  // A --value or --assume-read-only for a tool behind an unlock isn't unused: check
393
473
  // them against every tool the session saw, not just the starting menu.
394
474
  auto.ignored = autoScenario(result.union, { values: given, assumeReadOnly }).ignored;
395
475
  result.auto = { ...result.auto, ...auto };
396
476
  if (values['union-out'])
397
477
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
398
- await emit(formatSession(result, format), result.findings, 'session', values['union-out'] ?? (existsSync('menu.json') ? 'menu.json' : undefined));
478
+ await emit(formatSession(result, format), result.findings, 'session', values['union-out'] ?? (existsSync('menu.json') ? 'menu.json' : undefined), () => sessionHtml(result, stepMenus));
399
479
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
400
480
  }
401
481
  if (sub === 'session') {
402
482
  if (values.value || values['values-file'] || values['assume-read-only'])
403
483
  throw new UsageError('--value, --values-file and --assume-read-only go with --auto. In a scenario, write the values into the steps\' args, and list tools under assume_read_only.');
404
484
  if (!values.scenario)
405
- throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu#session-the-menu-changing-while-the-agent-works for the format.');
485
+ throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu/blob/main/docs/session.md for the format.');
406
486
  let scenario;
407
487
  try {
408
488
  scenario = await loadScenario(values.scenario);
@@ -415,10 +495,10 @@ export async function main(given) {
415
495
  return 0;
416
496
  }
417
497
  const sessionTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
418
- const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
498
+ const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'], onStepMenu: values.html !== undefined ? (step, menu) => stepMenus.set(step, menu) : undefined });
419
499
  if (values['union-out'])
420
500
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
421
- await emit(formatSession(result, format), result.findings, 'session', values['union-out'] ?? (existsSync('menu.json') ? 'menu.json' : undefined));
501
+ await emit(formatSession(result, format), result.findings, 'session', values['union-out'] ?? (existsSync('menu.json') ? 'menu.json' : undefined), () => sessionHtml(result, stepMenus));
422
502
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
423
503
  }
424
504
  const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
@@ -433,7 +513,7 @@ export async function main(given) {
433
513
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
434
514
  if (outPath)
435
515
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
436
- await emit(formatSnapshot(menu, findings, format, outPath, cost, notOffered), findings, 'snapshot', outPath);
516
+ await emit(formatSnapshot(menu, findings, format, outPath, cost, notOffered), findings, 'snapshot', outPath, () => snapshotHtml(menu, findings, { transport: target.kind, cost, notOffered, outPath }));
437
517
  if (values.badge !== undefined) {
438
518
  await writeFile(values.badge, JSON.stringify(badge(menu, findings), null, 2) + '\n');
439
519
  // stderr: stdout stays the report (or the JSON/SARIF a script parses).
@@ -469,7 +549,7 @@ async function authCommand(args, values) {
469
549
  return 0;
470
550
  }
471
551
  if (action !== 'login' && action !== 'logout')
472
- throw new UsageError(`${action ? `auth has no action "${action}"` : 'auth needs an action'}: login <url>, logout <url> or list. See toolmenu auth --help.`);
552
+ throw new UsageError(`${action ? `auth has no action "${action}"` : 'auth needs an action'}: login <url>, logout <url>, check <url> or list. See toolmenu auth --help.`);
473
553
  if (!url || extra.length)
474
554
  throw new UsageError(`auth ${action} needs one server URL: toolmenu auth ${action} https://example.com/mcp`);
475
555
  if (!/^https?:\/\//.test(url))
@@ -484,7 +564,7 @@ async function authCommand(args, values) {
484
564
  if (values['client-secret'] && !values['client-id'])
485
565
  throw new UsageError('--client-secret goes with --client-id');
486
566
  const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'], noBrowser: values['no-browser'] });
487
- process.stdout.write(`Logged in to ${result.name ?? url} (${url}): it lists ${result.tools} tool${result.tools === 1 ? '' : 's'} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`);
567
+ process.stdout.write(`Logged in to ${plain(result.name ?? url)} (${url}): it lists ${result.tools} tool${result.tools === 1 ? '' : 's'} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`);
488
568
  return 0;
489
569
  }
490
570
  /**
@@ -553,8 +633,9 @@ for (const method of ['log', 'info', 'debug']) {
553
633
  console[method] = (...args) => console.error(...args);
554
634
  }
555
635
  main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
556
- const message = `toolmenu: ${failureMessage(error)}`;
557
- process.stderr.write(`${colourFor(process.stderr) ? colouriseError(message) : message}\n`);
636
+ // An error can quote what a server said: shown, never acted on by the terminal.
637
+ const message = terminalSafe(`toolmenu: ${failureMessage(error)}`);
638
+ writeUnguarded(process.stderr, `${colourFor(process.stderr) ? colouriseError(message) : message}\n`);
558
639
  exitWhenFlushed(2);
559
640
  });
560
641
  function explainCommand(rest, command, format) {
@@ -612,24 +693,45 @@ function commandIn(args) {
612
693
  return undefined;
613
694
  }
614
695
  /**
615
- * toolmenu mcp passes header and env values (credentials) in TOOLMENU_MCP_ARGS, a JSON
616
- * array of arguments, not on the command line: argv is readable by any local user.
617
- * They go before the server command's "--". Removed from the environment once read.
696
+ * Arguments the CLI takes from the environment, each a JSON array of arguments that
697
+ * goes before the server command's "--": TOOLMENU_ARGS, for anyone who'd rather keep
698
+ * --header, --env or --client-secret values off the command line (argv is readable by
699
+ * any local user), and TOOLMENU_MCP_ARGS, which toolmenu mcp passes credentials in.
700
+ * Each is removed from the environment once read.
618
701
  */
619
702
  function withSecretArgs(argv) {
620
- const raw = process.env[SECRET_ARGS_ENV];
621
- if (raw === undefined)
622
- return argv;
623
- delete process.env[SECRET_ARGS_ENV];
624
- let extra;
625
- try {
626
- extra = JSON.parse(raw);
627
- }
628
- catch {
629
- extra = undefined;
703
+ const extra = [];
704
+ for (const name of [ARGS_ENV, SECRET_ARGS_ENV]) {
705
+ const raw = process.env[name];
706
+ if (raw === undefined)
707
+ continue;
708
+ delete process.env[name];
709
+ let parsed;
710
+ try {
711
+ parsed = JSON.parse(raw);
712
+ }
713
+ catch {
714
+ parsed = undefined;
715
+ }
716
+ if (!Array.isArray(parsed) || !parsed.every((a) => typeof a === 'string'))
717
+ throw new UsageError(`${name} must be a JSON array of strings, e.g. ["--header", "Authorization: Bearer …"].`);
718
+ // Options and their values only: no "--" (it would move where the server command
719
+ // starts) and no stray word, which parseArgs would quote back, value and all.
720
+ for (let i = 0; i < parsed.length; i++) {
721
+ const option = /^--([^=]+)(=|$)/.exec(parsed[i]);
722
+ const known = option ? CLI_OPTIONS[option[1]] : undefined;
723
+ if (!option || !known)
724
+ throw new UsageError(`${name} holds only toolmenu options and their values; item ${i + 1} isn't one${option ? ` (--${option[1]} isn't an option)` : ''}.`);
725
+ if (known.type === 'string' && option[2] !== '=') {
726
+ if (i + 1 >= parsed.length)
727
+ throw new UsageError(`${name}: --${option[1]} needs a value after it.`);
728
+ i++;
729
+ }
730
+ }
731
+ extra.push(...parsed);
630
732
  }
631
- if (!Array.isArray(extra) || !extra.every((a) => typeof a === 'string'))
632
- throw new UsageError(`${SECRET_ARGS_ENV} must be a JSON array of strings.`);
733
+ if (!extra.length)
734
+ return argv;
633
735
  const dash = argv.indexOf('--');
634
736
  return dash === -1 ? [...argv, ...extra] : [...argv.slice(0, dash), ...extra, ...argv.slice(dash)];
635
737
  }
package/dist/clients.d.ts CHANGED
@@ -11,8 +11,9 @@ export interface ClientProfile {
11
11
  /**
12
12
  * Whether MCP tools are deferred behind a tool search: `all` (every tool unless
13
13
  * marked to load up front), `chosen` (the integrator marks each tool), or `none`.
14
+ * Absent where the client's docs don't say.
14
15
  */
15
- defers: Sourced<'all' | 'chosen' | 'none'>;
16
+ defers?: Sourced<'all' | 'chosen' | 'none'>;
16
17
  /** What the model has of a deferred tool before it searches: its name, or nothing. */
17
18
  /**
18
19
  * What the model has of a deferred tool before it searches: its name, nothing, or its
@@ -30,12 +31,22 @@ export interface ClientProfile {
30
31
  searchFields?: Sourced<string[]>;
31
32
  /** How many tools a search returns unless the model asks for more. */
32
33
  searchLimit?: Sourced<number>;
33
- /** Tool names the API accepts. */
34
+ /**
35
+ * Tool names the API accepts. `rewrites`: the client changes a name outside the
36
+ * pattern (replaces characters, cuts it) instead of sending it and being refused.
37
+ */
34
38
  namePattern?: Sourced<{
35
39
  pattern: string;
36
40
  max: number;
37
41
  api: string;
42
+ rewrites?: string;
38
43
  }>;
44
+ /** The most tools the client sends the model at once. */
45
+ toolLimit?: Sourced<number>;
46
+ /** What the client leaves out of what a server offers, in its docs' words. */
47
+ toolsOnly?: Sourced<string>;
48
+ /** The client calls only tools marked readOnlyHint: true. */
49
+ readOnlyOnly?: Sourced<string>;
39
50
  /** Advice on which tools to keep loaded up front. */
40
51
  keepLoaded?: Sourced<string>;
41
52
  }
package/dist/clients.js CHANGED
@@ -11,6 +11,14 @@ const CLAUDE_DEFINE_TOOLS = 'https://platform.claude.com/docs/en/agents-and-tool
11
11
  const OPENAI_SPEC = 'https://github.com/openai/openai-openapi (openapi.yaml: FunctionToolParam, NamespaceToolParam, MCPTool)';
12
12
  const OPENAI_TOOL_SEARCH = 'https://developers.openai.com/api/docs/guides/tools-tool-search';
13
13
  const READ = '2026-11-02';
14
+ const VSCODE_TOOLS = 'https://code.visualstudio.com/docs/agents/run/tools';
15
+ const COPILOT_CLOUD = 'https://docs.github.com/en/copilot/concepts/agents/cloud-agent/mcp-and-cloud-agent';
16
+ const GEMINI_CLI_MCP = 'https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md';
17
+ const GEMINI_API = 'https://ai.google.dev/api/caching#FunctionDeclaration';
18
+ const ANTIGRAVITY_MCP = 'https://antigravity.google/docs/mcp';
19
+ const READ_2 = '2026-11-09';
20
+ const geminiName = { pattern: '^[a-zA-Z0-9_.:-]+$' };
21
+ const openaiName = { pattern: '^[a-zA-Z0-9_-]+$', max: 128 };
14
22
  const claudeName = { value: { pattern: '^[a-zA-Z0-9_-]{1,128}$', max: 128, api: 'the Claude API' }, source: CLAUDE_DEFINE_TOOLS, read: READ };
15
23
  export const CLIENTS = {
16
24
  'claude-code': {
@@ -50,7 +58,48 @@ export const CLIENTS = {
50
58
  // Not in the guide or the spec: how many tools a search returns, and which fields it matches on.
51
59
  // So search/findable doesn't rank for OpenAI.
52
60
  // FunctionToolParam.name: maxLength 128, pattern ^[a-zA-Z0-9_-]+$.
53
- namePattern: { value: { pattern: '^[a-zA-Z0-9_-]+$', max: 128, api: "OpenAI's Responses API" }, source: OPENAI_SPEC, read: READ },
61
+ namePattern: { value: { ...openaiName, api: "OpenAI's Responses API" }, source: OPENAI_SPEC, read: READ },
62
+ },
63
+ codex: {
64
+ label: 'Codex',
65
+ // Codex sends tools to OpenAI's Responses API: FunctionToolParam.name, ^[a-zA-Z0-9_-]+$, maxLength 128.
66
+ // Its MCP docs don't say whether it defers tools or what it does with a name outside that.
67
+ namePattern: { value: { ...openaiName, api: "OpenAI's Responses API, which Codex sends tools to" }, source: OPENAI_SPEC, read: READ_2 },
68
+ },
69
+ vscode: {
70
+ label: 'VS Code (GitHub Copilot Chat)',
71
+ // "A chat request can have a maximum of 128 tools enabled at a time."
72
+ toolLimit: { value: 128, source: VSCODE_TOOLS, read: READ_2 },
73
+ },
74
+ 'copilot-cloud-agent': {
75
+ label: 'GitHub Copilot cloud agent',
76
+ // "Copilot cloud agent and Copilot code review only support MCP tools. They do not currently support resources or prompts provided by the MCP server."
77
+ toolsOnly: { value: 'resources and prompts', source: COPILOT_CLOUD, read: READ_2 },
78
+ },
79
+ 'copilot-code-review': {
80
+ label: 'GitHub Copilot code review',
81
+ toolsOnly: { value: 'resources and prompts', source: COPILOT_CLOUD, read: READ_2 },
82
+ // "Copilot code review additionally requires tools to declare annotations.readOnlyHint: true."
83
+ readOnlyOnly: { value: 'annotations.readOnlyHint: true', source: COPILOT_CLOUD, read: READ_2 },
84
+ },
85
+ 'gemini-cli': {
86
+ label: 'Gemini CLI',
87
+ // "Characters other than letters, numbers, underscore (_), hyphen (-), dot (.), colon (:) are replaced with underscores";
88
+ // "Names longer than 63 characters are truncated with middle replacement".
89
+ namePattern: { value: { ...geminiName, max: 63, api: 'Gemini CLI', rewrites: 'replaces other characters with underscores and cuts longer names in the middle' }, source: GEMINI_CLI_MCP, read: READ_2 },
90
+ },
91
+ 'gemini-api': {
92
+ label: 'the Gemini API',
93
+ // FunctionDeclaration.name: "Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128."
94
+ namePattern: { value: { ...geminiName, max: 128, api: "the Gemini API's FunctionDeclaration.name" }, source: GEMINI_API, read: READ_2 },
95
+ },
96
+ antigravity: {
97
+ label: 'Antigravity',
98
+ // Lazy loading is the default: the system prompt lists each server's tool names, and the agent reads a
99
+ // tool's schema file before calling it. The user marks a tool "eager": true to register it in full.
100
+ defers: { value: 'chosen', source: ANTIGRAVITY_MCP, read: READ_2 },
101
+ beforeSearch: { value: 'name', source: ANTIGRAVITY_MCP, read: READ_2 },
102
+ keepLoaded: { value: 'Mark only frequently used core tools "eager": true: an eager tool\'s full schema is sent every turn.', source: ANTIGRAVITY_MCP, read: READ_2 },
54
103
  },
55
104
  };
56
105
  export const CLIENT_NAMES = Object.keys(CLIENTS);
@@ -75,8 +124,11 @@ export function nameProblem(name, profile) {
75
124
  if (name.length > rule.max)
76
125
  return `${name.length} characters, over ${rule.max}`;
77
126
  if (!new RegExp(rule.pattern).test(name)) {
78
- const bad = [...new Set([...name].filter((c) => !/[a-zA-Z0-9_-]/.test(c)))];
79
- return `has ${bad.map((c) => (c === ' ' ? 'a space' : `"${c}"`)).join(', ')}, outside letters, digits, _ and -`;
127
+ const cls = rule.pattern.match(/\[([^\]]+)\]/)?.[1] ?? 'a-zA-Z0-9_-';
128
+ const ok = new RegExp(`[${cls}]`);
129
+ const bad = [...new Set([...name].filter((c) => !ok.test(c)))];
130
+ const allowed = cls.includes('.') ? 'letters, digits, _, -, . and :' : 'letters, digits, _ and -';
131
+ return `has ${bad.map((c) => (c === ' ' ? 'a space' : `"${c}"`)).join(', ')}, outside ${allowed}`;
80
132
  }
81
133
  return undefined;
82
134
  }
@@ -87,7 +139,7 @@ export function loadsUpfront(tool) {
87
139
  /** What the menu costs under a client that defers tools: up front, and per tool a search loads. */
88
140
  export function clientCost(name, menu) {
89
141
  const profile = profileOf(name);
90
- if (!profile || profile.defers.value === 'none')
142
+ if (!profile?.defers || profile.defers.value === 'none')
91
143
  return undefined;
92
144
  const loaded = profile.defers.value === 'all' ? menu.tools.filter(loadsUpfront) : [];
93
145
  const deferred = menu.tools.filter((t) => !loaded.includes(t));
@@ -103,13 +155,15 @@ export function clientCost(name, menu) {
103
155
  ? deferred.reduce((n, t) => n + seenUpfront(t), 0) + loadedTokens
104
156
  : undefined;
105
157
  const onDemand = (t) => (seen === 'name-and-description' ? Math.max(0, t.tokens - seenUpfront(t)) : t.tokens);
106
- const basis = seen === 'name'
107
- ? `${profile.label} defers MCP tools and shows their names until a search loads one; the server's instructions load up front too and aren't counted here (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
108
- : seen === 'nothing'
109
- ? `with every tool deferred, the model sees none of them until a search loads one, and the docs advise keeping the 3–5 tools used most loaded (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
110
- : seen === 'name-and-description'
111
- ? `deferred as functions, each tool's name and description stay up front and its schema loads on demand; deferred as one MCP server, the model sees only the server's name and description (set where the server is added) until a search loads its tools (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
112
- : `${profile.label} defers per function or per MCP server; what the model sees before a search isn't documented, so no up-front figure`;
158
+ const basis = seen === 'name' && name === 'antigravity'
159
+ ? `${profile.label} lists each MCP tool's name and loads a tool's schema when the agent reads it; tools the user marks "eager" load in full and aren't counted here (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
160
+ : seen === 'name'
161
+ ? `${profile.label} defers MCP tools and shows their names until a search loads one; the server's instructions load up front too and aren't counted here (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
162
+ : seen === 'nothing'
163
+ ? `with every tool deferred, the model sees none of them until a search loads one, and the docs advise keeping the 3–5 tools used most loaded (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
164
+ : seen === 'name-and-description'
165
+ ? `deferred as functions, each tool's name and description stay up front and its schema loads on demand; deferred as one MCP server, the model sees only the server's name and description (set where the server is added) until a search loads its tools (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
166
+ : `${profile.label} defers per function or per MCP server; what the model sees before a search isn't documented, so no up-front figure`;
113
167
  const perTool = deferred.length ? Math.round(deferred.reduce((n, t) => n + onDemand(t), 0) / deferred.length) : 0;
114
168
  const biggest = [...deferred].sort((a, b) => onDemand(b) - onDemand(a))[0];
115
169
  const largest = biggest ? { name: biggest.name, tokens: onDemand(biggest) } : undefined;
package/dist/config.js CHANGED
@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
3
3
  import { CLIENTS } from './clients.js';
4
4
  import { LIST_WORDS } from './lists.js';
5
5
  import { CLIENT_LIMITS } from './rules/description.js';
6
+ import { jsonErrorAt } from './menu.js';
6
7
  const DEFAULT_PATH = 'toolmenu.config.json';
7
8
  /** Optional: no config file is fine. */
8
9
  export async function loadConfig(path) {
@@ -14,6 +15,11 @@ export async function loadConfig(path) {
14
15
  config = JSON.parse(await readFile(file, 'utf8'));
15
16
  }
16
17
  catch (error) {
18
+ // Unreadable: Node's own words (ENOENT…). Not JSON: where, never what it holds.
19
+ if (error instanceof SyntaxError) {
20
+ const at = jsonErrorAt(error);
21
+ throw new Error(`${file} isn't valid JSON${at ? ` (${at})` : ''}.`);
22
+ }
17
23
  throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
18
24
  }
19
25
  for (const [id, value] of Object.entries(config.rules ?? {})) {
package/dist/diff.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Finding, JsonSchema, Menu, Severity } from './types.js';
1
+ import type { Finding, JsonSchema, Menu, MenuTool, Severity } from './types.js';
2
2
  export type ChangeClass = 'breaking' | 'minor' | 'notice';
3
3
  export type Bump = 'major' | 'minor' | 'patch' | 'none';
4
4
  export interface DiffFinding extends Finding {
@@ -18,6 +18,27 @@ interface DiffRule {
18
18
  }
19
19
  /** Every diff rule, its default severity and what it means for semver. */
20
20
  export declare const DIFF_RULES: Record<string, DiffRule>;
21
+ /** The tools a diff compares, after the ignore globs, and how they changed by name. */
22
+ export interface DiffTools {
23
+ before: MenuTool[];
24
+ after: MenuTool[];
25
+ /** Each of `after`'s position in the newer menu as served, ignored tools included. */
26
+ positions: number[];
27
+ /** How many tools of the newer menu the ignore globs left out. */
28
+ ignored: number;
29
+ added: string[];
30
+ removed: string[];
31
+ renamed: {
32
+ from: string;
33
+ to: string;
34
+ }[];
35
+ }
36
+ /**
37
+ * The tools diffMenus compares and how they changed: ignored tools leave the
38
+ * comparison entirely, so they can't pair into a rename or show up as a reorder.
39
+ * The HTML report shows the same.
40
+ */
41
+ export declare function comparedTools(before: Menu, after: Menu, ignore?: string[]): DiffTools;
21
42
  export interface TokenChange {
22
43
  before: number;
23
44
  after: number;
@@ -78,6 +99,19 @@ export interface DiffOptions {
78
99
  serverVersionIsRelease?: boolean;
79
100
  }
80
101
  export declare function diffMenus(before: Menu, after: Menu, options?: DiffOptions): DiffResult;
102
+ /**
103
+ * One schema against its next version, anywhere in a tool: its type, allowed
104
+ * values and description; array items, object fields and union options, each
105
+ * compared the same way; and whatever's left, as one "review it". `at` is its
106
+ * path, and the path nested fields hang off: `gen.rows[]` for array items,
107
+ * `gen.block(kind="text")` for a union option.
108
+ */
109
+ /**
110
+ * A schema as an object. JSON Schema allows `true` (anything) and `false` (nothing)
111
+ * as a whole schema (`"items": true`, figma-mcp-rs); a broken server may send null or
112
+ * a string. Those are wrapped, not dropped, so a change to them still shows.
113
+ */
114
+ export declare function asSchema(node: unknown): JsonSchema;
81
115
  /**
82
116
  * The schema with local $refs (`#/$defs/…`, `#/definitions/…`) replaced by what
83
117
  * they point to, and the root $defs dropped: two spellings of one schema compare