toolmenu 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +150 -30
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +61 -18
  6. package/dist/auto.d.ts +71 -7
  7. package/dist/auto.js +267 -13
  8. package/dist/breakdown.d.ts +35 -6
  9. package/dist/breakdown.js +179 -23
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +116 -178
  13. package/dist/compare.js +20 -5
  14. package/dist/config.d.ts +5 -1
  15. package/dist/config.js +14 -0
  16. package/dist/connect.d.ts +4 -0
  17. package/dist/connect.js +132 -11
  18. package/dist/diff.d.ts +35 -1
  19. package/dist/diff.js +1132 -121
  20. package/dist/difference.d.ts +2 -0
  21. package/dist/difference.js +13 -12
  22. package/dist/explain.d.ts +103 -0
  23. package/dist/explain.js +434 -0
  24. package/dist/failures.d.ts +55 -0
  25. package/dist/failures.js +103 -0
  26. package/dist/help.d.ts +9 -0
  27. package/dist/help.js +198 -0
  28. package/dist/history.d.ts +13 -0
  29. package/dist/history.js +86 -6
  30. package/dist/init.d.ts +100 -5
  31. package/dist/init.js +520 -26
  32. package/dist/menu.js +10 -2
  33. package/dist/options.d.ts +135 -0
  34. package/dist/options.js +48 -0
  35. package/dist/probe.d.ts +15 -3
  36. package/dist/probe.js +35 -11
  37. package/dist/report.d.ts +1 -1
  38. package/dist/report.js +229 -99
  39. package/dist/rules/description.d.ts +7 -2
  40. package/dist/rules/description.js +89 -43
  41. package/dist/rules/determinism.d.ts +3 -1
  42. package/dist/rules/determinism.js +146 -11
  43. package/dist/rules/ids.d.ts +1 -1
  44. package/dist/rules/ids.js +9 -4
  45. package/dist/rules/index.d.ts +6 -0
  46. package/dist/rules/index.js +15 -5
  47. package/dist/rules/naming.d.ts +1 -1
  48. package/dist/rules/naming.js +66 -19
  49. package/dist/rules/rule.d.ts +18 -0
  50. package/dist/rules/rule.js +25 -1
  51. package/dist/rules/spec.d.ts +2 -0
  52. package/dist/rules/spec.js +61 -8
  53. package/dist/rules/write.d.ts +1 -1
  54. package/dist/rules/write.js +42 -10
  55. package/dist/semver.js +1 -1
  56. package/dist/session.d.ts +56 -7
  57. package/dist/session.js +800 -94
  58. package/dist/snapshot.d.ts +2 -2
  59. package/dist/snapshot.js +25 -7
  60. package/dist/types.d.ts +14 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +1 -1
