toolmenu 0.10.0 → 0.11.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 +11 -9
- package/dist/catalog.d.ts +20 -0
- package/dist/catalog.js +97 -14
- package/dist/config.d.ts +3 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -29,7 +29,7 @@ No LLM anywhere: the same inputs give the same answer, so it can sit in CI.
|
|
|
29
29
|
(`history` installs old versions with today's dependencies, so it records what they
|
|
30
30
|
serve now, which can differ from what they shipped with: FINDINGS F4.)
|
|
31
31
|
|
|
32
|
-
> **Status: 0.
|
|
32
|
+
> **Status: 0.11, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
|
|
33
33
|
> real servers: [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
|
|
34
34
|
|
|
35
35
|
## Start here
|
|
@@ -90,7 +90,7 @@ jobs:
|
|
|
90
90
|
- uses: actions/setup-node@v7
|
|
91
91
|
with: { node-version: 22 }
|
|
92
92
|
- run: npm ci && npm run build
|
|
93
|
-
- uses: niksa90/toolmenu@v0.
|
|
93
|
+
- uses: niksa90/toolmenu@v0.11.0
|
|
94
94
|
with:
|
|
95
95
|
command: node dist/server.js
|
|
96
96
|
baseline: menu.json # your committed snapshot
|
|
@@ -222,13 +222,15 @@ operations found in both snapshots with the same rules as tools.
|
|
|
222
222
|
npx toolmenu snapshot --catalog -- node dist/server.js
|
|
223
223
|
```
|
|
224
224
|
|
|
225
|
-
A search returns its top matches,
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
in
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
225
|
+
A search returns only its top matches, so toolmenu crawls the catalog by its own
|
|
226
|
+
words: it starts from the search tool's own example phrases and the nouns in your tool
|
|
227
|
+
names, then searches for every operation it finds or sees mentioned, until 20 queries
|
|
228
|
+
in a row turn up nothing new (at most 200). On Atlassian's hosted server that finds all
|
|
229
|
+
154 operations behind its 21 tools; on Sentry's, 65 behind 9, the same on every run.
|
|
230
|
+
Queries are paced and a rate limit is waited out. An operation not found this time is a
|
|
231
|
+
notice ("not returned by the same queries"), never "removed". To steer it, set
|
|
232
|
+
`"catalog": { "queries": [...], "maxQueries": 200, "crawl": true }` in
|
|
233
|
+
`toolmenu.config.json` (FINDINGS F15).
|
|
232
234
|
|
|
233
235
|
## `history`: a package's releases, researched
|
|
234
236
|
|
package/dist/catalog.d.ts
CHANGED
|
@@ -27,6 +27,12 @@ export interface CatalogOptions {
|
|
|
27
27
|
timeoutMs?: number;
|
|
28
28
|
/** Pause between queries, ms (default 300): hosted servers rate-limit searches (Sentry did). */
|
|
29
29
|
pauseMs?: number;
|
|
30
|
+
/** Follow the catalog's own words: search for each operation found or mentioned (default true). */
|
|
31
|
+
crawl?: boolean;
|
|
32
|
+
/** At most this many queries (default 200). */
|
|
33
|
+
maxQueries?: number;
|
|
34
|
+
/** Stop after this many queries in a row find nothing new (default 20): the catalog is exhausted. */
|
|
35
|
+
stopAfter?: number;
|
|
30
36
|
}
|
|
31
37
|
/** The menu's catalog search tool: read-only, one required query, named like one. */
|
|
32
38
|
export declare function findCatalogTool(tools: MenuTool[]): MenuTool | undefined;
|
|
@@ -48,3 +54,17 @@ export declare function operationsIn(result: {
|
|
|
48
54
|
structuredContent?: unknown;
|
|
49
55
|
content?: unknown;
|
|
50
56
|
}): MenuTool[];
|
|
57
|
+
/**
|
|
58
|
+
* The JSON value a text starts with, ignoring what follows: Atlassian's discover
|
|
59
|
+
* returns its results as JSON and then a prose list of related operations, which
|
|
60
|
+
* makes the whole text invalid JSON.
|
|
61
|
+
*/
|
|
62
|
+
export declare function leadingJson(text: string): unknown;
|
|
63
|
+
/**
|
|
64
|
+
* Operation names a result mentions without defining them: lines like
|
|
65
|
+
* "createJiraBoard — Create a new company-managed…" after Atlassian's JSON. Each
|
|
66
|
+
* is worth a search of its own.
|
|
67
|
+
*/
|
|
68
|
+
export declare function mentionedNames(result: {
|
|
69
|
+
content?: unknown;
|
|
70
|
+
}): string[];
|
package/dist/catalog.js
CHANGED
|
@@ -35,13 +35,33 @@ export async function readCatalog(conn, tools, options = {}) {
|
|
|
35
35
|
throw new Error(options.tool ? `--catalog: no tool named ${options.tool} in the menu.` : '--catalog: no catalog search tool in the menu (read-only, one required query, named like search_*_tools or discover). Name it with catalog.tool in the config.');
|
|
36
36
|
const queryParam = tool.inputSchema.required[0];
|
|
37
37
|
const limit = limitArg(tool.inputSchema);
|
|
38
|
-
|
|
38
|
+
// Seeds, then the catalog's own words: every operation found or mentioned is
|
|
39
|
+
// searched for by name, which finds it and its neighbours. Breadth first, in the
|
|
40
|
+
// order found, so the same catalog gives the same queries.
|
|
41
|
+
const queue = [...new Set(options.queries ?? [...describedExamples(tool), ...defaultQueries(tools)])];
|
|
42
|
+
const crawl = options.crawl ?? true;
|
|
43
|
+
// Crawl until the catalog stops yielding: a small one ends early, a big one
|
|
44
|
+
// (Atlassian's ~300 operations) goes on, up to the cap.
|
|
45
|
+
const maxQueries = options.maxQueries ?? 200;
|
|
46
|
+
const stopAfter = options.stopAfter ?? 20;
|
|
47
|
+
let dry = 0;
|
|
48
|
+
const asked = [];
|
|
49
|
+
const queued = new Set(queue);
|
|
50
|
+
const enqueue = (name) => {
|
|
51
|
+
const q = phrase(name);
|
|
52
|
+
if (crawl && q && !queued.has(q)) {
|
|
53
|
+
queued.add(q);
|
|
54
|
+
queue.push(q);
|
|
55
|
+
}
|
|
56
|
+
};
|
|
39
57
|
const found = new Map();
|
|
40
58
|
const failed = [];
|
|
41
59
|
const pause = options.pauseMs ?? 300;
|
|
42
|
-
|
|
43
|
-
|
|
60
|
+
while (queue.length && asked.length < maxQueries && dry < stopAfter) {
|
|
61
|
+
const query = queue.shift();
|
|
62
|
+
if (asked.length > 0)
|
|
44
63
|
await sleep(pause);
|
|
64
|
+
asked.push(query);
|
|
45
65
|
// A rate limit is waited out (2 s, 4 s, 8 s); anything else, or a limit that
|
|
46
66
|
// persists, leaves this query out and the catalog partial, never the snapshot
|
|
47
67
|
// failed: diff treats operations not found as notices.
|
|
@@ -55,10 +75,19 @@ export async function readCatalog(conn, tools, options = {}) {
|
|
|
55
75
|
}
|
|
56
76
|
if (result.isError)
|
|
57
77
|
failed.push({ query, error: text.slice(0, 200) || 'the tool returned an error' });
|
|
58
|
-
else
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
78
|
+
else {
|
|
79
|
+
const before = found.size;
|
|
80
|
+
for (const op of operationsIn(result)) {
|
|
81
|
+
if (found.has(op.name))
|
|
82
|
+
continue;
|
|
83
|
+
found.set(op.name, op);
|
|
84
|
+
enqueue(op.name);
|
|
85
|
+
}
|
|
86
|
+
for (const name of mentionedNames(result))
|
|
87
|
+
if (!found.has(name))
|
|
88
|
+
enqueue(name);
|
|
89
|
+
dry = found.size > before ? 0 : dry + 1;
|
|
90
|
+
}
|
|
62
91
|
break;
|
|
63
92
|
}
|
|
64
93
|
catch (error) {
|
|
@@ -73,7 +102,24 @@ export async function readCatalog(conn, tools, options = {}) {
|
|
|
73
102
|
}
|
|
74
103
|
}
|
|
75
104
|
const operations = [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
|
|
76
|
-
return { tool: tool.name, queries, operations, ...(failed.length ? { failed } : {}) };
|
|
105
|
+
return { tool: tool.name, queries: asked, operations, ...(failed.length ? { failed } : {}) };
|
|
106
|
+
}
|
|
107
|
+
/** An operation name as a search phrase: listJiraIssueWorklogs → "list jira issue worklogs". */
|
|
108
|
+
function phrase(name) {
|
|
109
|
+
return name
|
|
110
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
|
|
111
|
+
.split(/[^A-Za-z0-9]+/)
|
|
112
|
+
.filter(Boolean)
|
|
113
|
+
.map((w) => w.toLowerCase())
|
|
114
|
+
.join(' ');
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Example queries the search tool's own schema suggests: Atlassian's discover
|
|
118
|
+
* documents its query with "transition a jira issue", "list confluence spaces"…
|
|
119
|
+
*/
|
|
120
|
+
function describedExamples(tool) {
|
|
121
|
+
const text = [tool.description ?? '', ...Object.values(tool.inputSchema?.properties ?? {}).map((p) => String(p.description ?? ''))].join(' ');
|
|
122
|
+
return [...text.matchAll(/["“]([a-z][a-z0-9 ,'-]{5,60})["”]/g)].map((m) => m[1]).filter((q) => q.includes(' '));
|
|
77
123
|
}
|
|
78
124
|
const RATE_LIMIT = /rate.?limit|too many requests|\b429\b/i;
|
|
79
125
|
function sleep(ms) {
|
|
@@ -108,12 +154,9 @@ export function operationsIn(result) {
|
|
|
108
154
|
const text = part.text;
|
|
109
155
|
if (typeof text !== 'string')
|
|
110
156
|
continue;
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
catch {
|
|
115
|
-
// prose, not a catalog
|
|
116
|
-
}
|
|
157
|
+
const value = leadingJson(text);
|
|
158
|
+
if (value !== undefined)
|
|
159
|
+
roots.push(value);
|
|
117
160
|
}
|
|
118
161
|
const out = new Map();
|
|
119
162
|
const walk = (v, depth) => {
|
|
@@ -132,6 +175,46 @@ export function operationsIn(result) {
|
|
|
132
175
|
roots.forEach((r) => walk(r, 0));
|
|
133
176
|
return [...out.values()];
|
|
134
177
|
}
|
|
178
|
+
/**
|
|
179
|
+
* The JSON value a text starts with, ignoring what follows: Atlassian's discover
|
|
180
|
+
* returns its results as JSON and then a prose list of related operations, which
|
|
181
|
+
* makes the whole text invalid JSON.
|
|
182
|
+
*/
|
|
183
|
+
export function leadingJson(text) {
|
|
184
|
+
const trimmed = text.trimStart();
|
|
185
|
+
if (!/^[[{]/.test(trimmed))
|
|
186
|
+
return undefined;
|
|
187
|
+
try {
|
|
188
|
+
return JSON.parse(trimmed);
|
|
189
|
+
}
|
|
190
|
+
catch (error) {
|
|
191
|
+
const at = /position (\d+)/.exec(error instanceof Error ? error.message : '');
|
|
192
|
+
if (!at)
|
|
193
|
+
return undefined;
|
|
194
|
+
try {
|
|
195
|
+
return JSON.parse(trimmed.slice(0, Number(at[1])));
|
|
196
|
+
}
|
|
197
|
+
catch {
|
|
198
|
+
return undefined;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Operation names a result mentions without defining them: lines like
|
|
204
|
+
* "createJiraBoard — Create a new company-managed…" after Atlassian's JSON. Each
|
|
205
|
+
* is worth a search of its own.
|
|
206
|
+
*/
|
|
207
|
+
export function mentionedNames(result) {
|
|
208
|
+
const names = new Set();
|
|
209
|
+
for (const part of Array.isArray(result.content) ? result.content : []) {
|
|
210
|
+
const text = part.text;
|
|
211
|
+
if (typeof text !== 'string')
|
|
212
|
+
continue;
|
|
213
|
+
for (const m of text.matchAll(/^[ \t]*[-*]?[ \t]*`?([A-Za-z][A-Za-z0-9_.-]{2,80})`?[ \t]+(?:—|–|-{1,2}|:)[ \t]/gm))
|
|
214
|
+
names.add(m[1]);
|
|
215
|
+
}
|
|
216
|
+
return [...names];
|
|
217
|
+
}
|
|
135
218
|
function asOperation(o) {
|
|
136
219
|
if (typeof o.name !== 'string' || !o.name)
|
|
137
220
|
return undefined;
|
package/dist/config.d.ts
CHANGED