@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.
- package/CHANGELOG.md +34 -0
- package/README.md +134 -0
- package/bin/ads-cli.js +40 -0
- package/compass.yml +25 -0
- package/dist/cjs/cli.js +488 -0
- package/dist/cjs/commands/definitions.js +713 -0
- package/dist/cjs/commands/get-command.js +19 -0
- package/dist/cjs/commands/import-tool-handler.js +57 -0
- package/dist/cjs/commands/run-tool.js +106 -0
- package/dist/cjs/commands/types.js +1 -0
- package/dist/cjs/envelope/create-error-envelope.js +27 -0
- package/dist/cjs/envelope/create-success-envelope.js +38 -0
- package/dist/cjs/envelope/types.js +1 -0
- package/dist/cjs/output/disambiguation.js +31 -0
- package/dist/cjs/output/format-component.js +99 -0
- package/dist/cjs/output/format-disambiguation.js +29 -0
- package/dist/cjs/output/format-doc-object.js +115 -0
- package/dist/cjs/output/format-grouped-results.js +55 -0
- package/dist/cjs/output/format-icon.js +49 -0
- package/dist/cjs/output/format-lint-rules.js +52 -0
- package/dist/cjs/output/format-results.js +158 -0
- package/dist/cjs/output/format-token.js +39 -0
- package/dist/cjs/output/parse-lint-rule-records.js +47 -0
- package/dist/cjs/output/write-human-error.js +20 -0
- package/dist/cjs/output/write-human-result.js +31 -0
- package/dist/cjs/output/write-json-envelope.js +20 -0
- package/dist/cjs/output/writer.js +32 -0
- package/dist/cjs/parse-args.js +106 -0
- package/dist/cjs/types.js +53 -0
- package/dist/es2019/cli.js +406 -0
- package/dist/es2019/commands/definitions.js +683 -0
- package/dist/es2019/commands/get-command.js +9 -0
- package/dist/es2019/commands/import-tool-handler.js +22 -0
- package/dist/es2019/commands/run-tool.js +73 -0
- package/dist/es2019/commands/types.js +0 -0
- package/dist/es2019/envelope/create-error-envelope.js +20 -0
- package/dist/es2019/envelope/create-success-envelope.js +31 -0
- package/dist/es2019/envelope/types.js +0 -0
- package/dist/es2019/output/disambiguation.js +21 -0
- package/dist/es2019/output/format-component.js +88 -0
- package/dist/es2019/output/format-disambiguation.js +22 -0
- package/dist/es2019/output/format-doc-object.js +94 -0
- package/dist/es2019/output/format-grouped-results.js +51 -0
- package/dist/es2019/output/format-icon.js +39 -0
- package/dist/es2019/output/format-lint-rules.js +43 -0
- package/dist/es2019/output/format-results.js +142 -0
- package/dist/es2019/output/format-token.js +31 -0
- package/dist/es2019/output/parse-lint-rule-records.js +41 -0
- package/dist/es2019/output/write-human-error.js +14 -0
- package/dist/es2019/output/write-human-result.js +25 -0
- package/dist/es2019/output/write-json-envelope.js +15 -0
- package/dist/es2019/output/writer.js +22 -0
- package/dist/es2019/parse-args.js +100 -0
- package/dist/es2019/types.js +47 -0
- package/dist/esm/cli.js +484 -0
- package/dist/esm/commands/definitions.js +708 -0
- package/dist/esm/commands/get-command.js +13 -0
- package/dist/esm/commands/import-tool-handler.js +42 -0
- package/dist/esm/commands/run-tool.js +99 -0
- package/dist/esm/commands/types.js +0 -0
- package/dist/esm/envelope/create-error-envelope.js +21 -0
- package/dist/esm/envelope/create-success-envelope.js +31 -0
- package/dist/esm/envelope/types.js +0 -0
- package/dist/esm/output/disambiguation.js +24 -0
- package/dist/esm/output/format-component.js +92 -0
- package/dist/esm/output/format-disambiguation.js +22 -0
- package/dist/esm/output/format-doc-object.js +108 -0
- package/dist/esm/output/format-grouped-results.js +50 -0
- package/dist/esm/output/format-icon.js +42 -0
- package/dist/esm/output/format-lint-rules.js +46 -0
- package/dist/esm/output/format-results.js +151 -0
- package/dist/esm/output/format-token.js +32 -0
- package/dist/esm/output/parse-lint-rule-records.js +41 -0
- package/dist/esm/output/write-human-error.js +13 -0
- package/dist/esm/output/write-human-result.js +24 -0
- package/dist/esm/output/write-json-envelope.js +14 -0
- package/dist/esm/output/writer.js +26 -0
- package/dist/esm/parse-args.js +100 -0
- package/dist/esm/types.js +47 -0
- package/dist/types/cli.d.ts +20 -0
- package/dist/types/commands/definitions.d.ts +19 -0
- package/dist/types/commands/get-command.d.ts +8 -0
- package/dist/types/commands/import-tool-handler.d.ts +14 -0
- package/dist/types/commands/run-tool.d.ts +37 -0
- package/dist/types/commands/types.d.ts +149 -0
- package/dist/types/envelope/create-error-envelope.d.ts +12 -0
- package/dist/types/envelope/create-success-envelope.d.ts +16 -0
- package/dist/types/envelope/types.d.ts +60 -0
- package/dist/types/output/disambiguation.d.ts +50 -0
- package/dist/types/output/format-component.d.ts +12 -0
- package/dist/types/output/format-disambiguation.d.ts +11 -0
- package/dist/types/output/format-doc-object.d.ts +15 -0
- package/dist/types/output/format-grouped-results.d.ts +14 -0
- package/dist/types/output/format-icon.d.ts +13 -0
- package/dist/types/output/format-lint-rules.d.ts +14 -0
- package/dist/types/output/format-results.d.ts +24 -0
- package/dist/types/output/format-token.d.ts +12 -0
- package/dist/types/output/parse-lint-rule-records.d.ts +26 -0
- package/dist/types/output/write-human-error.d.ts +11 -0
- package/dist/types/output/write-human-result.d.ts +14 -0
- package/dist/types/output/write-json-envelope.d.ts +14 -0
- package/dist/types/output/writer.d.ts +25 -0
- package/dist/types/parse-args.d.ts +29 -0
- package/dist/types/types.d.ts +53 -0
- package/index.js +31 -0
- 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);
|