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.
- package/README.md +119 -41
- package/dist/apps.d.ts +56 -0
- package/dist/apps.js +99 -0
- package/dist/auth.d.ts +14 -0
- package/dist/auth.js +75 -2
- package/dist/auto.d.ts +6 -0
- package/dist/auto.js +70 -7
- package/dist/card.d.ts +18 -0
- package/dist/card.js +39 -0
- package/dist/cli.js +108 -24
- package/dist/colour.d.ts +8 -0
- package/dist/colour.js +70 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +2 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +45 -7
- package/dist/diff.js +112 -13
- package/dist/explain.d.ts +1 -0
- package/dist/explain.js +11 -0
- package/dist/failures.d.ts +24 -0
- package/dist/failures.js +58 -1
- package/dist/help.d.ts +1 -1
- package/dist/help.js +36 -4
- package/dist/mrtr.d.ts +9 -1
- package/dist/mrtr.js +17 -0
- package/dist/options.d.ts +15 -0
- package/dist/options.js +5 -0
- package/dist/probe.d.ts +11 -1
- package/dist/probe.js +18 -3
- package/dist/report.d.ts +3 -0
- package/dist/report.js +15 -8
- package/dist/rule-docs.d.ts +26 -0
- package/dist/rule-docs.js +88 -0
- package/dist/rule-docs.json +597 -0
- package/dist/rules/apps.d.ts +11 -0
- package/dist/rules/apps.js +156 -0
- package/dist/rules/auth.d.ts +18 -0
- package/dist/rules/auth.js +29 -0
- package/dist/rules/capabilities.d.ts +21 -0
- package/dist/rules/capabilities.js +103 -0
- package/dist/rules/card.d.ts +7 -0
- package/dist/rules/card.js +65 -0
- package/dist/rules/clients.js +1 -0
- package/dist/rules/description.js +3 -0
- package/dist/rules/handles.d.ts +13 -0
- package/dist/rules/handles.js +78 -0
- package/dist/rules/ids.js +35 -1
- package/dist/rules/index.js +20 -2
- package/dist/rules/naming.js +3 -0
- package/dist/rules/network.d.ts +21 -0
- package/dist/rules/network.js +63 -0
- package/dist/rules/rule.d.ts +20 -0
- package/dist/rules/search.js +1 -0
- package/dist/rules/spec.d.ts +9 -1
- package/dist/rules/spec.js +117 -3
- package/dist/rules/write.d.ts +0 -6
- package/dist/rules/write.js +11 -5
- package/dist/scan.d.ts +47 -0
- package/dist/scan.js +334 -0
- package/dist/session.d.ts +2 -0
- package/dist/session.js +149 -9
- package/dist/snapshot.d.ts +15 -0
- package/dist/snapshot.js +130 -5
- package/dist/types.d.ts +5 -0
- package/dist/words.d.ts +10 -0
- package/dist/words.js +44 -2
- package/package.json +2 -2
- 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
|
-
|
|
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(
|
|
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(
|
|
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
|
+
}
|