@atlaskit/ads-cli 0.1.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 (106) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +134 -0
  3. package/bin/ads-cli.js +40 -0
  4. package/compass.yml +25 -0
  5. package/dist/cjs/cli.js +488 -0
  6. package/dist/cjs/commands/definitions.js +713 -0
  7. package/dist/cjs/commands/get-command.js +19 -0
  8. package/dist/cjs/commands/import-tool-handler.js +57 -0
  9. package/dist/cjs/commands/run-tool.js +106 -0
  10. package/dist/cjs/commands/types.js +1 -0
  11. package/dist/cjs/envelope/create-error-envelope.js +27 -0
  12. package/dist/cjs/envelope/create-success-envelope.js +38 -0
  13. package/dist/cjs/envelope/types.js +1 -0
  14. package/dist/cjs/output/disambiguation.js +31 -0
  15. package/dist/cjs/output/format-component.js +99 -0
  16. package/dist/cjs/output/format-disambiguation.js +29 -0
  17. package/dist/cjs/output/format-doc-object.js +115 -0
  18. package/dist/cjs/output/format-grouped-results.js +55 -0
  19. package/dist/cjs/output/format-icon.js +49 -0
  20. package/dist/cjs/output/format-lint-rules.js +52 -0
  21. package/dist/cjs/output/format-results.js +158 -0
  22. package/dist/cjs/output/format-token.js +39 -0
  23. package/dist/cjs/output/parse-lint-rule-records.js +47 -0
  24. package/dist/cjs/output/write-human-error.js +20 -0
  25. package/dist/cjs/output/write-human-result.js +31 -0
  26. package/dist/cjs/output/write-json-envelope.js +20 -0
  27. package/dist/cjs/output/writer.js +32 -0
  28. package/dist/cjs/parse-args.js +106 -0
  29. package/dist/cjs/types.js +53 -0
  30. package/dist/es2019/cli.js +406 -0
  31. package/dist/es2019/commands/definitions.js +683 -0
  32. package/dist/es2019/commands/get-command.js +9 -0
  33. package/dist/es2019/commands/import-tool-handler.js +22 -0
  34. package/dist/es2019/commands/run-tool.js +73 -0
  35. package/dist/es2019/commands/types.js +0 -0
  36. package/dist/es2019/envelope/create-error-envelope.js +20 -0
  37. package/dist/es2019/envelope/create-success-envelope.js +31 -0
  38. package/dist/es2019/envelope/types.js +0 -0
  39. package/dist/es2019/output/disambiguation.js +21 -0
  40. package/dist/es2019/output/format-component.js +88 -0
  41. package/dist/es2019/output/format-disambiguation.js +22 -0
  42. package/dist/es2019/output/format-doc-object.js +94 -0
  43. package/dist/es2019/output/format-grouped-results.js +51 -0
  44. package/dist/es2019/output/format-icon.js +39 -0
  45. package/dist/es2019/output/format-lint-rules.js +43 -0
  46. package/dist/es2019/output/format-results.js +142 -0
  47. package/dist/es2019/output/format-token.js +31 -0
  48. package/dist/es2019/output/parse-lint-rule-records.js +41 -0
  49. package/dist/es2019/output/write-human-error.js +14 -0
  50. package/dist/es2019/output/write-human-result.js +25 -0
  51. package/dist/es2019/output/write-json-envelope.js +15 -0
  52. package/dist/es2019/output/writer.js +22 -0
  53. package/dist/es2019/parse-args.js +100 -0
  54. package/dist/es2019/types.js +47 -0
  55. package/dist/esm/cli.js +484 -0
  56. package/dist/esm/commands/definitions.js +708 -0
  57. package/dist/esm/commands/get-command.js +13 -0
  58. package/dist/esm/commands/import-tool-handler.js +42 -0
  59. package/dist/esm/commands/run-tool.js +99 -0
  60. package/dist/esm/commands/types.js +0 -0
  61. package/dist/esm/envelope/create-error-envelope.js +21 -0
  62. package/dist/esm/envelope/create-success-envelope.js +31 -0
  63. package/dist/esm/envelope/types.js +0 -0
  64. package/dist/esm/output/disambiguation.js +24 -0
  65. package/dist/esm/output/format-component.js +92 -0
  66. package/dist/esm/output/format-disambiguation.js +22 -0
  67. package/dist/esm/output/format-doc-object.js +108 -0
  68. package/dist/esm/output/format-grouped-results.js +50 -0
  69. package/dist/esm/output/format-icon.js +42 -0
  70. package/dist/esm/output/format-lint-rules.js +46 -0
  71. package/dist/esm/output/format-results.js +151 -0
  72. package/dist/esm/output/format-token.js +32 -0
  73. package/dist/esm/output/parse-lint-rule-records.js +41 -0
  74. package/dist/esm/output/write-human-error.js +13 -0
  75. package/dist/esm/output/write-human-result.js +24 -0
  76. package/dist/esm/output/write-json-envelope.js +14 -0
  77. package/dist/esm/output/writer.js +26 -0
  78. package/dist/esm/parse-args.js +100 -0
  79. package/dist/esm/types.js +47 -0
  80. package/dist/types/cli.d.ts +20 -0
  81. package/dist/types/commands/definitions.d.ts +19 -0
  82. package/dist/types/commands/get-command.d.ts +8 -0
  83. package/dist/types/commands/import-tool-handler.d.ts +14 -0
  84. package/dist/types/commands/run-tool.d.ts +37 -0
  85. package/dist/types/commands/types.d.ts +149 -0
  86. package/dist/types/envelope/create-error-envelope.d.ts +12 -0
  87. package/dist/types/envelope/create-success-envelope.d.ts +16 -0
  88. package/dist/types/envelope/types.d.ts +60 -0
  89. package/dist/types/output/disambiguation.d.ts +50 -0
  90. package/dist/types/output/format-component.d.ts +12 -0
  91. package/dist/types/output/format-disambiguation.d.ts +11 -0
  92. package/dist/types/output/format-doc-object.d.ts +15 -0
  93. package/dist/types/output/format-grouped-results.d.ts +14 -0
  94. package/dist/types/output/format-icon.d.ts +13 -0
  95. package/dist/types/output/format-lint-rules.d.ts +14 -0
  96. package/dist/types/output/format-results.d.ts +24 -0
  97. package/dist/types/output/format-token.d.ts +12 -0
  98. package/dist/types/output/parse-lint-rule-records.d.ts +26 -0
  99. package/dist/types/output/write-human-error.d.ts +11 -0
  100. package/dist/types/output/write-human-result.d.ts +14 -0
  101. package/dist/types/output/write-json-envelope.d.ts +14 -0
  102. package/dist/types/output/writer.d.ts +25 -0
  103. package/dist/types/parse-args.d.ts +29 -0
  104. package/dist/types/types.d.ts +53 -0
  105. package/index.js +31 -0
  106. package/package.json +30 -0
