toolmenu 0.11.0 → 0.13.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 +150 -30
  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 +61 -18
  6. package/dist/auto.d.ts +71 -7
  7. package/dist/auto.js +267 -13
  8. package/dist/breakdown.d.ts +35 -6
  9. package/dist/breakdown.js +179 -23
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +116 -178
  13. package/dist/compare.js +20 -5
  14. package/dist/config.d.ts +5 -1
  15. package/dist/config.js +14 -0
  16. package/dist/connect.d.ts +4 -0
  17. package/dist/connect.js +132 -11
  18. package/dist/diff.d.ts +35 -1
  19. package/dist/diff.js +1132 -121
  20. package/dist/difference.d.ts +2 -0
  21. package/dist/difference.js +13 -12
  22. package/dist/explain.d.ts +103 -0
  23. package/dist/explain.js +434 -0
  24. package/dist/failures.d.ts +55 -0
  25. package/dist/failures.js +103 -0
  26. package/dist/help.d.ts +9 -0
  27. package/dist/help.js +198 -0
  28. package/dist/history.d.ts +13 -0
  29. package/dist/history.js +86 -6
  30. package/dist/init.d.ts +100 -5
  31. package/dist/init.js +520 -26
  32. package/dist/menu.js +10 -2
  33. package/dist/options.d.ts +135 -0
  34. package/dist/options.js +48 -0
  35. package/dist/probe.d.ts +15 -3
  36. package/dist/probe.js +35 -11
  37. package/dist/report.d.ts +1 -1
  38. package/dist/report.js +229 -99
  39. package/dist/rules/description.d.ts +7 -2
  40. package/dist/rules/description.js +89 -43
  41. package/dist/rules/determinism.d.ts +3 -1
  42. package/dist/rules/determinism.js +146 -11
  43. package/dist/rules/ids.d.ts +1 -1
  44. package/dist/rules/ids.js +9 -4
  45. package/dist/rules/index.d.ts +6 -0
  46. package/dist/rules/index.js +15 -5
  47. package/dist/rules/naming.d.ts +1 -1
  48. package/dist/rules/naming.js +66 -19
  49. package/dist/rules/rule.d.ts +18 -0
  50. package/dist/rules/rule.js +25 -1
  51. package/dist/rules/spec.d.ts +2 -0
  52. package/dist/rules/spec.js +61 -8
  53. package/dist/rules/write.d.ts +1 -1
  54. package/dist/rules/write.js +42 -10
  55. package/dist/semver.js +1 -1
  56. package/dist/session.d.ts +56 -7
  57. package/dist/session.js +800 -94
  58. package/dist/snapshot.d.ts +2 -2
  59. package/dist/snapshot.js +25 -7
  60. package/dist/types.d.ts +14 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +1 -1
package/dist/connect.js CHANGED
@@ -1,6 +1,7 @@
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, Trace } from './explain.js';
4
5
  import { eraOf } from './menu.js';
5
6
  import { VERSION } from './version.js';
6
7
  /** Every response the server sent, matched to the request method, as it came off the wire. */
