toolmenu 0.25.1 → 0.27.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 (62) hide show
  1. package/README.md +312 -35
  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 +171 -56
  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 -17
  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 +17 -0
  28. package/dist/junit.js +87 -0
  29. package/dist/mcp-env.d.ts +6 -0
  30. package/dist/mcp-env.js +6 -0
  31. package/dist/mcp.d.ts +10 -0
  32. package/dist/mcp.js +86 -15
  33. package/dist/menu.d.ts +6 -0
  34. package/dist/menu.js +12 -1
  35. package/dist/options.d.ts +13 -0
  36. package/dist/options.js +4 -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/sarif.d.ts +2 -0
  56. package/dist/sarif.js +2 -2
  57. package/dist/scan.d.ts +9 -2
  58. package/dist/scan.js +46 -24
  59. package/dist/session.d.ts +17 -0
  60. package/dist/session.js +119 -13
  61. package/dist/snapshot.js +2 -1
  62. 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';
@@ -24,9 +27,12 @@ import { authDir, listLogins, login, logout } from './auth.js';
24
27
  import { existingMessage, initReport, planInit, shellWord, writeInit } from './init.js';
25
28
  import { SEVERITY_RANK } from './types.js';
26
29
  import { toSarif } from './sarif.js';
30
+ import { toJunit } from './junit.js';
31
+ import { diffHtml, sessionHtml, snapshotHtml } from './html.js';
27
32
  import { badge, badgeMarkdown } from './badge.js';
28
33
  import { VERSION } from './version.js';
29
- 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';
30
36
  import { CLI_OPTIONS } from './options.js';
31
37
  import { editDistance } from './words.js';
32
38
  import { formatScan, ListError, loadList, scan, scanExit } from './scan.js';
@@ -81,39 +87,64 @@ export async function main(given) {
81
87
  process.stderr.write(`toolmenu: ${sub} ignores ${stray.join(', ')}: ${one ? 'it is' : 'they are'} for other commands.\n → Next: Leave ${one ? 'it' : 'them'} out to silence this; toolmenu ${sub} --help lists the options ${sub} takes.\n`);
82
88
  }
83
89
  const asked = values.json ? 'json' : values.format ?? 'text';
84
- if (!['text', 'json', 'github', 'markdown', 'sarif'].includes(asked))
85
- throw new UsageError(`--format must be text, json, github, markdown or sarif`);
86
- // SARIF is a findings file for code scanning: --format sarif prints it instead of the
87
- // report, --sarif <path> writes it beside the report.
88
- const sarifCommands = ['snapshot', 'diff', 'session'];
89
- if ((asked === 'sarif' || values.sarif !== undefined || values['sarif-menu'] !== undefined) && !sarifCommands.includes(sub))
90
+ if (!['text', 'json', 'github', 'markdown', 'sarif', 'junit'].includes(asked))
91
+ throw new UsageError(`--format must be text, json, github, markdown, sarif or junit`);
92
+ // SARIF and JUnit are findings files, for code scanning and CI test reports: --format
93
+ // sarif|junit prints one instead of the report, --sarif / --junit <path> writes it beside the report.
94
+ const fileCommands = ['snapshot', 'diff', 'session'];
95
+ if ((asked === 'sarif' || values.sarif !== undefined || values['sarif-menu'] !== undefined) && !fileCommands.includes(sub))
90
96
  throw new UsageError(`SARIF output (--format sarif, --sarif, --sarif-menu) goes with snapshot, diff or session; ${sub} has none.`);
97
+ if ((asked === 'junit' || values.junit !== undefined) && !fileCommands.includes(sub))
98
+ throw new UsageError(`JUnit output (--format junit, --junit) goes with snapshot, diff or session; ${sub} has none.`);
91
99
  if (sub === 'session' && (values.plan || values.init) && (asked === 'sarif' || values.sarif !== undefined))
92
100
  throw new UsageError('SARIF needs findings: --plan and --init run nothing.');
101
+ if (sub === 'session' && (values.plan || values.init) && (asked === 'junit' || values.junit !== undefined))
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.');
93
107
  const sarifToStdout = asked === 'sarif';