@@ -0,0 +1,708 @@
1
+ import _toArray from "@babel/runtime/helpers/toArray";
2
+ import _typeof from "@babel/runtime/helpers/typeof";
3
+ import _defineProperty from "@babel/runtime/helpers/defineProperty";
4
+ function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
5
+ function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
6
+ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
7
+ /**
8
+ * The command definitions — the single source of truth for the ADS CLI surface.
9
+ *
10
+ * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
11
+ * from this one array, so there is no way for the runnable surface and the documented surface
12
+ * to drift apart. Each entry declares:
13
+ *
14
+ * - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
15
+ * - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
16
+ * - the metadata (description, flags, examples) surfaced by `--help`.
17
+ *
18
+ * The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
19
+ * copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
20
+ */
21
+
22
+ import { accessibilityGuidelines } from '@atlaskit/ads-mcp/a11y-guidelines';
23
+ import { migrationRegistry } from '@atlaskit/ads-mcp/migration-registry';
24
+ import { isDisambiguation } from '../output/disambiguation';
25
+ import { formatComponent } from '../output/format-component';
26
+ import { formatDisambiguation } from '../output/format-disambiguation';
27
+ import { formatDocObject } from '../output/format-doc-object';
28
+ import { formatIcon } from '../output/format-icon';
29
+ import { formatLintRules } from '../output/format-lint-rules';
30
+ import { formatToken } from '../output/format-token';
31
+ import { parseLintRuleRecords } from '../output/parse-lint-rule-records';
32
+ /**
33
+ * Shared `--limit` flag definition reused across the search-style commands.
34
+ */
35
+ var limitFlag = {
36
+ name: 'limit',
37
+ type: 'number',
38
+ alias: 'l',
39
+ description: 'Maximum matches per term.'
40
+ };
41
+
42
+ /**
43
+ * Parse and validate the `--limit` flag.
44
+ *
45
+ * Returns the numeric limit, `undefined` when the flag was not supplied, or `null` when it
46
+ * was supplied but is not a positive integer (a usage error).
47
+ */
48
+ var parseLimit = function parseLimit(flags) {
49
+ var raw = flags.limit;
50
+ if (raw === undefined) {
51
+ return undefined;
52
+ }
53
+ var parsed = typeof raw === 'number' ? raw : Number.parseInt(String(raw), 10);
54
+ if (!Number.isInteger(parsed) || parsed < 1) {
55
+ return null;
56
+ }
57
+ return parsed;
58
+ };
59
+
60
+ /**
61
+ * Map of the three `search --type` variants to their ADS MCP tool exports.
62
+ */
63
+ var searchKindTools = {
64
+ components: {
65
+ importPath: '@atlaskit/ads-mcp/tools/search-components',
66
+ handlerName: 'searchComponentsTool',
67
+ envelopeType: 'search-components'
68
+ },
69
+ tokens: {
70
+ importPath: '@atlaskit/ads-mcp/tools/search-tokens',
71
+ handlerName: 'searchTokensTool',
72
+ envelopeType: 'search-tokens'
73
+ },
74
+ icons: {
75
+ importPath: '@atlaskit/ads-mcp/tools/search-icons',
76
+ handlerName: 'searchIconsTool',
77
+ envelopeType: 'search-icons'
78
+ }
79
+ };
80
+ /**
81
+ * Accepted `--type` values (singular, matching the item command names) → the internal (plural)
82
+ * {@link SearchKind}. Everything downstream keys off the plural `SearchKind` (envelope types,
83
+ * grouped JSON keys), so the singular input normalises to it here.
84
+ */
85
+ var SEARCH_TYPE_VALUES = {
86
+ component: 'components',
87
+ token: 'tokens',
88
+ icon: 'icons'
89
+ };
90
+ var isSearchTypeValue = function isSearchTypeValue(value) {
91
+ return value in SEARCH_TYPE_VALUES;
92
+ };
93
+
94
+ /**
95
+ * Resolve the `--type` narrowing for a `search` invocation.
96
+ *
97
+ * Returns the {@link SearchKind} when `--type` is a valid kind, `undefined` when `--type` was
98
+ * omitted (caller should run a unified search), or `null` when `--type` is present but invalid.
99
+ */
100
+ var resolveSearchType = function resolveSearchType(flags) {
101
+ if (flags.type === undefined) {
102
+ return undefined;
103
+ }
104
+ var value = String(flags.type).toLowerCase();
105
+ return isSearchTypeValue(value) ? SEARCH_TYPE_VALUES[value] : null;
106
+ };
107
+
108
+ /**
109
+ * Map of the three `list <kind>` variants to their ADS MCP tool exports.
110
+ */
111
+ var listKindTools = {
112
+ components: {
113
+ importPath: '@atlaskit/ads-mcp/tools/get-all-components',
114
+ handlerName: 'getAllComponentsTool',
115
+ envelopeType: 'list-components'
116
+ },
117
+ tokens: {
118
+ importPath: '@atlaskit/ads-mcp/tools/get-all-tokens',
119
+ handlerName: 'getAllTokensTool',
120
+ envelopeType: 'list-tokens'
121
+ },
122
+ icons: {
123
+ importPath: '@atlaskit/ads-mcp/tools/get-all-icons',
124
+ handlerName: 'getAllIconsTool',
125
+ envelopeType: 'list-icons'
126
+ }
127
+ };
128
+
129
+ /**
130
+ * Valid ADS accessibility guideline topics accepted by `get-a11y-guidelines`.
131
+ *
132
+ * Derived at runtime from `@atlaskit/ads-mcp`'s `accessibilityGuidelines` object — the same
133
+ * source of truth the tool itself uses (`Object.keys(accessibilityGuidelines)`). Deriving rather
134
+ * than hardcoding keeps the CLI's validation and `--help` enumeration zero-drift: adding or
135
+ * removing a topic in `@atlaskit/ads-mcp` is picked up automatically. Omitting the topic asks the
136
+ * tool for its index response (the list of available topics), rather than a single topic's detail.
137
+ */
138
+ var A11Y_TOPICS = Object.keys(accessibilityGuidelines);
139
+
140
+ /**
141
+ * Valid migration guide ids accepted by `migration-guides`.
142
+ *
143
+ * Derived at runtime from `@atlaskit/ads-mcp`'s migration registry (keys are the ids each
144
+ * migration declares), so newly-registered guides are exposed by the CLI automatically with no
145
+ * manual sync. The underlying tool only reads the `migration` id (it ignores the schema's paired
146
+ * `description`), so the CLI can pass an empty description and let the user supply just the id.
147
+ */
148
+ var MIGRATION_IDS = Object.keys(migrationRegistry);
149
+
150
+ /**
151
+ * Build the invalid-limit usage error message.
152
+ */
153
+ var invalidLimitError = function invalidLimitError(flags) {
154
+ return {
155
+ error: "Invalid --limit value \"".concat(String(flags.limit), "\". Must be a positive integer.")
156
+ };
157
+ };
158
+
159
+ /**
160
+ * Convenience builder for a command that resolves to exactly one tool call.
161
+ */
162
+ var singleTool = function singleTool(_ref) {
163
+ var importPath = _ref.importPath,
164
+ handlerName = _ref.handlerName,
165
+ args = _ref.args,
166
+ meta = _ref.meta;
167
+ return {
168
+ tools: [{
169
+ key: 'result',
170
+ importPath: importPath,
171
+ handlerName: handlerName,
172
+ args: args
173
+ }],
174
+ meta: meta
175
+ };
176
+ };
177
+
178
+ /**
179
+ * Shared resolver for the narrowed single-type search (`search --type X`) that takes positional
180
+ * terms + `--limit`.
181
+ */
182
+ var resolveSearch = function resolveSearch(_ref2) {
183
+ var input = _ref2.input,
184
+ tool = _ref2.tool;
185
+ var terms = input.positionals;
186
+ if (terms.length === 0) {
187
+ return {
188
+ error: 'At least one search term is required.'
189
+ };
190
+ }
191
+ var limit = parseLimit(input.flags);
192
+ if (limit === null) {
193
+ return invalidLimitError(input.flags);
194
+ }
195
+ var args = _objectSpread({
196
+ terms: terms
197
+ }, limit === undefined ? {} : {
198
+ limit: limit
199
+ });
200
+ return singleTool({
201
+ importPath: tool.importPath,
202
+ handlerName: tool.handlerName,
203
+ args: args,
204
+ meta: args
205
+ });
206
+ };
207
+
208
+ /**
209
+ * The `--all` flag shared by the item commands (`component`, `token`, `icon`), which lists every
210
+ * entry of that kind instead of requiring a name.
211
+ */
212
+ var allFlag = {
213
+ name: 'all',
214
+ type: 'boolean',
215
+ description: 'List every entry of this kind instead of looking up a single name.'
216
+ };
217
+
218
+ /**
219
+ * Per-kind accessors describing how to read the display name and a secondary hint off a raw
220
+ * item record, and how many candidates to fetch when disambiguating.
221
+ *
222
+ * Components/tokens key their name off `name`; icons key theirs off `componentName`.
223
+ */
224
+ var itemFields = {
225
+ components: {
226
+ nameOf: function nameOf(item) {
227
+ var _item$name;
228
+ return String((_item$name = item.name) !== null && _item$name !== void 0 ? _item$name : '');
229
+ },
230
+ hintOf: function hintOf(item) {
231
+ return item.package ? String(item.package) : undefined;
232
+ }
233
+ },
234
+ tokens: {
235
+ nameOf: function nameOf(item) {
236
+ var _item$name2;
237
+ return String((_item$name2 = item.name) !== null && _item$name2 !== void 0 ? _item$name2 : '');
238
+ },
239
+ hintOf: function hintOf(item) {
240
+ return item.exampleValue ? "= ".concat(String(item.exampleValue)) : undefined;
241
+ }
242
+ },
243
+ icons: {
244
+ nameOf: function nameOf(item) {
245
+ var _item$componentName;
246
+ return String((_item$componentName = item.componentName) !== null && _item$componentName !== void 0 ? _item$componentName : '');
247
+ },
248
+ hintOf: function hintOf(item) {
249
+ return item.package ? String(item.package) : undefined;
250
+ }
251
+ }
252
+ };
253
+
254
+ /**
255
+ * Number of candidates fetched for an item lookup. One is not enough to detect ambiguity or to
256
+ * prefer an exact name match over a higher-ranked fuzzy hit; a small window is plenty.
257
+ */
258
+ var ITEM_LOOKUP_LIMIT = 8;
259
+
260
+ /**
261
+ * Trim a rule description down to a single-line hint for the disambiguation list. Rule
262
+ * descriptions can be a full sentence; a long hint would wrap and make the list hard to scan.
263
+ */
264
+ var truncateHint = function truncateHint(text) {
265
+ var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 72;
266
+ if (!text) {
267
+ return undefined;
268
+ }
269
+ var oneLine = text.replace(/\s+/g, ' ').trim();
270
+ return oneLine.length > max ? "".concat(oneLine.slice(0, max - 1).trimEnd(), "\u2026") : oneLine;
271
+ };
272
+
273
+ /**
274
+ * A representative example name per kind, used in each item command's `--help` examples.
275
+ */
276
+ var EXAMPLE_NAME = {
277
+ components: 'Button',
278
+ tokens: 'space.100',
279
+ icons: 'AddIcon'
280
+ };
281
+
282
+ /**
283
+ * Build one of the singular item commands (`component <name>`, `token <name>`, `icon <name>`).
284
+ *
285
+ * All three share the same shape, so they are generated from a single factory to avoid drift:
286
+ * - `<name>` → detail view. We fetch a small candidate window (not just the top hit) and then
287
+ * (a) render the item whose name matches exactly (case-insensitively), else
288
+ * (b) if exactly one candidate, render it, else
289
+ * (c) show a "did you mean?" disambiguation list rather than silently guessing.
290
+ * - `--all` → list every entry of the kind (via the kind's `get-all-*` tool).
291
+ * - no args → a friendly usage error (mirrors bare `docs a11y`/`docs migration` guidance).
292
+ *
293
+ * The exact-match step only *selects* from the tool's own ranked results — it never re-ranks —
294
+ * so the zero-drift contract with `@atlaskit/ads-mcp` is preserved.
295
+ */
296
+ var makeItemCommand = function makeItemCommand(_ref3) {
297
+ var kind = _ref3.kind,
298
+ name = _ref3.name,
299
+ _formatHuman = _ref3.formatHuman;
300
+ var searchTool = searchKindTools[kind];
301
+ var listTool = listKindTools[kind];
302
+ var _itemFields$kind = itemFields[kind],
303
+ nameOf = _itemFields$kind.nameOf,
304
+ hintOf = _itemFields$kind.hintOf;
305
+ return {
306
+ name: name,
307
+ description: "Get details for a single ADS ".concat(name, ", or list all with --all."),
308
+ usage: "".concat(name, " <name> | ").concat(name, " --all"),
309
+ flags: [allFlag],
310
+ examples: ["".concat(name, " ").concat(EXAMPLE_NAME[kind]), "".concat(name, " --all")],
311
+ // `--all` returns an array → render it as the compact per-row list for this kind. A single
312
+ // `<name>` lookup is post-processed by `transform` into either one detail object or a
313
+ // disambiguation marker, both handled by `formatHuman`.
314
+ resultKind: function resultKind(input) {
315
+ return input.flags.all ? kind : undefined;
316
+ },
317
+ envelopeType: function envelopeType(input) {
318
+ return input.flags.all ? listTool.envelopeType : name;
319
+ },
320
+ formatHuman: function formatHuman(data) {
321
+ // Ambiguous lookup → render the "did you mean?" list; otherwise the item detail view.
322
+ if (isDisambiguation(data)) {
323
+ return formatDisambiguation(data);
324
+ }
325
+ return _formatHuman(data);
326
+ },
327
+ // Turn the ranked candidate window into an exact match, a lone match, or a disambiguation
328
+ // marker. Skipped for `--all` (that path returns the full array untouched).
329
+ transform: function transform(_ref4) {
330
+ var _input$positionals$;
331
+ var data = _ref4.data,
332
+ input = _ref4.input;
333
+ if (input.flags.all) {
334
+ return data;
335
+ }
336
+ var query = (_input$positionals$ = input.positionals[0]) !== null && _input$positionals$ !== void 0 ? _input$positionals$ : '';
337
+ var candidates = Array.isArray(data) ? data : [];
338
+
339
+ // Prefer an exact, case-insensitive name match from the tool's own results.
340
+ var exact = candidates.find(function (item) {
341
+ return nameOf(item).toLowerCase() === query.toLowerCase();
342
+ });
343
+ if (exact) {
344
+ return exact;
345
+ }
346
+ // A single candidate is unambiguous — show it.
347
+ if (candidates.length === 1) {
348
+ return candidates[0];
349
+ }
350
+ // Otherwise do not guess: surface a disambiguation list.
351
+ return {
352
+ ambiguous: true,
353
+ query: query,
354
+ noun: name,
355
+ candidates: candidates.map(function (item) {
356
+ var itemName = nameOf(item);
357
+ return {
358
+ name: itemName,
359
+ hint: hintOf(item),
360
+ followUp: "".concat(name, " ").concat(itemName)
361
+ };
362
+ })
363
+ };
364
+ },
365
+ resolve: function resolve(input) {
366
+ // `--all` → list every entry of the kind (the get-all-* tools take no arguments).
367
+ if (input.flags.all) {
368
+ return singleTool({
369
+ importPath: listTool.importPath,
370
+ handlerName: listTool.handlerName,
371
+ meta: {
372
+ all: true
373
+ }
374
+ });
375
+ }
376
+ var name_ = input.positionals[0];
377
+ if (!name_) {
378
+ return {
379
+ error: "A ".concat(name, " name is required. Try `").concat(name, " <name>` or `").concat(name, " --all`.")
380
+ };
381
+ }
382
+
383
+ // Fetch a small candidate window (not just the top hit) so `transform` can prefer an
384
+ // exact name match and detect ambiguity. We never re-rank — only select.
385
+ return singleTool({
386
+ importPath: searchTool.importPath,
387
+ handlerName: searchTool.handlerName,
388
+ args: {
389
+ terms: [name_],
390
+ limit: ITEM_LOOKUP_LIMIT
391
+ },
392
+ meta: {
393
+ name: name_
394
+ }
395
+ });
396
+ }
397
+ };
398
+ };
399
+
400
+ /**
401
+ * Resolver for the unified `search` (no `--type`): fan out to all three search tools in one
402
+ * command. The results are grouped by kind (components/tokens/icons) rather than merged into a
403
+ * single ranked list — each tool ranks its own domain, and re-ranking across domains would
404
+ * mean duplicating ranking logic here (breaking the zero-drift contract with `@atlaskit/ads-mcp`).
405
+ */
406
+ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
407
+ var terms = input.positionals;
408
+ if (terms.length === 0) {
409
+ return {
410
+ error: 'At least one search term is required.'
411
+ };
412
+ }
413
+ var limit = parseLimit(input.flags);
414
+ if (limit === null) {
415
+ return invalidLimitError(input.flags);
416
+ }
417
+ var args = _objectSpread({
418
+ terms: terms
419
+ }, limit === undefined ? {} : {
420
+ limit: limit
421
+ });
422
+ return {
423
+ grouped: true,
424
+ tools: [_objectSpread(_objectSpread({
425
+ key: 'components'
426
+ }, searchKindTools.components), {}, {
427
+ args: args
428
+ }), _objectSpread(_objectSpread({
429
+ key: 'tokens'
430
+ }, searchKindTools.tokens), {}, {
431
+ args: args
432
+ }), _objectSpread(_objectSpread({
433
+ key: 'icons'
434
+ }, searchKindTools.icons), {}, {
435
+ args: args
436
+ })],
437
+ meta: args
438
+ };
439
+ };
440
+
441
+ /**
442
+ * The full set of CLI commands. Order here is the order shown by `--help`.
443
+ */
444
+ export var commands = [{
445
+ name: 'search',
446
+ description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
447
+ usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
448
+ flags: [{
449
+ name: 'type',
450
+ type: 'string',
451
+ alias: 't',
452
+ description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
453
+ }, limitFlag],
454
+ examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
455
+ // With `--type`, the result is a single kind (compact per-row rendering). Without it, the
456
+ // result is grouped across all kinds, so there is no single result kind — the grouped
457
+ // formatter handles rendering instead.
458
+ resultKind: function resultKind(input) {
459
+ var _resolveSearchType;
460
+ return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
461
+ },
462
+ envelopeType: function envelopeType(input) {
463
+ var searchType = resolveSearchType(input.flags);
464
+ return searchType ? searchKindTools[searchType].envelopeType : 'search';
465
+ },
466
+ resolve: function resolve(input) {
467
+ // No `--type`: unified search across all three kinds.
468
+ if (input.flags.type === undefined) {
469
+ return resolveUnifiedSearch(input);
470
+ }
471
+ // `--type X`: narrow to a single kind. `undefined` is unreachable here (handled by the
472
+ // bare-`type` guard above), but folding it in with `null` narrows `searchType` to a
473
+ // concrete `SearchKind` so it can index `searchKindTools`.
474
+ var searchType = resolveSearchType(input.flags);
475
+ if (searchType === null || searchType === undefined) {
476
+ return {
477
+ error: "Invalid --type value \"".concat(String(input.flags.type), "\". Must be one of: ").concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
478
+ };
479
+ }
480
+ return resolveSearch({
481
+ input: input,
482
+ tool: searchKindTools[searchType]
483
+ });
484
+ }
485
+ }, makeItemCommand({
486
+ kind: 'components',
487
+ name: 'component',
488
+ formatHuman: formatComponent
489
+ }), makeItemCommand({
490
+ kind: 'tokens',
491
+ name: 'token',
492
+ formatHuman: formatToken
493
+ }), makeItemCommand({
494
+ kind: 'icons',
495
+ name: 'icon',
496
+ formatHuman: formatIcon
497
+ }), {
498
+ name: 'lint-rules',
499
+ description: 'Get ADS ESLint lint rules, optionally filtered by term.',
500
+ usage: 'lint-rules [term...] [--limit N]',
501
+ flags: [limitFlag],
502
+ examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
503
+ envelopeType: function envelopeType() {
504
+ return 'lint-rules';
505
+ },
506
+ // Ambiguous fuzzy lookup → render the "did you mean?" list; otherwise print each rule's
507
+ // Markdown `content` verbatim rather than JSON.
508
+ formatHuman: function formatHuman(data) {
509
+ return isDisambiguation(data) ? formatDisambiguation(data) : formatLintRules(data);
510
+ },
511
+ // Mirror the item commands: a fuzzy term that matches one rule exactly (or a lone match)
512
+ // shows that rule's docs, but several matches with no exact name surface a disambiguation
513
+ // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
514
+ // intentionally returns every rule's content).
515
+ transform: function transform(_ref5) {
516
+ var data = _ref5.data,
517
+ input = _ref5.input;
518
+ var terms = input.positionals;
519
+ if (terms.length === 0) {
520
+ return data;
521
+ }
522
+
523
+ // Only rule records with a name can be disambiguated.
524
+ var candidates = parseLintRuleRecords(data).filter(function (rule) {
525
+ return rule !== null && _typeof(rule) === 'object' && typeof rule.ruleName === 'string';
526
+ });
527
+ // Not interpretable as named rule records → defer to the normal renderer / fallback.
528
+ if (candidates.length === 0) {
529
+ return data;
530
+ }
531
+ var query = terms.join(' ');
532
+ var nameOf = function nameOf(rule) {
533
+ var _rule$ruleName;
534
+ return (_rule$ruleName = rule.ruleName) !== null && _rule$ruleName !== void 0 ? _rule$ruleName : '';
535
+ };
536
+
537
+ // Prefer an exact, case-insensitive rule-name match from the tool's own results.
538
+ var exact = candidates.find(function (rule) {
539
+ return nameOf(rule).toLowerCase() === query.toLowerCase();
540
+ });
541
+ if (exact) {
542
+ return exact;
543
+ }
544
+ // A single candidate is unambiguous — show it.
545
+ if (candidates.length === 1) {
546
+ return candidates[0];
547
+ }
548
+ // Otherwise do not guess: surface a disambiguation list.
549
+ return {
550
+ ambiguous: true,
551
+ query: query,
552
+ noun: 'lint-rule',
553
+ candidates: candidates.map(function (rule) {
554
+ var name = nameOf(rule);
555
+ return {
556
+ name: name,
557
+ hint: truncateHint(rule.description),
558
+ followUp: "lint-rules ".concat(name)
559
+ };
560
+ })
561
+ };
562
+ },
563
+ resolve: function resolve(input) {
564
+ var terms = input.positionals;
565
+ var limit = parseLimit(input.flags);
566
+ if (limit === null) {
567
+ return invalidLimitError(input.flags);
568
+ }
569
+ // For a fuzzy term lookup, fetch a candidate window (not just the top hit) so `transform`
570
+ // can prefer an exact rule-name match and detect ambiguity. An explicit `--limit` overrides
571
+ // the window (and caps the "did you mean?" list). Bare `lint-rules` passes only what the
572
+ // user supplied.
573
+ var fetchLimit = terms.length > 0 ? limit !== null && limit !== void 0 ? limit : ITEM_LOOKUP_LIMIT : limit;
574
+ return singleTool({
575
+ importPath: '@atlaskit/ads-mcp/tools/get-lint-rules',
576
+ handlerName: 'getLintRulesTool',
577
+ args: _objectSpread({
578
+ terms: terms
579
+ }, fetchLimit === undefined ? {} : {
580
+ limit: fetchLimit
581
+ }),
582
+ // `meta` reports what the user asked for (their explicit `--limit`, if any), not the
583
+ // internal candidate window.
584
+ meta: _objectSpread({
585
+ terms: terms
586
+ }, limit === undefined ? {} : {
587
+ limit: limit
588
+ })
589
+ });
590
+ }
591
+ }, {
592
+ name: 'docs',
593
+ description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
594
+ usage: "docs <topic...> | docs a11y [".concat(A11Y_TOPICS.join('|'), "] | docs migration <").concat(MIGRATION_IDS.join('|'), ">"),
595
+ // No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
596
+ // guide, or a migration guide), so there is nothing to limit.
597
+ flags: [],
598
+ examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
599
+ envelopeType: function envelopeType(input) {
600
+ var namespace = input.positionals[0];
601
+ if (namespace === 'a11y') {
602
+ return 'docs-a11y';
603
+ }
604
+ if (namespace === 'migration') {
605
+ return 'docs-migration';
606
+ }
607
+ return 'docs-guidelines';
608
+ },
609
+ // `docs a11y` / `docs migration` return a structured object → render it as readable text.
610
+ // `docs <term>` returns a Markdown string, which `formatDocObject` declines (returns null),
611
+ // so the generic verbatim-string fallback prints it unchanged.
612
+ formatHuman: formatDocObject,
613
+ resolve: function resolve(input) {
614
+ var _input$positionals = _toArray(input.positionals),
615
+ namespace = _input$positionals[0],
616
+ rest = _arrayLikeToArray(_input$positionals).slice(1);
617
+
618
+ // `docs a11y [topic]` → accessibility guidance. The topic is optional; omitting it asks the
619
+ // tool for its index response, which lists the available topics for the user to pick from.
620
+ if (namespace === 'a11y') {
621
+ var topic = rest[0];
622
+ if (topic !== undefined && !A11Y_TOPICS.includes(topic)) {
623
+ return {
624
+ error: "Unknown a11y topic \"".concat(topic, "\". Must be one of: ").concat(A11Y_TOPICS.join(', '), ".")
625
+ };
626
+ }
627
+ return singleTool({
628
+ importPath: '@atlaskit/ads-mcp/tools/get-a11y-guidelines',
629
+ handlerName: 'getA11yGuidelinesTool',
630
+ args: topic === undefined ? {} : {
631
+ topic: topic
632
+ },
633
+ meta: topic === undefined ? {
634
+ namespace: namespace
635
+ } : {
636
+ namespace: namespace,
637
+ topic: topic
638
+ }
639
+ });
640
+ }
641
+
642
+ // `docs migration <id>` → a structured migration guide.
643
+ if (namespace === 'migration') {
644
+ var migration = rest[0];
645
+ // Bare `docs migration` (no id): return a friendly, exit-0 index of the available
646
+ // ids rather than erroring — consistent with bare `docs a11y` and bare `docs`.
647
+ if (!migration) {
648
+ return {
649
+ data: {
650
+ message: 'Specify a migration id to get the guide:',
651
+ availableIds: MIGRATION_IDS
652
+ },
653
+ meta: {
654
+ namespace: namespace,
655
+ index: true
656
+ }
657
+ };
658
+ }
659
+ if (!MIGRATION_IDS.includes(migration)) {
660
+ return {
661
+ error: "Unknown migration id \"".concat(migration, "\". Must be one of: ").concat(MIGRATION_IDS.join(', '), ".")
662
+ };
663
+ }
664
+ // The underlying tool reads only `migration`; its schema also declares a paired
665
+ // `description` which the handler ignores, so we pass an empty string.
666
+ return singleTool({
667
+ importPath: '@atlaskit/ads-mcp/tools/migration-guides',
668
+ handlerName: 'migrationGuidesTool',
669
+ args: {
670
+ migration: migration,
671
+ description: ''
672
+ },
673
+ meta: {
674
+ namespace: namespace,
675
+ migration: migration
676
+ }
677
+ });
678
+ }
679
+
680
+ // Bare `docs` (no args): return a friendly, exit-0 index of the available doc
681
+ // namespaces instead of erroring — mirroring how `docs a11y` (no topic) lists its
682
+ // topics. The shape is a doc object (`message` header + labelled lists) so it renders
683
+ // via `formatDocObject` for humans and as a structured envelope under `--json`.
684
+ var terms = input.positionals;
685
+ if (terms.length === 0) {
686
+ return {
687
+ data: {
688
+ message: 'Read ADS reference docs. Choose a topic:',
689
+ foundations: 'docs <topic...> — e.g. `docs spacing`, `docs color contrast` (any atlassian.design foundation)',
690
+ accessibility: "docs a11y [topic] \u2014 topics: ".concat(A11Y_TOPICS.join(', ')),
691
+ migrations: "docs migration <id> \u2014 ids: ".concat(MIGRATION_IDS.join(', '))
692
+ },
693
+ meta: {
694
+ namespace: 'index'
695
+ }
696
+ };
697
+ }
698
+ var args = {
699
+ terms: terms
700
+ };
701
+ return singleTool({
702
+ importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
703
+ handlerName: 'getGuidelinesTool',
704
+ args: args,
705
+ meta: args
706
+ });
707
+ }
708
+ }];