@atlaskit/ads-cli 0.1.0 → 0.3.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 +19 -0
- package/README.md +30 -9
- package/dist/cjs/cli.js +24 -32
- package/dist/cjs/commands/build-manifest.js +48 -0
- package/dist/cjs/commands/cli-metadata.js +31 -0
- package/dist/cjs/commands/definitions.js +97 -18
- package/dist/cjs/commands/get-version.js +24 -0
- package/dist/cjs/output/create-doc-search-results.js +55 -0
- package/dist/cjs/output/format-grouped-results.js +5 -3
- package/dist/cjs/output/format-manifest.js +26 -0
- package/dist/cjs/output/format-results.js +14 -5
- package/dist/es2019/cli.js +23 -31
- package/dist/es2019/commands/build-manifest.js +39 -0
- package/dist/es2019/commands/cli-metadata.js +25 -0
- package/dist/es2019/commands/definitions.js +86 -15
- package/dist/es2019/commands/get-version.js +18 -0
- package/dist/es2019/output/create-doc-search-results.js +42 -0
- package/dist/es2019/output/format-grouped-results.js +5 -3
- package/dist/es2019/output/format-manifest.js +18 -0
- package/dist/es2019/output/format-results.js +14 -5
- package/dist/esm/cli.js +23 -31
- package/dist/esm/commands/build-manifest.js +42 -0
- package/dist/esm/commands/cli-metadata.js +25 -0
- package/dist/esm/commands/definitions.js +97 -18
- package/dist/esm/commands/get-version.js +18 -0
- package/dist/esm/output/create-doc-search-results.js +48 -0
- package/dist/esm/output/format-grouped-results.js +5 -3
- package/dist/esm/output/format-manifest.js +19 -0
- package/dist/esm/output/format-results.js +14 -5
- package/dist/types/commands/build-manifest.d.ts +26 -0
- package/dist/types/commands/cli-metadata.d.ts +8 -0
- package/dist/types/commands/definitions.d.ts +4 -3
- package/dist/types/commands/get-version.d.ts +7 -0
- package/dist/types/commands/types.d.ts +30 -11
- package/dist/types/output/create-doc-search-results.d.ts +22 -0
- package/dist/types/output/format-grouped-results.d.ts +2 -3
- package/dist/types/output/format-manifest.d.ts +4 -0
- package/dist/types/output/format-results.d.ts +1 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,24 @@
|
|
|
1
1
|
# @atlaskit/ads-cli
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [`d678f1fec09ca`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/d678f1fec09ca) -
|
|
8
|
+
Include concise, query-labelled foundations docs in unified search results, with leading-text
|
|
9
|
+
previews, docs filtering, and detail commands. For example:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npx @atlaskit/ads-cli search contrast --type docs
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 0.2.0
|
|
16
|
+
|
|
17
|
+
### Minor Changes
|
|
18
|
+
|
|
19
|
+
- [`f37252516ee5d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f37252516ee5d) -
|
|
20
|
+
Add a `manifest` command for discovering ADS CLI commands in human-readable or JSON format.
|
|
21
|
+
|
|
3
22
|
## 0.1.0
|
|
4
23
|
|
|
5
24
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -23,12 +23,13 @@ The CLI has these commands:
|
|
|
23
23
|
|
|
24
24
|
| Command | Description |
|
|
25
25
|
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
|
-
| `search <query...>` | **Unified** fuzzy-search across components, tokens, and
|
|
26
|
+
| `search <query...>` | **Unified** fuzzy-search across components, tokens, icons, and foundations docs at once. Narrow results with `--type component\|token\|icon\|docs`; limit with `--limit N`. |
|
|
27
27
|
| `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
|
|
28
28
|
| `token <name>` | Detail for a single token. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token. |
|
|
29
29
|
| `icon <name>` | Detail for a single icon (with a copy-paste import). Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every icon. |
|
|
30
30
|
| `lint-rules [term...]` | ADS ESLint rules. A term that matches one rule (exactly or uniquely) prints its docs; several matches show a "did you mean?" list. Bare `lint-rules` prints every rule; `--limit N` caps the candidate list. |
|
|
31
31
|
| `docs <topic...>` | Read ADS reference docs. Three forms:<br>• `docs <term...>` — foundations guidelines (spacing, color, …)<br>• `docs a11y [topic]` — accessibility guidance (optional topic e.g. `buttons`, `forms`, `colors`)<br>• `docs migration <id>` — a structured migration guide |
|
|
32
|
+
| `manifest` | Describe every command, argument, flag, and JSON response type. Use `--json` for the machine-readable contract. |
|
|
32
33
|
|
|
33
34
|
### Global flags
|
|
34
35
|
|
|
@@ -39,11 +40,12 @@ The CLI has these commands:
|
|
|
39
40
|
## Examples
|
|
40
41
|
|
|
41
42
|
```sh
|
|
42
|
-
# Unified human-readable search — components, tokens, and
|
|
43
|
-
npx @atlaskit/ads-cli search
|
|
43
|
+
# Unified human-readable search — components, tokens, icons, and docs grouped together
|
|
44
|
+
npx @atlaskit/ads-cli search contrast
|
|
44
45
|
|
|
45
46
|
# Narrow to a single kind
|
|
46
47
|
npx @atlaskit/ads-cli search space color --type token
|
|
48
|
+
npx @atlaskit/ads-cli search contrast --type docs
|
|
47
49
|
|
|
48
50
|
# Detail for a single component, token, or icon
|
|
49
51
|
npx @atlaskit/ads-cli component Avatar
|
|
@@ -60,6 +62,9 @@ npx @atlaskit/ads-cli docs migration motion
|
|
|
60
62
|
|
|
61
63
|
# Machine-readable envelope for agents / jq
|
|
62
64
|
npx @atlaskit/ads-cli search button --json
|
|
65
|
+
|
|
66
|
+
# Discover the complete CLI contract
|
|
67
|
+
npx @atlaskit/ads-cli manifest --json
|
|
63
68
|
```
|
|
64
69
|
|
|
65
70
|
## Output contract
|
|
@@ -67,11 +72,13 @@ npx @atlaskit/ads-cli search button --json
|
|
|
67
72
|
- **Every command is human-readable by default; `--json` is the only path to structured output.**
|
|
68
73
|
`search` and the `--all` listings print one compact line per result (e.g.
|
|
69
74
|
`Avatar @atlaskit/avatar (42 props, 1 example)`), and unified `search` groups results into
|
|
70
|
-
`Components` / `Tokens` / `Icons` sections
|
|
71
|
-
|
|
72
|
-
`
|
|
73
|
-
|
|
74
|
-
|
|
75
|
+
`Components` / `Tokens` / `Icons` / `Docs` sections. Every `search` row includes a follow-up
|
|
76
|
+
command, such as `→ ads-cli component Avatar` or `→ ads-cli docs contrast`; this also applies to
|
|
77
|
+
narrowed `search --type` output. Documentation search results stay concise, while `docs <query>`
|
|
78
|
+
prints the full matched Markdown. `component`/`token`/`icon` print a readable detail view (the
|
|
79
|
+
icon view includes a copy-paste `import` line); `docs` (`foundations`, `a11y`, and `migration`)
|
|
80
|
+
and `lint-rules` print prose/Markdown. A raw JSON dump is only ever a last-resort fallback for an
|
|
81
|
+
unrecognised shape. For the **full structured payload**, use `--json`.
|
|
75
82
|
- **Lookups never silently guess.** `component`/`token`/`icon <name>` — and a fuzzy
|
|
76
83
|
`lint-rules <term>` — render the entry whose name matches exactly (case-insensitively). If there
|
|
77
84
|
is no exact match but several candidates, they print a `Did you mean?` list (each with a
|
|
@@ -79,6 +86,9 @@ npx @atlaskit/ads-cli search button --json
|
|
|
79
86
|
`{ "ambiguous": true, "query", "noun", "candidates": [...] }`.
|
|
80
87
|
- **Data is written to stdout only.** Logs, hints, and errors go to **stderr**. This keeps `--json`
|
|
81
88
|
output clean for piping.
|
|
89
|
+
- **The manifest is derived from the live command registry.** `manifest --json` lists every command,
|
|
90
|
+
positional argument, flag, example, and success response type without maintaining a separate copy
|
|
91
|
+
of the CLI surface.
|
|
82
92
|
- With `--json`, every success prints a `SuccessEnvelope` and every failure prints an
|
|
83
93
|
`ErrorEnvelope`:
|
|
84
94
|
|
|
@@ -88,7 +98,18 @@ npx @atlaskit/ads-cli search button --json
|
|
|
88
98
|
"type": "ads-cli/search",
|
|
89
99
|
"command": "search",
|
|
90
100
|
"ok": true,
|
|
91
|
-
"data": {
|
|
101
|
+
"data": {
|
|
102
|
+
"components": [ /* … */ ],
|
|
103
|
+
"tokens": [ /* … */ ],
|
|
104
|
+
"icons": [ /* … */ ],
|
|
105
|
+
"docs": [
|
|
106
|
+
{
|
|
107
|
+
"title": "Button",
|
|
108
|
+
"summary": "A concise preview of the leading textual content.",
|
|
109
|
+
"followUp": "docs button"
|
|
110
|
+
}
|
|
111
|
+
]
|
|
112
|
+
},
|
|
92
113
|
"meta": { "terms": ["button"], "count": 12 }
|
|
93
114
|
}
|
|
94
115
|
|
package/dist/cjs/cli.js
CHANGED
|
@@ -8,12 +8,15 @@ exports.run = void 0;
|
|
|
8
8
|
var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
|
|
9
9
|
var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
|
|
10
10
|
var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
|
|
11
|
+
var _cliMetadata = require("./commands/cli-metadata");
|
|
11
12
|
var _definitions = require("./commands/definitions");
|
|
12
13
|
var _getCommand = require("./commands/get-command");
|
|
14
|
+
var _getVersion = require("./commands/get-version");
|
|
13
15
|
var _importToolHandler = require("./commands/import-tool-handler");
|
|
14
16
|
var _runTool = require("./commands/run-tool");
|
|
15
17
|
var _createErrorEnvelope = require("./envelope/create-error-envelope");
|
|
16
18
|
var _createSuccessEnvelope = require("./envelope/create-success-envelope");
|
|
19
|
+
var _createDocSearchResults = require("./output/create-doc-search-results");
|
|
17
20
|
var _formatGroupedResults = require("./output/format-grouped-results");
|
|
18
21
|
var _formatResults = require("./output/format-results");
|
|
19
22
|
var _writeHumanError = require("./output/write-human-error");
|
|
@@ -36,30 +39,6 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
|
|
|
36
39
|
* It never reimplements search ranking or bundles a dataset copy — all query logic lives in
|
|
37
40
|
* `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
|
|
38
41
|
*/
|
|
39
|
-
/**
|
|
40
|
-
* Resolve the CLI version from package.json. Kept in a function so a failure to read it never
|
|
41
|
-
* crashes the CLI (it falls back to `0.0.0`).
|
|
42
|
-
*/
|
|
43
|
-
var getVersion = function getVersion() {
|
|
44
|
-
try {
|
|
45
|
-
var _pkgJson$version;
|
|
46
|
-
// Read our own package.json at runtime via the package-name subpath. This mirrors
|
|
47
|
-
// the sibling `@atlaskit/ads-mcp` package and is depth-independent, so it resolves
|
|
48
|
-
// correctly in both the in-repo source layout (`src/cli`) and the published build
|
|
49
|
-
// (`dist/cjs/cli`). Requires the `./package.json` subpath in this package's exports.
|
|
50
|
-
// eslint-disable-next-line import/no-extraneous-dependencies, @typescript-eslint/no-var-requires -- this uses require because not all supported node versions use the same import assertions/attributes
|
|
51
|
-
var pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
52
|
-
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
53
|
-
} catch (_unused) {
|
|
54
|
-
return '0.0.0';
|
|
55
|
-
}
|
|
56
|
-
};
|
|
57
|
-
|
|
58
|
-
/**
|
|
59
|
-
* One-line description of the CLI, shown at the top of `--help`.
|
|
60
|
-
*/
|
|
61
|
-
var CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
62
|
-
|
|
63
42
|
/**
|
|
64
43
|
* Build the top-level help text from the command registry so it can never drift from the
|
|
65
44
|
* runnable surface.
|
|
@@ -80,7 +59,11 @@ var buildHelpText = function buildHelpText() {
|
|
|
80
59
|
}).join('\n');
|
|
81
60
|
return "".concat(usageLines, "\n ").concat(command.description);
|
|
82
61
|
}).join('\n');
|
|
83
|
-
|
|
62
|
+
var globalFlagLines = _cliMetadata.globalFlags.map(function (flag) {
|
|
63
|
+
var aliases = flag.alias ? ", -".concat(flag.alias) : '';
|
|
64
|
+
return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
|
|
65
|
+
}).join('\n');
|
|
66
|
+
return [_cliMetadata.CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search contrast # unified: components, tokens, icons & docs', ' $ npx @atlaskit/ads-cli search button --type component', ' $ npx @atlaskit/ads-cli search contrast --type docs', ' $ npx @atlaskit/ads-cli component Button # detail for one component', ' $ npx @atlaskit/ads-cli token space.100 # detail for one token', ' $ npx @atlaskit/ads-cli icon --all # list every icon', ' $ npx @atlaskit/ads-cli docs spacing # foundations docs', ' $ npx @atlaskit/ads-cli docs a11y buttons # accessibility guidance', ' $ npx @atlaskit/ads-cli docs migration motion # migration guide', ' $ npx @atlaskit/ads-cli manifest --json # machine-readable CLI contract'].join('\n');
|
|
84
67
|
};
|
|
85
68
|
|
|
86
69
|
/**
|
|
@@ -287,7 +270,8 @@ var renderSingleResult = function renderSingleResult(_ref4) {
|
|
|
287
270
|
var resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
|
|
288
271
|
var compact = resultKind ? (0, _formatResults.formatCompactResults)({
|
|
289
272
|
kind: resultKind,
|
|
290
|
-
data: data
|
|
273
|
+
data: data,
|
|
274
|
+
showFollowUp: command.name === 'search'
|
|
291
275
|
}) : null;
|
|
292
276
|
var human = (_ref5 = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref5 !== void 0 ? _ref5 : null;
|
|
293
277
|
if (human !== null) {
|
|
@@ -315,7 +299,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
315
299
|
json = _ref6.json,
|
|
316
300
|
writer = _ref6.writer;
|
|
317
301
|
// Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
|
|
318
|
-
// empty domain does not blank out the others.
|
|
302
|
+
// empty domain does not blank out the others. The guidelines tool returns full Markdown, so
|
|
303
|
+
// summarize its highest-ranked match for search; `docs <query>` remains the detail view.
|
|
319
304
|
var grouped = {};
|
|
320
305
|
var _iterator = _createForOfIteratorHelper(results),
|
|
321
306
|
_step;
|
|
@@ -325,7 +310,14 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
325
310
|
key = _step$value.key,
|
|
326
311
|
data = _step$value.data,
|
|
327
312
|
isError = _step$value.isError;
|
|
328
|
-
|
|
313
|
+
if (key === 'docs' && !isError && typeof data === 'string' && data.trim() !== '') {
|
|
314
|
+
grouped[key] = (0, _createDocSearchResults.createDocSearchResults)({
|
|
315
|
+
data: data,
|
|
316
|
+
query: input.positionals.join(' ')
|
|
317
|
+
});
|
|
318
|
+
} else {
|
|
319
|
+
grouped[key] = isError || !Array.isArray(data) ? [] : data;
|
|
320
|
+
}
|
|
329
321
|
}
|
|
330
322
|
} catch (err) {
|
|
331
323
|
_iterator.e(err);
|
|
@@ -336,7 +328,7 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
336
328
|
return sum + arr.length;
|
|
337
329
|
}, 0);
|
|
338
330
|
if (totalCount === 0) {
|
|
339
|
-
var message =
|
|
331
|
+
var message = "No components, tokens, icons, or docs found for \"".concat(input.positionals.join(' '), "\".");
|
|
340
332
|
if (json) {
|
|
341
333
|
(0, _writeJsonEnvelope.writeJsonEnvelope)({
|
|
342
334
|
envelope: (0, _createErrorEnvelope.createErrorEnvelope)({
|
|
@@ -359,8 +351,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
359
351
|
envelope: (0, _createSuccessEnvelope.createSuccessEnvelope)({
|
|
360
352
|
envelopeType: command.envelopeType(input),
|
|
361
353
|
command: command.name,
|
|
362
|
-
// `data` for grouped commands is `{ components, tokens, icons }` (already
|
|
363
|
-
// per group), so `count` is the combined total across groups.
|
|
354
|
+
// `data` for grouped commands is `{ components, tokens, icons, docs }` (already
|
|
355
|
+
// counted per group), so `count` is the combined total across groups.
|
|
364
356
|
data: grouped,
|
|
365
357
|
meta: _objectSpread(_objectSpread({}, meta), {}, {
|
|
366
358
|
count: totalCount
|
|
@@ -409,7 +401,7 @@ var run = exports.run = /*#__PURE__*/function () {
|
|
|
409
401
|
_context3.next = 1;
|
|
410
402
|
break;
|
|
411
403
|
}
|
|
412
|
-
writer.out(getVersion());
|
|
404
|
+
writer.out((0, _getVersion.getVersion)());
|
|
413
405
|
return _context3.abrupt("return", _types.ExitCode.Ok);
|
|
414
406
|
case 1:
|
|
415
407
|
if (!(flags.help === true || command === undefined)) {
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.buildManifest = void 0;
|
|
7
|
+
var _cliMetadata = require("./cli-metadata");
|
|
8
|
+
/**
|
|
9
|
+
* Build machine-readable metadata for the ADS CLI.
|
|
10
|
+
*
|
|
11
|
+
* The manifest is projected from the same command definitions used for dispatch and help, so it
|
|
12
|
+
* does not duplicate the runnable command surface.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Build a serializable capability manifest from the live command registry.
|
|
17
|
+
*/
|
|
18
|
+
var buildManifest = exports.buildManifest = function buildManifest(commands, version) {
|
|
19
|
+
return {
|
|
20
|
+
schemaVersion: 1,
|
|
21
|
+
name: _cliMetadata.CLI_NAME,
|
|
22
|
+
bin: _cliMetadata.CLI_BIN_NAME,
|
|
23
|
+
version: version,
|
|
24
|
+
description: _cliMetadata.CLI_DESCRIPTION,
|
|
25
|
+
invocation: "npx ".concat(_cliMetadata.CLI_NAME),
|
|
26
|
+
commands: commands.map(function (_ref) {
|
|
27
|
+
var name = _ref.name,
|
|
28
|
+
description = _ref.description,
|
|
29
|
+
usage = _ref.usage,
|
|
30
|
+
commandArguments = _ref.arguments,
|
|
31
|
+
flags = _ref.flags,
|
|
32
|
+
examples = _ref.examples,
|
|
33
|
+
responseTypes = _ref.responseTypes;
|
|
34
|
+
return {
|
|
35
|
+
name: name,
|
|
36
|
+
description: description,
|
|
37
|
+
usage: usage,
|
|
38
|
+
arguments: commandArguments,
|
|
39
|
+
flags: flags,
|
|
40
|
+
examples: examples,
|
|
41
|
+
jsonSupported: true,
|
|
42
|
+
responseTypes: responseTypes
|
|
43
|
+
};
|
|
44
|
+
}),
|
|
45
|
+
globalFlags: _cliMetadata.globalFlags,
|
|
46
|
+
errorResponseType: 'ads-cli/error'
|
|
47
|
+
};
|
|
48
|
+
};
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.globalFlags = exports.CLI_NAME = exports.CLI_DESCRIPTION = exports.CLI_BIN_NAME = void 0;
|
|
7
|
+
/**
|
|
8
|
+
* Shared top-level ADS CLI metadata used by help and the capability manifest.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
var CLI_NAME = exports.CLI_NAME = '@atlaskit/ads-cli';
|
|
12
|
+
var CLI_BIN_NAME = exports.CLI_BIN_NAME = 'ads-cli';
|
|
13
|
+
var CLI_DESCRIPTION = exports.CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
14
|
+
var globalFlags = exports.globalFlags = [{
|
|
15
|
+
name: 'json',
|
|
16
|
+
type: 'boolean',
|
|
17
|
+
default: false,
|
|
18
|
+
description: 'Emit a machine-readable JSON envelope on stdout.'
|
|
19
|
+
}, {
|
|
20
|
+
name: 'help',
|
|
21
|
+
type: 'boolean',
|
|
22
|
+
alias: 'h',
|
|
23
|
+
default: false,
|
|
24
|
+
description: 'Show help.'
|
|
25
|
+
}, {
|
|
26
|
+
name: 'version',
|
|
27
|
+
type: 'boolean',
|
|
28
|
+
alias: 'v',
|
|
29
|
+
default: false,
|
|
30
|
+
description: 'Show the CLI version.'
|
|
31
|
+
}];
|
|
@@ -7,29 +7,35 @@ Object.defineProperty(exports, "__esModule", {
|
|
|
7
7
|
exports.commands = void 0;
|
|
8
8
|
var _toArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toArray"));
|
|
9
9
|
var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
|
|
10
|
+
var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
|
|
10
11
|
var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
|
|
11
12
|
var _a11yGuidelines = require("@atlaskit/ads-mcp/a11y-guidelines");
|
|
12
13
|
var _migrationRegistry = require("@atlaskit/ads-mcp/migration-registry");
|
|
14
|
+
var _createDocSearchResults = require("../output/create-doc-search-results");
|
|
13
15
|
var _disambiguation = require("../output/disambiguation");
|
|
14
16
|
var _formatComponent = require("../output/format-component");
|
|
15
17
|
var _formatDisambiguation = require("../output/format-disambiguation");
|
|
16
18
|
var _formatDocObject = require("../output/format-doc-object");
|
|
17
19
|
var _formatIcon = require("../output/format-icon");
|
|
18
20
|
var _formatLintRules = require("../output/format-lint-rules");
|
|
21
|
+
var _formatManifest = require("../output/format-manifest");
|
|
19
22
|
var _formatToken = require("../output/format-token");
|
|
20
23
|
var _parseLintRuleRecords = require("../output/parse-lint-rule-records");
|
|
24
|
+
var _buildManifest = require("./build-manifest");
|
|
25
|
+
var _getVersion = require("./get-version");
|
|
21
26
|
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; }
|
|
22
27
|
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; }
|
|
23
28
|
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) { (0, _defineProperty2.default)(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; } /**
|
|
24
29
|
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
25
30
|
*
|
|
26
|
-
*
|
|
31
|
+
* Command dispatch, top-level `--help`, and the self-describing manifest are derived
|
|
27
32
|
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
28
33
|
* to drift apart. Each entry declares:
|
|
29
34
|
*
|
|
30
35
|
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
31
36
|
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
32
|
-
* - the metadata (
|
|
37
|
+
* - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
|
|
38
|
+
* `--help`.
|
|
33
39
|
*
|
|
34
40
|
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
35
41
|
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
@@ -63,7 +69,7 @@ var parseLimit = function parseLimit(flags) {
|
|
|
63
69
|
};
|
|
64
70
|
|
|
65
71
|
/**
|
|
66
|
-
* Map of the
|
|
72
|
+
* Map of the `search --type` variants to their ADS MCP tool exports.
|
|
67
73
|
*/
|
|
68
74
|
var searchKindTools = {
|
|
69
75
|
components: {
|
|
@@ -80,17 +86,22 @@ var searchKindTools = {
|
|
|
80
86
|
importPath: '@atlaskit/ads-mcp/tools/search-icons',
|
|
81
87
|
handlerName: 'searchIconsTool',
|
|
82
88
|
envelopeType: 'search-icons'
|
|
89
|
+
},
|
|
90
|
+
docs: {
|
|
91
|
+
importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
|
|
92
|
+
handlerName: 'getGuidelinesTool',
|
|
93
|
+
envelopeType: 'search-docs'
|
|
83
94
|
}
|
|
84
95
|
};
|
|
85
96
|
/**
|
|
86
|
-
* Accepted `--type` values
|
|
87
|
-
*
|
|
88
|
-
* grouped JSON keys), so the singular input normalises to it here.
|
|
97
|
+
* Accepted `--type` values → the internal {@link SearchKind}. Entity inputs are singular to match
|
|
98
|
+
* their item commands; `docs` matches the dedicated documentation command.
|
|
89
99
|
*/
|
|
90
100
|
var SEARCH_TYPE_VALUES = {
|
|
91
101
|
component: 'components',
|
|
92
102
|
token: 'tokens',
|
|
93
|
-
icon: 'icons'
|
|
103
|
+
icon: 'icons',
|
|
104
|
+
docs: 'docs'
|
|
94
105
|
};
|
|
95
106
|
var isSearchTypeValue = function isSearchTypeValue(value) {
|
|
96
107
|
return value in SEARCH_TYPE_VALUES;
|
|
@@ -217,6 +228,7 @@ var resolveSearch = function resolveSearch(_ref2) {
|
|
|
217
228
|
var allFlag = {
|
|
218
229
|
name: 'all',
|
|
219
230
|
type: 'boolean',
|
|
231
|
+
default: false,
|
|
220
232
|
description: 'List every entry of this kind instead of looking up a single name.'
|
|
221
233
|
};
|
|
222
234
|
|
|
@@ -311,8 +323,15 @@ var makeItemCommand = function makeItemCommand(_ref3) {
|
|
|
311
323
|
name: name,
|
|
312
324
|
description: "Get details for a single ADS ".concat(name, ", or list all with --all."),
|
|
313
325
|
usage: "".concat(name, " <name> | ").concat(name, " --all"),
|
|
326
|
+
arguments: [{
|
|
327
|
+
name: 'name',
|
|
328
|
+
type: 'string',
|
|
329
|
+
required: false,
|
|
330
|
+
description: "Exact or fuzzy ADS ".concat(name, " name. Omit when using --all.")
|
|
331
|
+
}],
|
|
314
332
|
flags: [allFlag],
|
|
315
333
|
examples: ["".concat(name, " ").concat(EXAMPLE_NAME[kind]), "".concat(name, " --all")],
|
|
334
|
+
responseTypes: ["ads-cli/".concat(name), "ads-cli/".concat(listTool.envelopeType)],
|
|
316
335
|
// `--all` returns an array → render it as the compact per-row list for this kind. A single
|
|
317
336
|
// `<name>` lookup is post-processed by `transform` into either one detail object or a
|
|
318
337
|
// disambiguation marker, both handled by `formatHuman`.
|
|
@@ -403,10 +422,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
|
|
|
403
422
|
};
|
|
404
423
|
|
|
405
424
|
/**
|
|
406
|
-
* Resolver for the unified `search` (no `--type`): fan out to
|
|
407
|
-
* command. The results are grouped by kind
|
|
408
|
-
* single ranked list — each tool ranks its
|
|
409
|
-
* mean duplicating ranking logic here (breaking the
|
|
425
|
+
* Resolver for the unified `search` (no `--type`): fan out to the three entity search tools and
|
|
426
|
+
* foundations documentation search in one command. The results are grouped by kind
|
|
427
|
+
* (components/tokens/icons/docs) rather than merged into a single ranked list — each tool ranks its
|
|
428
|
+
* own domain, and re-ranking across domains would mean duplicating ranking logic here (breaking the
|
|
429
|
+
* zero-drift contract with `@atlaskit/ads-mcp`).
|
|
410
430
|
*/
|
|
411
431
|
var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
|
|
412
432
|
var terms = input.positionals;
|
|
@@ -438,25 +458,40 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
|
|
|
438
458
|
key: 'icons'
|
|
439
459
|
}, searchKindTools.icons), {}, {
|
|
440
460
|
args: args
|
|
461
|
+
}), _objectSpread(_objectSpread({
|
|
462
|
+
key: 'docs'
|
|
463
|
+
}, searchKindTools.docs), {}, {
|
|
464
|
+
args: args
|
|
441
465
|
})],
|
|
442
466
|
meta: args
|
|
443
467
|
};
|
|
444
468
|
};
|
|
445
469
|
|
|
446
470
|
/**
|
|
447
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
471
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
448
472
|
*/
|
|
449
473
|
var commands = exports.commands = [{
|
|
450
474
|
name: 'search',
|
|
451
|
-
description: 'Fuzzy-search ADS components, tokens, and
|
|
475
|
+
description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type).',
|
|
452
476
|
usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
|
|
477
|
+
arguments: [{
|
|
478
|
+
name: 'query',
|
|
479
|
+
type: 'string',
|
|
480
|
+
required: true,
|
|
481
|
+
variadic: true,
|
|
482
|
+
description: 'One or more terms to search for.'
|
|
483
|
+
}],
|
|
453
484
|
flags: [{
|
|
454
485
|
name: 'type',
|
|
455
486
|
type: 'string',
|
|
456
487
|
alias: 't',
|
|
488
|
+
choices: Object.keys(SEARCH_TYPE_VALUES),
|
|
457
489
|
description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
|
|
458
490
|
}, limitFlag],
|
|
459
|
-
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
|
|
491
|
+
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5', 'search contrast --type docs'],
|
|
492
|
+
responseTypes: ['ads-cli/search'].concat((0, _toConsumableArray2.default)(Object.values(searchKindTools).map(function (tool) {
|
|
493
|
+
return "ads-cli/".concat(tool.envelopeType);
|
|
494
|
+
}))),
|
|
460
495
|
// With `--type`, the result is a single kind (compact per-row rendering). Without it, the
|
|
461
496
|
// result is grouped across all kinds, so there is no single result kind — the grouped
|
|
462
497
|
// formatter handles rendering instead.
|
|
@@ -464,12 +499,20 @@ var commands = exports.commands = [{
|
|
|
464
499
|
var _resolveSearchType;
|
|
465
500
|
return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
|
|
466
501
|
},
|
|
502
|
+
transform: function transform(_ref5) {
|
|
503
|
+
var data = _ref5.data,
|
|
504
|
+
input = _ref5.input;
|
|
505
|
+
return resolveSearchType(input.flags) === 'docs' ? (0, _createDocSearchResults.createDocSearchResults)({
|
|
506
|
+
data: data,
|
|
507
|
+
query: input.positionals.join(' ')
|
|
508
|
+
}) : data;
|
|
509
|
+
},
|
|
467
510
|
envelopeType: function envelopeType(input) {
|
|
468
511
|
var searchType = resolveSearchType(input.flags);
|
|
469
512
|
return searchType ? searchKindTools[searchType].envelopeType : 'search';
|
|
470
513
|
},
|
|
471
514
|
resolve: function resolve(input) {
|
|
472
|
-
// No `--type`: unified search across all three kinds.
|
|
515
|
+
// No `--type`: unified search across all three entity kinds and foundations docs.
|
|
473
516
|
if (input.flags.type === undefined) {
|
|
474
517
|
return resolveUnifiedSearch(input);
|
|
475
518
|
}
|
|
@@ -503,8 +546,16 @@ var commands = exports.commands = [{
|
|
|
503
546
|
name: 'lint-rules',
|
|
504
547
|
description: 'Get ADS ESLint lint rules, optionally filtered by term.',
|
|
505
548
|
usage: 'lint-rules [term...] [--limit N]',
|
|
549
|
+
arguments: [{
|
|
550
|
+
name: 'term',
|
|
551
|
+
type: 'string',
|
|
552
|
+
required: false,
|
|
553
|
+
variadic: true,
|
|
554
|
+
description: 'Terms used to filter lint rules.'
|
|
555
|
+
}],
|
|
506
556
|
flags: [limitFlag],
|
|
507
557
|
examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
|
|
558
|
+
responseTypes: ['ads-cli/lint-rules'],
|
|
508
559
|
envelopeType: function envelopeType() {
|
|
509
560
|
return 'lint-rules';
|
|
510
561
|
},
|
|
@@ -517,9 +568,9 @@ var commands = exports.commands = [{
|
|
|
517
568
|
// shows that rule's docs, but several matches with no exact name surface a disambiguation
|
|
518
569
|
// list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
|
|
519
570
|
// intentionally returns every rule's content).
|
|
520
|
-
transform: function transform(
|
|
521
|
-
var data =
|
|
522
|
-
input =
|
|
571
|
+
transform: function transform(_ref6) {
|
|
572
|
+
var data = _ref6.data,
|
|
573
|
+
input = _ref6.input;
|
|
523
574
|
var terms = input.positionals;
|
|
524
575
|
if (terms.length === 0) {
|
|
525
576
|
return data;
|
|
@@ -597,10 +648,18 @@ var commands = exports.commands = [{
|
|
|
597
648
|
name: 'docs',
|
|
598
649
|
description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
|
|
599
650
|
usage: "docs <topic...> | docs a11y [".concat(A11Y_TOPICS.join('|'), "] | docs migration <").concat(MIGRATION_IDS.join('|'), ">"),
|
|
651
|
+
arguments: [{
|
|
652
|
+
name: 'topic',
|
|
653
|
+
type: 'string',
|
|
654
|
+
required: false,
|
|
655
|
+
variadic: true,
|
|
656
|
+
description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
|
|
657
|
+
}],
|
|
600
658
|
// No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
|
|
601
659
|
// guide, or a migration guide), so there is nothing to limit.
|
|
602
660
|
flags: [],
|
|
603
661
|
examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
|
|
662
|
+
responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
|
|
604
663
|
envelopeType: function envelopeType(input) {
|
|
605
664
|
var namespace = input.positionals[0];
|
|
606
665
|
if (namespace === 'a11y') {
|
|
@@ -710,4 +769,24 @@ var commands = exports.commands = [{
|
|
|
710
769
|
meta: args
|
|
711
770
|
});
|
|
712
771
|
}
|
|
772
|
+
}, {
|
|
773
|
+
name: 'manifest',
|
|
774
|
+
description: 'Describe every CLI command, argument, flag, and JSON response type.',
|
|
775
|
+
usage: 'manifest',
|
|
776
|
+
arguments: [],
|
|
777
|
+
flags: [],
|
|
778
|
+
examples: ['manifest --json'],
|
|
779
|
+
responseTypes: ['ads-cli/manifest'],
|
|
780
|
+
envelopeType: function envelopeType() {
|
|
781
|
+
return 'manifest';
|
|
782
|
+
},
|
|
783
|
+
formatHuman: _formatManifest.formatManifest,
|
|
784
|
+
resolve: function resolve() {
|
|
785
|
+
return {
|
|
786
|
+
data: (0, _buildManifest.buildManifest)(commands, (0, _getVersion.getVersion)()),
|
|
787
|
+
meta: {
|
|
788
|
+
schemaVersion: 1
|
|
789
|
+
}
|
|
790
|
+
};
|
|
791
|
+
}
|
|
713
792
|
}];
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.getVersion = void 0;
|
|
7
|
+
/**
|
|
8
|
+
* Resolve the CLI version from package.json.
|
|
9
|
+
*
|
|
10
|
+
* A failed package lookup must not prevent the CLI from running, so fall back to the development
|
|
11
|
+
* version used by the package source.
|
|
12
|
+
*/
|
|
13
|
+
var getVersion = exports.getVersion = function getVersion() {
|
|
14
|
+
try {
|
|
15
|
+
var _pkgJson$version;
|
|
16
|
+
// Read our own package.json at runtime via the package-name subpath. This is depth-independent,
|
|
17
|
+
// so it resolves in both the source layout and the published build.
|
|
18
|
+
// eslint-disable-next-line import/no-extraneous-dependencies, @typescript-eslint/no-var-requires -- this uses require because not all supported node versions use the same import assertions/attributes
|
|
19
|
+
var pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
20
|
+
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
21
|
+
} catch (_unused) {
|
|
22
|
+
return '0.0.0';
|
|
23
|
+
}
|
|
24
|
+
};
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
|
|
4
|
+
Object.defineProperty(exports, "__esModule", {
|
|
5
|
+
value: true
|
|
6
|
+
});
|
|
7
|
+
exports.createDocSearchResults = void 0;
|
|
8
|
+
var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
|
|
9
|
+
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; }
|
|
10
|
+
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) { (0, _defineProperty2.default)(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; }
|
|
11
|
+
/**
|
|
12
|
+
* A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
|
|
13
|
+
*
|
|
14
|
+
* Search only surfaces this summary. The `docs` command remains the detail view for the full
|
|
15
|
+
* Markdown content.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Truncate a one-line description so compact rows stay on a single line.
|
|
20
|
+
*/
|
|
21
|
+
var truncate = function truncate(text, max) {
|
|
22
|
+
return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Remove common Markdown formatting before showing documentation content in one row.
|
|
27
|
+
*/
|
|
28
|
+
var toPlainText = function toPlainText(text) {
|
|
29
|
+
return text.replace(/!\[[^\]]*]\([^)]*\)/g, '').replace(/\[([^\]]+)]\([^)]*\)/g, '$1').replace(/^\s{0,3}#{1,6}\s+/gm, '').replace(/<[^>]+>/g, ' ').replace(/[*_`~]/g, '').replace(/\s+/g, ' ').trim();
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Turn a full foundations-doc Markdown match into the concise record used by `search`.
|
|
34
|
+
*
|
|
35
|
+
* `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
|
|
36
|
+
* highest-ranked match is represented by the query and a preview of its leading textual content;
|
|
37
|
+
* the full payload remains available through the follow-up `docs <query>` command.
|
|
38
|
+
*/
|
|
39
|
+
var createDocSearchResults = exports.createDocSearchResults = function createDocSearchResults(_ref) {
|
|
40
|
+
var data = _ref.data,
|
|
41
|
+
query = _ref.query;
|
|
42
|
+
if (typeof data !== 'string' || data.trim() === '') {
|
|
43
|
+
return [];
|
|
44
|
+
}
|
|
45
|
+
var normalizedQuery = query.replace(/\s+/g, ' ').trim();
|
|
46
|
+
var title = normalizedQuery ? "".concat(normalizedQuery.charAt(0).toUpperCase()).concat(normalizedQuery.slice(1)) : 'Documentation';
|
|
47
|
+
var preview = toPlainText(data);
|
|
48
|
+
return [_objectSpread(_objectSpread({
|
|
49
|
+
title: truncate(title, 80)
|
|
50
|
+
}, preview ? {
|
|
51
|
+
summary: truncate(preview, 100)
|
|
52
|
+
} : {}), {}, {
|
|
53
|
+
followUp: "docs ".concat(query)
|
|
54
|
+
})];
|
|
55
|
+
};
|