toolmenu 0.25.2 → 0.27.1
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 +170 -683
- package/dist/args.d.ts +14 -2
- package/dist/args.js +44 -1
- package/dist/auth-check.d.ts +27 -0
- package/dist/auth-check.js +177 -0
- package/dist/auth.d.ts +7 -0
- package/dist/auth.js +29 -1
- package/dist/auto.d.ts +8 -0
- package/dist/auto.js +9 -2
- package/dist/breakdown.js +14 -10
- package/dist/cli.js +151 -49
- package/dist/clients.d.ts +13 -2
- package/dist/clients.js +65 -11
- package/dist/config.js +6 -0
- package/dist/diff.d.ts +35 -1
- package/dist/diff.js +57 -12
- package/dist/failures.js +4 -3
- package/dist/help.d.ts +1 -1
- package/dist/help.js +45 -18
- package/dist/history.js +5 -0
- package/dist/html.d.ts +29 -0
- package/dist/html.js +360 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/init.d.ts +14 -0
- package/dist/init.js +20 -6
- package/dist/junit.d.ts +6 -1
- package/dist/junit.js +12 -3
- package/dist/mcp-env.d.ts +6 -0
- package/dist/mcp-env.js +6 -0
- package/dist/mcp.d.ts +11 -1
- package/dist/mcp.js +123 -22
- package/dist/menu.d.ts +6 -0
- package/dist/menu.js +12 -1
- package/dist/options.d.ts +10 -0
- package/dist/options.js +3 -0
- package/dist/report.d.ts +14 -0
- package/dist/report.js +57 -51
- package/dist/review.d.ts +48 -0
- package/dist/review.js +212 -0
- package/dist/rule-docs.json +49 -4
- package/dist/rules/clients.d.ts +11 -0
- package/dist/rules/clients.js +65 -2
- package/dist/rules/determinism.d.ts +3 -0
- package/dist/rules/determinism.js +44 -7
- package/dist/rules/ids.js +5 -1
- package/dist/rules/index.js +5 -2
- package/dist/rules/output.d.ts +21 -0
- package/dist/rules/output.js +49 -0
- package/dist/rules/search.js +1 -1
- package/dist/rules/spec.d.ts +19 -0
- package/dist/rules/spec.js +86 -1
- package/dist/sanitize.d.ts +42 -0
- package/dist/sanitize.js +142 -0
- package/dist/scan.d.ts +9 -2
- package/dist/scan.js +46 -24
- package/dist/session.d.ts +17 -0
- package/dist/session.js +119 -13
- package/dist/snapshot.js +2 -1
- package/package.json +5 -3
package/dist/rule-docs.json
CHANGED
|
@@ -79,10 +79,20 @@
|
|
|
79
79
|
"severity": "info",
|
|
80
80
|
"text": "`snapshot --as name:credential` (repeatable) or `identities` in the config lists the menu once per identity: a header set (HTTP) or env vars (stdio) over `--header`/`--env`. The first identity's menu is saved and checked; each other one, from its own process or connection, is compared with it: tools it adds, lacks, or defines differently, and its tokens. The tool set **MAY** vary by authorization, so this is info. An identity that can't be listed is reported here, and the others are still compared"
|
|
81
81
|
},
|
|
82
|
+
"menu/client-features": {
|
|
83
|
+
"command": "snapshot",
|
|
84
|
+
"severity": "info",
|
|
85
|
+
"text": "`--client` only. What the client leaves out of what the server offers, from its own docs: GitHub Copilot cloud agent and code review use MCP tools only, not prompts or resources (with `--lists`, the server's prompts and resources are counted); code review also uses only tools marked `readOnlyHint: true`, and the finding lists the tools it skips. The detail names the source and read date"
|
|
86
|
+
},
|
|
87
|
+
"menu/client-limit": {
|
|
88
|
+
"command": "snapshot",
|
|
89
|
+
"severity": "warn",
|
|
90
|
+
"text": "`--client` only. More tools than the client sends the model at once: VS Code (GitHub Copilot Chat) allows 128 per chat request (code.visualstudio.com, agents/run/tools). This server alone is over it, so the user has to turn tools off before it works. Limits that only forum posts report (Cursor's 40) aren't checked"
|
|
91
|
+
},
|
|
82
92
|
"menu/connection-variance": {
|
|
83
93
|
"command": "snapshot",
|
|
84
94
|
"severity": "error",
|
|
85
|
-
"text": "The same over HTTP: a second connection with the same credentials gets a different menu. Retried once before reporting"
|
|
95
|
+
"text": "The same over HTTP: a second connection with the same credentials gets a different menu. Retried once before reporting. A difference only in fields the model doesn't read (output schema, annotations, an extra field such as a per-tool `version` hash) is a warning: no prompt cache is lost, but no baseline matches (the `@pipeworx` servers, bench 2026-11-09)"
|
|
86
96
|
},
|
|
87
97
|
"menu/capability-dependent": {
|
|
88
98
|
"command": "snapshot",
|
|
@@ -112,17 +122,17 @@
|
|
|
112
122
|
"menu/nondeterministic": {
|
|
113
123
|
"command": "snapshot",
|
|
114
124
|
"severity": "error",
|
|
115
|
-
"text": "Two identical `tools/list` calls return different menus. Reports what differed: order, description, schema, annotations, tool added, tool removed. Order and content changes are both cache-relevant. Spec basis for order: servers **SHOULD** return \"the same ordering across requests when the underlying set of tools has not changed\" (§12). Content changes are toolmenu's own rule (lesson 05), not a spec violation"
|
|
125
|
+
"text": "Two identical `tools/list` calls return different menus. Reports what differed: order, description, schema, annotations, tool added, tool removed. Order and content changes are both cache-relevant. Spec basis for order: servers **SHOULD** return \"the same ordering across requests when the underlying set of tools has not changed\" (§12). Content changes are toolmenu's own rule (lesson 05), not a spec violation. A difference only in fields the model doesn't read (output schema, annotations, an extra field such as a per-tool `version` hash) is a warning: no prompt cache is lost, but no baseline matches (the `@pipeworx` servers, bench 2026-11-09)"
|
|
116
126
|
},
|
|
117
127
|
"menu/process-variance": {
|
|
118
128
|
"command": "snapshot",
|
|
119
129
|
"severity": "error",
|
|
120
|
-
"text": "A second server process, started the same way, serves a different menu, so every restart misses the cache. Seen on mcp-atlassian: a default built from a Python set, in a new order every start (FINDINGS F12). toolmenu runs the main process with `PYTHONHASHSEED=0`, so a Python server's saved menu is reproducible, and the second with another seed. `--processes 1` turns it off"
|
|
130
|
+
"text": "A second server process, started the same way, serves a different menu, so every restart misses the cache. Seen on mcp-atlassian: a default built from a Python set, in a new order every start (FINDINGS F12). toolmenu runs the main process with `PYTHONHASHSEED=0`, so a Python server's saved menu is reproducible, and the second with another seed. `--processes 1` turns it off. A difference only in fields the model doesn't read (output schema, annotations, an extra field such as a per-tool `version` hash) is a warning: no prompt cache is lost, but no baseline matches (the `@pipeworx` servers, bench 2026-11-09)"
|
|
121
131
|
},
|
|
122
132
|
"naming/client-name": {
|
|
123
133
|
"command": "snapshot",
|
|
124
134
|
"severity": "warn",
|
|
125
|
-
"text": "`--client` only. Tool names outside the client's API name format: the Claude API's `^[a-zA-Z0-9_-]{1,128}$` (platform.claude.com define-tools) for `claude-code` and `claude-api-search`, OpenAI's `FunctionToolParam.name` (`^[a-zA-Z0-9_-]+$`, maxLength 128, openai/openai-openapi) for `openai`. The detail names the source and read date"
|
|
135
|
+
"text": "`--client` only. Tool names outside the client's API name format: the Claude API's `^[a-zA-Z0-9_-]{1,128}$` (platform.claude.com define-tools) for `claude-code` and `claude-api-search`, OpenAI's `FunctionToolParam.name` (`^[a-zA-Z0-9_-]+$`, maxLength 128, openai/openai-openapi) for `openai` and `codex`, the Gemini API's `FunctionDeclaration.name` (letters, digits, `_`, `:`, `.`, `-`, at most 128) for `gemini-api`. For `gemini-cli` the client rewrites instead of refusing (other characters become `_`, names over 63 characters are cut in the middle), so the finding says the model sees a name that isn't the server's. The detail names the source and read date"
|
|
126
136
|
},
|
|
127
137
|
"naming/route": {
|
|
128
138
|
"command": "snapshot",
|
|
@@ -189,6 +199,11 @@
|
|
|
189
199
|
"severity": "warn",
|
|
190
200
|
"text": "The handshake's `serverInfo` has no `name` or no `version`, so a client (and `diff --server-version-is-release`) can't tell which server or release answered"
|
|
191
201
|
},
|
|
202
|
+
"spec/tool-name": {
|
|
203
|
+
"command": "snapshot",
|
|
204
|
+
"severity": "warn, info, error",
|
|
205
|
+
"text": "A tool name outside the format the spec recommends from 2025-11-25 (SEP-986: 1 to 128 of `A-Z a-z 0-9 _ - .`); info on older protocols, which gave no format. An error on any protocol when a name has characters that act on a terminal or can't be seen (controls, format and bidi characters, default-ignorables such as variation selectors and Hangul fillers): what's read isn't the name the server takes. Other non-ASCII characters are named by code point, so a lookalike can't hide. Reports show hidden characters as escapes (the same class)"
|
|
206
|
+
},
|
|
192
207
|
"spec/task-required": {
|
|
193
208
|
"command": "snapshot",
|
|
194
209
|
"severity": "info",
|
|
@@ -534,6 +549,11 @@
|
|
|
534
549
|
"severity": "error",
|
|
535
550
|
"text": "The same tools mid-session in a different order: a cache miss for everything after the first moved tool"
|
|
536
551
|
},
|
|
552
|
+
"session/output-schema": {
|
|
553
|
+
"command": "session",
|
|
554
|
+
"severity": "error",
|
|
555
|
+
"text": "A tool that declares an `outputSchema` answered (not `isError`) with no `structuredContent`, or with one that doesn't match the schema. From 2025-06-18 servers **MUST** return conforming structured results; the official SDK client validates them and raises an error where the tool answered. Checked once per tool, on the calls a session makes (more with `--call-everything`). A warning when only `format` checks failed (a URI, a date): many validators skip format, so a client may let the result through"
|
|
556
|
+
},
|
|
537
557
|
"session/result-type": {
|
|
538
558
|
"command": "session",
|
|
539
559
|
"severity": "error",
|
|
@@ -593,5 +613,30 @@
|
|
|
593
613
|
"command": "session",
|
|
594
614
|
"severity": "warn, error if no call got through",
|
|
595
615
|
"text": "Calls that failed before reaching the tool: authentication, something missing on this machine (no Chrome), the network; or an answer, not marked `isError`, that is the API's 401 or 403 passed on as JSON (`{\"status\":401,\"code\":\"unauthorized\"}`, Notion's server). One finding for the run, not one per step, so an expired CI secret doesn't pass a run that tested nothing"
|
|
616
|
+
},
|
|
617
|
+
"auth/discovery": {
|
|
618
|
+
"command": "auth",
|
|
619
|
+
"severity": "error",
|
|
620
|
+
"text": "The server answered 401 and says it uses OAuth (a `WWW-Authenticate` header), but serves no OAuth protected resource metadata: not where the header's `resource_metadata` points, nor at a well-known URI. Servers that use OAuth **MUST** implement RFC 9728. Info when there's neither a header nor metadata (authorization is OPTIONAL in MCP, and the server may take an API key), when only the header is missing or lacks `resource_metadata`, or when the metadata couldn't be read"
|
|
621
|
+
},
|
|
622
|
+
"auth/resource-metadata": {
|
|
623
|
+
"command": "auth",
|
|
624
|
+
"severity": "error",
|
|
625
|
+
"text": "The protected resource metadata lists no `authorization_servers` (it **MUST** list one), or has no `resource`, or a `resource` on another origin or path: RFC 9728 §3.3 says it **MUST** be identical to the URL the client called (metadata named by `WWW-Authenticate`) or the identifier the well-known URI was built from, or the client **MUST NOT** use it. A warning when it's a same-origin parent of that URL, or only a trailing slash differs: the official MCP SDK client accepts those, a client that follows the RFC to the letter doesn't"
|
|
626
|
+
},
|
|
627
|
+
"auth/server-metadata": {
|
|
628
|
+
"command": "auth",
|
|
629
|
+
"severity": "error",
|
|
630
|
+
"text": "No authorization server metadata at the URIs the spec has clients try (RFC 8414, then OpenID Connect Discovery, path-aware), so a client can't find where to send the user"
|
|
631
|
+
},
|
|
632
|
+
"auth/pkce": {
|
|
633
|
+
"command": "auth",
|
|
634
|
+
"severity": "error",
|
|
635
|
+
"text": "The authorization server's metadata doesn't list `S256` in `code_challenge_methods_supported`. Clients **MUST** verify PKCE support from it and refuse to go on without it"
|
|
636
|
+
},
|
|
637
|
+
"auth/registration": {
|
|
638
|
+
"command": "auth",
|
|
639
|
+
"severity": "info",
|
|
640
|
+
"text": "No registration endpoint and no Client ID Metadata Documents: every client needs an app registered ahead of time"
|
|
596
641
|
}
|
|
597
642
|
}
|
package/dist/rules/clients.d.ts
CHANGED
|
@@ -5,3 +5,14 @@ import { type Rule } from './rule.js';
|
|
|
5
5
|
* ^[a-zA-Z0-9_-]{1,128}$, OpenAI's function names ^[a-zA-Z0-9_-]+$ up to 128.
|
|
6
6
|
*/
|
|
7
7
|
export declare const clientName: Rule;
|
|
8
|
+
/**
|
|
9
|
+
* --client: more tools than the client sends the model at once (VS Code: "A chat request
|
|
10
|
+
* can have a maximum of 128 tools enabled at a time"). This server alone is over it, so
|
|
11
|
+
* a user has to turn tools off before the client works with it.
|
|
12
|
+
*/
|
|
13
|
+
export declare const clientLimit: Rule;
|
|
14
|
+
/**
|
|
15
|
+
* --client: what the client leaves out of what the server offers (GitHub Copilot cloud agent
|
|
16
|
+
* and code review use MCP tools only; code review only tools marked readOnlyHint: true).
|
|
17
|
+
*/
|
|
18
|
+
export declare const clientFeatures: Rule;
|
package/dist/rules/clients.js
CHANGED
|
@@ -23,10 +23,73 @@ export const clientName = {
|
|
|
23
23
|
return [
|
|
24
24
|
{
|
|
25
25
|
...(bad.length === 1 ? { tool: bad[0].tool } : {}),
|
|
26
|
-
message:
|
|
26
|
+
message: rule.value.rewrites
|
|
27
|
+
? `${count(bad.length, 'tool name')} ${bad.length === 1 ? "doesn't" : "don't"} fit the tool names ${rule.value.api} keeps as they are (${rule.value.pattern}, at most ${rule.value.max} characters). It ${rule.value.rewrites}, so its model sees a name that isn't the server's, and two names can end up the same.`
|
|
28
|
+
: `${count(bad.length, 'tool name')} ${bad.length === 1 ? "doesn't" : "don't"} fit the tool name format of ${rule.value.api}${ctx.client === 'claude-code' ? `, which ${profile.label} sends tools to` : ''} (${rule.value.pattern}, at most ${rule.value.max} characters). MCP allows them, but a request that passes them to the API as they are is refused; a client that rewrites them shows the model a name that isn't the server's.`,
|
|
27
29
|
detail: [...bad.slice(0, 12).map((b) => `${b.tool}: ${b.why}`), ...(bad.length > 12 ? [`and ${bad.length - 12} more`] : []), `Source: ${rule.source} (read ${rule.read}).`],
|
|
28
|
-
fix:
|
|
30
|
+
fix: `Use letters, digits, _ and - in tool names (files_read, not files.read), at most ${Math.min(rule.value.max, 128)} characters.`,
|
|
29
31
|
},
|
|
30
32
|
];
|
|
31
33
|
},
|
|
32
34
|
};
|
|
35
|
+
/**
|
|
36
|
+
* --client: more tools than the client sends the model at once (VS Code: "A chat request
|
|
37
|
+
* can have a maximum of 128 tools enabled at a time"). This server alone is over it, so
|
|
38
|
+
* a user has to turn tools off before the client works with it.
|
|
39
|
+
*/
|
|
40
|
+
export const clientLimit = {
|
|
41
|
+
id: 'menu/client-limit',
|
|
42
|
+
scope: 'agent',
|
|
43
|
+
severity: 'warn',
|
|
44
|
+
summary: 'More tools than the client sends the model at once',
|
|
45
|
+
run(ctx) {
|
|
46
|
+
const profile = profileOf(ctx.client);
|
|
47
|
+
const limit = profile?.toolLimit;
|
|
48
|
+
const n = ctx.menu.tools.length;
|
|
49
|
+
if (!profile || !limit || n <= limit.value)
|
|
50
|
+
return [];
|
|
51
|
+
return [
|
|
52
|
+
{
|
|
53
|
+
message: `${n} tools, over the ${limit.value} ${profile.label} allows in one request, and that's this server alone, before any other server the user has. The user has to turn ${n - limit.value} or more off before it works, and picks which without knowing which ones the agent needs.`,
|
|
54
|
+
detail: [`Source: ${limit.source} (read ${limit.read}).`],
|
|
55
|
+
fix: 'Group the tools into toolsets a user turns on (the GitHub server\'s --toolsets), or fold several into one tool with an action parameter.',
|
|
56
|
+
},
|
|
57
|
+
];
|
|
58
|
+
},
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* --client: what the client leaves out of what the server offers (GitHub Copilot cloud agent
|
|
62
|
+
* and code review use MCP tools only; code review only tools marked readOnlyHint: true).
|
|
63
|
+
*/
|
|
64
|
+
export const clientFeatures = {
|
|
65
|
+
id: 'menu/client-features',
|
|
66
|
+
scope: 'agent',
|
|
67
|
+
severity: 'info',
|
|
68
|
+
summary: "Parts of the server the client doesn't use",
|
|
69
|
+
run(ctx) {
|
|
70
|
+
const profile = profileOf(ctx.client);
|
|
71
|
+
if (!profile)
|
|
72
|
+
return [];
|
|
73
|
+
const out = [];
|
|
74
|
+
const prompts = ctx.menu.prompts?.length ?? 0, resources = (ctx.menu.resources?.length ?? 0) + (ctx.menu.resourceTemplates?.length ?? 0);
|
|
75
|
+
if (profile.toolsOnly && prompts + resources) {
|
|
76
|
+
out.push({
|
|
77
|
+
message: `${profile.label} uses only MCP tools, not ${profile.toolsOnly.value}, so the server's ${[prompts && count(prompts, 'prompt'), resources && count(resources, 'resource')].filter(Boolean).join(' and ')} aren't available there. Anything an agent needs from them has to come through a tool for it to work in ${profile.label}.`,
|
|
78
|
+
detail: [`Source: ${profile.toolsOnly.source} (read ${profile.toolsOnly.read}).`],
|
|
79
|
+
fix: 'If an agent needs the content, offer it through a tool as well.',
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
if (profile.readOnlyOnly) {
|
|
83
|
+
const tools = kept(ctx.menu.tools, ctx);
|
|
84
|
+
const off = tools.filter((t) => t.annotations?.readOnlyHint !== true);
|
|
85
|
+
if (off.length) {
|
|
86
|
+
out.push({
|
|
87
|
+
message: `${profile.label} uses only tools marked readOnlyHint: true, and ${off.length === tools.length ? `none of the ${count(tools.length, 'tool')} is` : `${count(off.length, 'tool')} of ${tools.length} ${off.length === 1 ? "isn't" : "aren't"}`}, so ${off.length === 1 ? "it isn't" : "they aren't"} available there.`,
|
|
88
|
+
detail: [...off.slice(0, 12).map((t) => t.name), ...(off.length > 12 ? [`and ${off.length - 12} more`] : []), `Source: ${profile.readOnlyOnly.source} (read ${profile.readOnlyOnly.read}).`],
|
|
89
|
+
fix: 'Mark the tools that only read with readOnlyHint: true (and only those: clients act on it).',
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
return out;
|
|
94
|
+
},
|
|
95
|
+
};
|
|
@@ -1,5 +1,8 @@
|
|
|
1
|
+
import { type ToolChange } from '../compare.js';
|
|
1
2
|
import type { MenuTool, Severity } from '../types.js';
|
|
2
3
|
import { type Rule, type RuleFinding } from './rule.js';
|
|
4
|
+
/** The fields that differ, when none of them is one the model reads; undefined otherwise. */
|
|
5
|
+
export declare function outsideModel(before: MenuTool[], after: MenuTool[], changes: ToolChange[]): string[] | undefined;
|
|
3
6
|
export declare const nondeterministic: Rule;
|
|
4
7
|
/** What a second process or connection served, for the variance rules. */
|
|
5
8
|
export interface Probe {
|
|
@@ -45,6 +45,35 @@ function places(before, after) {
|
|
|
45
45
|
return [...changes.filter((c) => !EDITS.has(c.kind)).map((c) => `${c.kind}:${c.tool}`), ...everySpot(before, after, changes).map((s) => s.where)];
|
|
46
46
|
}
|
|
47
47
|
const isTime = (s) => TIMESTAMP.test(String(s.before)) && TIMESTAMP.test(String(s.after));
|
|
48
|
+
/**
|
|
49
|
+
* Changes the model reads: the tool set, its order, names, descriptions and input
|
|
50
|
+
* schemas (and their bytes: key order). Output schemas, annotations and other fields
|
|
51
|
+
* (a per-tool "version" hash: the @pipeworx servers) stay with the client.
|
|
52
|
+
*/
|
|
53
|
+
const MODEL_KINDS = new Set(['added', 'removed', 'moved', 'description', 'inputSchema', 'serialization']);
|
|
54
|
+
/** The fields that differ, when none of them is one the model reads; undefined otherwise. */
|
|
55
|
+
export function outsideModel(before, after, changes) {
|
|
56
|
+
if (!changes.length || changes.some((c) => MODEL_KINDS.has(c.kind)))
|
|
57
|
+
return undefined;
|
|
58
|
+
const fields = new Set();
|
|
59
|
+
for (const s of everySpot(before, after, changes)) {
|
|
60
|
+
const rest = s.where.slice(s.tool.length + 1);
|
|
61
|
+
if (rest)
|
|
62
|
+
fields.add(rest.split(/[.[]/)[0]);
|
|
63
|
+
}
|
|
64
|
+
for (const c of changes)
|
|
65
|
+
if (c.kind === 'outputSchema' || c.kind === 'annotations')
|
|
66
|
+
fields.add(c.kind);
|
|
67
|
+
return [...fields].sort();
|
|
68
|
+
}
|
|
69
|
+
/** "version", "version and annotations". */
|
|
70
|
+
function fieldList(fields) {
|
|
71
|
+
return fields.length <= 1 ? fields.join('') : `${fields.slice(0, -1).join(', ')} and ${fields.at(-1)}`;
|
|
72
|
+
}
|
|
73
|
+
/** Why a variance only in fields the model doesn't read still matters. */
|
|
74
|
+
function outsideModelCost(fields) {
|
|
75
|
+
return `It differs only in ${fieldList(fields)}, which clients keep to themselves: the model doesn't read ${fields.length === 1 ? 'it' : 'them'}, so prompt caches aren't affected, but no baseline matches, so every diff and review reports a change.`;
|
|
76
|
+
}
|
|
48
77
|
/** "list_transactions.end_date.default" or "a.b, c.d and 3 more places". */
|
|
49
78
|
function placesOf(found) {
|
|
50
79
|
const shown = found.slice(0, 2).map((s) => s.where).join(', ');
|
|
@@ -96,12 +125,16 @@ export const nondeterministic = {
|
|
|
96
125
|
const onlyOrder = changes.every((c) => c.kind === 'moved');
|
|
97
126
|
const found = spots(ctx.menu.tools, ctx.secondList, changes);
|
|
98
127
|
const tools = [...new Set(changes.map((c) => c.tool))];
|
|
128
|
+
const outside = outsideModel(ctx.menu.tools, ctx.secondList, changes);
|
|
99
129
|
return [
|
|
100
130
|
{
|
|
101
131
|
...(tools.length === 1 ? { tool: tools[0] } : {}),
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
132
|
+
...(outside ? { severity: 'warn' } : {}),
|
|
133
|
+
message: outside
|
|
134
|
+
? `Two identical tools/list calls, back to back, returned different menus. ${outsideModelCost(outside)} ${whatDiffers(changes, found)}`.trim()
|
|
135
|
+
: onlyOrder
|
|
136
|
+
? 'Two identical tools/list calls, back to back, returned the tools in a different order, so a cached prompt with the tool list rarely matches the next one: every conversation can miss the prompt cache. The spec says servers SHOULD keep the order stable.'
|
|
137
|
+
: `Two identical tools/list calls, back to back, returned different menus, so a cached prompt with the tool list rarely matches the next one: every conversation can miss the prompt cache. ${whatDiffers(changes, found)}`.trim(),
|
|
105
138
|
detail: detailFor(ctx.menu.tools, ctx.secondList, changes),
|
|
106
139
|
fix: fixFor(changes, found, 'call'),
|
|
107
140
|
},
|
|
@@ -146,10 +179,13 @@ export function varianceFinding(main, other, opts) {
|
|
|
146
179
|
detail = lines.slice(0, 10).concat(lines.length > 10 ? [`…and ${lines.length - 10} more`] : []);
|
|
147
180
|
}
|
|
148
181
|
const reordered = found.some((s) => s.reordered);
|
|
182
|
+
const outside = outsideModel(main, other, why);
|
|
149
183
|
const message = [
|
|
150
|
-
|
|
151
|
-
?
|
|
152
|
-
:
|
|
184
|
+
outside
|
|
185
|
+
? `A second ${stdio ? 'server process, started the same way,' : 'connection with the same credentials'} served a different menu. ${outsideModelCost(outside)}`
|
|
186
|
+
: stdio
|
|
187
|
+
? 'A second server process, started the same way, served a different menu, so every restart, and every client that starts its own copy, gets a tool list that no cached prompt matches.'
|
|
188
|
+
: `A second connection with the same credentials got a different menu, so clients can't share a cached tool list.${opts.modern ? ' On 2026-07-28 the tool set MUST NOT vary per connection.' : ''}`,
|
|
153
189
|
lead,
|
|
154
190
|
whatDiffers(why, found),
|
|
155
191
|
reordered
|
|
@@ -162,7 +198,8 @@ export function varianceFinding(main, other, opts) {
|
|
|
162
198
|
].filter(Boolean).join(' ');
|
|
163
199
|
return {
|
|
164
200
|
rule: stdio ? 'menu/process-variance' : 'menu/connection-variance',
|
|
165
|
-
|
|
201
|
+
// Only in fields the model doesn't read: a warning, not an error (no cache is lost).
|
|
202
|
+
severity: outside ? (stdio || opts.modern ? 'warn' : 'info') : stdio || opts.modern ? 'error' : 'warn',
|
|
166
203
|
message,
|
|
167
204
|
detail,
|
|
168
205
|
fix: fixFor(why, found, stdio ? 'process' : 'connection'),
|
package/dist/rules/ids.js
CHANGED
|
@@ -71,6 +71,9 @@ export function idParams(tool) {
|
|
|
71
71
|
return params;
|
|
72
72
|
}
|
|
73
73
|
function looksLikeIdValue(schema) {
|
|
74
|
+
// null, true, false: not a schema an ID's value is described by.
|
|
75
|
+
if (!schema || typeof schema !== 'object')
|
|
76
|
+
return false;
|
|
74
77
|
if (schema.enum)
|
|
75
78
|
return false; // a fixed set of values is chosen, not invented
|
|
76
79
|
const type = schema.type;
|
|
@@ -88,7 +91,8 @@ function withOperations(tools) {
|
|
|
88
91
|
const out = [...tools];
|
|
89
92
|
for (const t of tools) {
|
|
90
93
|
for (const schema of Object.values(t.inputSchema?.properties ?? {})) {
|
|
91
|
-
|
|
94
|
+
// A property schema can be anything a server sends (null, true): only an object has an enum.
|
|
95
|
+
for (const v of schema && typeof schema === 'object' && Array.isArray(schema.enum) ? schema.enum : []) {
|
|
92
96
|
if (typeof v !== 'string' || !/^[a-z]+(?:_[a-z]+)+$/.test(v))
|
|
93
97
|
continue;
|
|
94
98
|
// Lists and searches only: a router's get_workflow needs the ID it would hand out.
|
package/dist/rules/index.js
CHANGED
|
@@ -2,7 +2,7 @@ import { SEVERITY_RANK } from '../types.js';
|
|
|
2
2
|
import { buried, cut, lateInstruction } from './description.js';
|
|
3
3
|
import { connectionVariance, hostSpecific, nondeterministic, processVariance } from './determinism.js';
|
|
4
4
|
import { authoredIds } from './ids.js';
|
|
5
|
-
import { clientName } from './clients.js';
|
|
5
|
+
import { clientFeatures, clientLimit, clientName } from './clients.js';
|
|
6
6
|
import { invalidCredential } from './auth.js';
|
|
7
7
|
import { networkDependent } from './network.js';
|
|
8
8
|
import { capabilityDependent } from './capabilities.js';
|
|
@@ -10,7 +10,7 @@ import { listSchema, listVariance } from './lists.js';
|
|
|
10
10
|
import { handleLifetime } from './handles.js';
|
|
11
11
|
import { authVariance, cacheScopePublic } from './identities.js';
|
|
12
12
|
import { route, sharedWord, vagueId } from './naming.js';
|
|
13
|
-
import { cacheHints, deprecated, discover, duplicateName, extensionId, schema, serverInfo, taskRequired, toolsCapability } from './spec.js';
|
|
13
|
+
import { cacheHints, deprecated, discover, duplicateName, extensionId, schema, serverInfo, taskRequired, toolName, toolsCapability } from './spec.js';
|
|
14
14
|
import { noDryRun, readOnlyMismatch, unannotated } from './write.js';
|
|
15
15
|
import { gated } from './gated.js';
|
|
16
16
|
import { xMcpHeader } from './headers.js';
|
|
@@ -22,6 +22,7 @@ import { serverCard } from './card.js';
|
|
|
22
22
|
export const MENU_RULES = [
|
|
23
23
|
nondeterministic,
|
|
24
24
|
duplicateName,
|
|
25
|
+
toolName,
|
|
25
26
|
gated,
|
|
26
27
|
processVariance,
|
|
27
28
|
connectionVariance,
|
|
@@ -30,6 +31,8 @@ export const MENU_RULES = [
|
|
|
30
31
|
sharedWord,
|
|
31
32
|
route,
|
|
32
33
|
clientName,
|
|
34
|
+
clientLimit,
|
|
35
|
+
clientFeatures,
|
|
33
36
|
findable,
|
|
34
37
|
authoredIds,
|
|
35
38
|
handleLifetime,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { JsonSchema } from '../types.js';
|
|
2
|
+
/** The protocol version output schemas came in. */
|
|
3
|
+
export declare const OUTPUT_SCHEMA_SINCE = "2025-06-18";
|
|
4
|
+
/**
|
|
5
|
+
* What's wrong with a successful result against the tool's outputSchema, or
|
|
6
|
+
* undefined when it conforms (or the schema can't be compiled: then it's the
|
|
7
|
+
* schema that's broken, which spec/schema reports, not the result).
|
|
8
|
+
*/
|
|
9
|
+
export declare function outputProblem(schema: JsonSchema, result: {
|
|
10
|
+
structuredContent?: unknown;
|
|
11
|
+
}): string | undefined;
|
|
12
|
+
/**
|
|
13
|
+
* The same, and whether only `format` checks failed (a URI, a date): many validators
|
|
14
|
+
* skip format unless told to, so such a result may well pass a client.
|
|
15
|
+
*/
|
|
16
|
+
export declare function outputCheck(schema: JsonSchema, result: {
|
|
17
|
+
structuredContent?: unknown;
|
|
18
|
+
}): {
|
|
19
|
+
problem: string;
|
|
20
|
+
formatOnly: boolean;
|
|
21
|
+
} | undefined;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* session/output-schema: a tool that declares an outputSchema promises its results.
|
|
3
|
+
* 2025-06-18 and later: "If an output schema is provided, servers MUST provide
|
|
4
|
+
* structured results that conform to this schema", and clients SHOULD validate
|
|
5
|
+
* them; the official TypeScript SDK client does, and throws on a result that has no
|
|
6
|
+
* structuredContent or one that doesn't match. Checked on every call that answered
|
|
7
|
+
* (not isError), so it needs a session that calls the tool.
|
|
8
|
+
*/
|
|
9
|
+
import { Ajv } from 'ajv';
|
|
10
|
+
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
11
|
+
import addFormatsImport from 'ajv-formats';
|
|
12
|
+
const addFormats = (addFormatsImport.default ?? addFormatsImport);
|
|
13
|
+
/** The protocol version output schemas came in. */
|
|
14
|
+
export const OUTPUT_SCHEMA_SINCE = '2025-06-18';
|
|
15
|
+
const validators = new WeakMap();
|
|
16
|
+
/**
|
|
17
|
+
* What's wrong with a successful result against the tool's outputSchema, or
|
|
18
|
+
* undefined when it conforms (or the schema can't be compiled: then it's the
|
|
19
|
+
* schema that's broken, which spec/schema reports, not the result).
|
|
20
|
+
*/
|
|
21
|
+
export function outputProblem(schema, result) {
|
|
22
|
+
return outputCheck(schema, result)?.problem;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* The same, and whether only `format` checks failed (a URI, a date): many validators
|
|
26
|
+
* skip format unless told to, so such a result may well pass a client.
|
|
27
|
+
*/
|
|
28
|
+
export function outputCheck(schema, result) {
|
|
29
|
+
if (result.structuredContent === undefined)
|
|
30
|
+
return { problem: 'returned no structuredContent, although the tool declares an outputSchema', formatOnly: false };
|
|
31
|
+
let validate = validators.get(schema);
|
|
32
|
+
if (!validate) {
|
|
33
|
+
const draft2020 = typeof schema.$schema !== 'string' || schema.$schema.includes('2020-12');
|
|
34
|
+
const ajv = draft2020 ? new Ajv2020({ strict: false, allErrors: true }) : new Ajv({ strict: false, allErrors: true });
|
|
35
|
+
addFormats(ajv);
|
|
36
|
+
try {
|
|
37
|
+
validate = ajv.compile(schema);
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return undefined;
|
|
41
|
+
}
|
|
42
|
+
validators.set(schema, validate);
|
|
43
|
+
}
|
|
44
|
+
if (validate(result.structuredContent))
|
|
45
|
+
return undefined;
|
|
46
|
+
const all = validate.errors ?? [];
|
|
47
|
+
const errors = all.slice(0, 3).map((e) => `${e.instancePath || '(the result)'} ${e.message ?? 'is invalid'}`);
|
|
48
|
+
return { problem: `returned structuredContent that doesn't match its outputSchema: ${errors.join('; ')}`, formatOnly: all.length > 0 && all.every((e) => e.keyword === 'format') };
|
|
49
|
+
}
|
package/dist/rules/search.js
CHANGED
|
@@ -25,7 +25,7 @@ export const findable = {
|
|
|
25
25
|
if (profile) {
|
|
26
26
|
// A client that defers tools does it at any size; one whose search results
|
|
27
27
|
// aren't documented (OpenAI's spec doesn't say how many) isn't ranked against a guess.
|
|
28
|
-
if (profile.defers.value === 'none' || tools.length < 2)
|
|
28
|
+
if (!profile.defers || profile.defers.value === 'none' || tools.length < 2)
|
|
29
29
|
return [];
|
|
30
30
|
if (!profile.searchLimit && ctx.client !== 'claude-code')
|
|
31
31
|
return [];
|
package/dist/rules/spec.d.ts
CHANGED
|
@@ -4,6 +4,16 @@ export declare function resultValidator(version: string, result?: string): impor
|
|
|
4
4
|
export declare const schema: Rule;
|
|
5
5
|
export declare const toolsCapability: Rule;
|
|
6
6
|
export declare const duplicateName: Rule;
|
|
7
|
+
/**
|
|
8
|
+
* What's wrong with a tool name, or undefined when it fits the spec's format. `hidden`:
|
|
9
|
+
* it has characters that act on a terminal or can't be seen, so it can pass for
|
|
10
|
+
* another name or for none.
|
|
11
|
+
*/
|
|
12
|
+
export declare function toolNameProblem(name: string): {
|
|
13
|
+
why: string;
|
|
14
|
+
hidden: boolean;
|
|
15
|
+
} | undefined;
|
|
16
|
+
export declare const toolName: Rule;
|
|
7
17
|
export declare const discover: Rule;
|
|
8
18
|
export declare const deprecated: Rule;
|
|
9
19
|
/**
|
|
@@ -21,3 +31,12 @@ export declare const cacheHints: Rule;
|
|
|
21
31
|
*/
|
|
22
32
|
export declare const extensionId: Rule;
|
|
23
33
|
export declare const taskRequired: Rule;
|
|
34
|
+
/**
|
|
35
|
+
* The SDK's rejection, readable: "Invalid result for tools/list: [ {...zod issues...} ]"
|
|
36
|
+
* spans many lines, and its first line alone said only "…tools/list: [" (the
|
|
37
|
+
* @pipeworx servers, bench 2026-11-09). Each issue becomes a detail line, "path: message".
|
|
38
|
+
*/
|
|
39
|
+
export declare function sdkIssues(error: string): {
|
|
40
|
+
summary: string;
|
|
41
|
+
detail: string[];
|
|
42
|
+
};
|
package/dist/rules/spec.js
CHANGED
|
@@ -4,6 +4,7 @@ import { Ajv } from 'ajv';
|
|
|
4
4
|
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
5
5
|
import addFormatsImport from 'ajv-formats';
|
|
6
6
|
import { kept, names } from './rule.js';
|
|
7
|
+
import { HIDDEN_SOURCE } from '../sanitize.js';
|
|
7
8
|
// ajv-formats ships CommonJS; under NodeNext its default import is the module object.
|
|
8
9
|
const addFormats = (addFormatsImport.default ?? addFormatsImport);
|
|
9
10
|
const SCHEMA_DIR = fileURLToPath(new URL('../../schemas/', import.meta.url));
|
|
@@ -54,8 +55,10 @@ export const schema = {
|
|
|
54
55
|
}
|
|
55
56
|
const findings = [];
|
|
56
57
|
if (ctx.clientError && ctx.pages.every((page) => validate(page))) {
|
|
58
|
+
const said = sdkIssues(ctx.clientError);
|
|
57
59
|
findings.push({
|
|
58
|
-
message: `The official MCP SDK client rejected the tools/list result, so clients built on it list no tools. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${
|
|
60
|
+
message: `The official MCP SDK client rejected the tools/list result, so clients built on it list no tools. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${said.summary}`,
|
|
61
|
+
...(said.detail.length ? { detail: said.detail } : {}),
|
|
59
62
|
fix: 'Fix what the SDK names above, then list the tools with the official client to confirm.',
|
|
60
63
|
});
|
|
61
64
|
}
|
|
@@ -108,6 +111,64 @@ export const duplicateName = {
|
|
|
108
111
|
}));
|
|
109
112
|
},
|
|
110
113
|
};
|
|
114
|
+
/** The tool-name format the spec recommends from 2025-11-25 (SEP-986): 1 to 128 of A-Z a-z 0-9 _ - . */
|
|
115
|
+
const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
|
|
116
|
+
/** The characters reports show as escapes (sanitize.ts): one class, so what's flagged is what's escaped. */
|
|
117
|
+
const HIDDEN = new RegExp(HIDDEN_SOURCE, 'u');
|
|
118
|
+
const codePoint = (c) => `U+${c.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}`;
|
|
119
|
+
/**
|
|
120
|
+
* What's wrong with a tool name, or undefined when it fits the spec's format. `hidden`:
|
|
121
|
+
* it has characters that act on a terminal or can't be seen, so it can pass for
|
|
122
|
+
* another name or for none.
|
|
123
|
+
*/
|
|
124
|
+
export function toolNameProblem(name) {
|
|
125
|
+
if (TOOL_NAME.test(name))
|
|
126
|
+
return undefined;
|
|
127
|
+
const chars = [...name];
|
|
128
|
+
if (chars.length === 0)
|
|
129
|
+
return { why: 'it is empty', hidden: false };
|
|
130
|
+
const hidden = [...new Set(chars.filter((c) => HIDDEN.test(c)))];
|
|
131
|
+
const other = [...new Set(chars.filter((c) => !HIDDEN.test(c) && !/[A-Za-z0-9_.-]/.test(c)))];
|
|
132
|
+
// Printable ASCII as itself; anything else by code point too, so a lookalike can't hide.
|
|
133
|
+
const shown = other.map((c) => (c === ' ' ? 'a space' : /^[!-~]$/.test(c) ? `"${c}"` : `${codePoint(c)} "${c}"`));
|
|
134
|
+
const parts = [
|
|
135
|
+
...(hidden.length ? [`characters a terminal acts on or a reader can't see (${hidden.map(codePoint).join(', ')}: controls, invisible or text-direction characters)`] : []),
|
|
136
|
+
...(shown.length ? [shown.join(', ')] : []),
|
|
137
|
+
];
|
|
138
|
+
const long = chars.length > 128 ? `${chars.length} characters long, over 128` : '';
|
|
139
|
+
return { why: parts.length ? `it has ${parts.join('; and ')}${long ? `, and is ${long}` : ''}` : `it is ${long}`, hidden: hidden.length > 0 };
|
|
140
|
+
}
|
|
141
|
+
export const toolName = {
|
|
142
|
+
id: 'spec/tool-name',
|
|
143
|
+
severity: 'warn',
|
|
144
|
+
summary: "Tool names fit the format the spec recommends: 1 to 128 of A-Z, a-z, 0-9, _, - and .",
|
|
145
|
+
run(ctx) {
|
|
146
|
+
const bad = kept(ctx.menu.tools, ctx).flatMap((t) => {
|
|
147
|
+
const p = toolNameProblem(t.name);
|
|
148
|
+
return p ? [{ tool: t.name, ...p }] : [];
|
|
149
|
+
});
|
|
150
|
+
if (!bad.length)
|
|
151
|
+
return [];
|
|
152
|
+
// Hidden characters are an error on any protocol: the name can pass for another tool's.
|
|
153
|
+
// Otherwise a recommendation from 2025-11-25 on; before that the spec gave no format.
|
|
154
|
+
const hidden = bad.filter((b) => b.hidden);
|
|
155
|
+
const older = !!ctx.protocolVersion && ctx.protocolVersion < '2025-11-25';
|
|
156
|
+
return [
|
|
157
|
+
{
|
|
158
|
+
...(bad.length === 1 ? { tool: bad[0].tool } : {}),
|
|
159
|
+
...(hidden.length ? { severity: 'error' } : older ? { severity: 'info' } : {}),
|
|
160
|
+
message: `${bad.length === 1 ? `The tool name ${bad[0].tool} doesn't` : `${bad.length} tool names don't`} fit the tool name format the MCP spec recommends from 2025-11-25 (1 to 128 characters, A-Z, a-z, 0-9, _, - and .)` +
|
|
161
|
+
`${older ? `; this server speaks ${ctx.protocolVersion}, which gave no format, so it's for the move to 2025-11-25` : ''}. ` +
|
|
162
|
+
(hidden.length
|
|
163
|
+
? `${hidden.length === 1 ? (bad.length === 1 ? 'It has' : 'One has') : `${hidden.length} have`} characters that are hidden or act on the screen, so what an agent or a person reads isn't the name the server takes. `
|
|
164
|
+
: '') +
|
|
165
|
+
'Clients may refuse such a tool, rename it, or pass it to a model API that refuses it.',
|
|
166
|
+
detail: bad.slice(0, 12).map((b) => `${b.tool}: ${b.why}`).concat(bad.length > 12 ? [`and ${bad.length - 12} more`] : []),
|
|
167
|
+
fix: 'Name tools with letters, digits, _, - and . only (files_read or files.read, not "files read"), at most 128 characters.',
|
|
168
|
+
},
|
|
169
|
+
];
|
|
170
|
+
},
|
|
171
|
+
};
|
|
111
172
|
export const discover = {
|
|
112
173
|
id: 'spec/discover',
|
|
113
174
|
severity: 'info',
|
|
@@ -300,3 +361,27 @@ export const taskRequired = {
|
|
|
300
361
|
];
|
|
301
362
|
},
|
|
302
363
|
};
|
|
364
|
+
/**
|
|
365
|
+
* The SDK's rejection, readable: "Invalid result for tools/list: [ {...zod issues...} ]"
|
|
366
|
+
* spans many lines, and its first line alone said only "…tools/list: [" (the
|
|
367
|
+
* @pipeworx servers, bench 2026-11-09). Each issue becomes a detail line, "path: message".
|
|
368
|
+
*/
|
|
369
|
+
export function sdkIssues(error) {
|
|
370
|
+
const at = error.indexOf('[');
|
|
371
|
+
if (at !== -1) {
|
|
372
|
+
try {
|
|
373
|
+
const issues = JSON.parse(error.slice(at));
|
|
374
|
+
if (Array.isArray(issues) && issues.length) {
|
|
375
|
+
const detail = issues.slice(0, 10).map((i) => `${(i.path ?? []).join('.') || '(the result)'}: ${i.message ?? 'invalid'}`);
|
|
376
|
+
if (issues.length > 10)
|
|
377
|
+
detail.push(`…and ${issues.length - 10} more`);
|
|
378
|
+
return { summary: `${error.slice(0, at).trim().replace(/:$/, '')}, ${issues.length === 1 ? 'one problem' : `${issues.length} problems`}.`, detail };
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
catch {
|
|
382
|
+
// Not JSON after all: said as text below.
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
const flat = error.replace(/\s+/g, ' ').trim();
|
|
386
|
+
return { summary: flat.length > 300 ? `${flat.slice(0, 297)}…` : flat, detail: [] };
|
|
387
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Characters a terminal (or GitHub's log parser) acts on, or a reader can't see:
|
|
3
|
+
* controls (C0, C1, DEL), format characters (the bidi overrides and isolates that
|
|
4
|
+
* reorder what's shown, "Trojan Source"; zero-width spaces and joiners; the soft
|
|
5
|
+
* hyphen; tag characters), line and paragraph separators, everything Unicode says
|
|
6
|
+
* renders as nothing (variation selectors, Hangul fillers), and the blank braille
|
|
7
|
+
* cell. Newline and tab are in it: a server's newline would start a line of its own
|
|
8
|
+
* (a fake finding, a `::error::` workflow command). spec/tool-name uses the same class.
|
|
9
|
+
*/
|
|
10
|
+
export declare const HIDDEN_SOURCE = "[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Default_Ignorable_Code_Point}\\u2800]";
|
|
11
|
+
/** One field of server text, for the terminal: every control character shown as an escape. */
|
|
12
|
+
export declare function plain(text: string): string;
|
|
13
|
+
/**
|
|
14
|
+
* A whole report, last thing before it's printed: whatever control characters a field
|
|
15
|
+
* still carries are shown as escapes. Its own newlines and tabs stay; the fields that
|
|
16
|
+
* came from the server have already had theirs escaped by plain().
|
|
17
|
+
*/
|
|
18
|
+
export declare function terminalSafe(report: string): string;
|
|
19
|
+
export interface MdOptions {
|
|
20
|
+
/** In a table cell: pipes are escaped, even inside code spans (GFM requires it). */
|
|
21
|
+
cell?: boolean;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Text as a markdown code span that it can't close: a fence of backticks longer than
|
|
25
|
+
* any run inside it, padded when it starts or ends with one. Control characters are
|
|
26
|
+
* shown as escapes, so it's always one line.
|
|
27
|
+
*/
|
|
28
|
+
export declare function mdCode(text: string, options?: MdOptions): string;
|
|
29
|
+
/**
|
|
30
|
+
* A finding's text, or any line that carries server text, as markdown: toolmenu's own
|
|
31
|
+
* `code` spans stay code, everything else is escaped. A backtick in a server's text
|
|
32
|
+
* can only move where code starts and ends: every piece is rendered inert either way.
|
|
33
|
+
*/
|
|
34
|
+
export declare function mdText(text: string, options?: MdOptions): string;
|
|
35
|
+
/**
|
|
36
|
+
* The net under every field: from here on, text written to `stream` goes through
|
|
37
|
+
* terminalSafe(). For the CLI's stdout and stderr, whatever the command; JSON stays
|
|
38
|
+
* the same JSON (its escapes read back as the same characters). Twice is once.
|
|
39
|
+
*/
|
|
40
|
+
export declare function guardStream(stream: NodeJS.WritableStream): void;
|
|
41
|
+
/** Write past the net: only text already made safe, with toolmenu's own colour codes added. */
|
|
42
|
+
export declare function writeUnguarded(stream: NodeJS.WritableStream, text: string): void;
|