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