@@ -0,0 +1,135 @@
1
+ export declare const CLI_OPTIONS: {
2
+ readonly out: {
3
+ readonly type: 'string';
4
+ };
5
+ readonly 'no-write': {
6
+ readonly type: 'boolean';
7
+ };
8
+ readonly routes: {
9
+ readonly type: 'string';
10
+ };
11
+ readonly config: {
12
+ readonly type: 'string';
13
+ };
14
+ readonly format: {
15
+ readonly type: 'string';
16
+ };
17
+ readonly json: {
18
+ readonly type: 'boolean';
19
+ };
20
+ readonly 'fail-on': {
21
+ readonly type: 'string';
22
+ };
23
+ readonly header: {
24
+ readonly type: 'string';
25
+ readonly multiple: true;
26
+ };
27
+ readonly env: {
28
+ readonly type: 'string';
29
+ readonly multiple: true;
30
+ };
31
+ readonly timeout: {
32
+ readonly type: 'string';
33
+ };
34
+ readonly 'no-auth': {
35
+ readonly type: 'boolean';
36
+ };
37
+ readonly port: {
38
+ readonly type: 'string';
39
+ };
40
+ readonly scope: {
41
+ readonly type: 'string';
42
+ };
43
+ readonly 'client-id': {
44
+ readonly type: 'string';
45
+ };
46
+ readonly 'client-secret': {
47
+ readonly type: 'string';
48
+ };
49
+ readonly processes: {
50
+ readonly type: 'string';
51
+ };
52
+ readonly versions: {
53
+ readonly type: 'string';
54
+ };
55
+ readonly release: {
56
+ readonly type: 'string';
57
+ };
58
+ readonly 'server-version-is-release': {
59
+ readonly type: 'boolean';
60
+ };
61
+ readonly 'include-prereleases': {
62
+ readonly type: 'boolean';
63
+ };
64
+ readonly arg: {
65
+ readonly type: 'string';
66
+ readonly multiple: true;
67
+ };
68
+ readonly bin: {
69
+ readonly type: 'string';
70
+ };
71
+ readonly cmd: {
72
+ readonly type: 'string';
73
+ };
74
+ readonly 'allow-scripts': {
75
+ readonly type: 'boolean';
76
+ };
77
+ readonly 'install-timeout': {
78
+ readonly type: 'string';
79
+ };
80
+ readonly csv: {
81
+ readonly type: 'string';
82
+ };
83
+ readonly 'keep-installs': {
84
+ readonly type: 'boolean';
85
+ };
86
+ readonly scenario: {
87
+ readonly type: 'string';
88
+ };
89
+ readonly plan: {
90
+ readonly type: 'boolean';
91
+ };
92
+ readonly init: {
93
+ readonly type: 'boolean';
94
+ };
95
+ readonly 'union-out': {
96
+ readonly type: 'string';
97
+ };
98
+ readonly auto: {
99
+ readonly type: 'boolean';
100
+ };
101
+ readonly 'with-session': {
102
+ readonly type: 'boolean';
103
+ };
104
+ readonly catalog: {
105
+ readonly type: 'boolean';
106
+ };
107
+ readonly 'open-world': {
108
+ readonly type: 'boolean';
109
+ };
110
+ readonly 'max-calls': {
111
+ readonly type: 'string';
112
+ };
113
+ readonly 'save-scenario': {
114
+ readonly type: 'string';
115
+ };
116
+ readonly value: {
117
+ readonly type: 'string';
118
+ readonly multiple: true;
119
+ };
120
+ readonly 'values-file': {
121
+ readonly type: 'string';
122
+ };
123
+ readonly 'assume-read-only': {
124
+ readonly type: 'string';
125
+ readonly multiple: true;
126
+ };
127
+ readonly help: {
128
+ readonly type: 'boolean';
129
+ readonly short: 'h';
130
+ };
131
+ readonly version: {
132
+ readonly type: 'boolean';
133
+ readonly short: 'v';
134
+ };
135
+ };
@@ -0,0 +1,48 @@
1
+ /*
2
+ * The options parseArgs accepts, for every command. Kept apart from cli.ts (which runs on
3
+ * import) so the tests can check that help.ts names exactly these.
4
+ */
5
+ export const CLI_OPTIONS = {
6
+ out: { type: 'string' },
7
+ 'no-write': { type: 'boolean' },
8
+ routes: { type: 'string' },
9
+ config: { type: 'string' },
10
+ format: { type: 'string' },
11
+ json: { type: 'boolean' },
12
+ 'fail-on': { type: 'string' },
13
+ header: { type: 'string', multiple: true },
14
+ env: { type: 'string', multiple: true },
15
+ timeout: { type: 'string' },
16
+ 'no-auth': { type: 'boolean' },
17
+ port: { type: 'string' },
18
+ scope: { type: 'string' },
19
+ 'client-id': { type: 'string' },
20
+ 'client-secret': { type: 'string' },
21
+ processes: { type: 'string' },
22
+ versions: { type: 'string' },
23
+ release: { type: 'string' },
24
+ 'server-version-is-release': { type: 'boolean' },
25
+ 'include-prereleases': { type: 'boolean' },
26
+ arg: { type: 'string', multiple: true },
27
+ bin: { type: 'string' },
28
+ cmd: { type: 'string' },
29
+ 'allow-scripts': { type: 'boolean' },
30
+ 'install-timeout': { type: 'string' },
31
+ csv: { type: 'string' },
32
+ 'keep-installs': { type: 'boolean' },
33
+ scenario: { type: 'string' },
34
+ plan: { type: 'boolean' },
35
+ init: { type: 'boolean' },
36
+ 'union-out': { type: 'string' },
37
+ auto: { type: 'boolean' },
38
+ 'with-session': { type: 'boolean' },
39
+ catalog: { type: 'boolean' },
40
+ 'open-world': { type: 'boolean' },
41
+ 'max-calls': { type: 'string' },
42
+ 'save-scenario': { type: 'string' },
43
+ value: { type: 'string', multiple: true },
44
+ 'values-file': { type: 'string' },
45
+ 'assume-read-only': { type: 'string', multiple: true },
46
+ help: { type: 'boolean', short: 'h' },
47
+ version: { type: 'boolean', short: 'v' },
48
+ };
package/dist/probe.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type Target } from './connect.js';
1
+ import { type Connection, type Target } from './connect.js';
2
2
  import type { Probe } from './rules/determinism.js';
