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