@@ -50,6 +51,8 @@ export async function connect(target, options = {}) {
50
51
  let transport;
51
52
  let stderrText = '';
52
53
  let oauth = false;
54
+ const trace = new Trace();
55
+ let stdioStderr = null;
53
56
  if (target.kind === 'stdio') {
54
57
  const stdio = new StdioClientTransport({
55
58
  command: target.command,
@@ -59,8 +62,12 @@ export async function connect(target, options = {}) {
59
62
  stderr: 'pipe',
60
63
  });
61
64
  stdio.stderr?.on('data', (chunk) => {
62
- stderrText = (stderrText + chunk.toString()).slice(-4000);
65
+ const text = chunk.toString();
66
+ stderrText = (stderrText + text).slice(-4000);
67
+ trace.stderr(text);
63
68
  });
69
+ stdioStderr = stdio.stderr;
70
+ watchProcess(stdio, trace);
64
71
  transport = stdio;
65
72
  }
66
73
  else {
@@ -70,23 +77,33 @@ export async function connect(target, options = {}) {
70
77
  oauth = !target.noAuth && !ownAuth && hasLogin(target.url);
71
78
  transport = new StreamableHTTPClientTransport(new URL(target.url), {
72
79
  requestInit: { headers: target.headers ?? {} },
80
+ fetch: tracedFetch(trace),
73
81
  ...(oauth ? { authProvider: new StoredOAuthProvider(target.url) } : {}),
74
82
  });
75
83
  }
84
+ const context = { target, timeoutMs: options.timeoutMs, oauth };
76
85
  try {
77
86
  await client.connect(transport, { timeout: options.timeoutMs });
78
87
  }
79
88
  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}`;
89
+ // What failed is fixed now: the exit that follows toolmenu's own SIGTERM isn't the server's doing.
90
+ trace.failedAt = Date.now();
91
+ // A server that never answered is stopped now, not after close()'s grace period for a clean exit.
92
+ if (trace.process && !trace.exit) {
93
+ trace.stopped = true;
94
+ trace.process.kill('SIGTERM');
95
+ }
96
+ // Read stderr to its end: the last lines usually say why the server exited. A
97
+ // process that has exited closes its end of the pipe, so wait for all of it (a
98
+ // loaded CI runner took over a second for 300 lines, and the reason is last);
99
+ // one toolmenu just stopped gets a moment to exit first.
100
+ if (target.kind === 'stdio') {
101
+ if (!trace.exit)
102
+ await exited(trace, 1000);
103
+ await stderrEnded(stdioStderr, trace.exit ? STDERR_AFTER_EXIT_MS : 1000);
87
104
  }
88
105
  await client.close().catch(() => { });
89
- throw error;
106
+ throw explain(error, trace, context);
90
107
  }
91
108
  const wire = new WireLog();
92
109
  wire.tap(transport);
@@ -103,22 +120,126 @@ export async function connect(target, options = {}) {
103
120
  (oauth || Object.keys(target.headers ?? {}).some((h) => /^(authorization|x-api-key|api-key|cookie)$/i.test(h))),
104
121
  stderr: () => stderrText,
105
122
  close: () => client.close(),
123
+ explain: (error, stage) => explain(error, trace, { ...context, stage }),
124
+ stderrSettled: async () => {
125
+ if (target.kind !== 'stdio')
126
+ return;
127
+ // A server still running gets a moment to exit; one that exited is read to the end of its stderr.
128
+ if (!trace.exit)
129
+ await exited(trace, 200);
130
+ if (trace.exit)
131
+ await stderrEnded(stdioStderr, STDERR_AFTER_EXIT_MS);
132
+ },
133
+ };
134
+ }
135
+ /** 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. */
136
+ const STDERR_AFTER_EXIT_MS = 10_000;
137
+ /** Resolves when the traced process has exited, or after `maxMs`. */
138
+ function exited(trace, maxMs) {
139
+ const child = trace.process;
140
+ if (!child || trace.exit)
141
+ return Promise.resolve();
142
+ return new Promise((resolve) => {
143
+ const timer = setTimeout(resolve, maxMs);
144
+ child.once('exit', () => {
145
+ clearTimeout(timer);
146
+ // The exit listener that records trace.exit runs first: it was added at spawn.
147
+ resolve();
148
+ });
149
+ });
150
+ }
151
+ /** Resolves when `stream` has ended, or after `maxMs`. */
152
+ function stderrEnded(stream, maxMs) {
153
+ if (!stream || maxMs <= 0 || stream.readableEnded)
154
+ return Promise.resolve();
155
+ return new Promise((resolve) => {
156
+ const timer = setTimeout(resolve, maxMs);
157
+ stream.once('end', () => {
158
+ clearTimeout(timer);
159
+ resolve();
160
+ });
161
+ });
162
+ }
163
+ /**
164
+ * Watch the stdio process toolmenu keeps (not the throwaway one the SDK starts
165
+ * for the server/discover probe): when it started, what it was asked, what it
166
+ * answered, its exit, and stdout lines that aren't JSON-RPC. The hooks go on this
167
+ * instance only: the SDK clones the transport's class for the probe.
168
+ */
169
+ function watchProcess(stdio, trace) {
170
+ const start = stdio.start.bind(stdio);
171
+ stdio.start = async () => {
172
+ trace.sessionStartedAt = Date.now();
173
+ const onmessage = stdio.onmessage;
174
+ const ids = new Map();
175
+ const t = stdio;
176
+ t.onmessage = (message, extra) => {
177
+ if (!('method' in message) && 'id' in message && message.id !== undefined) {
178
+ const method = ids.get(message.id);
179
+ if (method)
180
+ trace.answered.add(method);
181
+ }
182
+ onmessage?.(message, extra);
183
+ };
184
+ const send = t.send.bind(stdio);
185
+ t.send = (message, options) => {
186
+ if ('method' in message && 'id' in message && message.id !== undefined) {
187
+ ids.set(message.id, message.method);
188
+ trace.send(message.method);
189
+ }
190
+ return send(message, options);
191
+ };
192
+ await start();
193
+ const child = stdio._process;
194
+ if (child) {
195
+ trace.process = child;
196
+ child.once('exit', (code, signal) => (trace.exit = { code, signal, afterStop: trace.stopped }));
197
+ child.stdout?.on('data', (chunk) => trace.stdout(chunk.toString()));
198
+ }
199
+ };
200
+ }
201
+ /** fetch, noting each JSON-RPC request's method and the answer's status, content type and final URL. */
202
+ function tracedFetch(trace) {
203
+ return async (input, init) => {
204
+ let method;
205
+ if (typeof init?.body === 'string') {
206
+ try {
207
+ const body = JSON.parse(init.body);
208
+ if (typeof body.method === 'string' && body.id !== undefined)
209
+ method = body.method;
210
+ }
211
+ catch {
212
+ // Not JSON: not a request to trace.
213
+ }
214
+ }
215
+ if (method)
216
+ trace.send(method);
217
+ const response = await fetch(input, init);
218
+ if (method) {
219
+ trace.http.set(method, { status: response.status, statusText: response.statusText, contentType: response.headers.get('content-type') ?? '', url: response.url });
220
+ }
221
+ return response;
106
222
  };
107
223
  }
108
224
  /** One full `tools/list`, bypassing the SDK's cache, read from the wire rather than the SDK's parsed copy. */
109
225
  export async function listTools(connection, options = {}) {
110
226
  const mark = connection.wire.responses.length;
111
227
  let clientError;
228
+ let caught;
112
229
  try {
113
230
  await connection.client.listTools(undefined, { cacheMode: 'bypass', timeout: options.timeoutMs });
114
231
  }
115
232
  catch (error) {
233
+ caught = error;
116
234
  clientError = error instanceof Error ? error.message : String(error);
117
235
  }
118
236
  const responses = connection.wire.since(mark, 'tools/list');
119
237
  const pages = responses.flatMap((r) => (r.result ? [r.result] : []));
120
- if (clientError && pages.length === 0)
121
- throw new Error(clientError);
238
+ if (clientError && pages.length === 0) {
239
+ // Let stderr arrive first, as for connect: the reason is usually its last lines.
240
+ await connection.stderrSettled?.();
241
+ throw connection.explain?.(caught, 'tools/list') ?? new Error(clientError);
242
+ }
122
243
  const first = pages[0] ?? {};
123
244
  return {
124
245
  tools: pages.flatMap((p) => (Array.isArray(p.tools) ? p.tools : [])),
package/dist/diff.d.ts CHANGED
@@ -1,8 +1,16 @@
1
- import type { Finding, Menu, Severity } from './types.js';
1
+ import type { Finding, JsonSchema, Menu, 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 {
5
5
  class?: ChangeClass;
6
+ /** Every place one change was found, when it's reached from several (a shared definition, or several tools). */
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[];
6
14
  }
7
15
  interface DiffRule {
8
16
  severity: Severity;
@@ -22,13 +30,29 @@ export interface TokenChange {
22
30
  delta: number;
23
31
  }[];
24
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
+ }>;
25
38
  export interface DiffResult {
26
39
  before: Menu['server'];
27
40
  after: Menu['server'];
28
41
  findings: DiffFinding[];
29
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. */
30
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;
31
53
  actualBump?: Bump;
54
+ /** When the actual bump is too small: the version to release instead (2.0.0). */
55
+ releaseAs?: string;
32
56
  /** The versions the bump was checked against, and where they came from. */
33
57
  release?: {
34
58
  before: string;
@@ -54,5 +78,15 @@ export interface DiffOptions {
54
78
  serverVersionIsRelease?: boolean;
55
79
  }
56
80
  export declare function diffMenus(before: Menu, after: Menu, options?: DiffOptions): DiffResult;
81
+ /**
82
+ * The schema with local $refs (`#/$defs/…`, `#/definitions/…`) replaced by what
83
+ * they point to, and the root $defs dropped: two spellings of one schema compare
84
+ * equal. A recursive definition is unrolled MAX_UNROLL level, then left as a
85
+ * $ref: a change to it shows in the levels above, and its $defs entry needn't be
86
+ * kept (keeping it made a recursive schema compare unequal to its own refactor,
87
+ * with nothing reported). A $ref toolmenu can't follow (another document) stays as
88
+ * it is. Keywords next to a $ref (a description) win over the target's.
89
+ */
90
+ export declare function resolveRefs(schema: JsonSchema | undefined): JsonSchema | undefined;
57
91
  export declare function versionBump(before: string | undefined, after: string | undefined): Bump | undefined;
58
92
  export {};