toolmenu 0.12.0 → 0.14.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 (63) hide show
  1. package/README.md +84 -23
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +59 -21
  6. package/dist/auto.d.ts +80 -6
  7. package/dist/auto.js +255 -19
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +64 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +170 -185
  13. package/dist/close.d.ts +8 -0
  14. package/dist/close.js +18 -0
  15. package/dist/config.d.ts +7 -1
  16. package/dist/config.js +17 -0
  17. package/dist/connect.d.ts +14 -0
  18. package/dist/connect.js +150 -16
  19. package/dist/diff.d.ts +23 -1
  20. package/dist/diff.js +574 -120
  21. package/dist/difference.d.ts +2 -0
  22. package/dist/difference.js +13 -12
  23. package/dist/explain.d.ts +113 -0
  24. package/dist/explain.js +461 -0
  25. package/dist/failures.d.ts +15 -0
  26. package/dist/failures.js +59 -2
  27. package/dist/help.d.ts +11 -0
  28. package/dist/help.js +205 -0
  29. package/dist/history.d.ts +13 -0
  30. package/dist/history.js +86 -6
  31. package/dist/init.d.ts +93 -2
  32. package/dist/init.js +508 -21
  33. package/dist/menu.js +10 -2
  34. package/dist/options.d.ts +141 -0
  35. package/dist/options.js +50 -0
  36. package/dist/report.d.ts +2 -2
  37. package/dist/report.js +305 -101
  38. package/dist/rules/description.d.ts +7 -2
  39. package/dist/rules/description.js +86 -42
  40. package/dist/rules/determinism.d.ts +4 -1
  41. package/dist/rules/determinism.js +175 -11
  42. package/dist/rules/gated.d.ts +7 -0
  43. package/dist/rules/gated.js +77 -0
  44. package/dist/rules/ids.d.ts +1 -1
  45. package/dist/rules/ids.js +9 -4
  46. package/dist/rules/index.d.ts +6 -0
  47. package/dist/rules/index.js +18 -6
  48. package/dist/rules/naming.d.ts +1 -1
  49. package/dist/rules/naming.js +91 -21
  50. package/dist/rules/rule.d.ts +25 -0
  51. package/dist/rules/rule.js +25 -1
  52. package/dist/rules/spec.d.ts +6 -0
  53. package/dist/rules/spec.js +56 -9
  54. package/dist/rules/write.d.ts +1 -1
  55. package/dist/rules/write.js +64 -14
  56. package/dist/session.d.ts +34 -9
  57. package/dist/session.js +525 -94
  58. package/dist/snapshot.d.ts +8 -2
  59. package/dist/snapshot.js +33 -2
  60. package/dist/types.d.ts +21 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +2 -2
package/dist/connect.js CHANGED
@@ -1,8 +1,12 @@
1
1
  import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
2
2
  import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/client/stdio';
3
3
  import { hasLogin, StoredOAuthProvider } from './auth.js';
4
+ import { explain, isCredentialHeader, Trace } from './explain.js';
5
+ import { endSession } from './close.js';
4
6
  import { eraOf } from './menu.js';
5
7
  import { VERSION } from './version.js';
8
+ export const PROTOCOLS = ['auto', 'legacy', 'modern'];
9
+ export const MODERN_VERSION = '2026-07-28';
6
10
  /** Every response the server sent, matched to the request method, as it came off the wire. */
7
11
  export class WireLog {
8
12
  responses = [];
@@ -46,10 +50,12 @@ export class WireLog {
46
50
  }
47
51
  }
