toolmenu 0.12.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 (58) hide show
  1. package/README.md +76 -20
  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 +53 -17
  6. package/dist/auto.d.ts +70 -6
  7. package/dist/auto.js +248 -17
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +62 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +80 -170
  13. package/dist/config.d.ts +5 -1
  14. package/dist/config.js +14 -0
  15. package/dist/connect.d.ts +4 -0
  16. package/dist/connect.js +132 -11
  17. package/dist/diff.d.ts +23 -1
  18. package/dist/diff.js +526 -114
  19. package/dist/difference.d.ts +2 -0
  20. package/dist/difference.js +13 -12
  21. package/dist/explain.d.ts +103 -0
  22. package/dist/explain.js +434 -0
  23. package/dist/failures.d.ts +9 -0
  24. package/dist/failures.js +17 -0
  25. package/dist/help.d.ts +9 -0
  26. package/dist/help.js +198 -0
  27. package/dist/history.d.ts +13 -0
  28. package/dist/history.js +86 -6
  29. package/dist/init.d.ts +92 -2
  30. package/dist/init.js +507 -20
  31. package/dist/menu.js +10 -2
  32. package/dist/options.d.ts +135 -0
  33. package/dist/options.js +48 -0
  34. package/dist/report.d.ts +1 -1
  35. package/dist/report.js +229 -99
  36. package/dist/rules/description.d.ts +7 -2
  37. package/dist/rules/description.js +85 -42
  38. package/dist/rules/determinism.d.ts +3 -1
  39. package/dist/rules/determinism.js +145 -11
  40. package/dist/rules/ids.d.ts +1 -1
  41. package/dist/rules/ids.js +9 -4
  42. package/dist/rules/index.d.ts +6 -0
  43. package/dist/rules/index.js +12 -4
  44. package/dist/rules/naming.d.ts +1 -1
  45. package/dist/rules/naming.js +66 -19
  46. package/dist/rules/rule.d.ts +18 -0
  47. package/dist/rules/rule.js +25 -1
  48. package/dist/rules/spec.js +33 -9
  49. package/dist/rules/write.d.ts +1 -1
  50. package/dist/rules/write.js +42 -10
  51. package/dist/session.d.ts +18 -8
  52. package/dist/session.js +484 -92
  53. package/dist/snapshot.d.ts +2 -2
  54. package/dist/snapshot.js +17 -2
  55. package/dist/types.d.ts +14 -0
  56. package/dist/words.d.ts +5 -0
  57. package/dist/words.js +14 -0
  58. package/package.json +1 -1
package/dist/catalog.d.ts CHANGED
@@ -1,27 +1,55 @@
1
1
  import type { Connection } from './connect.js';
2
- import type { MenuTool } from './types.js';
2
+ import type { Finding, MenuTool } from './types.js';
3
3
  /**
4
- * Operations a server keeps behind a search tool instead of in its menu (search
5
- * and execute: Sentry's search_sentry_tools, Atlassian's discover). `diff` can't
6
- * see them in the menu, so snapshot --catalog asks the search tool a fixed set of
7
- * queries and keeps what comes back.
4
+ * Operations a server keeps out of its menu, where `diff` can't see them:
5
+ *
6
+ * - behind a search tool (search and execute: Sentry's search_sentry_tools,
7
+ * Atlassian's discover). snapshot --catalog asks it a fixed set of queries and
8
+ * crawls by the names that come back.
9
+ * - behind command routers: one tool per area that takes a `command` and its
10
+ * `parameters`, and lists its commands when called with a flag like `learn: true`
11
+ * (Azure's namespace mode). snapshot --catalog calls each router once, in that
12
+ * listing mode only, and never with a command.
13
+ *
14
+ * Both keep operations in the same shape, so `diff` compares them the same way.
8
15
  */
9
16
  export interface Catalog {
10
- /** The search tool asked. */
17
+ /** The search tool asked; for routers, the router (one) or "the command routers" (several). */
11
18
  tool: string;
12
- /** The queries asked, in order: the same ones every run, so runs compare. */
19
+ /** The queries asked, in order: the same ones every run, so runs compare. Empty for routers: see `routers`. */
13
20
  queries: string[];
14
- /** Every operation found, by name. Not complete: a search returns its top matches. */
21
+ /** Every operation found, by name. From a search, not complete: a search returns its top matches. */
15
22
  operations: MenuTool[];
16
- /** Queries that failed (rate limits, errors): the catalog is partial where they would have looked. */
23
+ /** Queries (or routers, by name) that failed: the catalog is partial where they would have looked. */
17
24
  failed?: {
18
25
  query: string;
19
26
  error: string;
20
27
  }[];
28
+ /** Routers only: each router called, in menu order, the exact arguments sent, and how many operations it listed. */
29
+ routers?: {
30
+ tool: string;
31
+ arguments: Record<string, unknown>;
32
+ operations: number;
33
+ duplicates?: {
34
+ command: string;
35
+ kept: string[];
36
+ }[];
37
+ }[];
38
+ /** Routers only: tools that look like routers but weren't called, and why. */
39
+ skipped?: {
40
+ tool: string;
41
+ reason: string;
42
+ }[];
21
43
  }
