toolmenu 0.20.1 → 0.23.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 (68) hide show
  1. package/README.md +119 -41
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auth.d.ts +14 -0
  5. package/dist/auth.js +75 -2
  6. package/dist/auto.d.ts +6 -0
  7. package/dist/auto.js +70 -7
  8. package/dist/card.d.ts +18 -0
  9. package/dist/card.js +39 -0
  10. package/dist/cli.js +108 -24
  11. package/dist/colour.d.ts +8 -0
  12. package/dist/colour.js +70 -0
  13. package/dist/config.d.ts +2 -0
  14. package/dist/config.js +2 -0
  15. package/dist/connect.d.ts +14 -0
  16. package/dist/connect.js +45 -7
  17. package/dist/diff.js +112 -13
  18. package/dist/explain.d.ts +1 -0
  19. package/dist/explain.js +11 -0
  20. package/dist/failures.d.ts +24 -0
  21. package/dist/failures.js +58 -1
  22. package/dist/help.d.ts +1 -1
  23. package/dist/help.js +36 -4
  24. package/dist/mrtr.d.ts +9 -1
  25. package/dist/mrtr.js +17 -0
  26. package/dist/options.d.ts +15 -0
  27. package/dist/options.js +5 -0
  28. package/dist/probe.d.ts +11 -1
  29. package/dist/probe.js +18 -3
  30. package/dist/report.d.ts +3 -0
  31. package/dist/report.js +15 -8
  32. package/dist/rule-docs.d.ts +26 -0
  33. package/dist/rule-docs.js +88 -0
  34. package/dist/rule-docs.json +597 -0
  35. package/dist/rules/apps.d.ts +11 -0
  36. package/dist/rules/apps.js +156 -0
  37. package/dist/rules/auth.d.ts +18 -0
  38. package/dist/rules/auth.js +29 -0
  39. package/dist/rules/capabilities.d.ts +21 -0
  40. package/dist/rules/capabilities.js +103 -0
  41. package/dist/rules/card.d.ts +7 -0
  42. package/dist/rules/card.js +65 -0
  43. package/dist/rules/clients.js +1 -0
  44. package/dist/rules/description.js +3 -0
  45. package/dist/rules/handles.d.ts +13 -0
  46. package/dist/rules/handles.js +78 -0
  47. package/dist/rules/ids.js +35 -1
  48. package/dist/rules/index.js +20 -2
  49. package/dist/rules/naming.js +3 -0
  50. package/dist/rules/network.d.ts +21 -0
  51. package/dist/rules/network.js +63 -0
  52. package/dist/rules/rule.d.ts +20 -0
  53. package/dist/rules/search.js +1 -0
  54. package/dist/rules/spec.d.ts +9 -1
  55. package/dist/rules/spec.js +117 -3
  56. package/dist/rules/write.d.ts +0 -6
  57. package/dist/rules/write.js +11 -5
  58. package/dist/scan.d.ts +47 -0
  59. package/dist/scan.js +334 -0
  60. package/dist/session.d.ts +2 -0
  61. package/dist/session.js +149 -9
  62. package/dist/snapshot.d.ts +15 -0
  63. package/dist/snapshot.js +130 -5
  64. package/dist/types.d.ts +5 -0
  65. package/dist/words.d.ts +10 -0
  66. package/dist/words.js +44 -2
  67. package/package.json +2 -2
  68. package/schemas/server-card.json +260 -0
package/dist/report.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { agentMenu } from './apps.js';
1
2
  import { clip, stepLabel, stepsText } from './session.js';
2
3
  import { SEVERITY_RANK } from './types.js';
3
4
  import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
@@ -28,7 +29,12 @@ function costLine(cost) {
28
29
  ].filter(Boolean);
29
30
  return `as ${cost.label}: ${parts.join(' · ')}`;
30
31
  }