48
52
  export async function connect(target, options = {}) {
49
- const client = new Client({ name: 'toolmenu', version: VERSION }, { versionNegotiation: { mode: 'auto' } });
53
+ const client = new Client({ name: 'toolmenu', version: VERSION }, { versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' } });
50
54
  let transport;
51
55
  let stderrText = '';
52
56
  let oauth = false;
57
+ const trace = new Trace();
58
+ let stdioStderr = null;
53
59
  if (target.kind === 'stdio') {
54
60
  const stdio = new StdioClientTransport({
55
61
  command: target.command,
@@ -59,8 +65,12 @@ export async function connect(target, options = {}) {
59
65
  stderr: 'pipe',
60
66
  });
61
67
  stdio.stderr?.on('data', (chunk) => {
62
- stderrText = (stderrText + chunk.toString()).slice(-4000);
68
+ const text = chunk.toString();
69
+ stderrText = (stderrText + text).slice(-4000);
70
+ trace.stderr(text);
63
71
  });
72
+ stdioStderr = stdio.stderr;
73
+ watchProcess(stdio, trace);
64
74
  transport = stdio;
65
75
  }
66
76
  else {
@@ -70,27 +80,42 @@ export async function connect(target, options = {}) {
70
80
  oauth = !target.noAuth && !ownAuth && hasLogin(target.url);
71
81
  transport = new StreamableHTTPClientTransport(new URL(target.url), {
72
82
  requestInit: { headers: target.headers ?? {} },
83
+ fetch: tracedFetch(trace),
73
84
  ...(oauth ? { authProvider: new StoredOAuthProvider(target.url) } : {}),
74
85
  });
75
86
  }
87
+ const context = { target, timeoutMs: options.timeoutMs, oauth, ...(target.protocol && target.protocol !== 'auto' ? { protocol: target.protocol } : {}) };
76
88
  try {
77
- await client.connect(transport, { timeout: options.timeoutMs });
89
+ // A URL that answered as a 2025 server earlier in this run isn't probed again:
90
+ // each server/discover gets a 400 there, one line in its log per connection.
91
+ const prior = target.kind === 'http' && (!target.protocol || target.protocol === 'auto') && LEGACY_URLS.has(target.url) ? { prior: { kind: 'legacy' } } : {};
92
+ await client.connect(transport, { timeout: options.timeoutMs, ...prior });
78
93
  }
79
94
  catch (error) {
80
- // Give stderr a moment to arrive: it usually says why the server exited.
81
- await new Promise((resolve) => setTimeout(resolve, 100));
82
- const stderr = stderrText.trim();
83
- if (stderr && error instanceof Error)
84
- error.message += `\nserver stderr:\n${stderr}`;
85
- if (target.kind === 'http' && !oauth && error instanceof Error && /\b401\b|unauthori[sz]ed/i.test(error.message)) {
86
- error.message += `\nIf the server uses OAuth, log in once with: toolmenu auth login ${target.url}`;
95
+ // What failed is fixed now: the exit that follows toolmenu's own SIGTERM isn't the server's doing.
96
+ trace.failedAt = Date.now();
97
+ // A server that never answered is stopped now, not after close()'s grace period for a clean exit.
98
+ if (trace.process && !trace.exit) {
99
+ trace.stopped = true;
100
+ trace.process.kill('SIGTERM');
87
101
  }
88
- await client.close().catch(() => { });
89
- throw error;
102
+ // Read stderr to its end: the last lines usually say why the server exited. A
103
+ // process that has exited closes its end of the pipe, so wait for all of it (a
104
+ // loaded CI runner took over a second for 300 lines, and the reason is last);
105
+ // one toolmenu just stopped gets a moment to exit first.
106
+ if (target.kind === 'stdio') {
107
+ if (!trace.exit)
108
+ await exited(trace, 1000);
109
+ await stderrEnded(stdioStderr, trace.exit ? STDERR_AFTER_EXIT_MS : 1000);
110
+ }
111
+ await endSession(client, transport);
112
+ throw explain(error, trace, context);
90
113
  }
91
114
  const wire = new WireLog();
92
115
  wire.tap(transport);
93
116
  const protocolVersion = client.getNegotiatedProtocolVersion();
117
+ if (target.kind === 'http' && eraOf(protocolVersion) === 'legacy')
118
+ LEGACY_URLS.add(target.url);
94
119
  const server = client.getServerVersion() ?? {};
95
120
  return {
96
121
  client,
@@ -100,25 +125,134 @@ export async function connect(target, options = {}) {
100
125
  server: { name: server.name, version: server.version },
101
126
  capabilities: (client.getServerCapabilities() ?? {}),
102
127
  usedAuth: target.kind === 'http' &&
103
- (oauth || Object.keys(target.headers ?? {}).some((h) => /^(authorization|x-api-key|api-key|cookie)$/i.test(h))),
128
+ (oauth || Object.keys(target.headers ?? {}).some(isCredentialHeader)),
104
129
  stderr: () => stderrText,
105
- close: () => client.close(),
130
+ close: () => endSession(client, transport),
131
+ explain: (error, stage) => explain(error, trace, { ...context, stage }),
132
+ stderrSettled: async () => {
133
+ if (target.kind !== 'stdio')
134
+ return;
135
+ // A server still running gets a moment to exit; one that exited is read to the end of its stderr.
136
+ if (!trace.exit)
137
+ await exited(trace, 200);
138
+ if (trace.exit)
139
+ await stderrEnded(stdioStderr, STDERR_AFTER_EXIT_MS);
140
+ },
141
+ };
142
+ }
143
+ /**
144
+ * HTTP servers that answered with the 2025 handshake in this process. Kept for the
145
+ * run only: a server upgraded between runs is probed afresh next time.
146
+ */
147
+ const LEGACY_URLS = new Set();
148
+ /** How long to wait for an exited server's stderr to end: its pipe is closing, so this is only a ceiling for a stuck one. */
149
+ const STDERR_AFTER_EXIT_MS = 10_000;
150
+ /** Resolves when the traced process has exited, or after `maxMs`. */
151
+ function exited(trace, maxMs) {
152
+ const child = trace.process;
153
+ if (!child || trace.exit)
154
+ return Promise.resolve();
155
+ return new Promise((resolve) => {
156
+ const timer = setTimeout(resolve, maxMs);
157
+ child.once('exit', () => {
158
+ clearTimeout(timer);
159
+ // The exit listener that records trace.exit runs first: it was added at spawn.
160
+ resolve();
161
+ });
162
+ });
163
+ }
164
+ /** Resolves when `stream` has ended, or after `maxMs`. */
165
+ function stderrEnded(stream, maxMs) {
166
+ if (!stream || maxMs <= 0 || stream.readableEnded)
167
+ return Promise.resolve();
168
+ return new Promise((resolve) => {
169
+ const timer = setTimeout(resolve, maxMs);
170
+ stream.once('end', () => {
171
+ clearTimeout(timer);
172
+ resolve();
173
+ });
174
+ });
175
+ }
176
+ /**
177
+ * Watch the stdio process toolmenu keeps (not the throwaway one the SDK starts
178
+ * for the server/discover probe): when it started, what it was asked, what it
179
+ * answered, its exit, and stdout lines that aren't JSON-RPC. The hooks go on this
180
+ * instance only: the SDK clones the transport's class for the probe.
181
+ */
182
+ function watchProcess(stdio, trace) {
183
+ const start = stdio.start.bind(stdio);
184
+ stdio.start = async () => {
185
+ trace.sessionStartedAt = Date.now();
186
+ const onmessage = stdio.onmessage;
187
+ const ids = new Map();
188
+ const t = stdio;
189
+ t.onmessage = (message, extra) => {
190
+ if (!('method' in message) && 'id' in message && message.id !== undefined) {
191
+ const method = ids.get(message.id);
192
+ if (method)
193
+ trace.answered.add(method);
194
+ }
195
+ onmessage?.(message, extra);
196
+ };
197
+ const send = t.send.bind(stdio);
198
+ t.send = (message, options) => {
199
+ if ('method' in message && 'id' in message && message.id !== undefined) {
200
+ ids.set(message.id, message.method);
201
+ trace.send(message.method);
202
+ }
203
+ return send(message, options);
204
+ };
205
+ await start();
206
+ const child = stdio._process;
207
+ if (child) {
208
+ trace.process = child;
209
+ child.once('exit', (code, signal) => (trace.exit = { code, signal, afterStop: trace.stopped }));
210
+ child.stdout?.on('data', (chunk) => trace.stdout(chunk.toString()));
211
+ }
212
+ };
213
+ }
214
+ /** fetch, noting each JSON-RPC request's method and the answer's status, content type and final URL. */
215
+ function tracedFetch(trace) {
216
+ return async (input, init) => {
217
+ let method;
218
+ if (typeof init?.body === 'string') {
219
+ try {
220
+ const body = JSON.parse(init.body);
221
+ if (typeof body.method === 'string' && body.id !== undefined)
222
+ method = body.method;
223
+ }
224
+ catch {
225
+ // Not JSON: not a request to trace.
226
+ }
227
+ }
228
+ if (method)
229
+ trace.send(method);
230
+ const response = await fetch(input, init);
231
+ if (method) {
232
+ trace.http.set(method, { status: response.status, statusText: response.statusText, contentType: response.headers.get('content-type') ?? '', url: response.url });
233
+ }
234
+ return response;
106
235
  };
107
236
  }
108
237
  /** One full `tools/list`, bypassing the SDK's cache, read from the wire rather than the SDK's parsed copy. */
109
238
  export async function listTools(connection, options = {}) {
110
239
  const mark = connection.wire.responses.length;
111
240
  let clientError;
241
+ let caught;
112
242
  try {
113
243
  await connection.client.listTools(undefined, { cacheMode: 'bypass', timeout: options.timeoutMs });
114
244
  }
115
245
  catch (error) {
246
+ caught = error;
116
247
  clientError = error instanceof Error ? error.message : String(error);
117
248
  }
118
249
  const responses = connection.wire.since(mark, 'tools/list');
119
250
  const pages = responses.flatMap((r) => (r.result ? [r.result] : []));
120
- if (clientError && pages.length === 0)
121
- throw new Error(clientError);
251
+ if (clientError && pages.length === 0) {
252
+ // Let stderr arrive first, as for connect: the reason is usually its last lines.
253
+ await connection.stderrSettled?.();
254
+ throw connection.explain?.(caught, 'tools/list') ?? new Error(clientError);
255
+ }
122
256
  const first = pages[0] ?? {};
123
257
  return {
124
258
  tools: pages.flatMap((p) => (Array.isArray(p.tools) ? p.tools : [])),
package/dist/diff.d.ts CHANGED
@@ -3,8 +3,14 @@ export type ChangeClass = 'breaking' | 'minor' | 'notice';
3
3
  export type Bump = 'major' | 'minor' | 'patch' | 'none';
4
4
  export interface DiffFinding extends Finding {
5
5
  class?: ChangeClass;
6
- /** Every place one change was found, when it's reached from several (a shared definition). */
6
+ /** Every place one change was found, when it's reached from several (a shared definition, or several tools). */
7
7
  places?: string[];
8
+ /**
9
+ * Every tool the change was found in, when it's the same change in several
10
+ * (same rule, same parameter path, same schema before and after). `tool` is
11
+ * then left out. Counts are per change: one finding, however many tools.
12
+ */
13
+ tools?: string[];
8
14
  }
9
15
  interface DiffRule {
10
16
  severity: Severity;
@@ -24,13 +30,29 @@ export interface TokenChange {
24
30
  delta: number;
25
31
  }[];
26
32
  }
33
+ /** Per class: how many changes (findings), and how many tools they touch. */
34
+ export type ClassCounts = Record<ChangeClass, {
35
+ changes: number;
36
+ tools: number;
37
+ }>;
27
38
  export interface DiffResult {
28
39
  before: Menu['server'];
29
40
  after: Menu['server'];
30
41
  findings: DiffFinding[];
31
42
  tokens: TokenChange;
43
+ /** Breaking, minor and notice changes: counted per change, with the tools they touch. */
44
+ classes: ClassCounts;
45
+ /** What the changes call for by semver: breaking → major, new → minor, other → patch. */
32
46
  suggestedBump: Bump;
47
+ /**
48
+ * The smallest bump the release line needs (with a release to check): the
49
+ * suggested one, one step lower under 1.0.0 (npm's caret: ^0.2.3 accepts
50
+ * 0.2.x), none under 0.1.0.
51
+ */
52
+ requiredBump?: Bump;
33
53
  actualBump?: Bump;
54
+ /** When the actual bump is too small: the version to release instead (2.0.0). */
55
+ releaseAs?: string;
34
56
  /** The versions the bump was checked against, and where they came from. */
35
57
  release?: {
36
58
  before: string;