94
- const format = (sarifToStdout ? 'text' : asked);
95
- /** Print the report, or the SARIF log with --format sarif; write --sarif's file too. */
96
- const emit = async (report, findings, command, menuPath) => {
108
+ const junitToStdout = asked === 'junit';
109
+ const format = (sarifToStdout || junitToStdout ? 'text' : asked);
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());
97
116
  const menu = values['sarif-menu'] ?? menuPath;
117
+ const sarif = values.sarif !== undefined || sarifToStdout ? toSarif(findings, { command, menuPath: menu }) + '\n' : undefined;
118
+ // session's menuPath is where SARIF points, not what it checked (a live server): no target there.
119
+ const junit = values.junit !== undefined || junitToStdout ? toJunit(findings, { command, failOn, target: command === 'session' ? undefined : menuPath }) + '\n' : undefined;
98
120
  if (values.sarif !== undefined)
99
- await writeFile(values.sarif, toSarif(findings, { command, menuPath: menu }) + '\n');
121
+ await writeFile(values.sarif, sarif);
122
+ if (values.junit !== undefined)
123
+ await writeFile(values.junit, junit);
100
124
  if (sarifToStdout)
101
- process.stdout.write(toSarif(findings, { command, menuPath: menu }) + '\n');
125
+ process.stdout.write(sarif);
126
+ // JUnit is XML, escaped its own way; the report is already safe, its colour toolmenu's.
127
+ else if (junitToStdout)
128
+ writeUnguarded(process.stdout, junit);
102
129
  else if (report)
103
- process.stdout.write(show(report) + '\n');
130
+ writeUnguarded(process.stdout, show(report) + '\n');
104
131
  };
105
132
  // Colour for a report read in a terminal (colour.ts); piped, CI and other formats stay plain.
106
- 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
+ };
107
142
  const failOn = (values['fail-on'] ?? 'error');
108
143
  if (!(failOn in SEVERITY_RANK))
109
144
  throw new UsageError(`--fail-on must be error, warn or info`);
110
145
  const timeoutMs = values.timeout ? Number(values.timeout) : 30_000;
111
146
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
112
147
  throw new UsageError(`--timeout must be a positive number of milliseconds`);
113
- if (sub === 'auth')
114
- return authCommand(rest, values);
115
- if (sub === 'explain')
116
- return explainCommand(rest, command, format);
117
148
  if (sub === 'mcp') {
118
149
  if (command || rest.length)
119
150
  throw new UsageError('mcp takes no server: it is one. Add it to a client as: npx -y toolmenu mcp');
@@ -122,6 +153,38 @@ export async function main(given) {
122
153
  await serveMcp();
123
154
  return 0;
124
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);
125
188
  // The invocation up to the server, for examples in messages: a session example
126
189
  // without --auto or --scenario wouldn't run.
127
190
  const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
@@ -163,9 +226,14 @@ export async function main(given) {
163
226
  const concurrency = values.concurrency !== undefined ? Number(values.concurrency) : 4;
164
227
  if (!Number.isInteger(concurrency) || concurrency < 1)
165
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);
166
234
  let entries;
167
235
  try {
168
- entries = await loadList(rest[0]);
236
+ entries = await loadList(rest[0], allow);
169
237
  }
170
238
  catch (error) {
171
239
  if (error instanceof ListError)
@@ -195,16 +263,16 @@ export async function main(given) {
195
263
  ...(config.offlineCheck ? { offlineCheck: true } : {}),
196
264
  onDone: (row, done, total) => {
197
265
  if (tty)
198
- process.stderr.write(`\r\x1b[K ${done}/${total} ${row.name}`);
266
+ writeUnguarded(process.stderr, `\r\x1b[K ${done}/${total} ${plain(row.name)}`);
199
267
  },
200
268
  });
201
269
  if (tty)
202
- process.stderr.write('\r\x1b[K');
270
+ writeUnguarded(process.stderr, '\r\x1b[K');
203
271
  if (outDir)
204
272
  for (const r of rows)
205
273
  if (r.menu)
206
274
  await writeFile(join(outDir, `${r.name.replace(/[^\w.@-]+/g, '_')}.json`), JSON.stringify(r.menu, null, 2) + '\n');
207
- process.stdout.write(show(formatScan(rows, format, rest[0])) + '\n');
275
+ writeUnguarded(process.stdout, show(formatScan(rows, format, rest[0])) + '\n');
208
276
  return scanExit(rows, failOn);
209
277
  }