32
+ /** " · 2 not shown to the agent (MCP Apps visibility without "model", ~60 tokens)", or nothing. */
33
+ function appOnlyNote(a) {
34
+ return a ? ` · ${a.tools} not shown to the agent (MCP Apps visibility without "model", ~${a.tokens.toLocaleString('en-US')} tokens)` : '';
35
+ }
31
36
  export function formatSnapshot(menu, findings, format, outPath, cost, notOffered = []) {
37
+ const view = agentMenu(menu);
32
38
  if (format === 'json') {
33
39
  return JSON.stringify({
34
40
  command: 'snapshot',
@@ -36,7 +42,8 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
36
42
  tools: menu.tools.length,
37
43
  totalTokens: menu.totalTokens,
38
44
  listMeta: menu.listMeta,
39
- breakdown: breakdown(menu),
45
+ ...(view.appOnly ? { appOnly: view.appOnly } : {}),
46
+ breakdown: breakdown(view.shown),
40
47
  ...(cost ? { client: cost } : {}),
41
48
  ...(menu.prompts ? { prompts: menu.prompts.length } : {}),
42
49
  ...(menu.resources ? { resources: menu.resources.length } : {}),
@@ -54,18 +61,18 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
54
61
  return [
55
62
  `### toolmenu snapshot: \`${s.name ?? 'server'}\` ${s.version ?? ''}`.trimEnd(),
56
63
  '',
57
- `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
64
+ `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
58
65
  ...(cost ? ['', `${costLine(cost)}. _${cost.basis}._`] : []),
59
66
  ...(otherLists(menu) ? ['', `Also listed: ${otherLists(menu)}`] : []),
60
67
  '',
61
68
  ...mdFindings(findings),
62
- ...mdBreakdown(menu),
69
+ ...mdBreakdown(view.shown),
63
70
  ].join('\n');
64
71
  }
65
72
  const s = menu.server;
66
73
  const lines = [
67
74
  `toolmenu snapshot ${s.name ?? 'unknown server'} ${s.version ?? ''}`.trimEnd(),
68
- ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
75
+ ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
69
76
  ];
70
77
  if (cost)
71
78
  lines.push(` ${costLine(cost)}`, ` ${cost.basis}`);
@@ -77,7 +84,7 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
77
84
  if (outPath)
78
85
  lines.push(` wrote ${outPath}`);
79
86
  lines.push('');
80
- const where = breakdownLines(breakdown(menu), menu.tools.length);
87
+ const where = breakdownLines(breakdown(view.shown), view.shown.tools.length);
81
88
  if (where.length)
82
89
  lines.push(...where, '');
83
90
  lines.push(...findingLines(findings));
@@ -87,7 +94,7 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
87
94
  function mdBreakdown(menu) {
88
95
  return breakdownMarkdown(breakdown(menu), menu.tools.length);
89
96
  }
90
- function findingLines(findings) {
97
+ export function findingLines(findings) {
91
98
  const lines = [];
92
99
  for (const f of findings) {
93
100
  lines.push(`${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
@@ -106,7 +113,7 @@ function summaryLine(findings) {
106
113
  const mark = c.error ? '✗' : c.warn ? '!' : '✓';
107
114
  return `${mark} ${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`;
108
115
  }
109
- function githubLines(findings) {
116
+ export function githubLines(findings) {
110
117
  return findings.map((f) => {
111
118
  const level = f.severity === 'error' ? 'error' : f.severity === 'warn' ? 'warning' : 'notice';
112
119
  const body = [f.message, ...(f.detail ?? []), ...(f.fix ? [`→ Next: ${f.fix}`] : [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
@@ -534,7 +541,7 @@ function stepPrefix(f, prefix) {
534
541
  function mdCell(text) {
535
542
  return text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
536
543
  }
537
- function mdFindings(findings) {
544
+ export function mdFindings(findings) {
538
545
  if (findings.length === 0)
539
546
  return ['No findings.'];
540
547
  const row = (f) => `| ${f.severity === 'error' ? '**error**' : f.severity} | \`${f.rule}\`${f.confidence === 'unsure' ? ' · _unsure_' : ''} | ${mdCell([f.message, ...(f.detail ?? [])].join(' · '))}${f.fix ? `<br>**→ Next:** ${mdCell(f.fix)}` : ''} |`;
@@ -0,0 +1,26 @@
1
+ export interface RuleDoc {
2
+ command: string;
3
+ severity: string;
4
+ text: string;
5
+ }
6
+ export declare function ruleDocs(): Record<string, RuleDoc>;
7
+ /**
8
+ * The rule a name means: the id itself, or the part after the slash when only one
9
+ * rule ends that way (vague-id → naming/vague-id). Otherwise the ids close to it.
10
+ */
11
+ export declare function findRule(name: string): {
12
+ id: string;
13
+ } | {
14
+ near: string[];
15
+ };
16
+ export interface Explained extends RuleDoc {
17
+ rule: string;
18
+ /** diff rules: what the change means for semver. */
19
+ class?: string;
20
+ /** Menu rules: the protocol version the rule applies from. */
21
+ since?: string;
22
+ }
23
+ export declare function explain(id: string): Explained;
24
+ export declare function formatExplained(e: Explained): string;
25
+ /** `toolmenu explain` with no rule: every id, by command. */
26
+ export declare function listRules(): string;
@@ -0,0 +1,88 @@
1
+ /*
2
+ * `toolmenu explain <rule>`: one entry of docs/RULES.md, which the build copies to
3
+ * dist/rule-docs.json (docs/ isn't in the npm package).
4
+ */
5
+ import { readFileSync } from 'node:fs';
6
+ import { DIFF_RULES } from './diff.js';
7
+ import { MENU_RULES } from './rules/index.js';
8
+ import { editDistance } from './words.js';
9
+ let cache;
10
+ export function ruleDocs() {
11
+ cache ??= JSON.parse(readFileSync(new URL('./rule-docs.json', import.meta.url), 'utf8'));
12
+ return cache;
13
+ }
14
+ /** Markdown out of a table cell, for a terminal: `code` and **bold** as plain words. */
15
+ function plain(text) {
16
+ return text.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/`([^`]+)`/g, '$1');
17
+ }
18
+ function wrap(text, width, indent) {
19
+ const lines = [];
20
+ let line = '';
21
+ for (const word of text.split(/\s+/)) {
22
+ if (line && line.length + 1 + word.length > width) {
23
+ lines.push(indent + line);
24
+ line = word;
25
+ }
26
+ else
27
+ line = line ? `${line} ${word}` : word;
28
+ }
29
+ if (line)
30
+ lines.push(indent + line);
31
+ return lines;
32
+ }
33
+ /**
34
+ * The rule a name means: the id itself, or the part after the slash when only one
35
+ * rule ends that way (vague-id → naming/vague-id). Otherwise the ids close to it.
36
+ */
37
+ export function findRule(name) {
38
+ const docs = ruleDocs();
39
+ const wanted = name.trim().toLowerCase();
40
+ if (Object.hasOwn(docs, wanted))
41
+ return { id: wanted };
42
+ const ids = Object.keys(docs);
43
+ const tail = ids.filter((id) => id.split('/')[1] === wanted);
44
+ if (tail.length === 1)
45
+ return { id: tail[0] };
46
+ if (tail.length > 1)
47
+ return { near: tail };
48
+ const scored = ids
49
+ .map((id) => ({ id, d: Math.min(editDistance(wanted, id), editDistance(wanted, id.split('/')[1]) + (wanted.includes('/') ? 99 : 0)) }))
50
+ .filter((x) => x.d <= Math.max(2, Math.floor(wanted.length / 4)));
51
+ const contains = ids.filter((id) => wanted.length >= 3 && id.includes(wanted));
52
+ const near = [...new Set([...scored.sort((a, b) => a.d - b.d).map((x) => x.id), ...contains])];
53
+ return { near: near.slice(0, 5) };
54
+ }
55
+ export function explain(id) {
56
+ const doc = ruleDocs()[id];
57
+ const menu = MENU_RULES.find((r) => r.id === id);
58
+ const diff = Object.hasOwn(DIFF_RULES, id) ? DIFF_RULES[id] : undefined;
59
+ return {
60
+ rule: id,
61
+ ...doc,
62
+ severity: doc.severity.replace(/ \((?:breaking|minor|notice)\)$/, ''),
63
+ ...(diff?.class ? { class: diff.class } : {}),
64
+ ...(menu?.since ? { since: menu.since } : {}),
65
+ };
66
+ }
67
+ export function formatExplained(e) {
68
+ return [
69
+ `${e.rule} (${e.command}, ${e.severity}${e.class ? `, ${e.class}` : ''})`,
70
+ '',
71
+ ...wrap(plain(e.text), 86, ' '),
72
+ ...(e.since ? ['', ` Checked on servers that speak ${e.since} or later.`] : []),
73
+ '',
74
+ ` Change its level, or turn it off, in toolmenu.config.json:`,
75
+ ` { "rules": { "${e.rule}": "off" } } (or "error", "warn", "info")`,
76
+ '',
77
+ ].join('\n');
78
+ }
79
+ /** `toolmenu explain` with no rule: every id, by command. */
80
+ export function listRules() {
81
+ const by = new Map();
82
+ for (const [id, doc] of Object.entries(ruleDocs()))
83
+ by.set(doc.command, [...(by.get(doc.command) ?? []), id]);
84
+ const out = ['Rules, by the command that reports them. toolmenu explain <rule> says what one checks.', ''];
85
+ for (const [command, ids] of by)
86
+ out.push(`${command}:`, ...wrap(ids.join(' '), 86, ' '), '');
87
+ return out.join('\n');
88
+ }