3
3
  import type { Menu, MenuTool } from './types.js';
4
4
  /**
@@ -16,12 +16,24 @@ export declare const PROBE_SEED = "1";
16
16
  export declare function seeded(target: Target, seed: string): Target;
17
17
  /** A command that starts the server in a container: the seed (and --env) don't reach it unless passed through. */
18
18
  export declare function isContainerWrapper(target: Target): boolean;
19
+ /**
20
+ * A connection still refused for being too many requests after the waits, said as
21
+ * that and what to do about it, not as the transport's error. Anything else as is.
22
+ */
23
+ export declare function refusedForTooMany(error: unknown, waitedMs: number): unknown;
24
+ /** connect, with a refusal for being too many waited out (connecting is read-only). */
25
+ export declare function connectPatiently(target: Target, options?: {
26
+ timeoutMs?: number;
27
+ waits?: number[];
28
+ }): Promise<Connection>;
19
29
  /** The menu a fresh process (stdio) or connection (HTTP) serves: connect, list once, close. */
20
- export declare function probeMenu(target: Target, timeoutMs: number): Promise<Menu>;
30
+ export declare function probeMenu(target: Target, timeoutMs: number, waits?: number[], waited?: {
31
+ ms: number;
32
+ }): Promise<Menu>;
21
33
  /**
22
34
  * Menus from `processes - 1` fresh processes (stdio) or connections (HTTP), to
23
35
  * compare with the main one. stdio probes run with a different hash seed each. An
24
36
  * HTTP probe that differs is retried once: a rolling deploy can serve two
25
37
  * versions for a moment.
26
38
  */
27
- export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number): Promise<Probe[]>;
39
+ export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[]): Promise<Probe[]>;
package/dist/probe.js CHANGED
@@ -2,6 +2,7 @@ import { basename } from 'node:path';
2
2
  import { connect, listTools } from './connect.js';
3
3
  import { compareMenus } from './compare.js';
4
4
  import { buildMenu } from './menu.js';