210
278
  if (sub === 'diff') {
@@ -221,9 +289,28 @@ export async function main(given) {
221
289
  release,
222
290
  serverVersionIsRelease: values['server-version-is-release'] ?? config.serverVersionIsRelease,
223
291
  });
224
- 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]] }));
225
293
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
226
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
+ }
227
314
  if (sub === 'history') {
228
315
  if (command)
229
316
  throw new UsageError('history takes an npm package name, not a command. Use --cmd for unusual entry points.');
@@ -254,7 +341,7 @@ export async function main(given) {
254
341
  });
255
342
  if (values.csv)
256
343
  await writeFile(values.csv, historyCsv(result));
257
- process.stdout.write(show(formatHistory(result, format, outDir, values.csv)) + '\n');
344
+ writeUnguarded(process.stdout, show(formatHistory(result, format, outDir, values.csv)) + '\n');
258
345
  return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
259
346
  }
260
347
  if (sub === 'session' && values.init) {
@@ -276,7 +363,7 @@ export async function main(given) {
276
363
  const found = result.isError ? [] : valuesFromListing(result);
277
364
  if (found.length) {
278
365
  unlockValues[unlock] = found;
279
- read.push(`${found.length} values for ${unlock} from ${lister}`);
366
+ read.push(`${found.length} values for ${plain(unlock)} from ${plain(lister)}`);
280
367
  }
281
368
  }
282
369
  catch {
@@ -298,7 +385,7 @@ export async function main(given) {
298
385
  throw new UsageError(existingMessage(plan));
299
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 } : {}) });
300
387
  await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
301
- 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));
302
389
  return 0;
303
390
  }
304
391
  if (sub === 'session' && values.auto) {
@@ -329,26 +416,32 @@ export async function main(given) {
329
416
  throw new UsageError(error instanceof Error ? error.message : String(error));
330
417
  }
331
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
+ }
332
424
  const waited = { ms: 0 };
333
425
  const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
334
426
  throw refusedForTooMany(error, waited.ms);
335
427
  });
336
- const options = { openWorld: values['open-world'], createHandles: values['create-handles'], values: given, assumeReadOnly };
337
- 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) });
338
431
  // Each unlock value gets its own budget for the tools it brings, so the first
339
432
  // toolsets can't use up the calls the last ones need. --max-calls, when given,
340
433
  // caps every call, and the starting menu leaves up to half of it for the unlocks.
341
434
  const reserve = givenMax === undefined ? 0 : Math.min(perUnlock * plan.unlockValues, Math.floor(givenMax / 2));
342
435
  if (reserve)
343
436
  plan = autoScenario(menu, { ...options, maxCalls: givenMax - reserve });
344
- const maxCalls = givenMax ?? 20 + perUnlock * plan.unlockValues;
437
+ const maxCalls = givenMax ?? (everything ? Infinity : 20 + perUnlock * plan.unlockValues);
345
438
  if (savePath)
346
439
  await writeFile(savePath, scenarioYaml(plan, menu.server.name));
347
440
  if (values.plan) {
348
441
  process.stdout.write(formatPlan(plan.scenario, 'auto') + '\n');
349
442
  return 0;
350
443
  }
351
- 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 } : {}) };
352
445
  // Tools that appear mid-session (behind an unlock) are planned when they appear,
353
446
  // under the same rules and what's left of --max-calls. Each tool once.
354
447
  const planned = new Set([...plan.called, ...plan.skipped.map((s) => s.tool)]);
