toolmenu 0.25.1 → 0.27.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 (62) hide show
  1. package/README.md +312 -35
  2. package/dist/args.d.ts +14 -2
  3. package/dist/args.js +44 -1
  4. package/dist/auth-check.d.ts +27 -0
  5. package/dist/auth-check.js +177 -0
  6. package/dist/auth.d.ts +7 -0
  7. package/dist/auth.js +29 -1
  8. package/dist/auto.d.ts +8 -0
  9. package/dist/auto.js +9 -2
  10. package/dist/breakdown.js +14 -10
  11. package/dist/cli.js +171 -56
  12. package/dist/clients.d.ts +13 -2
  13. package/dist/clients.js +65 -11
  14. package/dist/config.js +6 -0
  15. package/dist/diff.d.ts +35 -1
  16. package/dist/diff.js +57 -12
  17. package/dist/failures.js +4 -3
  18. package/dist/help.d.ts +1 -1
  19. package/dist/help.js +45 -17
  20. package/dist/history.js +5 -0
  21. package/dist/html.d.ts +29 -0
  22. package/dist/html.js +360 -0
  23. package/dist/index.d.ts +3 -2
  24. package/dist/index.js +3 -2
  25. package/dist/init.d.ts +14 -0
  26. package/dist/init.js +20 -6
  27. package/dist/junit.d.ts +17 -0
  28. package/dist/junit.js +87 -0
  29. package/dist/mcp-env.d.ts +6 -0
  30. package/dist/mcp-env.js +6 -0
  31. package/dist/mcp.d.ts +10 -0
  32. package/dist/mcp.js +86 -15
  33. package/dist/menu.d.ts +6 -0
  34. package/dist/menu.js +12 -1
  35. package/dist/options.d.ts +13 -0
  36. package/dist/options.js +4 -0
  37. package/dist/report.d.ts +14 -0
  38. package/dist/report.js +57 -51
  39. package/dist/review.d.ts +48 -0
  40. package/dist/review.js +212 -0
  41. package/dist/rule-docs.json +49 -4
  42. package/dist/rules/clients.d.ts +11 -0
  43. package/dist/rules/clients.js +65 -2
  44. package/dist/rules/determinism.d.ts +3 -0
  45. package/dist/rules/determinism.js +44 -7
  46. package/dist/rules/ids.js +5 -1
  47. package/dist/rules/index.js +5 -2
  48. package/dist/rules/output.d.ts +21 -0
  49. package/dist/rules/output.js +49 -0
  50. package/dist/rules/search.js +1 -1
  51. package/dist/rules/spec.d.ts +19 -0
  52. package/dist/rules/spec.js +86 -1
  53. package/dist/sanitize.d.ts +42 -0
  54. package/dist/sanitize.js +142 -0
  55. package/dist/sarif.d.ts +2 -0
  56. package/dist/sarif.js +2 -2
  57. package/dist/scan.d.ts +9 -2
  58. package/dist/scan.js +46 -24
  59. package/dist/session.d.ts +17 -0
  60. package/dist/session.js +119 -13
  61. package/dist/snapshot.js +2 -1
  62. package/package.json +5 -3
package/dist/diff.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Finding, JsonSchema, Menu, Severity } from './types.js';
1
+ import type { Finding, JsonSchema, Menu, MenuTool, Severity } from './types.js';
2
2
  export type ChangeClass = 'breaking' | 'minor' | 'notice';
3
3
  export type Bump = 'major' | 'minor' | 'patch' | 'none';