5
+ import { patiently, quotedSentence, RATE_LIMIT_ADVICE, serverWords, tooMany, waitedFor, whyNot } from './failures.js';
5
6
  /**
6
7
  * The hash seed of the process whose menu toolmenu saves and compares. Python
7
8
  * orders sets of strings by a per-process random seed; pinning it makes a Python
@@ -23,35 +24,58 @@ export function seeded(target, seed) {
23
24
  export function isContainerWrapper(target) {
24
25
  return target.kind === 'stdio' && /^(docker|podman|nerdctl)(\.exe)?$/.test(basename(target.command));
25
26
  }
26
- /** The menu a fresh process (stdio) or connection (HTTP) serves: connect, list once, close. */
27
- export async function probeMenu(target, timeoutMs) {
28
- const c = await connect(target, { timeoutMs });
27
+ /**
28
+ * A connection still refused for being too many requests after the waits, said as
29
+ * that and what to do about it, not as the transport's error. Anything else as is.
30
+ */
31
+ export function refusedForTooMany(error, waitedMs) {
32
+ if (!tooMany(error))
33
+ return error;
34
+ return new Error(`Rate-limited while connecting, and still after waiting ${waitedFor(waitedMs)}: ${quotedSentence(serverWords(error))} ${RATE_LIMIT_ADVICE}`);
35
+ }
36
+ /** connect, with a refusal for being too many waited out (connecting is read-only). */
37
+ export async function connectPatiently(target, options = {}) {
38
+ const waited = { ms: 0 };
29
39
  try {
30
- const list = await listTools(c, { timeoutMs });
31
- return buildMenu(list.tools, { name: c.server.name, version: c.server.version, protocolVersion: c.protocolVersion, era: c.era });
40
+ return await patiently(() => connect(target, { timeoutMs: options.timeoutMs }), { waits: options.waits, error: tooMany, waited });
32
41
  }
33
- finally {
34
- await c.close().catch(() => { });
42
+ catch (error) {
43
+ throw refusedForTooMany(error, waited.ms);
35
44
  }
36
45
  }
46
+ /** The menu a fresh process (stdio) or connection (HTTP) serves: connect, list once, close. */
47
+ export async function probeMenu(target, timeoutMs, waits, waited) {
48
+ // Read-only: a refusal for being too many is waited out and the probe sent again.
49
+ return patiently(async () => {
50
+ const c = await connect(target, { timeoutMs });
51
+ try {
52
+ const list = await listTools(c, { timeoutMs });
53
+ return buildMenu(list.tools, { name: c.server.name, version: c.server.version, protocolVersion: c.protocolVersion, era: c.era });
54
+ }
55
+ finally {
56
+ await c.close().catch(() => { });
57
+ }
58
+ }, { waits, error: tooMany, waited });
59
+ }
37
60
  /**
38
61
  * Menus from `processes - 1` fresh processes (stdio) or connections (HTTP), to
39
62
  * compare with the main one. stdio probes run with a different hash seed each. An
40
63
  * HTTP probe that differs is retried once: a rolling deploy can serve two
41
64
  * versions for a moment.
42
65
  */
43
- export async function probeVariance(target, main, processes, timeoutMs) {
66
+ export async function probeVariance(target, main, processes, timeoutMs, waits) {
44
67
  const probes = [];
45
68
  for (let i = 0; i < processes - 1; i++) {
46
69
  const seed = String(Number(PROBE_SEED) + i);
70
+ const waited = { ms: 0 };
47
71
  try {
48
- let tools = (await probeMenu(seeded(target, seed), timeoutMs)).tools;
72
+ let tools = (await probeMenu(seeded(target, seed), timeoutMs, waits, waited)).tools;
49
73
  if (target.kind === 'http' && compareMenus(main, tools).length)
50
- tools = (await probeMenu(target, timeoutMs)).tools;
74
+ tools = (await probeMenu(target, timeoutMs, waits, waited)).tools;
51
75
  probes.push({ tools });
52
76
  }
53
77
  catch (error) {
54
- probes.push({ error: error instanceof Error ? error.message : String(error) });
78
+ probes.push({ error: tooMany(error) ? whyNot(error, waited.ms) : error instanceof Error ? error.message : String(error) });
55
79
  }
56
80
  }
57
81
  return probes;
package/dist/report.d.ts CHANGED
@@ -6,6 +6,6 @@ export type Format = 'text' | 'json' | 'github' | 'markdown';
6
6
  export declare function counts(findings: Finding[]): Record<Severity, number>;
7
7
  export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string): string;
8
8
  export declare function formatDiff(d: DiffResult, beforeTools: number, afterTools: number, format: Format): string;
9
- export declare function formatHistory(h: HistoryResult, format: Format, outDir: string): string;
9
+ export declare function formatHistory(h: HistoryResult, format: Format, outDir: string, csvPath?: string): string;
10
10
  export declare function formatSession(s: SessionResult, format: Format): string;
11
11
  export declare function formatPlan(scenario: Scenario, name: string): string;