@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,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
|
+
}];
|