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/mcp.d.ts CHANGED
@@ -56,6 +56,16 @@ export declare function folder(baseCwd: string, cwd?: string): {
56
56
  } | {
57
57
  error: string;
58
58
  };
59
+ /**
60
+ * Where save_as may write, or why it can't: a file inside the call's folder (symlinks
61
+ * followed), either new or a toolmenu menu file already. The agent picks the path, so
62
+ * it can't be used to overwrite anything else (a shell profile, a source file).
63
+ */
64
+ export declare function savePath(dir: string, saveAs: string): {
65
+ path: string;
66
+ } | {
67
+ error: string;
68
+ };
59
69
  export declare function build(baseCwd?: string): McpServer;
60
70
  /**
61
71
  * Serve over stdio until the client closes stdin, then stop every run still going.
package/dist/mcp.js CHANGED
@@ -8,15 +8,15 @@
8
8
  * out, or the client closing the connection stops the child and the server it started.
9
9
  */
10
10
  import { spawn, spawnSync } from 'node:child_process';
11
- import { statSync } from 'node:fs';
12
- import { isAbsolute, resolve } from 'node:path';
11
+ import { lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
12
+ import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
13
13
  import { fileURLToPath } from 'node:url';
14
14
  import { McpServer } from '@modelcontextprotocol/server';
15
15
  import { serveStdio } from '@modelcontextprotocol/server/stdio';
16
16
  import * as z from 'zod';
17
17
  import { CLIENT_NAMES } from './clients.js';
18
18
  import { VERSION } from './version.js';
19
- import { SECRET_ARGS_ENV } from './mcp-env.js';
19
+ import { ARGS_ENV, SECRET_ARGS_ENV } from './mcp-env.js';
20
20
  export { SECRET_ARGS_ENV };
21
21
  const CLI = fileURLToPath(new URL('./cli.js', import.meta.url));
22
22
  /** A whole run's ceiling. Each request inside it already has the CLI's own --timeout. */
@@ -90,6 +90,7 @@ export function runCli(args, cwd, options = {}) {
90
90
  // were. Neither reaches the server under test: it gets a minimal environment.
91
91
  const env = { ...process.env, NO_COLOR: '1', NODE_NO_WARNINGS: '1' };
92
92
  delete env[SECRET_ARGS_ENV];
93
+ delete env[ARGS_ENV];
93
94
  if (secretArgs.length)
94
95
  env[SECRET_ARGS_ENV] = JSON.stringify(secretArgs);
95
96
  // detached: its own process group (Linux, macOS). On Windows it would open a console
@@ -170,6 +171,16 @@ export function serverArgs(a) {
170
171
  return { error: 'env goes with command: an HTTP server is already running. Use headers for credentials.' };
171
172
  if (!/^https?:\/\//.test(a.url))
172
173
  return { error: `url must be an http(s) URL; got "${a.url}". For a stdio server, give command.` };
174
+ let parsed;
175
+ try {
176
+ parsed = new URL(a.url);
177
+ }
178
+ catch {
179
+ return { error: 'url is not a valid URL. Give a Streamable HTTP endpoint such as https://example.com/mcp.' };
180
+ }
181
+ // Arguments are visible to other local users (ps), so credentials can't ride in the URL.
182
+ if (parsed.username || parsed.password)
183
+ return { error: 'Credentials must be passed using headers, not embedded in the URL: drop the user:password@ part and give e.g. {"Authorization": "Basic ..."} in headers.' };
173
184
  return { before: [a.url], secret: Object.entries(a.headers ?? {}).flatMap(([k, v]) => ['--header', `${k}: ${v}`]), after: [] };
174
185
  }
175
186
  if (a.headers && Object.keys(a.headers).length)
@@ -190,6 +201,53 @@ export function folder(baseCwd, cwd) {
190
201
  }
191
202
  /** A path as an absolute one, so a value starting with "-" can't be read as an option. */
192
203
  const absolute = (dir, path) => (isAbsolute(path) ? path : resolve(dir, path));
204
+ /** Whether `path` is `dir` itself or inside it, by path alone. */
205
+ const inside = (dir, path) => {
206
+ const rel = relative(dir, path);
207
+ return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
208
+ };
209
+ /**
210
+ * Where save_as may write, or why it can't: a file inside the call's folder (symlinks
211
+ * followed), either new or a toolmenu menu file already. The agent picks the path, so
212
+ * it can't be used to overwrite anything else (a shell profile, a source file).
213
+ */
214
+ export function savePath(dir, saveAs) {
215
+ const path = absolute(dir, saveAs);
216
+ const outside = { error: `save_as "${saveAs}" is outside the folder the call runs in (${dir}). Give a path inside it, e.g. new-menu.json.` };
217
+ if (!inside(dir, path))
218
+ return outside;
219
+ let realDir;
220
+ let realParent;
221
+ try {
222
+ realDir = realpathSync(dir);
223
+ realParent = realpathSync(dirname(path));
224
+ }
225
+ catch {
226
+ return { error: `save_as "${saveAs}": the folder ${dirname(path)} doesn't exist.` };
227
+ }
228
+ if (!inside(realDir, realParent))
229
+ return outside;
230
+ let existing;
231
+ try {
232
+ existing = lstatSync(path);
233
+ }
234
+ catch {
235
+ return { path };
236
+ }
237
+ if (existing.isSymbolicLink() || !existing.isFile())
238
+ return { error: `save_as "${saveAs}" is ${existing.isSymbolicLink() ? 'a symbolic link' : 'not a file'}; toolmenu only writes a new file or replaces a menu file.` };
239
+ // A hard link: writing it would rewrite the same file wherever else it's linked.
240
+ if (existing.nlink > 1)
241
+ return { error: `save_as "${saveAs}" is a file with other names (a hard link), so writing it would change it there too. Pick a new name, e.g. new-menu.json.` };
242
+ let menu = false;
243
+ try {
244
+ menu = JSON.parse(readFileSync(path, 'utf8'))?.toolmenu === 1;
245
+ }
246
+ catch {
247
+ // not JSON: not a menu
248
+ }
249
+ return menu ? { path } : { error: `save_as "${saveAs}" already exists and isn't a toolmenu menu file, so it wasn't overwritten. Pick a new name, e.g. new-menu.json.` };
250
+ }
193
251
  const failed = (text) => ({ content: [{ type: 'text', text }], isError: true });
194
252
  export function build(baseCwd = process.cwd()) {
195
253
  const server = new McpServer({ name: 'toolmenu', version: VERSION }, {
@@ -212,21 +270,34 @@ export function build(baseCwd = process.cwd()) {
212
270
  };
213
271
  server.registerTool('snapshot_menu', {
214
272
  description: "Check an MCP server's tool list: start or connect to it, list its tools, and report findings (what agents misread, what breaks clients or prompt caches) and the token cost. " +
215
- 'Writes the menu file only when save_as is given (the baseline for diff_menus).',
273
+ 'A command server is started by running command as given, so only pass a command you would run yourself. ' +
274
+ 'Writes the menu file only when save_as is given (the baseline for diff_menus): a new file inside cwd, or an existing menu file there.',
216
275
  inputSchema: {
217
276
  ...serverShape,
218
- save_as: z.string().optional().describe('Write the menu here (menu.json for a baseline), relative to cwd. Default: not written.'),
277
+ save_as: z.string().optional().describe('Write the menu here (menu.json for a baseline), relative to cwd and inside it: a new file, or a menu file to replace. Default: not written.'),
219
278
  client: z.enum(CLIENT_NAMES).optional().describe('Also check the menu as this client loads it: what it cuts, finds and refuses.'),
220
279
  catalog: z.boolean().optional().describe('Also read the operations behind a search tool or command routers.'),
221
280
  },
222
- annotations: { title: 'Snapshot a server menu', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
223
- }, (a, ctx) => forServer(a, ctx, (dir, s) => [
224
- 'snapshot',
225
- ...s.before,
226
- a.save_as ? `--out=${absolute(dir, a.save_as)}` : '--no-write',
227
- ...(a.client ? [`--client=${a.client}`] : []),
228
- ...(a.catalog ? ['--catalog'] : []),
229
- ]));
281
+ // It runs an arbitrary command: destructive as far as a client deciding what to approve can know.
282
+ annotations: { title: 'Snapshot a server menu', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
283
+ }, (a, ctx) => {
284
+ let out = '--no-write';
285
+ if (a.save_as) {
286
+ const f = folder(baseCwd, a.cwd);
287
+ const p = 'error' in f ? undefined : savePath(f.dir, a.save_as);
288
+ if (p && 'error' in p)
289
+ return failed(p.error);
290
+ if (p)
291
+ out = `--out=${p.path}`;
292
+ }
293
+ return forServer(a, ctx, (_dir, s) => [
294
+ 'snapshot',
295
+ ...s.before,
296
+ out,
297
+ ...(a.client ? [`--client=${a.client}`] : []),
298
+ ...(a.catalog ? ['--catalog'] : []),
299
+ ]);
300
+ });
230
301
  server.registerTool('diff_menus', {
231
302
  description: 'Compare two menu files (from snapshot_menu save_as, or toolmenu snapshot): breaking changes for clients, the token change per conversation, and the version bump it needs. Reads files only.',
232
303
  inputSchema: {
@@ -245,13 +316,13 @@ export function build(baseCwd = process.cwd()) {
245
316
  });
246
317
  server.registerTool('check_session', {
247
318
  description: "Check whether an MCP server's menu changes while an agent works: call its tools marked readOnlyHint whose arguments the schema can fill, list the menu after each call, and report each change with the call that caused it. " +
248
- 'Calls only read-only tools; never one marked openWorldHint unless open_world is set.',
319
+ 'Calls only read-only tools; never one marked openWorldHint unless open_world is set. A command server is started by running command as given, so only pass a command you would run yourself.',
249
320
  inputSchema: {
250
321
  ...serverShape,
251
322
  max_calls: z.number().int().min(1).optional().describe('At most this many calls (default 20).'),
252
323
  open_world: z.boolean().optional().describe('Also call read-only tools marked openWorldHint (web search, fetch): they may cost API credits.'),
253
324
  },
254
- annotations: { title: 'Run a session against a server', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
325
+ annotations: { title: 'Run a session against a server', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
255
326
  }, (a, ctx) => forServer(a, ctx, (_dir, s) => [
256
327
  'session',
257
328
  '--auto',
package/dist/menu.d.ts CHANGED
@@ -12,5 +12,11 @@ export declare function toolTokens(tool: Record<string, unknown>): number;
12
12
  export declare function toolDefinition(tool: MenuTool): Record<string, unknown>;
13
13
  export declare function buildMenu(rawTools: Record<string, unknown>[], server: Menu['server'], listMeta?: Menu['listMeta']): Menu;
14
14
  export declare function eraOf(protocolVersion: string | undefined): Era | undefined;
15
+ /**
16
+ * Where JSON.parse gave up, "at position 12 (line 1 column 13)", or '' when Node didn't
17
+ * say. Never its whole message: Node quotes the text around the error, and the file may
18
+ * be one the user didn't mean to show (a symlink, a path an agent gave).
19
+ */
20
+ export declare function jsonErrorAt(error: unknown): string;
15
21
  /** Read a menu.json written by `toolmenu snapshot`. */
16
22
  export declare function loadMenu(path: string): Promise<Menu>;
package/dist/menu.js CHANGED
@@ -39,6 +39,14 @@ export function eraOf(protocolVersion) {
39
39
  return undefined;
40
40
  return protocolVersion >= '2026-07-28' ? 'modern' : 'legacy';
41
41
  }
42
+ /**
43
+ * Where JSON.parse gave up, "at position 12 (line 1 column 13)", or '' when Node didn't
44
+ * say. Never its whole message: Node quotes the text around the error, and the file may
45
+ * be one the user didn't mean to show (a symlink, a path an agent gave).
46
+ */
47
+ export function jsonErrorAt(error) {
48
+ return /at position \d+(?: \(line \d+ column \d+\))?/.exec(error instanceof Error ? error.message : '')?.[0] ?? '';
49
+ }
42
50
  /** Read a menu.json written by `toolmenu snapshot`. */
43
51
  export async function loadMenu(path) {
44
52
  const { readFile } = await import('node:fs/promises');
@@ -55,7 +63,10 @@ export async function loadMenu(path) {
55
63
  data = JSON.parse(text);
56
64
  }
57
65
  catch (error) {
58
- throw new Error(`${path} isn't valid JSON: ${error instanceof Error ? error.message : String(error)}. If it was cut short or edited by hand, write it again with \`toolmenu snapshot\`.`);
66
+ // Where, not what: Node's message quotes the file's first bytes, and the path may be
67
+ // any file (toolmenu mcp's diff_menus takes one from an agent).
68
+ const at = jsonErrorAt(error);
69
+ throw new Error(`${path} isn't valid JSON${at ? ` (${at})` : ''}. If it was cut short or edited by hand, write it again with \`toolmenu snapshot\`.`);
59
70
  }
60
71
  const menu = data;
61
72
  if (menu?.toolmenu !== 1 || !Array.isArray(menu.tools)) {
package/dist/options.d.ts CHANGED
@@ -5,6 +5,12 @@ export declare const CLI_OPTIONS: {
5
5
  readonly sarif: {
6
6
  readonly type: 'string';
7
7
  };
8
+ readonly junit: {
9
+ readonly type: 'string';
10
+ };
11
+ readonly html: {
12
+ readonly type: 'string';
13
+ };
8
14
  readonly badge: {
9
15
  readonly type: 'string';
10
16
  };
@@ -20,6 +26,10 @@ export declare const CLI_OPTIONS: {
20
26
  readonly concurrency: {
21
27
  readonly type: 'string';
22
28
  };
29
+ readonly 'allow-env': {
30
+ readonly type: 'string';
31
+ readonly multiple: true;
32
+ };
23
33
  readonly 'no-write': {
24
34
  readonly type: 'boolean';
25
35
  };
@@ -147,6 +157,9 @@ export declare const CLI_OPTIONS: {
147
157
  readonly 'open-world': {
148
158
  readonly type: 'boolean';
149
159
  };
160
+ readonly 'call-everything': {
161
+ readonly type: 'boolean';
162
+ };
150
163
  readonly 'max-calls': {
151
164
  readonly type: 'string';
152
165
  };
package/dist/options.js CHANGED
@@ -5,11 +5,14 @@
5
5
  export const CLI_OPTIONS = {
6
6
  out: { type: 'string' },
7
7
  sarif: { type: 'string' },
8
+ junit: { type: 'string' },
9
+ html: { type: 'string' },
8
10
  badge: { type: 'string' },
9
11
  'sarif-menu': { type: 'string' },
10
12
  'out-dir': { type: 'string' },
11
13
  'offline-check': { type: 'boolean' },
12
14
  concurrency: { type: 'string' },
15
+ 'allow-env': { type: 'string', multiple: true },
13
16
  'no-write': { type: 'boolean' },
14
17
  routes: { type: 'string' },
15
18
  config: { type: 'string' },
@@ -51,6 +54,7 @@ export const CLI_OPTIONS = {
51
54
  'with-session': { type: 'boolean' },
52
55
  catalog: { type: 'boolean' },
53
56
  'open-world': { type: 'boolean' },
57
+ 'call-everything': { type: 'boolean' },
54
58
  'max-calls': { type: 'string' },
55
59
  'max-calls-per-unlock': { type: 'string' },
56
60
  'save-scenario': { type: 'string' },
package/dist/report.d.ts CHANGED
@@ -5,9 +5,23 @@ import { type Scenario, type SessionResult } from './session.js';
5
5
  import { type Finding, type Menu, type Severity } from './types.js';
6
6
  export type Format = 'text' | 'json' | 'github' | 'markdown';
7
7
  export declare function counts(findings: Finding[]): Record<Severity, number>;
8
+ /** --client: "as Claude Code: up front ~N tokens (…) · on demand ~M per tool loaded (largest: x, ~K)". */
9
+ export declare function costLine(cost: ClientCost, name?: (tool: string) => string): string;
8
10
  export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string, cost?: ClientCost, notOffered?: string[]): string;
9
11
  export declare function findingLines(findings: Finding[]): string[];
10
12
  export declare function githubLines(findings: Finding[]): string[];
13
+ export declare function signed(n: number): string;
14
+ /** "3 breaking (25 tools) · 2 minor (2 tools) · 11 notice (10 tools)": changes, and the tools they touch. */
15
+ export declare function classLine(d: DiffResult): string;
16
+ /**
17
+ * The version verdict: the bump these changes suggest, then whether the release's
18
+ * bump is enough (and what to release instead), or why it wasn't checked.
19
+ */
20
+ export declare function bumpVerdict(d: DiffResult, md?: boolean): {
21
+ line: string;
22
+ short: boolean;
23
+ };
24
+ export declare function releasePair(d: DiffResult, md?: boolean): string;
11
25
  export declare function formatDiff(d: DiffResult, beforeTools: number, afterTools: number, format: Format): string;
12
26
  export declare function formatHistory(h: HistoryResult, format: Format, outDir: string, csvPath?: string): string;
13
27
  export declare function formatSession(s: SessionResult, format: Format): string;
package/dist/report.js CHANGED
@@ -3,6 +3,7 @@ import { clip, stepLabel, stepsText } from './session.js';
3
3
  import { SEVERITY_RANK } from './types.js';
4
4
  import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
5
5
  import { autoSummary } from './auto.js';
6
+ import { mdCode, mdText, plain } from './sanitize.js';
6
7
  const LABEL = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
7
8
  export function counts(findings) {
8
9
  const c = { error: 0, warn: 0, info: 0 };
@@ -22,10 +23,10 @@ function otherLists(menu) {
22
23
  ].filter(Boolean).join(' · ');
23
24
  }
24
25
  /** --client: "as Claude Code: up front ~N tokens (…) · on demand ~M per tool loaded (largest: x, ~K)". */
25
- function costLine(cost) {
26
+ export function costLine(cost, name = plain) {
26
27
  const parts = [
27
28
  cost.upfront !== undefined ? `up front ~${cost.upfront.toLocaleString('en-US')} tokens${cost.loaded.length ? ` (names, and ${plural(cost.loaded.length, 'tool')} loaded in full)` : ''}` : '',
28
- `on demand ~${cost.perTool.toLocaleString('en-US')} per tool a search loads${cost.largest ? ` (largest: ${cost.largest.tool}, ~${cost.largest.tokens.toLocaleString('en-US')})` : ''}`,
29
+ `on demand ~${cost.perTool.toLocaleString('en-US')} per tool a search loads${cost.largest ? ` (largest: ${name(cost.largest.tool)}, ~${cost.largest.tokens.toLocaleString('en-US')})` : ''}`,
29
30
  ].filter(Boolean);
30
31
  return `as ${cost.label}: ${parts.join(' · ')}`;
31
32
  }
@@ -59,10 +60,10 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
59
60
  if (format === 'markdown') {
60
61
  const s = menu.server;
61
62
  return [
62
- `### toolmenu snapshot: \`${s.name ?? 'server'}\` ${s.version ?? ''}`.trimEnd(),
63
+ `### toolmenu snapshot: ${mdCode(s.name ?? 'server')} ${mdText(s.version ?? '')}`.trimEnd(),
63
64
  '',
64
- `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
65
- ...(cost ? ['', `${costLine(cost)}. _${cost.basis}._`] : []),
65
+ `Protocol ${mdText(s.protocolVersion ?? 'unknown')} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
66
+ ...(cost ? ['', `${costLine(cost, mdCode)}. _${cost.basis}._`] : []),
66
67
  ...(otherLists(menu) ? ['', `Also listed: ${otherLists(menu)}`] : []),
67
68
  '',
68
69
  ...mdFindings(findings),
@@ -71,8 +72,8 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
71
72
  }
72
73
  const s = menu.server;
73
74
  const lines = [
74
- `toolmenu snapshot ${s.name ?? 'unknown server'} ${s.version ?? ''}`.trimEnd(),
75
- ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
75
+ `toolmenu snapshot ${plain(s.name ?? 'unknown server')} ${plain(s.version ?? '')}`.trimEnd(),
76
+ ` protocol ${plain(s.protocolVersion ?? 'unknown')} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
76
77
  ];
77
78
  if (cost)
78
79
  lines.push(` ${costLine(cost)}`, ` ${cost.basis}`);
@@ -98,11 +99,11 @@ export function findingLines(findings) {
98
99
  const lines = [];
99
100
  for (const f of findings) {
100
101
  lines.push(`${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
101
- lines.push(` ${f.message}`);
102
+ lines.push(` ${plain(f.message)}`);
102
103
  for (const d of f.detail ?? [])
103
- lines.push(` ${d}`);
104
+ lines.push(` ${plain(d)}`);
104
105
  if (f.fix)
105
- lines.push(` → Next: ${f.fix}`);
106
+ lines.push(` → Next: ${plain(f.fix)}`);
106
107
  }
107
108
  lines.push(findings.length ? '' : 'No findings.');
108
109
  return lines;
@@ -116,11 +117,12 @@ function summaryLine(findings) {
116
117
  export function githubLines(findings) {
117
118
  return findings.map((f) => {
118
119
  const level = f.severity === 'error' ? 'error' : f.severity === 'warn' ? 'warning' : 'notice';
119
- const body = [f.message, ...(f.detail ?? []), ...(f.fix ? [`→ Next: ${f.fix}`] : [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
120
+ // plain(): a newline in the server's text is shown, not a line of the annotation.
121
+ const body = [f.message, ...(f.detail ?? []), ...(f.fix ? [`→ Next: ${f.fix}`] : [])].map(plain).join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
120
122
  return `::${level} title=toolmenu ${f.rule}${unsureMark(f)}::${body}`;
121
123
  });
122
124
  }
123
- function signed(n) {
125
+ export function signed(n) {
124
126
  return `${n > 0 ? '+' : n < 0 ? '−' : '±'}${Math.abs(n).toLocaleString('en-US')}`;
125
127
  }
126
128
  function tokenSentence(d) {
@@ -132,7 +134,7 @@ function tokenSentence(d) {
132
134
  return 'no change in menu size';
133
135
  }
134
136
  /** "3 breaking (25 tools) · 2 minor (2 tools) · 11 notice (10 tools)": changes, and the tools they touch. */
135
- function classLine(d) {
137
+ export function classLine(d) {
136
138
  const part = (c) => {
137
139
  const { changes, tools } = d.classes[c];
138
140
  return `${changes} ${c}${changes && tools ? ` (${plural(tools, 'tool')})` : ''}`;
@@ -143,22 +145,25 @@ function classLine(d) {
143
145
  * The version verdict: the bump these changes suggest, then whether the release's
144
146
  * bump is enough (and what to release instead), or why it wasn't checked.
145
147
  */
146
- function bumpVerdict(d, md = false) {
148
+ export function bumpVerdict(d, md = false) {
147
149
  const b = (s) => (md ? `**${s}**` : s);
150
+ /** A version, as given: from --release or the server. */
151
+ const v = (s) => (md ? mdText(s) : plain(s));
148
152
  const suggested = `suggested bump: ${b(d.suggestedBump)}`;
149
153
  if (!d.actualBump || !d.release)
150
154
  return { line: `${suggested} · not checked (${d.bumpNotChecked ?? 'pass --release old..new'})`, short: false };
151
- const pair = `${d.release.before} → ${d.release.after} is a ${d.actualBump} bump`;
155
+ const pair = `${v(d.release.before)} → ${v(d.release.after)} is a ${d.actualBump} bump`;
152
156
  const required = d.requiredBump ?? d.suggestedBump;
153
157
  const below1 = required !== d.suggestedBump ? ` (under 1.0.0 ${required === 'none' ? 'anything goes' : `a ${required} is enough`})` : '';
154
158
  const rank = { none: 0, patch: 1, minor: 2, major: 3 };
155
159
  if (rank[d.actualBump] >= rank[required])
156
160
  return { line: `${suggested} · ${pair}: enough${below1}`, short: false };
157
- return { line: `${suggested} · ${pair}: ${b(`too small, release ${d.releaseAs ?? `a ${required}`}`)}${below1}`, short: true };
161
+ return { line: `${suggested} · ${pair}: ${b(`too small, release ${d.releaseAs ? v(d.releaseAs) : `a ${required}`}`)}${below1}`, short: true };
158
162
  }
159
- function releasePair(d) {
163
+ export function releasePair(d, md = false) {
164
+ const v = (s) => (md ? mdText(s) : plain(s));
160
165
  // Name the release versions when there are some; otherwise say whose version this is.
161
- return d.release?.source === 'release' ? `${d.release.before} → ${d.release.after}` : `${d.before.version ?? '?'} → ${d.after.version ?? '?'} (server-reported)`;
166
+ return d.release?.source === 'release' ? `${v(d.release.before)} → ${v(d.release.after)}` : `${v(d.before.version ?? '?')} → ${v(d.after.version ?? '?')} (server-reported)`;
162
167
  }
163
168
  export function formatDiff(d, beforeTools, afterTools, format) {
164
169
  if (format === 'json') {
@@ -169,12 +174,12 @@ export function formatDiff(d, beforeTools, afterTools, format) {
169
174
  const verdict = bumpVerdict(d);
170
175
  const tokenLine = `~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')} (${signed(d.tokens.delta)}, estimate): ${tokenSentence(d)}`;
171
176
  if (format === 'github') {
172
- return [...githubLines(d.findings), `::notice title=toolmenu diff::${name} ${pair}. Changes: ${classLine(d)}. Tokens: ${tokenLine}. Version: ${verdict.line}.`].join('\n');
177
+ return [...githubLines(d.findings), `::notice title=toolmenu diff::${ghEscape(`${name} ${pair}. Changes: ${classLine(d)}. Tokens: ${tokenLine}. Version: ${verdict.line}.`)}`].join('\n');
173
178
  }
174
179
  if (format === 'markdown')
175
180
  return mdDiff(d, beforeTools, afterTools);
176
181
  const lines = [
177
- `toolmenu diff ${name} ${pair}`,
182
+ `toolmenu diff ${plain(name)} ${pair}`,
178
183
  ` changes ${classLine(d)}`,
179
184
  ` version ${verdict.line}`,
180
185
  ` tokens ${tokenLine}`,
@@ -185,7 +190,7 @@ export function formatDiff(d, beforeTools, afterTools, format) {
185
190
  if (d.tokens.tools.length) {
186
191
  lines.push('Token change by tool (estimate):');
187
192
  for (const t of d.tokens.tools.slice(0, 10))
188
- lines.push(` ${signed(t.delta).padStart(7)} ${t.name}`);
193
+ lines.push(` ${signed(t.delta).padStart(7)} ${plain(t.name)}`);
189
194
  if (d.tokens.tools.length > 10)
190
195
  lines.push(` …and ${d.tokens.tools.length - 10} more`);
191
196
  lines.push('');
@@ -205,7 +210,7 @@ function mdDiff(d, beforeTools, afterTools) {
205
210
  `**${signed(d.tokens.delta)} tokens** (~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')}, estimate)`,
206
211
  `${beforeTools} → ${afterTools} tools`,
207
212
  ].join(' · ');
208
- const lines = [`### toolmenu diff: \`${name}\` ${releasePair(d)}`, '', headline, '', `> **Version:** ${verdict.line}`, ''];
213
+ const lines = [`### toolmenu diff: ${mdCode(name)} ${releasePair(d, true)}`, '', headline, '', `> **Version:** ${verdict.line}`, ''];
209
214
  if (d.tokens.delta !== 0)
210
215
  lines.splice(lines.length - 1, 0, '>', `> **Tokens:** ${tokenSentence(d)}.`);
211
216
  const table = (findings) => ['| | Rule | Change |', '|---|---|---|', ...findings.map(mdDiffRow)];
@@ -230,7 +235,7 @@ function mdDiff(d, beforeTools, afterTools) {
230
235
  if (d.tokens.tools.length) {
231
236
  lines.push('<details><summary>Token change by tool (estimate)</summary>', '', '| Tool | Before | After | Change |', '|---|---:|---:|---:|');
232
237
  for (const t of d.tokens.tools.slice(0, 30))
233
- lines.push(`| \`${t.name}\` | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
238
+ lines.push(`| ${mdCode(t.name, { cell: true })} | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
234
239
  if (d.tokens.tools.length > 30)
235
240
  lines.push(`| …and ${d.tokens.tools.length - 30} more | | | |`);
236
241
  lines.push('', '</details>', '');
@@ -244,7 +249,7 @@ function mdDiffRow(f) {
244
249
  const list = /^(tools|operations|moved): (.*)$/.exec(line);
245
250
  if (list)
246
251
  return `<details><summary>all ${list[2].split(', ').length} ${list[1] === 'moved' ? 'moved tools' : list[1]}</summary>${mdCell(list[2])}</details>`;
247
- return `<br><sub>${mdCell(line).replace(/</g, '&lt;')}</sub>`;
252
+ return `<br><sub>${mdCell(line)}</sub>`;
248
253
  });
249
254
  const sev = f.severity === 'error' ? '**error**' : f.severity;
250
255
  return `| ${sev} | \`${f.rule}\`${f.confidence === 'unsure' ? ' · _unsure_' : ''} | ${mdCell(f.message)}${detail.join('')}${f.fix ? `<br>**→ Next:** ${mdCell(f.fix)}` : ''} |`;
@@ -291,7 +296,7 @@ export function formatHistory(h, format, outDir, csvPath) {
291
296
  : [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)];
292
297
  if (format === 'markdown') {
293
298
  const lines = [
294
- `### toolmenu history: \`${h.package}\``,
299
+ `### toolmenu history: ${mdCode(h.package)}`,
295
300
  '',
296
301
  `${scope.charAt(0).toUpperCase()}${scope.slice(1)}.`,
297
302
  '',
@@ -303,23 +308,23 @@ export function formatHistory(h, format, outDir, csvPath) {
303
308
  lines.push('', '**Breaking changes**', '');
304
309
  for (const r of breaking) {
305
310
  for (const m of r.diff.breakingChanges.slice(0, BREAKING_SHOWN))
306
- lines.push(`- \`${r.version}\` (vs ${r.diff.from}): ${mdCell(m)}`);
311
+ lines.push(`- ${mdCode(r.version)} (vs ${mdText(r.diff.from)}): ${mdCell(m)}`);
307
312
  if (r.diff.breakingChanges.length > BREAKING_SHOWN)
308
- lines.push(`- \`${r.version}\`: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
313
+ lines.push(`- ${mdCode(r.version)}: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
309
314
  }
310
315
  }
311
316
  if (failed.length) {
312
317
  lines.push('', `**Failed** (${failed.length} of ${h.rows.length})`, '');
313
318
  for (const g of failureGroups(failed, failure))
314
- lines.push(`- \`${g.versions}\` · ${g.row.reason}${g.row.confidence === 'unsure' ? ' · _unsure_' : ''}: ${mdCell(g.message)}${g.fix ? `<br>**→ Next:** ${mdCell(g.fix)}` : ''}`);
319
+ lines.push(`- ${mdCode(g.versions)} · ${g.row.reason}${g.row.confidence === 'unsure' ? ' · _unsure_' : ''}: ${mdCell(g.message)}${g.fix ? `<br>**→ Next:** ${mdCell(g.fix)}` : ''}`);
315
320
  }
316
321
  lines.push('', `**${summary}**`, '', `<sub>${saved.charAt(0).toUpperCase()}${saved.slice(1)}.</sub>`);
317
322
  return lines.join('\n');
318
323
  }
319
- const table = [head, ...h.rows.map(cells)];
324
+ const table = [head, ...h.rows.map((r) => cells(r).map(plain))];
320
325
  const widths = table[0].map((_, c) => Math.max(...table.map((row) => row[c].length)));
321
326
  const lines = [
322
- `toolmenu history ${h.package}`,
327
+ `toolmenu history ${plain(h.package)}`,
323
328
  ` ${scope}`,
324
329
  '',
325
330
  ...table.map((row) => ' ' + row.map((cell, c) => cell.padEnd(widths[c])).join(' ').trimEnd()),
@@ -329,19 +334,19 @@ export function formatHistory(h, format, outDir, csvPath) {
329
334
  lines.push('Breaking changes:');
330
335
  for (const r of breaking) {
331
336
  for (const m of r.diff.breakingChanges.slice(0, BREAKING_SHOWN))
332
- lines.push(` ${r.version} (vs ${r.diff.from}): ${m}`);
337
+ lines.push(` ${plain(r.version)} (vs ${plain(r.diff.from)}): ${plain(m)}`);
333
338
  if (r.diff.breakingChanges.length > BREAKING_SHOWN)
334
- lines.push(` ${r.version}: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
339
+ lines.push(` ${plain(r.version)}: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
335
340
  }
336
341
  lines.push('');
337
342
  }
338
343
  if (failed.length) {
339
344
  lines.push(`Failed (${failed.length} of ${h.rows.length}):`);
340
345
  for (const g of failureGroups(failed, failure)) {
341
- lines.push(` ${g.versions} ${g.row.reason}${g.row.confidence === 'unsure' ? ' · unsure' : ''}`);
342
- lines.push(` ${g.message}`);
346
+ lines.push(` ${plain(g.versions)} ${g.row.reason}${g.row.confidence === 'unsure' ? ' · unsure' : ''}`);
347
+ lines.push(` ${plain(g.message)}`);
343
348
  if (g.fix)
344
- lines.push(` → Next: ${g.fix}`);
349
+ lines.push(` → Next: ${plain(g.fix)}`);
345
350
  }
346
351
  lines.push('');
347
352
  }
@@ -374,7 +379,7 @@ function failureGroups(failed, failure) {
374
379
  });
375
380
  }
376
381
  function ghEscape(text) {
377
- return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
382
+ return plain(text).replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
378
383
  }
379
384
  export function formatSession(s, format) {
380
385
  if (format === 'json') {
@@ -387,17 +392,17 @@ export function formatSession(s, format) {
387
392
  }
388
393
  if (format === 'markdown') {
389
394
  const lines = [
390
- `### toolmenu session: \`${s.scenario}\``,
395
+ `### toolmenu session: ${mdCode(s.scenario)}`,
391
396
  '',
392
- `\`${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)`,
397
+ `${mdCode(s.server.name ?? 'server')} ${mdText(s.server.version ?? '')} · protocol ${mdText(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)`,
393
398
  '',
394
- ...(s.auto ? [...autoSummary(s.auto).map((l, i) => (i === 0 ? `**${l.replace(/^auto: /, 'auto:** ')}` : `- ${l.trim()}`)), ''] : []),
399
+ ...(s.auto ? [...autoSummary(s.auto).map((l, i) => (i === 0 ? `**auto:** ${mdText(l.replace(/^auto: /, ''))}` : `- ${mdText(l.trim())}`)), ''] : []),
395
400
  ...(callCounts(s) ? [`**Calls:** ${callCounts(s)}`, ''] : []),
396
401
  ...(menuChange(s) ? [`**Menu:** ${menuChange(s)}`, ''] : []),
397
402
  ...causes(s.findings, (count, f, where, text) => count ? `**${count}:**` : `- ${f.severity === 'error' ? '**ERROR**' : LABEL[f.severity].trim()} \`${f.rule}\` · ${where} · ${mdCell(text)}`),
398
403
  '| Step | Menu | list_changed | Scope |',
399
404
  '|---|---|---|---|',
400
- ...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 ?? ''} |`),
405
+ ...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**') : ''} | ${mdCell(st.scope ?? '')} |`),
401
406
  '',
402
407
  ...mdFindings(s.findings.map((f) => ({ ...f, message: stepPrefix(f, `Step ${f.step}: `) }))),
403
408
  ];
@@ -405,26 +410,26 @@ export function formatSession(s, format) {
405
410
  }
406
411
  const tok = (n) => `~${n.toLocaleString('en-US')}`;
407
412
  const lines = [
408
- `toolmenu session ${s.scenario}`,
409
- ` ${s.server.name ?? 'server'} ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport}`,
413
+ `toolmenu session ${plain(s.scenario)}`,
414
+ ` ${plain(s.server.name ?? 'server')} ${plain(s.server.version ?? '')} · protocol ${plain(s.server.protocolVersion ?? '?')} · ${s.transport}`,
410
415
  ` baseline: ${plural(s.baseline.tools, 'tool')} · ${tok(s.baseline.tokens)} tokens (estimate) · listening for list_changed: ${s.listening ? 'yes' : 'no'}`,
411
- ...(s.auto ? autoSummary(s.auto).map((l, i) => (i === 0 ? ` ${l}` : ` ${l}`)) : []),
416
+ ...(s.auto ? autoSummary(s.auto).map((l, i) => (i === 0 ? ` ${plain(l)}` : ` ${plain(l)}`)) : []),
412
417
  ...(callCounts(s) ? [` calls: ${callCounts(s)}`] : []),
413
418
  // Before the first step only: what a fresh one sees after a change is each step's scope.
414
419
  ` fresh-${s.transport === 'stdio' ? 'process' : 'connection'} check of the starting menu: ${s.connectionCheck === undefined ? 'not checked' : s.connectionCheck === 'same' ? 'the same' : 'DIFFERENT'}`,
415
420
  '',
416
421
  ...(menuChange(s) ? [`menu: ${menuChange(s)}`] : []),
417
- ...causes(s.findings, (count, f, where, text) => (count ? `${count}:` : ` ${LABEL[f.severity]} ${f.rule} · ${where} · ${text}`)),
422
+ ...causes(s.findings, (count, f, where, text) => (count ? `${count}:` : ` ${LABEL[f.severity]} ${f.rule} · ${where} · ${plain(text)}`)),
418
423
  ];
419
424
  const at = (step) => s.findings.filter((f) => f.step === step);
420
425
  const block = (findings) => {
421
426
  for (const f of findings) {
422
427
  lines.push(` ${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
423
- lines.push(` ${f.message}`);
428
+ lines.push(` ${plain(f.message)}`);
424
429
  for (const d of f.detail ?? [])
425
- lines.push(` ${d}`);
430
+ lines.push(` ${plain(d)}`);
426
431
  if (f.fix)
427
- lines.push(` → Next: ${f.fix}`);
432
+ lines.push(` → Next: ${plain(f.fix)}`);
428
433
  }
429
434
  };
430
435
  block(at(0));
@@ -441,9 +446,9 @@ export function formatSession(s, format) {
441
446
  step.changed ? `menu changed${delta ? ` · ${delta > 0 ? '+' : '−'}${plural(Math.abs(delta), 'tool')}` : ''}` : step.status === 'ok' ? 'no change' : '',
442
447
  step.changed ? (step.listChanged ? 'list_changed received' : 'no list_changed') : '',
443
448
  step.scope ? `scope: ${step.scope}` : '',
444
- step.note ?? '',
449
+ plain(step.note ?? ''),
445
450
  ].filter(Boolean);
446
- lines.push(`step ${step.index}: ${step.label} · ${facts.join(' · ')}`);
451
+ lines.push(`step ${step.index}: ${plain(step.label)} · ${facts.join(' · ')}`);
447
452
  block(at(step.index));
448
453
  }
449
454
  // Findings about the whole run (session/untested), after the steps.
@@ -524,7 +529,7 @@ function callCounts(s) {
524
529
  }
525
530
  export function formatPlan(scenario, name) {
526
531
  const lines = [`toolmenu session --plan ${name}`, ` allow_writes: ${scenario.allowWrites}${scenario.allowWrites ? '' : ' (tools not marked readOnlyHint will be refused)'}`, ''];
527
- scenario.steps.forEach((step, i) => lines.push(`step ${i + 1}: ${stepLabel(step)}${step.kind === 'wait_for' ? ` (up to ${step.timeoutMs} ms)` : ''}`));
532
+ scenario.steps.forEach((step, i) => lines.push(`step ${i + 1}: ${plain(stepLabel(step))}${step.kind === 'wait_for' ? ` (up to ${step.timeoutMs} ms)` : ''}`));
528
533
  lines.push('', 'After every step the menu is listed and compared with the one before. Nothing was run.');
529
534
  return lines.join('\n');
530
535
  }
@@ -538,8 +543,9 @@ function stepPrefix(f, prefix) {
538
543
  return f.message;
539
544
  return prefix + f.message;
540
545
  }
546
+ /** Text in a table cell: escaped (sanitize.ts), so a server's words stay words. */
541
547
  function mdCell(text) {
542
- return text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
548
+ return mdText(text, { cell: true });
543
549
  }
544
550
  export function mdFindings(findings) {
545
551
  if (findings.length === 0)