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
@@ -0,0 +1,49 @@
1
+ /*
2
+ * session/output-schema: a tool that declares an outputSchema promises its results.
3
+ * 2025-06-18 and later: "If an output schema is provided, servers MUST provide
4
+ * structured results that conform to this schema", and clients SHOULD validate
5
+ * them; the official TypeScript SDK client does, and throws on a result that has no
6
+ * structuredContent or one that doesn't match. Checked on every call that answered
7
+ * (not isError), so it needs a session that calls the tool.
8
+ */
9
+ import { Ajv } from 'ajv';
10
+ import { Ajv2020 } from 'ajv/dist/2020.js';
11
+ import addFormatsImport from 'ajv-formats';
12
+ const addFormats = (addFormatsImport.default ?? addFormatsImport);
13
+ /** The protocol version output schemas came in. */
14
+ export const OUTPUT_SCHEMA_SINCE = '2025-06-18';
15
+ const validators = new WeakMap();
16
+ /**
17
+ * What's wrong with a successful result against the tool's outputSchema, or
18
+ * undefined when it conforms (or the schema can't be compiled: then it's the
19
+ * schema that's broken, which spec/schema reports, not the result).
20
+ */
21
+ export function outputProblem(schema, result) {
22
+ return outputCheck(schema, result)?.problem;
23
+ }
24
+ /**
25
+ * The same, and whether only `format` checks failed (a URI, a date): many validators
26
+ * skip format unless told to, so such a result may well pass a client.
27
+ */
28
+ export function outputCheck(schema, result) {
29
+ if (result.structuredContent === undefined)
30
+ return { problem: 'returned no structuredContent, although the tool declares an outputSchema', formatOnly: false };
31
+ let validate = validators.get(schema);
32
+ if (!validate) {
33
+ const draft2020 = typeof schema.$schema !== 'string' || schema.$schema.includes('2020-12');
34
+ const ajv = draft2020 ? new Ajv2020({ strict: false, allErrors: true }) : new Ajv({ strict: false, allErrors: true });
35
+ addFormats(ajv);
36
+ try {
37
+ validate = ajv.compile(schema);
38
+ }
39
+ catch {
40
+ return undefined;
41
+ }
42
+ validators.set(schema, validate);
43
+ }
44
+ if (validate(result.structuredContent))
45
+ return undefined;
46
+ const all = validate.errors ?? [];
47
+ const errors = all.slice(0, 3).map((e) => `${e.instancePath || '(the result)'} ${e.message ?? 'is invalid'}`);
48
+ return { problem: `returned structuredContent that doesn't match its outputSchema: ${errors.join('; ')}`, formatOnly: all.length > 0 && all.every((e) => e.keyword === 'format') };
49
+ }
@@ -25,7 +25,7 @@ export const findable = {
25
25
  if (profile) {
26
26
  // A client that defers tools does it at any size; one whose search results
27
27
  // aren't documented (OpenAI's spec doesn't say how many) isn't ranked against a guess.
28
- if (profile.defers.value === 'none' || tools.length < 2)
28
+ if (!profile.defers || profile.defers.value === 'none' || tools.length < 2)
29
29
  return [];
30
30
  if (!profile.searchLimit && ctx.client !== 'claude-code')
31
31
  return [];
@@ -4,6 +4,16 @@ export declare function resultValidator(version: string, result?: string): impor
4
4
  export declare const schema: Rule;
5
5
  export declare const toolsCapability: Rule;
6
6
  export declare const duplicateName: Rule;
7
+ /**
8
+ * What's wrong with a tool name, or undefined when it fits the spec's format. `hidden`:
9
+ * it has characters that act on a terminal or can't be seen, so it can pass for
10
+ * another name or for none.
11
+ */
12
+ export declare function toolNameProblem(name: string): {
13
+ why: string;
14
+ hidden: boolean;
15
+ } | undefined;
16
+ export declare const toolName: Rule;
7
17
  export declare const discover: Rule;
8
18
  export declare const deprecated: Rule;
9
19
  /**
@@ -21,3 +31,12 @@ export declare const cacheHints: Rule;
21
31
  */
22
32
  export declare const extensionId: Rule;
23
33
  export declare const taskRequired: Rule;
34
+ /**
35
+ * The SDK's rejection, readable: "Invalid result for tools/list: [ {...zod issues...} ]"
36
+ * spans many lines, and its first line alone said only "…tools/list: [" (the
37
+ * @pipeworx servers, bench 2026-11-09). Each issue becomes a detail line, "path: message".
38
+ */
39
+ export declare function sdkIssues(error: string): {
40
+ summary: string;
41
+ detail: string[];
42
+ };
@@ -4,6 +4,7 @@ import { Ajv } from 'ajv';
4
4
  import { Ajv2020 } from 'ajv/dist/2020.js';
5
5
  import addFormatsImport from 'ajv-formats';
6
6
  import { kept, names } from './rule.js';
7
+ import { HIDDEN_SOURCE } from '../sanitize.js';
7
8
  // ajv-formats ships CommonJS; under NodeNext its default import is the module object.
8
9
  const addFormats = (addFormatsImport.default ?? addFormatsImport);
9
10
  const SCHEMA_DIR = fileURLToPath(new URL('../../schemas/', import.meta.url));
@@ -54,8 +55,10 @@ export const schema = {
54
55
  }
55
56
  const findings = [];
56
57
  if (ctx.clientError && ctx.pages.every((page) => validate(page))) {
58
+ const said = sdkIssues(ctx.clientError);
57
59
  findings.push({
58
- message: `The official MCP SDK client rejected the tools/list result, so clients built on it list no tools. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${ctx.clientError.split('\n')[0]}`,
60
+ message: `The official MCP SDK client rejected the tools/list result, so clients built on it list no tools. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${said.summary}`,
61
+ ...(said.detail.length ? { detail: said.detail } : {}),
59
62
  fix: 'Fix what the SDK names above, then list the tools with the official client to confirm.',
60
63
  });
61
64
  }
@@ -108,6 +111,64 @@ export const duplicateName = {
108
111
  }));
