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.
- package/README.md +150 -30
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +61 -18
- package/dist/auto.d.ts +71 -7
- package/dist/auto.js +267 -13
- package/dist/breakdown.d.ts +35 -6
- package/dist/breakdown.js +179 -23
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +116 -178
- package/dist/compare.js +20 -5
- package/dist/config.d.ts +5 -1
- package/dist/config.js +14 -0
- package/dist/connect.d.ts +4 -0
- package/dist/connect.js +132 -11
- package/dist/diff.d.ts +35 -1
- package/dist/diff.js +1132 -121
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +103 -0
- package/dist/explain.js +434 -0
- package/dist/failures.d.ts +55 -0
- package/dist/failures.js +103 -0
- package/dist/help.d.ts +9 -0
- package/dist/help.js +198 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +100 -5
- package/dist/init.js +520 -26
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +135 -0
- package/dist/options.js +48 -0
- package/dist/probe.d.ts +15 -3
- package/dist/probe.js +35 -11
- package/dist/report.d.ts +1 -1
- package/dist/report.js +229 -99
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +89 -43
- package/dist/rules/determinism.d.ts +3 -1
- package/dist/rules/determinism.js +146 -11
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +15 -5
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +66 -19
- package/dist/rules/rule.d.ts +18 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +2 -0
- package/dist/rules/spec.js +61 -8
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +42 -10
- package/dist/semver.js +1 -1
- package/dist/session.d.ts +56 -7
- package/dist/session.js +800 -94
- package/dist/snapshot.d.ts +2 -2
- package/dist/snapshot.js +25 -7
- package/dist/types.d.ts +14 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- 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
|
-
|
|
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
|
-
//
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
if (
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
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 {};
|