toolmenu 0.7.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 (56) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +311 -0
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +283 -0
  5. package/dist/compare.d.ts +32 -0
  6. package/dist/compare.js +108 -0
  7. package/dist/config.d.ts +19 -0
  8. package/dist/config.js +27 -0
  9. package/dist/connect.d.ts +66 -0
  10. package/dist/connect.js +122 -0
  11. package/dist/diff.d.ts +58 -0
  12. package/dist/diff.js +404 -0
  13. package/dist/history.d.ts +88 -0
  14. package/dist/history.js +219 -0
  15. package/dist/index.d.ts +10 -0
  16. package/dist/index.js +9 -0
  17. package/dist/menu.d.ts +9 -0
  18. package/dist/menu.js +57 -0
  19. package/dist/report.d.ts +11 -0
  20. package/dist/report.js +278 -0
  21. package/dist/routes.d.ts +22 -0
  22. package/dist/routes.js +76 -0
  23. package/dist/rules/description.d.ts +28 -0
  24. package/dist/rules/description.js +158 -0
  25. package/dist/rules/determinism.d.ts +2 -0
  26. package/dist/rules/determinism.js +35 -0
  27. package/dist/rules/ids.d.ts +11 -0
  28. package/dist/rules/ids.js +138 -0
  29. package/dist/rules/index.d.ts +11 -0
  30. package/dist/rules/index.js +42 -0
  31. package/dist/rules/naming.d.ts +4 -0
  32. package/dist/rules/naming.js +145 -0
  33. package/dist/rules/rule.d.ts +33 -0
  34. package/dist/rules/rule.js +1 -0
  35. package/dist/rules/spec.d.ts +5 -0
  36. package/dist/rules/spec.js +102 -0
  37. package/dist/rules/write.d.ts +3 -0
  38. package/dist/rules/write.js +55 -0
  39. package/dist/semver.d.ts +11 -0
  40. package/dist/semver.js +41 -0
  41. package/dist/session.d.ts +90 -0
  42. package/dist/session.js +519 -0
  43. package/dist/snapshot.d.ts +16 -0
  44. package/dist/snapshot.js +42 -0
  45. package/dist/types.d.ts +49 -0
  46. package/dist/types.js +1 -0
  47. package/dist/version.d.ts +2 -0
  48. package/dist/version.js +3 -0
  49. package/dist/words.d.ts +14 -0
  50. package/dist/words.js +63 -0
  51. package/package.json +57 -0
  52. package/schemas/2024-11-05.json +2077 -0
  53. package/schemas/2025-03-26.json +2139 -0
  54. package/schemas/2025-06-18.json +2517 -0
  55. package/schemas/2025-11-25.json +4058 -0
  56. package/schemas/2026-07-28.json +3963 -0