109
112
  },
110
113
  };
114
+ /** The tool-name format the spec recommends from 2025-11-25 (SEP-986): 1 to 128 of A-Z a-z 0-9 _ - . */
115
+ const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
116
+ /** The characters reports show as escapes (sanitize.ts): one class, so what's flagged is what's escaped. */
117
+ const HIDDEN = new RegExp(HIDDEN_SOURCE, 'u');
118
+ const codePoint = (c) => `U+${c.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}`;
119
+ /**
120
+ * What's wrong with a tool name, or undefined when it fits the spec's format. `hidden`:
121
+ * it has characters that act on a terminal or can't be seen, so it can pass for
122
+ * another name or for none.
123
+ */
124
+ export function toolNameProblem(name) {
125
+ if (TOOL_NAME.test(name))
126
+ return undefined;
127
+ const chars = [...name];
128
+ if (chars.length === 0)
129
+ return { why: 'it is empty', hidden: false };
130
+ const hidden = [...new Set(chars.filter((c) => HIDDEN.test(c)))];
131
+ const other = [...new Set(chars.filter((c) => !HIDDEN.test(c) && !/[A-Za-z0-9_.-]/.test(c)))];
132
+ // Printable ASCII as itself; anything else by code point too, so a lookalike can't hide.
133
+ const shown = other.map((c) => (c === ' ' ? 'a space' : /^[!-~]$/.test(c) ? `"${c}"` : `${codePoint(c)} "${c}"`));
134
+ const parts = [
135
+ ...(hidden.length ? [`characters a terminal acts on or a reader can't see (${hidden.map(codePoint).join(', ')}: controls, invisible or text-direction characters)`] : []),
136
+ ...(shown.length ? [shown.join(', ')] : []),
137
+ ];
138
+ const long = chars.length > 128 ? `${chars.length} characters long, over 128` : '';
139
+ return { why: parts.length ? `it has ${parts.join('; and ')}${long ? `, and is ${long}` : ''}` : `it is ${long}`, hidden: hidden.length > 0 };
140
+ }
141
+ export const toolName = {
142
+ id: 'spec/tool-name',
143
+ severity: 'warn',
144
+ summary: "Tool names fit the format the spec recommends: 1 to 128 of A-Z, a-z, 0-9, _, - and .",
145
+ run(ctx) {
146
+ const bad = kept(ctx.menu.tools, ctx).flatMap((t) => {
147
+ const p = toolNameProblem(t.name);
148
+ return p ? [{ tool: t.name, ...p }] : [];
149
+ });
150
+ if (!bad.length)
151
+ return [];
152
+ // Hidden characters are an error on any protocol: the name can pass for another tool's.
153
+ // Otherwise a recommendation from 2025-11-25 on; before that the spec gave no format.
154
+ const hidden = bad.filter((b) => b.hidden);
155
+ const older = !!ctx.protocolVersion && ctx.protocolVersion < '2025-11-25';
156
+ return [
157
+ {
158
+ ...(bad.length === 1 ? { tool: bad[0].tool } : {}),
159
+ ...(hidden.length ? { severity: 'error' } : older ? { severity: 'info' } : {}),
160
+ message: `${bad.length === 1 ? `The tool name ${bad[0].tool} doesn't` : `${bad.length} tool names don't`} fit the tool name format the MCP spec recommends from 2025-11-25 (1 to 128 characters, A-Z, a-z, 0-9, _, - and .)` +
161
+ `${older ? `; this server speaks ${ctx.protocolVersion}, which gave no format, so it's for the move to 2025-11-25` : ''}. ` +
162
+ (hidden.length
163
+ ? `${hidden.length === 1 ? (bad.length === 1 ? 'It has' : 'One has') : `${hidden.length} have`} characters that are hidden or act on the screen, so what an agent or a person reads isn't the name the server takes. `
164
+ : '') +
165
+ 'Clients may refuse such a tool, rename it, or pass it to a model API that refuses it.',
166
+ detail: bad.slice(0, 12).map((b) => `${b.tool}: ${b.why}`).concat(bad.length > 12 ? [`and ${bad.length - 12} more`] : []),
167
+ fix: 'Name tools with letters, digits, _, - and . only (files_read or files.read, not "files read"), at most 128 characters.',
168
+ },
169
+ ];
170
+ },
171
+ };
111
172
  export const discover = {
112
173
  id: 'spec/discover',
113
174
  severity: 'info',
@@ -300,3 +361,27 @@ export const taskRequired = {
300
361
  ];
301
362
  },
