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
@@ -2,7 +2,7 @@ import { type Target } from './connect.js';
2
2
  import { type RuleSettings } from './rules/index.js';
3
3
  import { type CatalogOptions } from './catalog.js';
4
4
  import type { Routes } from './routes.js';
5
- import type { Finding, Menu } from './types.js';
5
+ import { type Finding, type Menu } from './types.js';
6
6
  export interface SnapshotOptions extends RuleSettings {
7
7
  routes?: Routes;
8
8
  timeoutMs?: number;
@@ -13,7 +13,7 @@ export interface SnapshotOptions extends RuleSettings {
13
13
  * included. Default 2; 1 turns the check off.
14
14
  */
15
15
  processes?: number;
16
- /** Also read the operations behind a catalog search tool (true, or which tool and queries). */
16
+ /** Also read the operations behind a catalog search tool or command routers (true, or which ones and how). */
17
17
  catalog?: boolean | CatalogOptions;
18
18
  }
19
19
  export interface SnapshotResult {
package/dist/snapshot.js CHANGED
@@ -1,17 +1,22 @@
1
- import { connect, listTools } from './connect.js';
1
+ import { listTools } from './connect.js';
2
+ import { patiently, tooMany } from './failures.js';
3
+ import { ConnectError } from './explain.js';
2
4
  import { buildMenu } from './menu.js';
3
- import { isContainerWrapper, MAIN_SEED, probeVariance, seeded } from './probe.js';
5
+ import { connectPatiently, isContainerWrapper, MAIN_SEED, probeVariance, seeded } from './probe.js';
4
6
  import { MENU_RULES, runRules } from './rules/index.js';
5
- import { readCatalog } from './catalog.js';
7
+ import { catalogFindings, readCatalog } from './catalog.js';
8
+ import { SEVERITY_RANK } from './types.js';
6
9
  /** Establish the menu: connect, list the tools twice, run the menu rules. */
7
10
  export async function snapshot(target, options = {}) {
8
- const connection = await connect(seeded(target, MAIN_SEED), { timeoutMs: options.timeoutMs });
11
+ // Connecting and listing are read-only: a refusal for being too many is waited
12
+ // out and they're sent again (CI behind a shared rate limit).
13
+ const connection = await connectPatiently(seeded(target, MAIN_SEED), { timeoutMs: options.timeoutMs });
9
14
  let menu;
10
15
  let secondList;
11
16
  let first;
12
17
  try {
13
- first = await listTools(connection, options);
14
- const second = await listTools(connection, options);
18
+ first = await patiently(() => listTools(connection, options), { error: tooMany });
19
+ const second = await patiently(() => listTools(connection, options), { error: tooMany });
15
20
  const server = {
16
21
  name: connection.server.name,
17
22
  version: connection.server.version,
@@ -26,7 +31,8 @@ export async function snapshot(target, options = {}) {
26
31
  }
27
32
  catch (error) {
28
33
  const stderr = connection.stderr().trim();
29
- if (stderr && error instanceof Error)
34
+ // A ConnectError already shows the stderr lines that matter.
35
+ if (stderr && error instanceof Error && !(error instanceof ConnectError))
30
36
  error.message += `\nserver stderr:\n${stderr}`;
31
37
  throw error;
32
38
  }
@@ -52,5 +58,17 @@ export async function snapshot(target, options = {}) {
52
58
  probes,
53
59
  wrapper: isContainerWrapper(target),
54
60
  }, options);
61
+ // What --catalog called and what it got, under the same settings as the rules
62
+ // (rules: { "catalog/read": "off" }, ignore).
63
+ if (menu.catalog) {
64
+ const ignore = (options.ignore ?? []).map((g) => new RegExp('^' + g.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$'));
65
+ for (const f of catalogFindings(menu.catalog)) {
66
+ const configured = options.rules?.[f.rule];
67
+ if (configured === 'off' || (f.tool && ignore.some((re) => re.test(f.tool))))
68
+ continue;
69
+ findings.push({ ...f, severity: configured ?? f.severity });
70
+ }
71
+ findings.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
72
+ }
55
73
  return { menu, findings };
56
74
  }
package/dist/types.d.ts CHANGED
@@ -10,6 +10,20 @@ export interface Finding {
10
10
  detail?: string[];
11
11
  /** For `session`: the scenario step that caused it (0 = before the first step). */
12
12
  step?: number;
13
+ /** For `session`: every step it happened at, when one finding stands for several (`step` is the first). */
14
+ steps?: number[];
15
+ /**
16
+ * The next step, as one instruction the reader can act on ("Sort the values",
17
+ * "Rerun with --processes 1"). Shown as "Next:" in every format. Omitted only when
18
+ * there is nothing to do.
19
+ */
20
+ fix?: string;
21
+ /**
22
+ * 'unsure': a heuristic or an inference that can be wrong (a guess from names,
23
+ * a failure whose cause isn't known). The message then says what was seen and
24
+ * where, not what it means. Absent: toolmenu observed it directly.
25
+ */
26
+ confidence?: 'unsure';
13
27
  }
14
28
  /** A tool exactly as the server returned it, plus toolmenu's token estimate. */
15
29
  export interface MenuTool {
package/dist/words.d.ts CHANGED
@@ -6,6 +6,11 @@ export declare const LOOKUP_VERBS: Set<string>;
6
6
  /** Lookups that return collections: they hand out IDs even when they take one (get_block_children). */
7
7
  export declare const COLLECTION_VERBS: Set<string>;
8
8
  export declare const WRITE_VERBS: Set<string>;
9
+ /**
10
+ * "a" or "an" for a word, by how it sounds, not its first letter: a user, a UUID,
11
+ * a URL, a one-time code; an order, an update, an hour.
12
+ */
13
+ export declare function article(word: string): 'a' | 'an';
9
14
  /** Words most of a server's tool names share (`firecrawl_`, `API-`, `browser_`): no information. */
10
15
  export declare function commonWords(names: string[]): Set<string>;
11
16
  /** The tool's verb: the first word that is one, skipping prefixes like `API-`. */
package/dist/words.js CHANGED
@@ -40,6 +40,20 @@ export const WRITE_VERBS = new Set([
40
40
  'delete', 'remove', 'drop', 'purge', 'destroy', 'clear', 'revoke', 'cancel', 'archive', 'close',
41
41
  'send', 'post', 'publish', 'submit', 'write', 'save', 'upload', 'move', 'rename', 'assign', 'invite', 'approve',
42
42
  ]);
43
+ /**
44
+ * "a" or "an" for a word, by how it sounds, not its first letter: a user, a UUID,
45
+ * a URL, a one-time code; an order, an update, an hour.
46
+ */
47
+ export function article(word) {
48
+ const w = word.toLowerCase();
49
+ // u said "you" (user, uuid, url, unique, usage, unit), and "one" said "won".
50
+ if (/^(uu|url|uri|uni(?!n)|u[bcfgklmrstvz][aeiouy]|one\b|one[-_]|once)/.test(w))
51
+ return 'a';
52
+ // A silent h: an hour, an honest answer.
53
+ if (/^(hour|honest|honor|honour|heir)/.test(w))
54
+ return 'an';
55
+ return /^[aeiou]/.test(w) ? 'an' : 'a';
56
+ }
43
57
  /** Words too generic to tell tools apart. */
44
58
  const GENERIC = new Set(['tool', 'mcp', 'api', 'data', 'info', 'item', 'object', 'value', 'result', 'detail', 'all', 'by', 'for', 'of', 'to', 'from', 'with', 'and', 'or', 'the', 'a', 'an', 'my']);
45
59
  /** Words most of a server's tool names share (`firecrawl_`, `API-`, `browser_`): no information. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
5
  "author": "Niksa (https://niksa.me)",
6
6
  "main": "dist/index.js",