22
44
  export interface CatalogOptions {
23
45
  /** The search tool, when detection picks the wrong one. */
24
46
  tool?: string;
47
+ /**
48
+ * The command routers to read, by name, when detection misses them: every router
49
+ * to call (detection is then off). Each still needs a listing flag and an optional
50
+ * command, or it isn't called.
51
+ */
52
+ routers?: string[];
25
53
  /** The queries to ask. Default: derived from the menu. */
26
54
  queries?: string[];
27
55
  timeoutMs?: number;
@@ -42,8 +70,41 @@ export declare function findCatalogTool(tools: MenuTool[]): MenuTool | undefined
42
70
  * "update" and "delete".
43
71
  */
44
72
  export declare function defaultQueries(tools: MenuTool[], max?: number): string[];
45
- /** Ask the search tool every query and collect the operations it returns. */
73
+ /**
74
+ * Read the operations behind the menu: from the search tool (named, or detected),
75
+ * else from the command routers (named, or detected).
76
+ */
46
77
  export declare function readCatalog(conn: Connection, tools: MenuTool[], options?: CatalogOptions): Promise<Catalog>;
78
+ /** What goes in a required free-text parameter (Azure's `intent`): a request to list, nothing to act on. */
79
+ export declare const LISTING_PHRASE = "List the available commands and their parameters.";
80
+ export interface RouterCall {
81
+ tool: MenuTool;
82
+ /** The exact arguments sent: the listing flag and fixed phrases, never a command. */
83
+ arguments: Record<string, unknown>;
84
+ }
85
+ type Shape = {
86
+ call: RouterCall;
87
+ } | {
88
+ reason: string;
89
+ };
90
+ /**
91
+ * How to list a router's commands safely, or why it can't be. `named`: the config
92
+ * named it, so the description's wording isn't needed. Undefined: not a router.
93
+ */
94
+ export declare function routerShape(tool: MenuTool, named?: boolean): Shape | undefined;
95
+ /** The routers in a menu (menu order), and those that look like routers but can't be listed safely. */
96
+ export declare function findRouters(tools: MenuTool[]): {
97
+ usable: RouterCall[];
98
+ skipped: {
99
+ tool: string;
100
+ reason: string;
101
+ }[];
102
+ };
103
+ /**
104
+ * Findings about the read itself: what was called (catalog/read), what failed
105
+ * (catalog/failed, one per cause) and what was left alone (catalog/skipped).
106
+ */
107
+ export declare function catalogFindings(catalog: Catalog): Finding[];
47
108
  /**
48
109
  * Operation definitions in a search result: objects with a `name` and either a
49
110
  * JSON Schema (`inputSchema`, `input_schema`, `parameters`) or a list of
@@ -53,13 +114,28 @@ export declare function readCatalog(conn: Connection, tools: MenuTool[], options
53
114
  export declare function operationsIn(result: {
54
115
  structuredContent?: unknown;
55
116
  content?: unknown;
117
+ }, options?: {
118
+ nameKeys?: string[];
119
+ embedded?: boolean;
120
+ keepAll?: boolean;
56
121
  }): MenuTool[];
122
+ /** A router's answer that is a readable, empty command list: `[]`, or `{ "commands": [] }`. */
123
+ export declare function listsNothing(result: {
124
+ structuredContent?: unknown;
125
+ content?: unknown;
126
+ }): boolean;
57
127
  /**
58
128
  * The JSON value a text starts with, ignoring what follows: Atlassian's discover
59
129
  * returns its results as JSON and then a prose list of related operations, which
60
130
  * makes the whole text invalid JSON.
61
131
  */
62
132
  export declare function leadingJson(text: string): unknown;
133
+ /**
134
+ * The first JSON value in a text that opens with prose: Azure's routers answer
135
+ * "Here are the available commands… \n[{"command":…}]". The text itself when it
136
+ * starts with JSON; else each line that starts with [ or {, in order.
137
+ */
138
+ export declare function embeddedJson(text: string): unknown;
63
139
  /**
64
140
  * Operation names a result mentions without defining them: lines like
65
141
  * "createJiraBoard — Create a new company-managed…" after Atlassian's JSON. Each
@@ -68,3 +144,4 @@ export declare function leadingJson(text: string): unknown;
68
144
  export declare function mentionedNames(result: {
69
145
  content?: unknown;
70
146
  }): string[];
147
+ export {};