@@ -0,0 +1,219 @@
1
+ import { compareVersions } from './semver.js';
2
+ import { execFile } from 'node:child_process';
3
+ import { existsSync } from 'node:fs';
4
+ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
5
+ import { tmpdir } from 'node:os';
6
+ import { join } from 'node:path';
7
+ import { promisify } from 'node:util';
8
+ import { diffMenus } from './diff.js';
9
+ import { snapshot } from './snapshot.js';
10
+ const run = promisify(execFile);
11
+ const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
12
+ /** The npm registry, through the user's own npm (their config, proxy and registry). */
13
+ export const npmSource = {
14
+ async versions(pkg) {
15
+ const { stdout } = await run(npm, ['view', pkg, 'versions', 'time', '--json'], { maxBuffer: 64 * 1024 * 1024, shell: process.platform === 'win32' });
16
+ const data = JSON.parse(stdout);
17
+ const versions = typeof data.versions === 'string' ? [data.versions] : data.versions ?? [];
18
+ return versions.map((version) => ({ version, published: data.time?.[version] }));
19
+ },
20
+ async install(pkg, version, dir, { allowScripts, timeoutMs }) {
21
+ await writeFile(join(dir, 'package.json'), JSON.stringify({ name: 'toolmenu-history-install', private: true }));
22
+ const args = ['install', `${pkg}@${version}`, '--no-audit', '--no-fund', '--loglevel=error'];
23
+ if (!allowScripts)
24
+ args.push('--ignore-scripts');
25
+ await run(npm, args, { cwd: dir, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, shell: process.platform === 'win32' });
26
+ },
27
+ };
28
+ /** Dependencies worth recording: they decide the protocol and how schemas get built (FINDINGS F4). */
29
+ export const WATCHED_DEPENDENCIES = [
30
+ '@modelcontextprotocol/sdk',
31
+ '@modelcontextprotocol/server',
32
+ '@modelcontextprotocol/core',
33
+ 'zod',
34
+ 'zod-to-json-schema',
35
+ ];
36
+ export async function history(pkg, options) {
37
+ const source = options.source ?? npmSource;
38
+ const all = await source.versions(pkg);
39
+ // Version order, not publish order: a backport (1.0.1 after 2.0.0) is diffed
40
+ // against 1.0.0, not against 2.0.0.
41
+ const candidates = all
42
+ .map((v, index) => ({ v, index }))
43
+ .filter(({ v }) => options.includePrereleases || !v.version.includes('-'))
44
+ .sort((a, b) => compareVersions(a.v.version, b.v.version) || a.index - b.index)
45
+ .map(({ v }) => v);
46
+ const count = options.versions ?? 10;
47
+ const picked = Number.isFinite(count) ? candidates.slice(-count) : candidates;
48
+ await mkdir(options.outDir, { recursive: true });
49
+ const rows = [];
50
+ let previous;
51
+ for (const [i, v] of picked.entries()) {
52
+ options.onProgress?.(`[${i + 1}/${picked.length}] ${pkg}@${v.version}`);
53
+ const { row, menu } = await inspectVersion(pkg, v, options, source);
54
+ if (menu && previous)
55
+ row.diff = compareRows(previous, { row, menu });
56
+ if (menu)
57
+ previous = { row, menu };
58
+ rows.push(row);
59
+ }
60
+ const result = { package: pkg, installedAt: new Date().toISOString(), totalVersions: all.length, rows };
61
+ await writeFile(join(options.outDir, 'history.json'), JSON.stringify(result, null, 2) + '\n');
62
+ return result;
63
+ }
64
+ async function inspectVersion(pkg, v, options, source) {
65
+ const row = { version: v.version, ...(v.published ? { published: v.published } : {}), status: 'failed' };
66
+ const dir = await mkdtemp(join(tmpdir(), 'toolmenu-history-'));
67
+ try {
68
+ try {
69
+ await source.install(pkg, v.version, dir, { allowScripts: options.allowScripts ?? false, timeoutMs: options.installTimeoutMs ?? 180_000 });
70
+ }
71
+ catch (error) {
72
+ return { row: fail(row, 'install-failed', error) };
73
+ }
74
+ const pkgDir = join(dir, 'node_modules', ...pkg.split('/'));
75
+ const manifest = JSON.parse(await readFile(join(pkgDir, 'package.json'), 'utf8'));
76
+ row.declared = pick(manifest.dependencies ?? {}, WATCHED_DEPENDENCIES);
77
+ row.resolved = await resolvedDependencies(dir);
78
+ const command = commandFor(pkg, pkgDir, dir, manifest.bin, options);
79
+ if (!command)
80
+ return { row: fail(row, 'no-bin', new Error('The package has no bin to start, and no --cmd was given.')) };
81
+ let result;
82
+ try {
83
+ result = await snapshot({ kind: 'stdio', command: command[0], args: [...command.slice(1), ...(options.args ?? [])], env: options.env, cwd: dir }, { timeoutMs: options.timeoutMs ?? 30_000 });
84
+ }
85
+ catch (error) {
86
+ return { row: fail(row, classifyFailure(error), error) };
87
+ }
88
+ const { menu, findings } = result;
89
+ const menuFile = `${v.version}.json`;
90
+ await writeFile(join(options.outDir, menuFile), JSON.stringify(menu, null, 2) + '\n');
91
+ Object.assign(row, {
92
+ status: 'ok',
93
+ protocolVersion: menu.server.protocolVersion,
94
+ serverInfo: { name: menu.server.name, version: menu.server.version },
95
+ tools: menu.tools.length,
96
+ tokens: menu.totalTokens,
97
+ counts: countBySeverity(findings),
98
+ rules: countByRule(findings),
99
+ menuFile,
100
+ });
101
+ return { row, menu };
102
+ }
103
+ finally {
104
+ if (!options.keepInstalls)
105
+ await rm(dir, { recursive: true, force: true });
106
+ else
107
+ options.onProgress?.(` kept install: ${dir}`);
108
+ }
109
+ }
110
+ function commandFor(pkg, pkgDir, installDir, bin, options) {
111
+ let binPath;
112
+ if (typeof bin === 'string')
113
+ binPath = bin;
114
+ else if (bin && Object.keys(bin).length) {
115
+ const names = Object.keys(bin);
116
+ const base = pkg.split('/').pop();
117
+ const name = options.bin ?? (names.length === 1 ? names[0] : names.find((n) => n === base || n.endsWith(base)) ?? names[0]);
118
+ binPath = bin[name];
119
+ }
120
+ const binFile = binPath ? join(pkgDir, binPath) : undefined;
121
+ if (options.cmd) {
122
+ return splitCommand(options.cmd.replaceAll('{bin}', binFile ?? '').replaceAll('{dir}', installDir));
123
+ }
124
+ if (!binFile || !existsSync(binFile))
125
+ return undefined;
126
+ return [process.execPath, binFile];
127
+ }
128
+ function splitCommand(cmd) {
129
+ return (cmd.match(/"[^"]*"|'[^']*'|\S+/g) ?? []).map((part) => part.replace(/^["']|["']$/g, ''));
130
+ }
131
+ const ENV_HINT = /api[_\s-]?key|access[_\s-]?token|\btoken\b|environment variable|env var|credential|must be set|is not set|not configured|missing required/i;
132
+ const ARGS_HINT = /usage:|at least one (directory|argument)|missing argument|expected .*argument|no (directory|path) (was )?(given|provided)/i;
133
+ export function classifyFailure(error) {
134
+ const text = error instanceof Error ? error.message : String(error);
135
+ if (ARGS_HINT.test(text))
136
+ return 'needs-args';
137
+ if (ENV_HINT.test(text))
138
+ return 'needs-env';
139
+ if (/timed out|timeout/i.test(text))
140
+ return 'timeout';
141
+ return 'crashed';
142
+ }
143
+ function fail(row, reason, error) {
144
+ return Object.assign(row, { status: 'failed', reason, error: summarizeError(error) });
145
+ }
146
+ /** The lines that say what went wrong, not the stack trace. */
147
+ export function summarizeError(error) {
148
+ const lines = (error instanceof Error ? error.message : String(error)).split('\n').map((l) => l.trim()).filter(Boolean);
149
+ const telling = lines.filter((l) => !/^at\s|^node:|^Node\.js v|^[{}]$|^\^+$/.test(l));
150
+ const causes = telling.filter((l) => /error|cannot|not found|missing|usage|required|denied|refused/i.test(l));
151
+ return [...new Set([...(causes.length ? causes : telling).slice(0, 4), ...lines.filter((l) => /^code:/.test(l))])].join('\n').slice(0, 800);
152
+ }
153
+ /** Every installed copy of the watched dependencies, from the lockfile npm wrote. */
154
+ async function resolvedDependencies(dir) {
155
+ const lockPath = join(dir, 'package-lock.json');
156
+ if (!existsSync(lockPath))
157
+ return {};
158
+ const lock = JSON.parse(await readFile(lockPath, 'utf8'));
159
+ const found = {};
160
+ for (const [path, info] of Object.entries(lock.packages ?? {})) {
161
+ for (const name of WATCHED_DEPENDENCIES) {
162
+ if (info.version && path.endsWith(`node_modules/${name}`))
163
+ (found[name] ??= new Set()).add(info.version);
164
+ }
165
+ }
166
+ return Object.fromEntries(Object.entries(found).map(([name, versions]) => [name, [...versions].sort()]));
167
+ }
168
+ function compareRows(before, after) {
169
+ // The release is the npm version: servers often report a version that never changes (F5).
170
+ const d = diffMenus(before.menu, after.menu, { release: { before: before.row.version, after: after.row.version } });
171
+ const count = (c) => d.findings.filter((f) => f.class === c).length;
172
+ return {
173
+ from: before.row.version,
174
+ tokenDelta: d.tokens.delta,
175
+ breaking: count('breaking'),
176
+ minor: count('minor'),
177
+ notice: count('notice'),
178
+ suggestedBump: d.suggestedBump,
179
+ ...(d.actualBump ? { actualBump: d.actualBump } : {}),
180
+ bumpTooSmall: d.findings.some((f) => f.rule === 'diff/version-bump'),
181
+ breakingChanges: d.findings.filter((f) => f.class === 'breaking').map((f) => f.message),
182
+ };
183
+ }
184
+ function pick(deps, names) {
185
+ return Object.fromEntries(names.filter((n) => deps[n]).map((n) => [n, deps[n]]));
186
+ }
187
+ function countBySeverity(findings) {
188
+ const c = { error: 0, warn: 0, info: 0 };
189
+ for (const f of findings)
190
+ c[f.severity]++;
191
+ return c;
192
+ }
193
+ function countByRule(findings) {
194
+ const c = {};
195
+ for (const f of findings)
196
+ c[f.rule] = (c[f.rule] ?? 0) + 1;
197
+ return c;
198
+ }
199
+ const CSV_COLUMNS = [
200
+ 'version', 'published', 'status', 'reason', 'protocol', 'server_version', 'tools', 'tokens',
201
+ 'sdk', 'zod', 'errors', 'warnings', 'info', 'token_delta', 'breaking', 'minor', 'notice', 'suggested_bump',
202
+ ];
203
+ export function historyCsv(result) {
204
+ const cell = (v) => {
205
+ const s = v === undefined ? '' : String(v);
206
+ return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
207
+ };
208
+ const lines = [CSV_COLUMNS.join(',')];
209
+ for (const r of result.rows) {
210
+ const sdk = r.resolved?.['@modelcontextprotocol/sdk'] ?? r.resolved?.['@modelcontextprotocol/server'];
211
+ lines.push([
212
+ r.version, r.published?.slice(0, 10), r.status, r.reason, r.protocolVersion, r.serverInfo?.version, r.tools, r.tokens,
213
+ sdk?.join(' '), r.resolved?.zod?.join(' '), r.counts?.error, r.counts?.warn, r.counts?.info,
214
+ r.diff?.tokenDelta, r.diff?.breaking, r.diff?.minor, r.diff?.notice, r.diff?.suggestedBump,
215
+ ].map(cell).join(','));
216
+ }
217
+ return lines.join('\n') + '\n';
218
+ }
219
+ export { compareVersions };
@@ -0,0 +1,10 @@
1
+ export { snapshot, type SnapshotOptions, type SnapshotResult } from './snapshot.js';
2
+ export { connect, listTools, type Target, type Connection } from './connect.js';
3
+ export { buildMenu, countTokens, loadMenu } from './menu.js';
4
+ export { diffMenus, versionBump, DIFF_RULES, type DiffResult, type DiffOptions, type DiffFinding, type ChangeClass, type Bump, type TokenChange } from './diff.js';
5
+ export { history, historyCsv, npmSource, classifyFailure, WATCHED_DEPENDENCIES, type HistoryResult, type HistoryRow, type HistoryOptions, type PackageSource, type PublishedVersion, type FailureReason } from './history.js';
6
+ export { session, loadScenario, parseScenario, changeFindings, starterScenario, type Scenario, type Step, type SessionResult, type SessionOptions, type StepRecord, type Scope } from './session.js';
7
+ export { compareMenus, cacheBreak, canonical, type ToolChange, type ChangeKind, type CacheBreak } from './compare.js';
8
+ export { MENU_RULES, runRules, type Rule, type RuleContext, type RuleSettings } from './rules/index.js';
9
+ export { loadRoutes, routeScores, type Routes } from './routes.js';
10
+ export type { Finding, Menu, MenuTool, Severity, Era } from './types.js';
package/dist/index.js ADDED
@@ -0,0 +1,9 @@
1
+ export { snapshot } from './snapshot.js';
2
+ export { connect, listTools } from './connect.js';
3
+ export { buildMenu, countTokens, loadMenu } from './menu.js';
4
+ export { diffMenus, versionBump, DIFF_RULES } from './diff.js';
5
+ export { history, historyCsv, npmSource, classifyFailure, WATCHED_DEPENDENCIES } from './history.js';
6
+ export { session, loadScenario, parseScenario, changeFindings, starterScenario } from './session.js';
7
+ export { compareMenus, cacheBreak, canonical } from './compare.js';
8
+ export { MENU_RULES, runRules } from './rules/index.js';
9
+ export { loadRoutes, routeScores } from './routes.js';
package/dist/menu.d.ts ADDED
@@ -0,0 +1,9 @@
1
+ import type { Era, Menu, MenuTool } from './types.js';
2
+ /** Estimated tokens for a piece of text. An estimate: vendors tokenize differently. */
3
+ export declare function countTokens(text: string): number;
4
+ /** The tool definition without toolmenu's own `tokens` field. */
5
+ export declare function toolDefinition(tool: MenuTool): Record<string, unknown>;
6
+ export declare function buildMenu(rawTools: Record<string, unknown>[], server: Menu['server'], listMeta?: Menu['listMeta']): Menu;
7
+ export declare function eraOf(protocolVersion: string | undefined): Era | undefined;
8
+ /** Read a menu.json written by `toolmenu snapshot`. */
9
+ export declare function loadMenu(path: string): Promise<Menu>;
package/dist/menu.js ADDED
@@ -0,0 +1,57 @@
1
+ import { Tiktoken } from 'js-tiktoken/lite';
2
+ import o200k from 'js-tiktoken/ranks/o200k_base';
3
+ let encoder;
4
+ /** Estimated tokens for a piece of text. An estimate: vendors tokenize differently. */
5
+ export function countTokens(text) {
6
+ encoder ??= new Tiktoken(o200k);
7
+ return encoder.encode(text).length;
8
+ }
9
+ /** The tool definition without toolmenu's own `tokens` field. */
10
+ export function toolDefinition(tool) {
11
+ const { tokens: _tokens, ...definition } = tool;
12
+ return definition;
13
+ }
14
+ export function buildMenu(rawTools, server, listMeta) {
15
+ const tools = rawTools.map((raw) => ({
16
+ ...raw,
17
+ tokens: countTokens(JSON.stringify(raw)),
18
+ }));
19
+ return {
20
+ toolmenu: 1,
21
+ server,
22
+ capturedAt: new Date().toISOString(),
23
+ tools,
24
+ totalTokens: tools.reduce((sum, t) => sum + t.tokens, 0),
25
+ ...(listMeta && Object.keys(listMeta).length ? { listMeta } : {}),
26
+ };
27
+ }
28
+ export function eraOf(protocolVersion) {
29
+ if (!protocolVersion)
30
+ return undefined;
31
+ return protocolVersion >= '2026-07-28' ? 'modern' : 'legacy';
32
+ }
33
+ /** Read a menu.json written by `toolmenu snapshot`. */
34
+ export async function loadMenu(path) {
35
+ const { readFile } = await import('node:fs/promises');
36
+ let data;
37
+ try {
38
+ data = JSON.parse(await readFile(path, 'utf8'));
39
+ }
40
+ catch (error) {
41
+ throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);
42
+ }
43
+ const menu = data;
44
+ if (menu?.toolmenu !== 1 || !Array.isArray(menu.tools)) {
45
+ throw new Error(`${path} isn't a toolmenu menu file (expected "toolmenu": 1 and a "tools" list). Write one with \`toolmenu snapshot\`.`);
46
+ }
47
+ for (const t of menu.tools) {
48
+ if (typeof t?.name !== 'string')
49
+ throw new Error(`${path}: every tool needs a name`);
50
+ if (typeof t.tokens !== 'number')
51
+ t.tokens = countTokens(JSON.stringify(t));
52
+ }
53
+ if (typeof menu.totalTokens !== 'number')
54
+ menu.totalTokens = menu.tools.reduce((s, t) => s + t.tokens, 0);
55
+ menu.server ??= {};
56
+ return menu;
57
+ }
@@ -0,0 +1,11 @@
1
+ import type { DiffResult } from './diff.js';
2
+ import type { HistoryResult } from './history.js';
3
+ import { type Scenario, type SessionResult } from './session.js';
4
+ import type { Finding, Menu, Severity } from './types.js';
5
+ export type Format = 'text' | 'json' | 'github' | 'markdown';
6
+ export declare function counts(findings: Finding[]): Record<Severity, number>;
7
+ export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string): string;
8
+ export declare function formatDiff(d: DiffResult, beforeTools: number, afterTools: number, format: Format): string;
9
+ export declare function formatHistory(h: HistoryResult, format: Format, outDir: string): string;
10
+ export declare function formatSession(s: SessionResult, format: Format): string;
11
+ export declare function formatPlan(scenario: Scenario, name: string): string;
package/dist/report.js ADDED
@@ -0,0 +1,278 @@
1
+ import { stepLabel } from './session.js';
2
+ const LABEL = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
3
+ export function counts(findings) {
4
+ const c = { error: 0, warn: 0, info: 0 };
5
+ for (const f of findings)
6
+ c[f.severity]++;
7
+ return c;
8
+ }
9
+ function plural(n, word) {
10
+ return `${n} ${word}${n === 1 ? '' : 's'}`;
11
+ }
12
+ export function formatSnapshot(menu, findings, format, outPath) {
13
+ if (format === 'json') {
14
+ return JSON.stringify({
15
+ command: 'snapshot',
16
+ server: menu.server,
17
+ tools: menu.tools.length,
18
+ totalTokens: menu.totalTokens,
19
+ listMeta: menu.listMeta,
20
+ written: outPath ?? null,
21
+ counts: counts(findings),
22
+ findings,
23
+ }, null, 2);
24
+ }
25
+ if (format === 'github')
26
+ return githubLines(findings).join('\n');
27
+ if (format === 'markdown') {
28
+ const s = menu.server;
29
+ return [
30
+ `### toolmenu snapshot: \`${s.name ?? 'server'}\` ${s.version ?? ''}`.trimEnd(),
31
+ '',
32
+ `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
33
+ '',
34
+ ...mdFindings(findings),
35
+ ].join('\n');
36
+ }
37
+ const s = menu.server;
38
+ const lines = [
39
+ `toolmenu snapshot ${s.name ?? 'unknown server'} ${s.version ?? ''}`.trimEnd(),
40
+ ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
41
+ ];
42
+ if (outPath)
43
+ lines.push(` wrote ${outPath}`);
44
+ lines.push('');
45
+ lines.push(...findingLines(findings));
46
+ lines.push(summaryLine(findings));
47
+ return lines.join('\n');
48
+ }
49
+ function findingLines(findings) {
50
+ const lines = [];
51
+ for (const f of findings) {
52
+ lines.push(`${LABEL[f.severity]} ${f.rule}`);
53
+ lines.push(` ${f.message}`);
54
+ for (const d of f.detail ?? [])
55
+ lines.push(` ${d}`);
56
+ }
57
+ lines.push(findings.length ? '' : 'No findings.');
58
+ return lines;
59
+ }
60
+ function summaryLine(findings) {
61
+ const c = counts(findings);
62
+ return `${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`;
63
+ }
64
+ function githubLines(findings) {
65
+ return findings.map((f) => {
66
+ const level = f.severity === 'error' ? 'error' : f.severity === 'warn' ? 'warning' : 'notice';
67
+ const body = [f.message, ...(f.detail ?? [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
68
+ return `::${level} title=toolmenu ${f.rule}::${body}`;
69
+ });
70
+ }
71
+ function signed(n) {
72
+ return `${n > 0 ? '+' : n < 0 ? '−' : '±'}${Math.abs(n).toLocaleString('en-US')}`;
73
+ }
74
+ function tokenSentence(d) {
75
+ const n = Math.abs(d.tokens.delta).toLocaleString('en-US');
76
+ if (d.tokens.delta > 0)
77
+ return `this release adds ~${n} tokens to every conversation that loads the menu`;
78
+ if (d.tokens.delta < 0)
79
+ return `this release saves ~${n} tokens in every conversation that loads the menu`;
80
+ return 'no change in menu size';
81
+ }
82
+ export function formatDiff(d, beforeTools, afterTools, format) {
83
+ if (format === 'json') {
84
+ return JSON.stringify({ command: 'diff', ...d, counts: counts(d.findings) }, null, 2);
85
+ }
86
+ const classes = { breaking: 0, minor: 0, notice: 0 };
87
+ for (const f of d.findings)
88
+ if (f.class)
89
+ classes[f.class]++;
90
+ // Name the release versions when there are some; otherwise say whose version this is.
91
+ const pair = d.release?.source === 'release'
92
+ ? `${d.release.before} → ${d.release.after}`
93
+ : `${d.before.version ?? '?'} → ${d.after.version ?? '?'} (server-reported)`;
94
+ const actual = d.actualBump ?? `not checked (${d.bumpNotChecked ?? 'pass --release'})`;
95
+ const headline = `${d.after.name ?? d.before.name ?? 'server'} ${pair}`;
96
+ const tokenLine = `~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')} tokens (${signed(d.tokens.delta)}, estimate): ${tokenSentence(d)}`;
97
+ const bumpLine = `suggested bump: ${d.suggestedBump} · actual: ${actual}`;
98
+ if (format === 'github') {
99
+ return [...githubLines(d.findings), `::notice title=toolmenu diff::${headline}. ${tokenLine}. ${bumpLine}.`].join('\n');
100
+ }
101
+ if (format === 'markdown') {
102
+ const lines = [
103
+ `### toolmenu diff: \`${d.after.name ?? d.before.name ?? 'server'}\` ${pair}`,
104
+ '',
105
+ `**${signed(d.tokens.delta)} tokens** (~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')}, estimate): ${tokenSentence(d)}.`,
106
+ '',
107
+ `**${classes.breaking} breaking** · ${classes.minor} minor · ${classes.notice} notice · suggested bump: **${d.suggestedBump}** (actual: ${actual}) · ${beforeTools} → ${afterTools} tools`,
108
+ '',
109
+ ...mdFindings(d.findings),
110
+ ];
111
+ if (d.tokens.tools.length) {
112
+ lines.push('', '<details><summary>Token change by tool (estimate)</summary>', '', '| Tool | Before | After | Change |', '|---|---:|---:|---:|');
113
+ for (const t of d.tokens.tools.slice(0, 30))
114
+ lines.push(`| \`${t.name}\` | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
115
+ if (d.tokens.tools.length > 30)
116
+ lines.push(`| …and ${d.tokens.tools.length - 30} more | | | |`);
117
+ lines.push('', '</details>');
118
+ }
119
+ return lines.join('\n');
120
+ }
121
+ const lines = [
122
+ `toolmenu diff ${headline}`,
123
+ ` ${beforeTools} → ${afterTools} tools · ${tokenLine}`,
124
+ ` ${classes.breaking} breaking · ${classes.minor} minor · ${classes.notice} notice · ${bumpLine}`,
125
+ '',
126
+ ...findingLines(d.findings),
127
+ ];
128
+ if (d.tokens.tools.length) {
129
+ lines.push('Token change by tool (estimate):');
130
+ for (const t of d.tokens.tools.slice(0, 10))
131
+ lines.push(` ${signed(t.delta).padStart(7)} ${t.name}`);
132
+ if (d.tokens.tools.length > 10)
133
+ lines.push(` …and ${d.tokens.tools.length - 10} more`);
134
+ lines.push('');
135
+ }
136
+ lines.push(summaryLine(d.findings));
137
+ return lines.join('\n');
138
+ }
139
+ export function formatHistory(h, format, outDir) {
140
+ if (format === 'json')
141
+ return JSON.stringify({ command: 'history', ...h }, null, 2);
142
+ const ok = h.rows.filter((r) => r.status === 'ok');
143
+ const failed = h.rows.filter((r) => r.status === 'failed');
144
+ const reasons = {};
145
+ for (const r of failed)
146
+ reasons[r.reason ?? 'crashed'] = (reasons[r.reason ?? 'crashed'] ?? 0) + 1;
147
+ const failSummary = failed.length ? ` (${Object.entries(reasons).map(([k, n]) => `${k} ${n}`).join(', ')})` : '';
148
+ if (format === 'github') {
149
+ const lines = h.rows.flatMap((r) => r.status === 'failed'
150
+ ? [`::warning title=toolmenu history ${r.version}::failed: ${r.reason}`]
151
+ : (r.diff?.breakingChanges ?? []).map((m) => `::error title=toolmenu history ${r.version}::${m}`));
152
+ return [...lines, `::notice title=toolmenu history::${h.package}: ${ok.length} of ${h.rows.length} versions inspected${failSummary}`].join('\n');
153
+ }
154
+ const sdkOf = (r) => (r.resolved?.['@modelcontextprotocol/sdk'] ?? r.resolved?.['@modelcontextprotocol/server'] ?? []).join('+') || '-';
155
+ const table = [
156
+ ['version', 'published', 'protocol', 'tools', 'tokens', 'sdk', 'zod', 'findings', 'vs previous'],
157
+ ...h.rows.map((r) => r.status === 'failed'
158
+ ? [r.version, r.published?.slice(0, 10) ?? '', `failed: ${r.reason}`, '', '', sdkOf(r), (r.resolved?.zod ?? []).join('+') || '-', '', '']
159
+ : [
160
+ r.version,
161
+ r.published?.slice(0, 10) ?? '',
162
+ r.protocolVersion ?? '?',
163
+ String(r.tools ?? ''),
164
+ `~${(r.tokens ?? 0).toLocaleString('en-US')}`,
165
+ sdkOf(r),
166
+ (r.resolved?.zod ?? []).join('+') || '-',
167
+ [r.counts?.error ? `${r.counts.error} err` : '', r.counts?.warn ? `${r.counts.warn} warn` : ''].filter(Boolean).join(' ') || 'clean',
168
+ r.diff
169
+ ? `${signed(r.diff.tokenDelta)} tokens · ${[r.diff.breaking && `${r.diff.breaking} breaking`, r.diff.minor && `${r.diff.minor} minor`, r.diff.notice && `${r.diff.notice} notice`].filter(Boolean).join(' · ') || 'no changes'}`
170
+ : '—',
171
+ ]),
172
+ ];
173
+ const widths = table[0].map((_, c) => Math.max(...table.map((row) => row[c].length)));
174
+ const lines = [
175
+ `toolmenu history ${h.package}`,
176
+ ` last ${h.rows.length} of ${h.totalVersions} published versions · installed ${h.installedAt.slice(0, 10)}`,
177
+ ` (each version was installed today: dependencies resolve as of today, not as shipped)`,
178
+ '',
179
+ ...table.map((row) => ' ' + row.map((cell, c) => cell.padEnd(widths[c])).join(' ').trimEnd()),
180
+ '',
181
+ ];
182
+ const breaking = h.rows.filter((r) => r.diff?.breakingChanges.length);
183
+ if (breaking.length) {
184
+ lines.push('Breaking changes:');
185
+ for (const r of breaking)
186
+ for (const m of r.diff.breakingChanges)
187
+ lines.push(` ${r.version} (vs ${r.diff.from}): ${m}`);
188
+ lines.push('');
189
+ }
190
+ if (failed.length) {
191
+ lines.push('Failed:');
192
+ for (const r of failed)
193
+ lines.push(` ${r.version}: ${r.reason}. ${(r.error ?? '').split('\n')[0].slice(0, 160)}`);
194
+ lines.push('');
195
+ }
196
+ lines.push(`${h.rows.length} inspected · ${ok.length} ok · ${failed.length} failed${failSummary} · wrote ${outDir}`);
197
+ return lines.join('\n');
198
+ }
199
+ export function formatSession(s, format) {
200
+ if (format === 'json')
201
+ return JSON.stringify({ command: 'session', ...s, counts: counts(s.findings) }, null, 2);
202
+ if (format === 'github') {
203
+ return githubLines(s.findings.map((f) => ({ ...f, message: f.step ? `step ${f.step} (${s.steps[f.step - 1]?.label}): ${f.message}` : f.message }))).join('\n');
204
+ }
205
+ if (format === 'markdown') {
206
+ const lines = [
207
+ `### toolmenu session: \`${s.scenario}\``,
208
+ '',
209
+ `\`${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)`,
210
+ '',
211
+ '| Step | Menu | list_changed | Scope |',
212
+ '|---|---|---|---|',
213
+ ...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 ?? ''} |`),
214
+ '',
215
+ ...mdFindings(s.findings.map((f) => ({ ...f, message: f.step ? `Step ${f.step}: ${f.message}` : f.message }))),
216
+ ];
217
+ return lines.join('\n');
218
+ }
219
+ const tok = (n) => `~${n.toLocaleString('en-US')}`;
220
+ const lines = [
221
+ `toolmenu session ${s.scenario}`,
222
+ ` ${s.server.name ?? 'server'} ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport}`,
223
+ ` baseline: ${plural(s.baseline.tools, 'tool')} · ${tok(s.baseline.tokens)} tokens (estimate) · listening for list_changed: ${s.listening ? 'yes' : 'no'}`,
224
+ ` fresh-connection check: ${s.connectionCheck === 'same' ? 'a second connection got the same menu' : 'a second connection got a DIFFERENT menu'}`,
225
+ '',
226
+ ];
227
+ const at = (step) => s.findings.filter((f) => f.step === step);
228
+ const block = (findings) => {
229
+ for (const f of findings) {
230
+ lines.push(` ${LABEL[f.severity]} ${f.rule}`);
231
+ lines.push(` ${f.message}`);
232
+ for (const d of f.detail ?? [])
233
+ lines.push(` ${d}`);
234
+ }
235
+ };
236
+ block(at(0));
237
+ if (at(0).length)
238
+ lines.push('');
239
+ for (const step of s.steps) {
240
+ const facts = [
241
+ step.status !== 'ok' ? step.status : '',
242
+ step.changed ? 'menu changed' : step.status === 'ok' ? 'no change' : '',
243
+ step.changed ? (step.listChanged ? 'list_changed received' : 'no list_changed') : '',
244
+ step.scope ? `scope: ${step.scope}` : '',
245
+ step.note ?? '',
246
+ ].filter(Boolean);
247
+ lines.push(`step ${step.index}: ${step.label} · ${facts.join(' · ')}`);
248
+ block(at(step.index));
249
+ }
250
+ lines.push('');
251
+ lines.push(`final: ${plural(s.final.tools, 'tool')} · ${tok(s.final.tokens)} tokens (estimate)`);
252
+ lines.push(summaryLine(s.findings));
253
+ return lines.join('\n');
254
+ }
255
+ export function formatPlan(scenario, name) {
256
+ const lines = [`toolmenu session --plan ${name}`, ` allow_writes: ${scenario.allowWrites}${scenario.allowWrites ? '' : ' (tools not marked readOnlyHint will be refused)'}`, ''];
257
+ scenario.steps.forEach((step, i) => lines.push(`step ${i + 1}: ${stepLabel(step)}${step.kind === 'wait_for' ? ` (up to ${step.timeoutMs} ms)` : ''}`));
258
+ lines.push('', 'After every step the menu is listed and compared with the one before. Nothing was run.');
259
+ return lines.join('\n');
260
+ }
261
+ function mdCell(text) {
262
+ return text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
263
+ }
264
+ function mdFindings(findings) {
265
+ if (findings.length === 0)
266
+ return ['No findings.'];
267
+ const row = (f) => `| ${f.severity === 'error' ? '**error**' : f.severity} | \`${f.rule}\` | ${mdCell([f.message, ...(f.detail ?? [])].join(' · '))} |`;
268
+ const head = ['| | Rule | Finding |', '|---|---|---|'];
269
+ const loud = findings.filter((f) => f.severity !== 'info');
270
+ const quiet = findings.filter((f) => f.severity === 'info');
271
+ const c = counts(findings);
272
+ const lines = loud.length ? [...head, ...loud.map(row)] : [];
273
+ // Info goes in a fold so a PR comment leads with what needs attention.
274
+ if (quiet.length)
275
+ lines.push('', `<details><summary>${quiet.length} info</summary>`, '', ...head, ...quiet.map(row), '', '</details>');
276
+ lines.push('', `${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`);
277
+ return lines;
278
+ }
@@ -0,0 +1,22 @@
1
+ import type { MenuTool } from './types.js';
2
+ export type Routes = Record<string, {
3
+ must_match?: string[];
4
+ must_not_match?: string[];
5
+ }>;
6
+ export declare function loadRoutes(path: string): Promise<Routes>;
7
+ /** The words of a keyword that have to be there for a tool to match it. */
8
+ export declare function routeWords(keyword: string): string[];
9
+ /**
10
+ * How strongly each tool matches a keyword. Deterministic, no LLM, the way a
11
+ * keyword or BM25 tool search sees it (it can't read "not"):
12
+ * - name: 1 per route word in the tool name, plus 2 if the name has them all
13
+ * (a one-word route in the name scores 3);
14
+ * - description: 1 per mention of the exact phrase (up to 3), or 1 if the name
15
+ * and description have every word between them but never as the phrase.
16
+ * Singular and plural count as the same word.
17
+ */
18
+ export declare function routeScores(keyword: string, tools: MenuTool[]): Map<string, number>;
19
+ /** Keyword words a tool has nowhere in its name or description. */
20
+ export declare function missingWords(keyword: string, tool: MenuTool): string[];
21
+ /** The sentence where a tool's description mentions the keyword next to a "not", if it does. */
22
+ export declare function negatedMention(keyword: string, tool: MenuTool): string | undefined;