302
363
  };
364
+ /**
365
+ * The SDK's rejection, readable: "Invalid result for tools/list: [ {...zod issues...} ]"
366
+ * spans many lines, and its first line alone said only "…tools/list: [" (the
367
+ * @pipeworx servers, bench 2026-11-09). Each issue becomes a detail line, "path: message".
368
+ */
369
+ export function sdkIssues(error) {
370
+ const at = error.indexOf('[');
371
+ if (at !== -1) {
372
+ try {
373
+ const issues = JSON.parse(error.slice(at));
374
+ if (Array.isArray(issues) && issues.length) {
375
+ const detail = issues.slice(0, 10).map((i) => `${(i.path ?? []).join('.') || '(the result)'}: ${i.message ?? 'invalid'}`);
376
+ if (issues.length > 10)
377
+ detail.push(`…and ${issues.length - 10} more`);
378
+ return { summary: `${error.slice(0, at).trim().replace(/:$/, '')}, ${issues.length === 1 ? 'one problem' : `${issues.length} problems`}.`, detail };
379
+ }
380
+ }
381
+ catch {
382
+ // Not JSON after all: said as text below.
383
+ }
384
+ }
385
+ const flat = error.replace(/\s+/g, ' ').trim();
386
+ return { summary: flat.length > 300 ? `${flat.slice(0, 297)}…` : flat, detail: [] };
387
+ }
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Characters a terminal (or GitHub's log parser) acts on, or a reader can't see:
3
+ * controls (C0, C1, DEL), format characters (the bidi overrides and isolates that
4
+ * reorder what's shown, "Trojan Source"; zero-width spaces and joiners; the soft
5
+ * hyphen; tag characters), line and paragraph separators, everything Unicode says
6
+ * renders as nothing (variation selectors, Hangul fillers), and the blank braille
7
+ * cell. Newline and tab are in it: a server's newline would start a line of its own
8
+ * (a fake finding, a `::error::` workflow command). spec/tool-name uses the same class.
9
+ */
10
+ export declare const HIDDEN_SOURCE = "[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Default_Ignorable_Code_Point}\\u2800]";
11
+ /** One field of server text, for the terminal: every control character shown as an escape. */
12
+ export declare function plain(text: string): string;
13
+ /**
14
+ * A whole report, last thing before it's printed: whatever control characters a field
15
+ * still carries are shown as escapes. Its own newlines and tabs stay; the fields that
16
+ * came from the server have already had theirs escaped by plain().
17
+ */
18
+ export declare function terminalSafe(report: string): string;
19
+ export interface MdOptions {
20
+ /** In a table cell: pipes are escaped, even inside code spans (GFM requires it). */
21
+ cell?: boolean;
22
+ }
23
+ /**
24
+ * Text as a markdown code span that it can't close: a fence of backticks longer than
25
+ * any run inside it, padded when it starts or ends with one. Control characters are
26
+ * shown as escapes, so it's always one line.
27
+ */
28
+ export declare function mdCode(text: string, options?: MdOptions): string;
29
+ /**
30
+ * A finding's text, or any line that carries server text, as markdown: toolmenu's own
31
+ * `code` spans stay code, everything else is escaped. A backtick in a server's text
32
+ * can only move where code starts and ends: every piece is rendered inert either way.
33
+ */
34
+ export declare function mdText(text: string, options?: MdOptions): string;
35
+ /**
36
+ * The net under every field: from here on, text written to `stream` goes through
37
+ * terminalSafe(). For the CLI's stdout and stderr, whatever the command; JSON stays
38
+ * the same JSON (its escapes read back as the same characters). Twice is once.
39
+ */
40
+ export declare function guardStream(stream: NodeJS.WritableStream): void;
41
+ /** Write past the net: only text already made safe, with toolmenu's own colour codes added. */
42
+ export declare function writeUnguarded(stream: NodeJS.WritableStream, text: string): void;
@@ -0,0 +1,142 @@
1
+ /*
2
+ * Text a server chose (tool names, descriptions, versions, error output), made safe
3
+ * for where toolmenu prints it. The menu file keeps the exact bytes; only what's
4
+ * shown changes.
5
+ *
6
+ * Shown as escapes, not dropped: a name with an escape sequence in it reads
7
+ * `a\u001b[2Jb`, so the report says what the server really sent and two different
8
+ * names never look the same. spec/tool-name says what's wrong with such a name.
9
+ */
10
+ /**
11
+ * Characters a terminal (or GitHub's log parser) acts on, or a reader can't see:
12
+ * controls (C0, C1, DEL), format characters (the bidi overrides and isolates that
13
+ * reorder what's shown, "Trojan Source"; zero-width spaces and joiners; the soft
14
+ * hyphen; tag characters), line and paragraph separators, everything Unicode says
15
+ * renders as nothing (variation selectors, Hangul fillers), and the blank braille
16
+ * cell. Newline and tab are in it: a server's newline would start a line of its own
17
+ * (a fake finding, a `::error::` workflow command). spec/tool-name uses the same class.
18
+ */
19
+ export const HIDDEN_SOURCE = '[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Default_Ignorable_Code_Point}\\u2800]';
20
+ const UNSAFE = new RegExp(HIDDEN_SOURCE, 'gu');
21
+ // The same but newline and tab, for a report whose own lines are already made.
22
+ const UNSAFE_IN_REPORT = new RegExp(`(?![\\n\\t])${HIDDEN_SOURCE}`, 'gu');
23
+ const NAMED = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
24
+ /**
25
+ * A character as an escape: \u001b; past the first plane as its UTF-16 pair
26
+ * (\udb40\udc41), which JSON and JavaScript read back as the same character, so a
27
+ * JSON report run through terminalSafe() is still the same JSON.
28
+ */
29
+ const visible = (c) => NAMED[c] ??
30
+ [...Array(c.length).keys()].map((i) => `\\u${c.charCodeAt(i).toString(16).padStart(4, '0')}`).join('');
31
+ /** One field of server text, for the terminal: every control character shown as an escape. */
32
+ export function plain(text) {
33
+ return text.replace(UNSAFE, visible);
34
+ }
35
+ /**
36
+ * A whole report, last thing before it's printed: whatever control characters a field
37
+ * still carries are shown as escapes. Its own newlines and tabs stay; the fields that
38
+ * came from the server have already had theirs escaped by plain().
39
+ */
40
+ export function terminalSafe(report) {
41
+ return report.replace(UNSAFE_IN_REPORT, visible);
42
+ }
43
+ /** Links toolmenu's own messages make, kept clickable in markdown. */
44
+ const OWN_LINKS = ['https://github.com/niksa90/toolmenu', 'https://code.claude.com/docs/', 'https://modelcontextprotocol.io/'];
45
+ /**
46
+ * Markdown that GitHub would act on in plain text: links and images ([ ] !), HTML
47
+ * and autolinks (< >), entities (&), escapes, table cells (|) and bold (*). Not _ or
48
+ * ~: they're in most tool names, and at worst they italicize or strike text through.
49
+ */
50
+ const MD_SPECIAL = /[\\`*[\]<>!|&]/;
51
+ /** MD_SPECIAL, and what GitHub links on its own: @mentions, #refs and GH-refs, bare URLs. */
52
+ const MD_INERT = new RegExp(`${MD_SPECIAL.source}|@|#(?=\\d)|\\bGH-(?=\\d)|:\\/\\/|\\bwww\\.`, 'gi');
53
+ const MD_ESCAPE = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
54
+ /** A zero-width space, as an entity: breaks a mention, reference or autolink without showing. */
55
+ const ZWSP = '&#8203;';
56
+ /**
57
+ * A link toolmenu's own messages make: one of OWN_LINKS, then the end, "/", "#" or "?",
58
+ * with no dot segments (/../ would leave the path the prefix names) and nothing that
59
+ * markdown or a URL parser reads specially.
60
+ */
61
+ function ownLink(url) {
62
+ return OWN_LINKS.some((p) => url.startsWith(p) && (p.endsWith('/') || url.length === p.length || '/#?'.includes(url[p.length]))) && !/(^|[\\/])\.\.?([\\/?#]|$)|%2e|[\\\\*[\]!&@]/i.test(url);
63
+ }
64
+ /** Plain text (no backticks in it) as inert markdown. */
65
+ function mdPlain(text) {
66
+ let out = '';
67
+ // A link toolmenu itself makes stays a link; anything else that would autolink doesn't.
68
+ const parts = text.split(/(https?:\/\/[^\s<>()|`]+)/);
69
+ parts.forEach((part, i) => {
70
+ if (i % 2 === 1 && ownLink(part)) {
71
+ out += part;
72
+ return;
73
+ }
74
+ // One pass, so no replacement sees another's output (the # of an entity).
75
+ out += part.replace(MD_INERT, (m) => {
76
+ if (m === '@' || m === '#')
77
+ return `${m}${ZWSP}`; // no mention or mailto link; no cross-reference on an issue
78
+ if (/^GH-$/i.test(m))
79
+ return `${m.slice(0, 2)}${ZWSP}-`;
80
+ if (m === '://')
81
+ return `:${ZWSP}//`; // https://…: shown, not linked
82
+ if (/^www\./i.test(m))
83
+ return `${m.slice(0, 3)}${ZWSP}.`;
84
+ return MD_ESCAPE[m] ?? `\\${m}`;
85
+ });
86
+ });
87
+ return out;
88
+ }
89
+ /**
90
+ * Text as a markdown code span that it can't close: a fence of backticks longer than
91
+ * any run inside it, padded when it starts or ends with one. Control characters are
92
+ * shown as escapes, so it's always one line.
93
+ */
94
+ export function mdCode(text, options = {}) {
95
+ const shown = plain(text);
96
+ if (!shown)
97
+ return '';
98
+ // A loop, not Math.max(...runs): a name with 100k backtick runs would overflow the stack.
99
+ let longest = 0;
100
+ for (const run of shown.matchAll(/`+/g))
101
+ longest = Math.max(longest, run[0].length);
102
+ const fence = '`'.repeat(longest + 1);
103
+ const pad = /^[`\s]|[`\s]$/.test(shown) ? ' ' : '';
104
+ const body = options.cell ? shown.replace(/\|/g, '\\|') : shown;
105
+ return `${fence}${pad}${body}${pad}${fence}`;
106
+ }
107
+ /**
108
+ * A finding's text, or any line that carries server text, as markdown: toolmenu's own
109
+ * `code` spans stay code, everything else is escaped. A backtick in a server's text
110
+ * can only move where code starts and ends: every piece is rendered inert either way.
111
+ */
112
+ export function mdText(text, options = {}) {
113
+ const pieces = plain(text).split('`');
114
+ // An unpaired backtick: the last piece is text, the backtick shown.
115
+ const unpaired = pieces.length % 2 === 0;
116
+ return pieces
117
+ .map((piece, i) => {
118
+ const last = i === pieces.length - 1;
119
+ if (i % 2 === 1 && !(unpaired && last))
120
+ return mdCode(piece, options);
121
+ const escaped = mdPlain(piece);
122
+ return unpaired && last ? `\\\`${escaped}` : escaped;
123
+ })
124
+ .join('');
125
+ }
126
+ const unguarded = new WeakMap();
127
+ /**
128
+ * The net under every field: from here on, text written to `stream` goes through
129
+ * terminalSafe(). For the CLI's stdout and stderr, whatever the command; JSON stays
130
+ * the same JSON (its escapes read back as the same characters). Twice is once.
131
+ */
132
+ export function guardStream(stream) {
133
+ if (unguarded.has(stream))
134
+ return;
135
+ const write = stream.write.bind(stream);
136
+ unguarded.set(stream, write);
137
+ stream.write = (chunk, ...rest) => write(typeof chunk === 'string' ? terminalSafe(chunk) : chunk, ...rest);
138
+ }
139
+ /** Write past the net: only text already made safe, with toolmenu's own colour codes added. */
140
+ export function writeUnguarded(stream, text) {
141
+ (unguarded.get(stream) ?? stream.write.bind(stream))(text);
142
+ }
package/dist/sarif.d.ts CHANGED
@@ -11,4 +11,6 @@ export interface SarifOptions {
11
11
  export declare function repoRoot(from?: string): string;
12
12
  /** The line of each tool's "name" in a menu file written by toolmenu (1-based). */
13
13
  export declare function toolLines(text: string): Map<string, number>;
14
+ /** The tools a finding is about: its tool, or each tool of a change found in several. JUnit uses it too. */
15
+ export declare function toolsOf(f: Finding): string[];
14
16
  export declare function toSarif(findings: Finding[], options: SarifOptions): string;
package/dist/sarif.js CHANGED
@@ -46,8 +46,8 @@ export function toolLines(text) {
46
46
  }
47
47
  return lines;
48
48
  }
49
- /** The tools a finding is about: its tool, or each tool of a change found in several. */
50
- function toolsOf(f) {
49
+ /** The tools a finding is about: its tool, or each tool of a change found in several. JUnit uses it too. */
50
+ export function toolsOf(f) {
51
51
  const several = f.tools;
52
52
  if (Array.isArray(several))
53
53
  return several.filter((t) => typeof t === 'string');
package/dist/scan.d.ts CHANGED
@@ -15,11 +15,18 @@ export interface ScanEntry {
15
15
  }
16
16
  export declare class ListError extends Error {
17
17
  }
18
+ /**
19
+ * Which environment variables a config's ${VAR} may be filled from: the names given
20
+ * with --allow-env, or all of them ('*'). None by default: the config file picks
21
+ * where each value goes (a URL, a header, a server's arguments), so a config from
22
+ * someone else could send any of your environment to a server of theirs.
23
+ */
24
+ export type AllowEnv = ReadonlySet<string> | '*';
18
25
  /** Words of a command line: whitespace-separated, with '…' and "…" kept together. */
19
26
  export declare function splitCommand(line: string): string[];
20
27
  /** The servers in a list file, unique names (a repeat gets #2, #3). */
21
- export declare function parseList(text: string, file: string, env?: NodeJS.ProcessEnv): ScanEntry[];
22
- export declare function loadList(file: string): Promise<ScanEntry[]>;
28
+ export declare function parseList(text: string, file: string, env?: NodeJS.ProcessEnv, allow?: AllowEnv): ScanEntry[];
29
+ export declare function loadList(file: string, allow?: AllowEnv): Promise<ScanEntry[]>;
23
30
  export interface ScanRow {
24
31
  name: string;
25
32
  /** Where the server is, printable: a URL without its query, or the command line. Never headers or env values. */
package/dist/scan.js CHANGED
@@ -8,16 +8,27 @@
8
8
  import { readFile } from 'node:fs/promises';
9
9
  import { ConnectError, clean, commandLine } from './explain.js';
10
10
  import { counts, findingLines, githubLines, mdFindings } from './report.js';
11
+ import { mdCode, mdText, plain } from './sanitize.js';
11
12
  import { snapshot } from './snapshot.js';
13
+ import { jsonErrorAt } from './menu.js';
12
14
  import { SEVERITY_RANK } from './types.js';
13
15
  export class ListError extends Error {
14
16
  }
15
- /** `${VAR}`, `${VAR:-default}` (Claude Code) and `${env:VAR}` (VS Code), from the environment. */
16
- function expand(value, env, missing) {
17
+ /** `${VAR}`, `${VAR:-default}` (Claude Code) and `${env:VAR}` (VS Code), from the environment, where allowed. */
18
+ function expand(value, env, missing, allow, blocked) {
17
19
  return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, fallback) => {
20
+ const allowed = allow === '*' || allow.has(name);
21
+ // Not allowed: the environment isn't read at all. With a default, the default, set
22
+ // or not, so a server can't learn which variables exist from which URL it gets.
23
+ if (!allowed && fallback !== undefined)
24
+ return fallback;
18
25
  const v = env[name];
19
- if (v !== undefined && v !== '')
20
- return v;
26
+ if (v !== undefined && v !== '') {
27
+ if (allowed)
28
+ return v;
29
+ blocked.add(name);
30
+ return '';
31
+ }
21
32
  if (fallback !== undefined)
22
33
  return fallback;
23
34
  missing.add(name);
@@ -33,21 +44,23 @@ function record(v) {
33
44
  return Object.fromEntries(Object.entries(v).filter(([, x]) => typeof x === 'string'));
34
45
  }
35
46
  /** One server from a client config: `{ command, args, env, cwd }` or `{ url, headers }`. */
36
- function fromConfig(name, raw, env) {
47
+ function fromConfig(name, raw, env, allow) {
37
48
  if (!raw || typeof raw !== 'object')
38
49
  return { name, problem: 'not an object' };
39
50
  const s = raw;
40
51
  if (s.disabled === true || s.enabled === false)
41
52
  return { name, disabled: true };
42
53
  const missing = new Set();
43
- const x = (v) => expand(v, env, missing);
54
+ const blocked = new Set();
55
+ const x = (v) => expand(v, env, missing, allow, blocked);
44
56
  const map = (r) => (r ? Object.fromEntries(Object.entries(r).map(([k, v]) => [k, x(v)])) : undefined);
45
57
  const type = typeof s.type === 'string' ? s.type : typeof s.transport === 'string' ? s.transport : undefined;
46
58
  let target;
47
59
  if (typeof s.url === 'string' || typeof s.serverUrl === 'string' || typeof s.httpUrl === 'string') {
48
60
  if (type === 'sse')
49
61
  return { name, problem: 'HTTP+SSE transport, which toolmenu doesn\'t speak (Streamable HTTP only)' };
50
- const url = x((s.url ?? s.serverUrl ?? s.httpUrl));
62
+ const raw = [s.url, s.serverUrl, s.httpUrl].find((u) => typeof u === 'string');
63
+ const url = x(raw);
51
64
  const headers = map(record(s.headers));
52
65
  target = { kind: 'http', url, ...(headers && Object.keys(headers).length ? { headers } : {}) };
53
66
  }
@@ -65,13 +78,19 @@ function fromConfig(name, raw, env) {
65
78
  }
66
79
  else
67
80
  return { name, problem: 'neither a command nor a url' };
81
+ // Set but not allowed: not checked, rather than checked with the value left out.
82
+ if (blocked.size) {
83
+ const list = [...blocked].sort();
84
+ return { name, problem: `${list.join(', ')} ${list.length === 1 ? 'is' : 'are'} set, but not passed in: scan fills \${VAR} only from the variables named with --allow-env (--allow-env ${list.join(',')}), so a config can't send the rest of your environment anywhere` };
85
+ }
68
86
  // A missing variable would send an empty credential: say so instead of checking a server set up wrong.
69
87
  if (missing.size)
70
88
  return { name, problem: `${[...missing].join(', ')} ${missing.size === 1 ? 'is' : 'are'} not set (the config refers to ${missing.size === 1 ? 'it' : 'them'})` };
89
+ // The URL as the config writes it: a filled-in ${VAR} may be a secret.
71
90
  if (target.kind === 'http' && !/^https?:\/\//.test(target.url))
72
- return { name, problem: `"${clean(target.url, 60)}" isn't an http(s) URL` };
91
+ return { name, problem: `"${clean([s.url, s.serverUrl, s.httpUrl].find((u) => typeof u === 'string'), 60)}" isn't an http(s) URL` };
73
92
  const shown = target.kind === 'http'
74
- ? { kind: 'http', url: (s.url ?? s.serverUrl ?? s.httpUrl) }
93
+ ? { kind: 'http', url: [s.url, s.serverUrl, s.httpUrl].find((u) => typeof u === 'string') }
75
94
  : { kind: 'stdio', command: s.command, args: s.args ?? [] };
76
95
  return { name, target, shown };
77
96
  }
@@ -161,7 +180,7 @@ function fromLines(text) {
161
180
  return entries;
162
181
  }
163
182
  /** The servers in a list file, unique names (a repeat gets #2, #3). */
164
- export function parseList(text, file, env = process.env) {
183
+ export function parseList(text, file, env = process.env, allow = new Set()) {
165
184
  let entries;
166
185
  if (/\.jsonc?$/i.test(file) || /^\s*\{/.test(text)) {
167
186
  let json;
@@ -170,13 +189,14 @@ export function parseList(text, file, env = process.env) {
170
189
  json = JSON.parse(text.replace(/^\s*\/\/.*$/gm, ''));
171
190
  }
172
191
  catch (error) {
173
- throw new ListError(`${file} isn't valid JSON: ${error.message}`);
192
+ const at = jsonErrorAt(error);
193
+ throw new ListError(`${file} isn't valid JSON${at ? ` (${at})` : ''}`);
174
194
  }
175
195
  const j = json;
176
196
  const servers = j.mcpServers ?? j.servers ?? j.mcp?.servers ?? j['mcp.servers'];
177
197
  if (!servers || typeof servers !== 'object' || Array.isArray(servers))
178
198
  throw new ListError(`${file} has no mcpServers or servers object, the key MCP clients keep their servers under`);
179
- entries = Object.entries(servers).map(([name, raw]) => fromConfig(name, raw, env));
199
+ entries = Object.entries(servers).map(([name, raw]) => fromConfig(name, raw, env, allow));
180
200
  }
181
201
  else
182
202
  entries = fromLines(text);
@@ -189,7 +209,7 @@ export function parseList(text, file, env = process.env) {
189
209
  return n === 1 ? e : { ...e, name: `${e.name}#${n}` };
190
210
  });
191
211
  }
192
- export async function loadList(file) {
212
+ export async function loadList(file, allow = new Set()) {
193
213
  let text;
194
214
  try {
195
215
  text = await readFile(file, 'utf8');
@@ -197,7 +217,7 @@ export async function loadList(file) {
197
217
  catch (error) {
198
218
  throw new ListError(`couldn't read ${file}: ${error.code ?? error.message}`);
199
219
  }
200
- return parseList(text, file);
220
+ return parseList(text, file, process.env, allow);
201
221
  }
202
222
  /** Printable location. A URL's query and credentials can hold keys, so they're left out. */
203
223
  export function where(target) {
@@ -297,33 +317,35 @@ export function formatScan(rows, format, file) {
297
317
  if (format === 'github') {
298
318
  const lines = [];
299
319
  for (const r of rows) {
320
+ // The title ends at the first comma or "::": the name goes in the message.
300
321
  if (r.failed)
301
- lines.push(`::error title=toolmenu scan ${r.name}::${status(r)}`);
322
+ lines.push(`::error title=toolmenu scan::${plain(`${r.name}: ${status(r)}`).replace(/%/g, '%25')}`);
302
323
  lines.push(...githubLines(r.findings.map((f) => ({ ...f, message: `${r.name}: ${f.message}` }))));
303
324
  }
304
325
  return lines.join('\n');
305
326
  }
306
327
  if (format === 'markdown') {
307
- const cell = (t) => t.replace(/\|/g, '\\|').replace(/\n/g, ' ');
308
- const lines = [`### toolmenu scan: ${cell(file)}`, '', '| Server | Tools | Tokens | Findings |', '|---|--:|--:|---|'];
328
+ const cell = (t) => mdText(t, { cell: true });
329
+ const lines = [`### toolmenu scan: ${mdText(file)}`, '', '| Server | Tools | Tokens | Findings |', '|---|--:|--:|---|'];
309
330
  for (const r of rows)
310
- lines.push(`| \`${cell(r.name)}\` | ${r.menu ? r.menu.tools.length : '–'} | ${r.menu ? `~${tokens(r.menu.totalTokens)}` : '–'} | ${cell(status(r))} |`);
331
+ lines.push(`| ${mdCode(r.name, { cell: true })} | ${r.menu ? r.menu.tools.length : '–'} | ${r.menu ? `~${tokens(r.menu.totalTokens)}` : '–'} | ${cell(status(r))} |`);
311
332
  lines.push('', totals(rows));
312
333
  for (const r of rows.filter((x) => x.findings.length))
313
- lines.push('', `#### \`${cell(r.name)}\``, '', ...mdFindings(r.findings));
334
+ lines.push('', `#### ${mdCode(r.name)}`, '', ...mdFindings(r.findings));
314
335
  return lines.join('\n');
315
336
  }
316
- const nameWidth = Math.min(32, Math.max(6, ...rows.map((r) => r.name.length)));
317
- const lines = [`toolmenu scan ${file}`, ''];
337
+ const nameWidth = Math.min(32, Math.max(6, ...rows.map((r) => plain(r.name).length)));
338
+ const lines = [`toolmenu scan ${plain(file)}`, ''];
318
339
  lines.push(` ${'server'.padEnd(nameWidth)} ${'tools'.padStart(5)} ${'tokens'.padStart(6)} findings`);
319
340
  for (const r of rows) {
320
- const name = r.name.length > nameWidth ? `${r.name.slice(0, nameWidth - 1)}…` : r.name;
321
- lines.push(` ${name.padEnd(nameWidth)} ${(r.menu ? String(r.menu.tools.length) : '–').padStart(5)} ${(r.menu ? `~${tokens(r.menu.totalTokens)}` : '–').padStart(6)} ${status(r)}`);
341
+ const shown = plain(r.name);
342
+ const name = shown.length > nameWidth ? `${shown.slice(0, nameWidth - 1)}…` : shown;
343
+ lines.push(` ${name.padEnd(nameWidth)} ${(r.menu ? String(r.menu.tools.length) : '–').padStart(5)} ${(r.menu ? `~${tokens(r.menu.totalTokens)}` : '–').padStart(6)} ${plain(status(r))}`);
322
344
  }
323
345
  lines.push('', totals(rows));
324
346
  for (const r of rows.filter((x) => x.findings.length)) {
325
347
  const s = r.menu.server;
326
- lines.push('', `── ${r.name} ${s.name ?? ''} ${s.version ?? ''} · protocol ${s.protocolVersion ?? 'unknown'}`.trimEnd(), '');
348
+ lines.push('', `── ${plain(r.name)} ${plain(s.name ?? '')} ${plain(s.version ?? '')} · protocol ${plain(s.protocolVersion ?? 'unknown')}`.trimEnd(), '');
327
349
  lines.push(...findingLines(r.findings).filter((l, i, all) => !(i === all.length - 1 && l === '')));
328
350
  }
329
351
  if (rows.some((r) => r.wantsCredentials))
package/dist/session.d.ts CHANGED
@@ -65,6 +65,21 @@ export interface StepRecord {
65
65
  tools: number;
66
66
  tokens: number;
67
67
  }
68
+ /**
69
+ * A tool in the menu after a step: its tokens, and whether this step inserted, appended,
70
+ * moved or edited it. Tools the step removed come last, marked removed.
71
+ */
72
+ export interface StepTool {
73
+ name: string;
74
+ tokens: number;
75
+ change?: 'inserted' | 'appended' | 'moved' | 'edited' | 'removed';
76
+ }
77
+ /**
78
+ * What a step's changes did to each tool of the menu after it, by position (two tools
79
+ * can share a name). An added tool is appended when only added tools follow it. The
80
+ * tools it removed (from `before`, the menu before the step) follow, marked removed.
81
+ */
82
+ export declare function stepMenu(tools: MenuTool[], changes?: ToolChange[], before?: MenuTool[]): StepTool[];
68
83
  export interface SessionResult {
69
84
  scenario: string;
70
85
  server: Menu['server'];
@@ -108,6 +123,8 @@ export interface SessionOptions {
108
123
  unionOut?: boolean;
109
124
  /** session --auto: what the plan called and skipped, so a run that called nothing isn't a clean one. */
110
125
  auto?: AutoSummary;
126
+ /** Called with the menu after each step that listed it (stepMenu), for the HTML report. Not part of the result, so no report carries it. */
127
+ onStepMenu?: (step: number, menu: StepTool[]) => void;
111
128
  /** Waits before retrying a request refused for being too many (default 2, 4, 8, 16, 32 s: a per-minute limit clears within them). */
112
129
  rateLimitWaitsMs?: number[];
113
130
  }