@@ -360,7 +453,7 @@ export async function main(given) {
360
453
  if (!fresh.length)
361
454
  return [];
362
455
  const left = maxCalls - spent;
363
- 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 });
364
457
  // Left out by this unlock's own budget, not by the total: say which, for the right flag.
365
458
  if (perUnlock < left)
366
459
  for (const s of more.skipped)
@@ -375,14 +468,14 @@ export async function main(given) {
375
468
  plan.scenario.assumeReadOnly = [...(plan.scenario.assumeReadOnly ?? []), ...more.assumed];
376
469
  return more.scenario.steps;
377
470
  };
378
- 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 });
379
472
  // A --value or --assume-read-only for a tool behind an unlock isn't unused: check
380
473
  // them against every tool the session saw, not just the starting menu.
381
474
  auto.ignored = autoScenario(result.union, { values: given, assumeReadOnly }).ignored;
382
475
  result.auto = { ...result.auto, ...auto };
383
476
  if (values['union-out'])
384
477
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
385
- 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));
386
479
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
387
480
  }
388
481
  if (sub === 'session') {
@@ -402,10 +495,10 @@ export async function main(given) {
402
495
  return 0;
403
496
  }
404
497
  const sessionTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
405
- 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 });
406
499
  if (values['union-out'])
407
500
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
408
- 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));
409
502
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
410
503
  }
411
504
  const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
@@ -420,7 +513,7 @@ export async function main(given) {
420
513
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
421
514
  if (outPath)
422
515
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
423
- 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 }));
424
517
  if (values.badge !== undefined) {
425
518
  await writeFile(values.badge, JSON.stringify(badge(menu, findings), null, 2) + '\n');
426
519
  // stderr: stdout stays the report (or the JSON/SARIF a script parses).
@@ -456,7 +549,7 @@ async function authCommand(args, values) {
456
549
  return 0;
457
550
  }
458
551
  if (action !== 'login' && action !== 'logout')
459
- 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.`);
460
553
  if (!url || extra.length)
461
554
  throw new UsageError(`auth ${action} needs one server URL: toolmenu auth ${action} https://example.com/mcp`);
462
555
  if (!/^https?:\/\//.test(url))
@@ -471,7 +564,7 @@ async function authCommand(args, values) {
471
564
  if (values['client-secret'] && !values['client-id'])
472
565
  throw new UsageError('--client-secret goes with --client-id');
473
566
  const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'], noBrowser: values['no-browser'] });
474
- 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`);
475
568
  return 0;
476
569
  }
477
570
  /**
@@ -540,8 +633,9 @@ for (const method of ['log', 'info', 'debug']) {
540
633
  console[method] = (...args) => console.error(...args);
541
634
  }
542
635
  main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
543
- const message = `toolmenu: ${failureMessage(error)}`;
544
- 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`);
545
639
  exitWhenFlushed(2);
546
640
  });
547
641
  function explainCommand(rest, command, format) {
@@ -599,24 +693,45 @@ function commandIn(args) {
599
693
  return undefined;
600
694
  }
601
695
  /**
602
- * toolmenu mcp passes header and env values (credentials) in TOOLMENU_MCP_ARGS, a JSON
603
- * array of arguments, not on the command line: argv is readable by any local user.
604
- * 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.
605
701
  */
606
702
  function withSecretArgs(argv) {
607
- const raw = process.env[SECRET_ARGS_ENV];
608
- if (raw === undefined)
609
- return argv;
610
- delete process.env[SECRET_ARGS_ENV];
611
- let extra;
612
- try {
613
- extra = JSON.parse(raw);
614
- }
615
- catch {
616
- 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);
617
732
  }
618
- if (!Array.isArray(extra) || !extra.every((a) => typeof a === 'string'))
619
- throw new UsageError(`${SECRET_ARGS_ENV} must be a JSON array of strings.`);
733
+ if (!extra.length)
734
+ return argv;
620
735
  const dash = argv.indexOf('--');
621
736
  return dash === -1 ? [...argv, ...extra] : [...argv.slice(0, dash), ...extra, ...argv.slice(dash)];
622
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 ?? {})) {