4
4
  export interface DiffFinding extends Finding {
@@ -18,6 +18,27 @@ interface DiffRule {
18
18
  }
19
19
  /** Every diff rule, its default severity and what it means for semver. */
20
20
  export declare const DIFF_RULES: Record<string, DiffRule>;
21
+ /** The tools a diff compares, after the ignore globs, and how they changed by name. */
22
+ export interface DiffTools {
23
+ before: MenuTool[];
24
+ after: MenuTool[];
25
+ /** Each of `after`'s position in the newer menu as served, ignored tools included. */
26
+ positions: number[];
27
+ /** How many tools of the newer menu the ignore globs left out. */
28
+ ignored: number;
29
+ added: string[];
30
+ removed: string[];
31
+ renamed: {
32
+ from: string;
33
+ to: string;
34
+ }[];
35
+ }
36
+ /**
37
+ * The tools diffMenus compares and how they changed: ignored tools leave the
38
+ * comparison entirely, so they can't pair into a rename or show up as a reorder.
39
+ * The HTML report shows the same.
40
+ */
41
+ export declare function comparedTools(before: Menu, after: Menu, ignore?: string[]): DiffTools;
21
42
  export interface TokenChange {
22
43
  before: number;
23
44
  after: number;
@@ -78,6 +99,19 @@ export interface DiffOptions {
78
99
  serverVersionIsRelease?: boolean;
79
100
  }
80
101
  export declare function diffMenus(before: Menu, after: Menu, options?: DiffOptions): DiffResult;
102
+ /**
103
+ * One schema against its next version, anywhere in a tool: its type, allowed
104
+ * values and description; array items, object fields and union options, each
105
+ * compared the same way; and whatever's left, as one "review it". `at` is its
106
+ * path, and the path nested fields hang off: `gen.rows[]` for array items,
107
+ * `gen.block(kind="text")` for a union option.
108
+ */
109
+ /**
110
+ * A schema as an object. JSON Schema allows `true` (anything) and `false` (nothing)
111
+ * as a whole schema (`"items": true`, figma-mcp-rs); a broken server may send null or
112
+ * a string. Those are wrapped, not dropped, so a change to them still shows.
113
+ */
114
+ export declare function asSchema(node: unknown): JsonSchema;
81
115
  /**
82
116
  * The schema with local $refs (`#/$defs/…`, `#/definitions/…`) replaced by what
83
117
  * they point to, and the root $defs dropped: two spellings of one schema compare
package/dist/diff.js CHANGED
@@ -79,6 +79,31 @@ export const DIFF_RULES = {
79
79
  'diff/resources': { severity: 'info', class: 'notice' },
80
80
  'diff/lists-unread': { severity: 'info' },
81
81
  };
82
+ /**
83
+ * The tools diffMenus compares and how they changed: ignored tools leave the
84
+ * comparison entirely, so they can't pair into a rename or show up as a reorder.
85
+ * The HTML report shows the same.
86
+ */
87
+ export function comparedTools(before, after, ignore) {
88
+ const ignored = ignoreMatcher(ignore);
89
+ const oldTools = before.tools.filter((t) => !ignored(t.name));
90
+ const positions = [];
91
+ const newTools = after.tools.filter((t, i) => !ignored(t.name) && positions.push(i) > 0);
92
+ const oldNames = new Set(oldTools.map((t) => t.name));
93
+ const newNames = new Set(newTools.map((t) => t.name));
94
+ const renames = findRenames(oldTools.filter((t) => !newNames.has(t.name)), newTools.filter((t) => !oldNames.has(t.name)));
95
+ const from = new Set(renames.map((r) => r.from.name));
96
+ const to = new Set(renames.map((r) => r.to.name));
97
+ return {
98
+ before: oldTools,
99
+ after: newTools,
100
+ positions,
101
+ ignored: after.tools.length - newTools.length,
102
+ added: newTools.filter((t) => !oldNames.has(t.name) && !to.has(t.name)).map((t) => t.name),
103
+ removed: oldTools.filter((t) => !newNames.has(t.name) && !from.has(t.name)).map((t) => t.name),
104
+ renamed: renames.map((r) => ({ from: r.from.name, to: r.to.name })),
105
+ };
106
+ }
82
107
  /**
83
108
  * In fixes: the release a breaking change should ship in. Resolved once the
84
109
  * versions are known (resolveFixes): "release it as 2.0.0", or "ship it in a
@@ -92,16 +117,15 @@ export function diffMenus(before, after, options = {}) {
92
117
  const modern = isModern(after);
93
118
  // A tool the old release already lost to a bad annotation isn't news; on a 2025 server it lost nothing.
94
119
  const headers = { headers: modern, oldHeaders: isModern(before) };
95
- // Ignored tools leave the comparison entirely, so they can't pair into a
96
- // rename or show up as a reorder.
97
120
  const ignored = ignoreMatcher(options.ignore);
98
- const oldTools = before.tools.filter((t) => !ignored(t.name));
99
- const newTools = after.tools.filter((t) => !ignored(t.name));
121
+ const compared = comparedTools(before, after, options.ignore);
122
+ const oldTools = compared.before;
123
+ const newTools = compared.after;
100
124
  const oldByName = new Map(oldTools.map((t) => [t.name, t]));
101
125
  const newByName = new Map(newTools.map((t) => [t.name, t]));
102
126
  const removed = oldTools.filter((t) => !newByName.has(t.name));
103
127
  const added = newTools.filter((t) => !oldByName.has(t.name));
104
- const renames = findRenames(removed, added);
128
+ const renames = compared.renamed.map((r) => ({ from: oldByName.get(r.from), to: newByName.get(r.to) }));
105
129
  const renamedFrom = new Set(renames.map((r) => r.from.name));
106
130
  const renamedTo = new Set(renames.map((r) => r.to.name));
107
131
  for (const { from, to } of renames) {
@@ -813,7 +837,23 @@ function sameKind(a, b) {
813
837
  * path, and the path nested fields hang off: `gen.rows[]` for array items,
814
838
  * `gen.block(kind="text")` for a union option.
815
839
  */
816
- function compareSchema(w, at, before, after, depth) {
840
+ /**
841
+ * A schema as an object. JSON Schema allows `true` (anything) and `false` (nothing)
842
+ * as a whole schema (`"items": true`, figma-mcp-rs); a broken server may send null or
843
+ * a string. Those are wrapped, not dropped, so a change to them still shows.
844
+ */
845
+ export function asSchema(node) {
846
+ if (node === true)
847
+ return {};
848
+ if (node === false)
849
+ return { not: {} };
850
+ if (node && typeof node === 'object' && !Array.isArray(node))
851
+ return node;
852
+ return { 'x-toolmenu-not-a-schema': node };
853
+ }
854
+ function compareSchema(w, at, rawBefore, rawAfter, depth) {
855
+ const before = asSchema(rawBefore);
856
+ const after = asSchema(rawAfter);
817
857
  // Past the limit, a change is said as such, not passed off as an unclassified one.
818
858
  if (depth >= MAX_DEPTH) {
819
859
  if (canonical(sameTypes(before)) !== canonical(sameTypes(after))) {
@@ -841,7 +881,10 @@ function compareSchema(w, at, before, after, depth) {
841
881
  if (accepts(after, before))
842
882
  say(w, 'diff/type-widened', at, ` now accepts more types: ${pair}`, '', [before, after]);
843
883
  else {
844
- say(w, 'diff/param-type', at, ` changed type: ${pair}`, `Calls that send ${oldType ? `${article(oldType)} ${oldType}` : 'any other type'} fail validation.`, [before, after], {
884
+ // Only the types the new schema no longer takes: null|string → string loses null.
885
+ const newTypes = new Set(typesOf(after) ?? []);
886
+ const lost = [...new Set(typesOf(before) ?? [])].filter((t) => !newTypes.has(t) && !(t === 'integer' && newTypes.has('number'))).sort().join(' or ');
887
+ say(w, 'diff/param-type', at, ` changed type: ${pair}`, `Calls that send ${lost ? `${article(lost)} ${lost}` : 'any other type'} fail validation.`, [before, after], {
845
888
  fix: oldType && newType ? `Accept both (${[...new Set([...oldType.split('|'), ...newType.split('|')])].join('|')}) for one release, or ${BREAKING_RELEASE}.` : `Restore the old type, or ${BREAKING_RELEASE}.`,
846
889
  });
847
890
  }
@@ -909,7 +952,7 @@ function compareSchema(w, at, before, after, depth) {
909
952
  * node's), as the one option.
910
953
  */
911
954
  function optionsOf(s) {
912
- const options = unionOptions(s);
955
+ const options = unionOptions(s)?.map(asSchema);
913
956
  return options && options.length > 0 ? options : [undescribed(s)];
914
957
  }
915
958
  /**
@@ -1168,9 +1211,10 @@ function discriminator(options) {
1168
1211
  const names = Object.keys(own[0].properties).sort();
1169
1212
  return names.find((n) => own.every((o) => fixedValue(o.properties[n]) !== undefined));
1170
1213
  }
1171
- function fixedValue(s) {
1172
- if (!s)
1214
+ function fixedValue(raw) {
1215
+ if (raw === undefined)
1173
1216
  return undefined;
1217
+ const s = asSchema(raw);
1174
1218
  if ('const' in s)
1175
1219
  return s.const;
1176
1220
  return Array.isArray(s.enum) && s.enum.length === 1 ? s.enum[0] : undefined;
@@ -1539,7 +1583,7 @@ function destructive(a) {
1539
1583
  return !readOnly(a) && a.destructiveHint !== false;
1540
1584
  }
1541
1585
  function hasDefault(schema) {
1542
- return 'default' in schema;
1586
+ return 'default' in asSchema(schema);
1543
1587
  }
1544
1588
  function show(value) {
1545
1589
  return value === undefined ? '(unset)' : JSON.stringify(value);
@@ -1639,7 +1683,8 @@ function typeAlternatives(schema) {
1639
1683
  function allowedValues(schema) {
1640
1684
  if (Array.isArray(schema.enum))
1641
1685
  return schema.enum;
1642
- return 'const' in schema ? [schema.const] : undefined;
1686
+ const s = asSchema(schema);
1687
+ return 'const' in s ? [s.const] : undefined;
1643
1688
  }
1644
1689
  function enumChange(before, after) {
1645
1690
  const a = allowedValues(before);
package/dist/failures.js CHANGED
@@ -15,19 +15,20 @@ const CLIENT = /client capabilit(?:y|ies)\b[^.]{0,60}\b(?:do(?:es)? not|don't|do
15
15
  // or the wrong operating system: "Editmamei runs on Windows and macOS; this process
16
16
  // is on "linux"" (editmamei), "Unsupported platform: linux" (an OS name, not any
17
17
  // "platform" argument: "Unsupported platform: myspace" is the tool's own error).
18
- const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\bunsupported (?:platform|operating system|OS)(?:\s*[.!]?\s*$|\s*\.\s|[^.\n]{0,40}?\b(?:linux|darwin|macos|win32|windows(?:_nt)?|freebsd|openbsd|aix|sunos|android)(?![a-z]))|\bnot supported on (?:this|the current) (?:platform|operating system|OS)\b/i;
18
+ const ENVIRONMENT = /could not find [^.]{0,40}executable|\bno (?:browser|chrome|chromium) (?:was )?found\b|\bnot a git repository\b|\b(?:extension|app|application|plugin|bridge) is not (?:connected|running)\b|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\bunsupported (?:platform|operating system|OS)(?:\s*[.!]?\s*$|\s*\.\s|[^.\n]{0,40}?\b(?:linux|darwin|macos|win32|windows(?:_nt)?|freebsd|openbsd|aix|sunos|android)(?![a-z]))|\bnot supported on (?:this|the current) (?:platform|operating system|OS)\b/i;
19
19
  // "401 Bad credentials" (GitHub), "Authorization Expired" (Sentry), "Invalid
20
20
  // token" (Firecrawl), "authentication token is not valid" (Apify), "Please provide
21
21
  // a valid access token" (Supabase), "NetlifyUnauthError: You're not logged into
22
22
  // Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
23
- // auth is missing", "Runtime credentials are missing" (securenow). Not a bare
23
+ // auth is missing", "Runtime credentials are missing" (securenow), "ADR Aggregator API key not
24
+ // configured" (mcp-adr-analysis-server). Not a bare
24
25
  // "token": plenty of errors mention one.
25
26
  // Hosted servers ask the user to sign in in their own words: "Sign in to Ideal (or create
26
27
  // your creator account) to continue", "Connect your Novamris account to read its saved chart".
27
28
  const SIGN_IN = /\bsign in to\b|\blog ?in to (?:continue|use)\b|\bconnect your [\w .'-]{1,40}? account\b/i;
28
29
  // A paid tool: "Payment required: $0.50 over MPP" (a hosted server), HTTP 402, no credits left.
29
30
  const PAYMENT = /\bpayment required\b|\b(?:HTTP|status(?: code)?) 402\b|\binsufficient (?:credits?|balance|funds)\b/i;
30
- const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
31
+ const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\b(?:api[ _-]?key|access token|auth token|credentials?)\b (?:is |are |was |were )?not (?:configured|set|provided)\b|\bneeds? (?:an? )?(?:[\w-]+ )?(?:credentials?|api[ _-]?key|access token)\b|\bmissing (?:required )?authentication credentials?\b|\b[a-z0-9_]*(?:api_?key|token|secret)\b (?:is |was )?not (?:set|configured|provided)\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
31
32
  const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
32
33
  // "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
33
34
  // "**Input Error**" (Sentry), JSON-RPC's invalid params.
package/dist/help.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
1
+ export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'review', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
2
2
  export type Command = (typeof COMMANDS)[number];
3
3
  /** `toolmenu --help`: what toolmenu is and which command to reach for. */
4
4
  export declare function overview(): string;
package/dist/help.js CHANGED
@@ -4,7 +4,7 @@
4
4
  * codes. Option names and behaviour live in cli.ts; this file only describes them.
5
5
  */
6
6
  import { VERSION } from './version.js';
7
- export const COMMANDS = ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
7
+ export const COMMANDS = ['init', 'snapshot', 'diff', 'review', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
8
8
  /** Every option, once: its spelling and what it does (continuation lines are indented by the renderer). */
9
9
  const OPTIONS = {
10
10
  out: ['--out <path>', ['where to write the menu (default: menu.json)']],
@@ -12,9 +12,11 @@ const OPTIONS = {
12
12
  routes: ['--routes <path>', ['routes.yml: pin which words route to which tools']],
13
13
  catalog: ['--catalog', ['also read the operations behind a search tool (search and execute:', 'discover, search_*_tools) or command routers (listed with learn: true,', 'never run) and keep them in the menu file for diff']],
14
14
  config: ['--config <path>', ['config file (default: toolmenu.config.json, if present)']],
15
- format: ['--format <fmt>', ['text (default), json, github (annotations), markdown (PR comments)', 'or sarif (code scanning; snapshot, diff and session)']],
15
+ format: ['--format <fmt>', ['text (default), json, github (annotations), markdown (PR comments)', 'sarif (code scanning) or junit (CI test reports); sarif and junit: snapshot,', 'diff and session']],
16
16
  badge: ['--badge <path>', ['also write a README badge there (a shields.io endpoint file: tools, tokens,', 'errors or warnings). Commit it with the menu file; it prints the README line']],
17
17
  sarif: ['--sarif <path>', ['also write the findings as SARIF 2.1.0 to this file, for GitHub code', 'scanning (upload it with github/codeql-action/upload-sarif)']],
18
+ junit: ['--junit <path>', ['also write the findings as JUnit XML to this file, for CI test reports', '(GitLab, Jenkins, Azure DevOps, CircleCI): findings at --fail-on or above fail']],
19
+ html: ['--html <path>', ['also write the report as one self-contained HTML page (no script, works', 'offline): keep it as a CI artifact or send it to someone']],
18
20
  'sarif-menu': ['--sarif-menu <path>', ['the committed menu file SARIF results point at, at each tool\'s line', '(default: the menu file this command wrote, or diff\'s newer one)']],
19
21
  json: ['--json', ['same as --format json']],
20
22
  'fail-on': ['--fail-on <level>', ['exit 1 on findings at this level or above: error (default), warn, info']],
@@ -23,7 +25,7 @@ const OPTIONS = {
23
25
  protocol: ['--protocol <auto|legacy|modern>', ['which handshake to make (default: auto)', 'legacy: the 2025 handshake only; modern: 2026-07-28 only, an error if the server lacks it']],
24
26
  as: ['--as <name>[:<credential>]', ['list the menu as this identity too, repeatable: a header ("reader:Authorization:', 'Bearer ...") or env var ("admin:ROLE=admin") on top of --header/--env. The first', 'is the main one (its menu is saved); the others are compared with it']],
25
27
  lists: ['--lists <kinds>', ['which lists to read and check, comma-separated: tools (always),', 'prompts, resources (resources/list and resources/templates/list).', 'Saved in the menu file beside the tools']],
26
- client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search)', 'or openai (Responses API tool_search): cost up front and per tool, names it refuses']],
28
+ client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search),', 'openai (Responses API tool_search), codex, antigravity (lazy tools), gemini-cli', '(renames), gemini-api, vscode (128 tools a request), copilot-cloud-agent and', 'copilot-code-review (tools only; review: read-only tools only)']],
27
29
  'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
28
30
  timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
29
31
  processes: ['--processes <n>', ['server processes (stdio) or connections (HTTP) to compare, the main', 'one included (default: 2). 1 opens no second one: for servers with one', 'session per client']],
@@ -34,6 +36,7 @@ const OPTIONS = {
34
36
  init: ['--init', ["write a starter scenario from the server's menu (to --scenario,", 'default scenario.yml; never overwrites)']],
35
37
  auto: ['--auto', ['build the steps from the menu: every read-only tool whose required', 'arguments the schema can fill (const, default, examples, enum, type),', 'then the first call again']],
36
38
  'create-handles': ['--create-handles', ['with --auto on 2026-07-28, call the tool that creates a session, basket or cart', '(a write, so only with this flag; never one marked destructiveHint) and give', 'the tools that take it back the handle it returned']],
39
+ 'call-everything': ['--call-everything', ['with --auto, call every tool once, writes and open-world ones included, with a', 'made-up value (toolmenu-test, 1) where the schema gives none. Stdio only: run', 'the server in a sandbox with nothing to lose (no credentials, no network)']],
37
40
  'open-world': ['--open-world', ['with --auto, also call read-only tools marked openWorldHint: true', '(web search, fetch, scraping): they may cost API credits']],
38
41
  'max-calls': ['--max-calls <n>', ['with --auto, at most n calls in all, the tools unlocks bring', 'included (default: 20, plus --max-calls-per-unlock for each unlock value)']],
39
42
  'max-calls-per-unlock': ['--max-calls-per-unlock <n>', ['with --auto, at most n calls for the tools each unlock value', 'brings (default: 5), so every toolset gets some']],
@@ -59,6 +62,7 @@ const OPTIONS = {
59
62
  'offline-check': ['--offline-check', ['stdio: list the menu once more with the network cut off (the proxy variables', 'pointed at a closed port): a server whose menu depends on what it fetches at start']],
60
63
  concurrency: ['--concurrency <n>', ['servers checked at a time (default: 4)']],
61
64
  'out-dir': ['--out-dir <dir>', ["write each server's menu file there, as <name>.json (default: none)"]],
65
+ 'allow-env': ['--allow-env <names>', ['environment variables a config\'s ${VAR} may be filled from, comma-', "separated or repeated; '*' for all (default: none)"]],
62
66
  'no-browser': ['--no-browser', ["don't open a browser: print the login URL, open it on any device, and paste", 'back the address the browser ends on (over SSH, in a container, on a remote box)']],
63
67
  scope: ['--scope <scopes>', ["scopes to ask for (default: the server's)"]],
64
68
  'client-id': ['--client-id <id>', ['a pre-registered client, for servers without dynamic registration']],
@@ -88,7 +92,7 @@ const HELP = {
88
92
  'reports what in the menu confuses agents or breaks prompt caches.',
89
93
  SERVER_NOTE,
90
94
  ],
91
- own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check', 'sarif', 'sarif-menu', 'badge'],
95
+ own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check', 'sarif', 'sarif-menu', 'junit', 'html', 'badge'],
92
96
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
93
97
  examples: [
94
98
  'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
@@ -100,11 +104,28 @@ const HELP = {
100
104
  summary: 'compare two menu files: breaking changes, token change, semver bump',
101
105
  usage: ['toolmenu diff [options] <old.json> <new.json>'],
102
106
  about: ['Compares two menus written by snapshot (or session --union-out). Starts no server.'],
103
- own: ['release', 'server-version-is-release', 'sarif', 'sarif-menu'],
107
+ own: ['release', 'server-version-is-release', 'sarif', 'sarif-menu', 'junit', 'html'],
104
108
  shared: ['config', 'format', 'json', 'fail-on'],
105
109
  examples: ['toolmenu diff menu.json new-menu.json', 'toolmenu diff --release 1.4.0..1.5.0 --format markdown old.json new.json'],
106
110
  exits: ['0 no findings at or above --fail-on', '1 findings at or above --fail-on', "2 a menu file can't be read, or bad usage"],
107
111
  },
112
+ review: {
113
+ summary: 'should a new menu file replace the baseline? a verdict, and the findings it adds or clears',
114
+ usage: ['toolmenu review [options] <baseline.json> <new.json>'],
115
+ about: [
116
+ 'Compares the new menu with the committed baseline as diff does, runs the menu rules on',
117
+ 'both files, and says whether to accept it: what breaks callers, which findings are new,',
118
+ 'which are gone. Starts no server. Pass --release to check breaking changes against the bump.',
119
+ ],
120
+ own: ['release', 'server-version-is-release'],
121
+ shared: ['config', 'format', 'json', 'fail-on'],
122
+ examples: ['toolmenu review menu.json new-menu.json', 'toolmenu review --release 1.4.0..2.0.0 --format markdown menu.json new-menu.json'],
123
+ exits: [
124
+ '0 accept: unchanged, safe, or breaking changes the release allows',
125
+ '1 not as it is: breaking changes without a release that allows them, or new findings at or above --fail-on',
126
+ "2 a menu file can't be read, or bad usage",
127
+ ],
128
+ },
108
129
  session: {
109
130
  summary: 'run a session (scripted or --auto) and watch the menu change',
110
131
  usage: [
@@ -118,7 +139,7 @@ const HELP = {
118
139
  'prompt cache, a different menu in a fresh process.',
119
140
  SERVER_NOTE,
120
141
  ],
121
- own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'create-handles', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation', 'sarif', 'sarif-menu'],
142
+ own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'call-everything', 'create-handles', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation', 'sarif', 'sarif-menu', 'junit', 'html'],
122
143
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
123
144
  examples: [
124
145
  'toolmenu session --auto -- node dist/index.js',
@@ -145,35 +166,42 @@ const HELP = {
145
166
  exits: ['0 at least one version was inspected', '1 every version failed', "2 bad usage, or the package's versions couldn't be listed"],
146
167
  },
147
168
  auth: {
148
- summary: 'log in to an OAuth-protected HTTP server once',
149
- usage: ['toolmenu auth login [options] <url>', 'toolmenu auth logout <url>', 'toolmenu auth list'],
169
+ summary: 'log in to an OAuth-protected HTTP server once, or check its OAuth discovery',
170
+ usage: ['toolmenu auth login [options] <url>', 'toolmenu auth logout <url>', 'toolmenu auth list', 'toolmenu auth check <url>'],
150
171
  about: [
151
172
  'login opens the browser once and stores the tokens (only you can read the file);',
152
173
  'snapshot and session then use them for that URL (--no-auth to skip).',
153
174
  'Stored in $TOOLMENU_AUTH_DIR, else $XDG_CONFIG_HOME/toolmenu/auth, else ~/.config/toolmenu/auth.',
175
+ 'check walks the server\'s OAuth discovery the way a client that follows the spec does,',
176
+ 'without logging in: the 401, the protected resource metadata, the authorization server\'s',
177
+ 'metadata, PKCE and registration (auth/* rules in docs/RULES.md).',
154
178
  ],
155
179
  own: ['port', 'no-browser', 'scope', 'client-id', 'client-secret'],
156
- shared: [],
180
+ shared: ['format', 'json', 'fail-on', 'timeout'],
157
181
  examples: [
158
182
  'toolmenu auth login https://example.com/mcp',
183
+ 'toolmenu auth check https://mcp.example.com/mcp',
159
184
  'toolmenu auth login --client-id <id> --client-secret <secret> https://example.com/mcp',
160
185
  'toolmenu auth list',
161
186
  ],
162
- exits: ['0 done (logout of a URL with no login is not an error)', '2 the login failed, or bad usage'],
187
+ exits: ['0 done (logout of a URL with no login is not an error; check: no findings at or above --fail-on)', '1 check: findings at or above --fail-on', '2 the login failed, or bad usage'],
163
188
  },
164
189
  scan: {
165
190
  summary: 'snapshot every server in an MCP client config or a list, side by side',
166
191
  usage: ['toolmenu scan [options] <list>'],
167
192
  about: [
168
193
  'The list is an MCP client config (Claude Desktop, Claude Code .mcp.json, Cursor,',
169
- 'VS Code: the mcpServers or servers object, ${VAR} filled from the environment), or a',
170
- 'text file with one server per line: a URL or a command, optionally "name<TAB>" first.',
171
- 'Runs snapshot on each (nothing written unless --out-dir). A server that could not be',
172
- 'started or read is a row that says why, and makes the exit code 2: it was not checked.',
194
+ 'VS Code: the mcpServers or servers object), or a text file with one server per line:',
195
+ 'a URL or a command, optionally "name<TAB>" first. Runs snapshot on each (nothing',
196
+ 'written unless --out-dir). A server that could not be started or read is a row that',
197
+ 'says why, and makes the exit code 2: it was not checked.',
198
+ 'scan starts every command in the list: scan only lists you would run yourself.',
199
+ '${VAR} in a config is filled only from variables named with --allow-env; an entry',
200
+ 'that uses another is not checked, so a config cannot send your environment anywhere.',
173
201
  ],
174
- own: ['concurrency', 'out-dir'],
202
+ own: ['concurrency', 'out-dir', 'allow-env'],
175
203
  shared: ['config', 'format', 'json', 'fail-on', 'no-auth', 'protocol', 'timeout', 'processes'],
176
- examples: ['toolmenu scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json', 'toolmenu scan .mcp.json --format markdown', 'toolmenu scan servers.txt --concurrency 8 --out-dir menus'],
204
+ examples: ['toolmenu scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json --allow-env GITHUB_TOKEN', 'toolmenu scan .mcp.json --format markdown', 'toolmenu scan servers.txt --concurrency 8 --out-dir menus'],
177
205
  exits: ['0 every server checked, no findings at or above --fail-on', '1 findings at or above --fail-on', "2 a server wasn't checked (couldn't start, couldn't connect, a variable not set), or bad usage"],
178
206
  },
179
207
  explain: {
@@ -215,7 +243,7 @@ export function overview() {
215
243
  const width = Math.max(...COMMANDS.map((c) => c.length)) + 3;
216
244
  return [
217
245
  `toolmenu ${VERSION}`,
218
- "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
246
+ "Test your MCP server the way agents and clients meet it: the menu, the calls, the results, the sign-in, every release.",
219
247
  '',
220
248
  'Usage: toolmenu <command> [options]',
221
249
  '',
package/dist/history.js CHANGED
@@ -9,6 +9,8 @@ import { diffMenus } from './diff.js';
9
9
  import { snapshot } from './snapshot.js';
10
10
  const run = promisify(execFile);
11
11
  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
12
+ /** A registry version as npm publishes them: 1.2.3, 1.2.3-rc.1, 1.2.3+build. */
13
+ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
12
14
  /** The npm registry, through the user's own npm (their config, proxy and registry). */
13
15
  export const npmSource = {
14
16
  async versions(pkg) {
@@ -48,8 +50,11 @@ export async function history(pkg, options) {
48
50
  const all = await source.versions(pkg);
49
51
  // Version order, not publish order: a backport (1.0.1 after 2.0.0) is diffed
50
52
  // against 1.0.0, not against 2.0.0.
53
+ // Only versions shaped like semver: each is used in a file name and an npm argument
54
+ // (through a shell on Windows), and a registry is another party.
51
55
  const candidates = all
52
56
  .map((v, index) => ({ v, index }))
57
+ .filter(({ v }) => SEMVER.test(v.version))
53
58
  .filter(({ v }) => options.includePrereleases || !v.version.includes('-'))
54
59
  .sort((a, b) => compareVersions(a.v.version, b.v.version) || a.index - b.index)
55
60
  .map(({ v }) => v);
package/dist/html.d.ts ADDED
@@ -0,0 +1,29 @@
1
+ import type { ClientCost } from './clients.js';
2
+ import type { DiffResult, DiffTools } from './diff.js';
3
+ import { type SessionResult, type StepTool } from './session.js';
4
+ import type { Finding, Menu } from './types.js';
5
+ export declare function esc(text: unknown): string;
6
+ export interface SnapshotHtmlOptions {
7
+ /** stdio or http, for the subtitle. */
8
+ transport?: string;
9
+ /** --client: what the menu costs under that client. */
10
+ cost?: ClientCost;
11
+ /** --lists asked for that the server doesn't offer. */
12
+ notOffered?: string[];
13
+ /** Where the menu file was written. */
14
+ outPath?: string;
15
+ }
16
+ /** The snapshot page. It counts as the text report does: every tool the server lists, app-only ones marked. */
17
+ export declare function snapshotHtml(menu: Menu, findings: Finding[], options?: SnapshotHtmlOptions): string;
18
+ export interface DiffHtmlOptions {
19
+ /** The two menu files, as given on the command line. */
20
+ paths?: [string, string];
21
+ }
22
+ /**
23
+ * The diff page, from what diffMenus compared and decided (`tools`, from its onTools):
24
+ * the tools after the ignore globs, and which were added, removed and renamed. Token
25
+ * totals are the result's, which leave app-only tools out, as the text report's do.
26
+ */
27
+ export declare function diffHtml(result: DiffResult, tools: DiffTools, options?: DiffHtmlOptions): string;
28
+ /** The session page. `menus`: the menu after each step, from session's onStepMenu. */
29
+ export declare function sessionHtml(result: SessionResult, menus?: Map<number, StepTool[]>): string;