@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/dist/esm/cli.js
CHANGED
|
@@ -17,12 +17,15 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
|
|
|
17
17
|
* `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
|
|
18
18
|
*/
|
|
19
19
|
|
|
20
|
+
import { CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
|
|
20
21
|
import { commands } from './commands/definitions';
|
|
21
22
|
import { getCommand } from './commands/get-command';
|
|
23
|
+
import { getVersion } from './commands/get-version';
|
|
22
24
|
import { importToolHandler } from './commands/import-tool-handler';
|
|
23
25
|
import { runTool } from './commands/run-tool';
|
|
24
26
|
import { createErrorEnvelope } from './envelope/create-error-envelope';
|
|
25
27
|
import { createSuccessEnvelope } from './envelope/create-success-envelope';
|
|
28
|
+
import { createDocSearchResults } from './output/create-doc-search-results';
|
|
26
29
|
import { formatGroupedResults } from './output/format-grouped-results';
|
|
27
30
|
import { formatCompactResults } from './output/format-results';
|
|
28
31
|
import { writeHumanError } from './output/write-human-error';
|
|
@@ -32,30 +35,6 @@ import { defaultWriter } from './output/writer';
|
|
|
32
35
|
import { parseArgs } from './parse-args';
|
|
33
36
|
import { ExitCode } from './types';
|
|
34
37
|
|
|
35
|
-
/**
|
|
36
|
-
* Resolve the CLI version from package.json. Kept in a function so a failure to read it never
|
|
37
|
-
* crashes the CLI (it falls back to `0.0.0`).
|
|
38
|
-
*/
|
|
39
|
-
var getVersion = function getVersion() {
|
|
40
|
-
try {
|
|
41
|
-
var _pkgJson$version;
|
|
42
|
-
// Read our own package.json at runtime via the package-name subpath. This mirrors
|
|
43
|
-
// the sibling `@atlaskit/ads-mcp` package and is depth-independent, so it resolves
|
|
44
|
-
// correctly in both the in-repo source layout (`src/cli`) and the published build
|
|
45
|
-
// (`dist/cjs/cli`). Requires the `./package.json` subpath in this package's exports.
|
|
46
|
-
// 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
|
|
47
|
-
var pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
48
|
-
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
49
|
-
} catch (_unused) {
|
|
50
|
-
return '0.0.0';
|
|
51
|
-
}
|
|
52
|
-
};
|
|
53
|
-
|
|
54
|
-
/**
|
|
55
|
-
* One-line description of the CLI, shown at the top of `--help`.
|
|
56
|
-
*/
|
|
57
|
-
var CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
58
|
-
|
|
59
38
|
/**
|
|
60
39
|
* Build the top-level help text from the command registry so it can never drift from the
|
|
61
40
|
* runnable surface.
|
|
@@ -76,7 +55,11 @@ var buildHelpText = function buildHelpText() {
|
|
|
76
55
|
}).join('\n');
|
|
77
56
|
return "".concat(usageLines, "\n ").concat(command.description);
|
|
78
57
|
}).join('\n');
|
|
79
|
-
|
|
58
|
+
var globalFlagLines = globalFlags.map(function (flag) {
|
|
59
|
+
var aliases = flag.alias ? ", -".concat(flag.alias) : '';
|
|
60
|
+
return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
|
|
61
|
+
}).join('\n');
|
|
62
|
+
return [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');
|
|
80
63
|
};
|
|
81
64
|
|
|
82
65
|
/**
|
|
@@ -283,7 +266,8 @@ var renderSingleResult = function renderSingleResult(_ref4) {
|
|
|
283
266
|
var resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
|
|
284
267
|
var compact = resultKind ? formatCompactResults({
|
|
285
268
|
kind: resultKind,
|
|
286
|
-
data: data
|
|
269
|
+
data: data,
|
|
270
|
+
showFollowUp: command.name === 'search'
|
|
287
271
|
}) : null;
|
|
288
272
|
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;
|
|
289
273
|
if (human !== null) {
|
|
@@ -311,7 +295,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
311
295
|
json = _ref6.json,
|
|
312
296
|
writer = _ref6.writer;
|
|
313
297
|
// Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
|
|
314
|
-
// empty domain does not blank out the others.
|
|
298
|
+
// empty domain does not blank out the others. The guidelines tool returns full Markdown, so
|
|
299
|
+
// summarize its highest-ranked match for search; `docs <query>` remains the detail view.
|
|
315
300
|
var grouped = {};
|
|
316
301
|
var _iterator = _createForOfIteratorHelper(results),
|
|
317
302
|
_step;
|
|
@@ -321,7 +306,14 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
321
306
|
key = _step$value.key,
|
|
322
307
|
data = _step$value.data,
|
|
323
308
|
isError = _step$value.isError;
|
|
324
|
-
|
|
309
|
+
if (key === 'docs' && !isError && typeof data === 'string' && data.trim() !== '') {
|
|
310
|
+
grouped[key] = createDocSearchResults({
|
|
311
|
+
data: data,
|
|
312
|
+
query: input.positionals.join(' ')
|
|
313
|
+
});
|
|
314
|
+
} else {
|
|
315
|
+
grouped[key] = isError || !Array.isArray(data) ? [] : data;
|
|
316
|
+
}
|
|
325
317
|
}
|
|
326
318
|
} catch (err) {
|
|
327
319
|
_iterator.e(err);
|
|
@@ -332,7 +324,7 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
332
324
|
return sum + arr.length;
|
|
333
325
|
}, 0);
|
|
334
326
|
if (totalCount === 0) {
|
|
335
|
-
var message =
|
|
327
|
+
var message = "No components, tokens, icons, or docs found for \"".concat(input.positionals.join(' '), "\".");
|
|
336
328
|
if (json) {
|
|
337
329
|
writeJsonEnvelope({
|
|
338
330
|
envelope: createErrorEnvelope({
|
|
@@ -355,8 +347,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
|
|
|
355
347
|
envelope: createSuccessEnvelope({
|
|
356
348
|
envelopeType: command.envelopeType(input),
|
|
357
349
|
command: command.name,
|
|
358
|
-
// `data` for grouped commands is `{ components, tokens, icons }` (already
|
|
359
|
-
// per group), so `count` is the combined total across groups.
|
|
350
|
+
// `data` for grouped commands is `{ components, tokens, icons, docs }` (already
|
|
351
|
+
// counted per group), so `count` is the combined total across groups.
|
|
360
352
|
data: grouped,
|
|
361
353
|
meta: _objectSpread(_objectSpread({}, meta), {}, {
|
|
362
354
|
count: totalCount
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Build machine-readable metadata for the ADS CLI.
|
|
3
|
+
*
|
|
4
|
+
* The manifest is projected from the same command definitions used for dispatch and help, so it
|
|
5
|
+
* does not duplicate the runnable command surface.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { CLI_BIN_NAME, CLI_DESCRIPTION, CLI_NAME, globalFlags } from './cli-metadata';
|
|
9
|
+
/**
|
|
10
|
+
* Build a serializable capability manifest from the live command registry.
|
|
11
|
+
*/
|
|
12
|
+
export var buildManifest = function buildManifest(commands, version) {
|
|
13
|
+
return {
|
|
14
|
+
schemaVersion: 1,
|
|
15
|
+
name: CLI_NAME,
|
|
16
|
+
bin: CLI_BIN_NAME,
|
|
17
|
+
version: version,
|
|
18
|
+
description: CLI_DESCRIPTION,
|
|
19
|
+
invocation: "npx ".concat(CLI_NAME),
|
|
20
|
+
commands: commands.map(function (_ref) {
|
|
21
|
+
var name = _ref.name,
|
|
22
|
+
description = _ref.description,
|
|
23
|
+
usage = _ref.usage,
|
|
24
|
+
commandArguments = _ref.arguments,
|
|
25
|
+
flags = _ref.flags,
|
|
26
|
+
examples = _ref.examples,
|
|
27
|
+
responseTypes = _ref.responseTypes;
|
|
28
|
+
return {
|
|
29
|
+
name: name,
|
|
30
|
+
description: description,
|
|
31
|
+
usage: usage,
|
|
32
|
+
arguments: commandArguments,
|
|
33
|
+
flags: flags,
|
|
34
|
+
examples: examples,
|
|
35
|
+
jsonSupported: true,
|
|
36
|
+
responseTypes: responseTypes
|
|
37
|
+
};
|
|
38
|
+
}),
|
|
39
|
+
globalFlags: globalFlags,
|
|
40
|
+
errorResponseType: 'ads-cli/error'
|
|
41
|
+
};
|
|
42
|
+
};
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared top-level ADS CLI metadata used by help and the capability manifest.
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
export var CLI_NAME = '@atlaskit/ads-cli';
|
|
6
|
+
export var CLI_BIN_NAME = 'ads-cli';
|
|
7
|
+
export var CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
8
|
+
export var globalFlags = [{
|
|
9
|
+
name: 'json',
|
|
10
|
+
type: 'boolean',
|
|
11
|
+
default: false,
|
|
12
|
+
description: 'Emit a machine-readable JSON envelope on stdout.'
|
|
13
|
+
}, {
|
|
14
|
+
name: 'help',
|
|
15
|
+
type: 'boolean',
|
|
16
|
+
alias: 'h',
|
|
17
|
+
default: false,
|
|
18
|
+
description: 'Show help.'
|
|
19
|
+
}, {
|
|
20
|
+
name: 'version',
|
|
21
|
+
type: 'boolean',
|
|
22
|
+
alias: 'v',
|
|
23
|
+
default: false,
|
|
24
|
+
description: 'Show the CLI version.'
|
|
25
|
+
}];
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import _toArray from "@babel/runtime/helpers/toArray";
|
|
2
2
|
import _typeof from "@babel/runtime/helpers/typeof";
|
|
3
|
+
import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
|
|
3
4
|
import _defineProperty from "@babel/runtime/helpers/defineProperty";
|
|
4
5
|
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
6
|
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; }
|
|
@@ -7,13 +8,14 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
|
|
|
7
8
|
/**
|
|
8
9
|
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
9
10
|
*
|
|
10
|
-
*
|
|
11
|
+
* Command dispatch, top-level `--help`, and the self-describing manifest are derived
|
|
11
12
|
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
12
13
|
* to drift apart. Each entry declares:
|
|
13
14
|
*
|
|
14
15
|
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
15
16
|
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
16
|
-
* - the metadata (
|
|
17
|
+
* - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
|
|
18
|
+
* `--help`.
|
|
17
19
|
*
|
|
18
20
|
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
19
21
|
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
@@ -21,14 +23,18 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
|
|
|
21
23
|
|
|
22
24
|
import { accessibilityGuidelines } from '@atlaskit/ads-mcp/a11y-guidelines';
|
|
23
25
|
import { migrationRegistry } from '@atlaskit/ads-mcp/migration-registry';
|
|
26
|
+
import { createDocSearchResults } from '../output/create-doc-search-results';
|
|
24
27
|
import { isDisambiguation } from '../output/disambiguation';
|
|
25
28
|
import { formatComponent } from '../output/format-component';
|
|
26
29
|
import { formatDisambiguation } from '../output/format-disambiguation';
|
|
27
30
|
import { formatDocObject } from '../output/format-doc-object';
|
|
28
31
|
import { formatIcon } from '../output/format-icon';
|
|
29
32
|
import { formatLintRules } from '../output/format-lint-rules';
|
|
33
|
+
import { formatManifest } from '../output/format-manifest';
|
|
30
34
|
import { formatToken } from '../output/format-token';
|
|
31
35
|
import { parseLintRuleRecords } from '../output/parse-lint-rule-records';
|
|
36
|
+
import { buildManifest } from './build-manifest';
|
|
37
|
+
import { getVersion } from './get-version';
|
|
32
38
|
/**
|
|
33
39
|
* Shared `--limit` flag definition reused across the search-style commands.
|
|
34
40
|
*/
|
|
@@ -58,7 +64,7 @@ var parseLimit = function parseLimit(flags) {
|
|
|
58
64
|
};
|
|
59
65
|
|
|
60
66
|
/**
|
|
61
|
-
* Map of the
|
|
67
|
+
* Map of the `search --type` variants to their ADS MCP tool exports.
|
|
62
68
|
*/
|
|
63
69
|
var searchKindTools = {
|
|
64
70
|
components: {
|
|
@@ -75,17 +81,22 @@ var searchKindTools = {
|
|
|
75
81
|
importPath: '@atlaskit/ads-mcp/tools/search-icons',
|
|
76
82
|
handlerName: 'searchIconsTool',
|
|
77
83
|
envelopeType: 'search-icons'
|
|
84
|
+
},
|
|
85
|
+
docs: {
|
|
86
|
+
importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
|
|
87
|
+
handlerName: 'getGuidelinesTool',
|
|
88
|
+
envelopeType: 'search-docs'
|
|
78
89
|
}
|
|
79
90
|
};
|
|
80
91
|
/**
|
|
81
|
-
* Accepted `--type` values
|
|
82
|
-
*
|
|
83
|
-
* grouped JSON keys), so the singular input normalises to it here.
|
|
92
|
+
* Accepted `--type` values → the internal {@link SearchKind}. Entity inputs are singular to match
|
|
93
|
+
* their item commands; `docs` matches the dedicated documentation command.
|
|
84
94
|
*/
|
|
85
95
|
var SEARCH_TYPE_VALUES = {
|
|
86
96
|
component: 'components',
|
|
87
97
|
token: 'tokens',
|
|
88
|
-
icon: 'icons'
|
|
98
|
+
icon: 'icons',
|
|
99
|
+
docs: 'docs'
|
|
89
100
|
};
|
|
90
101
|
var isSearchTypeValue = function isSearchTypeValue(value) {
|
|
91
102
|
return value in SEARCH_TYPE_VALUES;
|
|
@@ -212,6 +223,7 @@ var resolveSearch = function resolveSearch(_ref2) {
|
|
|
212
223
|
var allFlag = {
|
|
213
224
|
name: 'all',
|
|
214
225
|
type: 'boolean',
|
|
226
|
+
default: false,
|
|
215
227
|
description: 'List every entry of this kind instead of looking up a single name.'
|
|
216
228
|
};
|
|
217
229
|
|
|
@@ -306,8 +318,15 @@ var makeItemCommand = function makeItemCommand(_ref3) {
|
|
|
306
318
|
name: name,
|
|
307
319
|
description: "Get details for a single ADS ".concat(name, ", or list all with --all."),
|
|
308
320
|
usage: "".concat(name, " <name> | ").concat(name, " --all"),
|
|
321
|
+
arguments: [{
|
|
322
|
+
name: 'name',
|
|
323
|
+
type: 'string',
|
|
324
|
+
required: false,
|
|
325
|
+
description: "Exact or fuzzy ADS ".concat(name, " name. Omit when using --all.")
|
|
326
|
+
}],
|
|
309
327
|
flags: [allFlag],
|
|
310
328
|
examples: ["".concat(name, " ").concat(EXAMPLE_NAME[kind]), "".concat(name, " --all")],
|
|
329
|
+
responseTypes: ["ads-cli/".concat(name), "ads-cli/".concat(listTool.envelopeType)],
|
|
311
330
|
// `--all` returns an array → render it as the compact per-row list for this kind. A single
|
|
312
331
|
// `<name>` lookup is post-processed by `transform` into either one detail object or a
|
|
313
332
|
// disambiguation marker, both handled by `formatHuman`.
|
|
@@ -398,10 +417,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
|
|
|
398
417
|
};
|
|
399
418
|
|
|
400
419
|
/**
|
|
401
|
-
* Resolver for the unified `search` (no `--type`): fan out to
|
|
402
|
-
* command. The results are grouped by kind
|
|
403
|
-
* single ranked list — each tool ranks its
|
|
404
|
-
* mean duplicating ranking logic here (breaking the
|
|
420
|
+
* Resolver for the unified `search` (no `--type`): fan out to the three entity search tools and
|
|
421
|
+
* foundations documentation search in one command. The results are grouped by kind
|
|
422
|
+
* (components/tokens/icons/docs) rather than merged into a single ranked list — each tool ranks its
|
|
423
|
+
* own domain, and re-ranking across domains would mean duplicating ranking logic here (breaking the
|
|
424
|
+
* zero-drift contract with `@atlaskit/ads-mcp`).
|
|
405
425
|
*/
|
|
406
426
|
var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
|
|
407
427
|
var terms = input.positionals;
|
|
@@ -433,25 +453,40 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
|
|
|
433
453
|
key: 'icons'
|
|
434
454
|
}, searchKindTools.icons), {}, {
|
|
435
455
|
args: args
|
|
456
|
+
}), _objectSpread(_objectSpread({
|
|
457
|
+
key: 'docs'
|
|
458
|
+
}, searchKindTools.docs), {}, {
|
|
459
|
+
args: args
|
|
436
460
|
})],
|
|
437
461
|
meta: args
|
|
438
462
|
};
|
|
439
463
|
};
|
|
440
464
|
|
|
441
465
|
/**
|
|
442
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
466
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
443
467
|
*/
|
|
444
468
|
export var commands = [{
|
|
445
469
|
name: 'search',
|
|
446
|
-
description: 'Fuzzy-search ADS components, tokens, and
|
|
470
|
+
description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type).',
|
|
447
471
|
usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
|
|
472
|
+
arguments: [{
|
|
473
|
+
name: 'query',
|
|
474
|
+
type: 'string',
|
|
475
|
+
required: true,
|
|
476
|
+
variadic: true,
|
|
477
|
+
description: 'One or more terms to search for.'
|
|
478
|
+
}],
|
|
448
479
|
flags: [{
|
|
449
480
|
name: 'type',
|
|
450
481
|
type: 'string',
|
|
451
482
|
alias: 't',
|
|
483
|
+
choices: Object.keys(SEARCH_TYPE_VALUES),
|
|
452
484
|
description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
|
|
453
485
|
}, limitFlag],
|
|
454
|
-
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
|
|
486
|
+
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5', 'search contrast --type docs'],
|
|
487
|
+
responseTypes: ['ads-cli/search'].concat(_toConsumableArray(Object.values(searchKindTools).map(function (tool) {
|
|
488
|
+
return "ads-cli/".concat(tool.envelopeType);
|
|
489
|
+
}))),
|
|
455
490
|
// With `--type`, the result is a single kind (compact per-row rendering). Without it, the
|
|
456
491
|
// result is grouped across all kinds, so there is no single result kind — the grouped
|
|
457
492
|
// formatter handles rendering instead.
|
|
@@ -459,12 +494,20 @@ export var commands = [{
|
|
|
459
494
|
var _resolveSearchType;
|
|
460
495
|
return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
|
|
461
496
|
},
|
|
497
|
+
transform: function transform(_ref5) {
|
|
498
|
+
var data = _ref5.data,
|
|
499
|
+
input = _ref5.input;
|
|
500
|
+
return resolveSearchType(input.flags) === 'docs' ? createDocSearchResults({
|
|
501
|
+
data: data,
|
|
502
|
+
query: input.positionals.join(' ')
|
|
503
|
+
}) : data;
|
|
504
|
+
},
|
|
462
505
|
envelopeType: function envelopeType(input) {
|
|
463
506
|
var searchType = resolveSearchType(input.flags);
|
|
464
507
|
return searchType ? searchKindTools[searchType].envelopeType : 'search';
|
|
465
508
|
},
|
|
466
509
|
resolve: function resolve(input) {
|
|
467
|
-
// No `--type`: unified search across all three kinds.
|
|
510
|
+
// No `--type`: unified search across all three entity kinds and foundations docs.
|
|
468
511
|
if (input.flags.type === undefined) {
|
|
469
512
|
return resolveUnifiedSearch(input);
|
|
470
513
|
}
|
|
@@ -498,8 +541,16 @@ export var commands = [{
|
|
|
498
541
|
name: 'lint-rules',
|
|
499
542
|
description: 'Get ADS ESLint lint rules, optionally filtered by term.',
|
|
500
543
|
usage: 'lint-rules [term...] [--limit N]',
|
|
544
|
+
arguments: [{
|
|
545
|
+
name: 'term',
|
|
546
|
+
type: 'string',
|
|
547
|
+
required: false,
|
|
548
|
+
variadic: true,
|
|
549
|
+
description: 'Terms used to filter lint rules.'
|
|
550
|
+
}],
|
|
501
551
|
flags: [limitFlag],
|
|
502
552
|
examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
|
|
553
|
+
responseTypes: ['ads-cli/lint-rules'],
|
|
503
554
|
envelopeType: function envelopeType() {
|
|
504
555
|
return 'lint-rules';
|
|
505
556
|
},
|
|
@@ -512,9 +563,9 @@ export var commands = [{
|
|
|
512
563
|
// shows that rule's docs, but several matches with no exact name surface a disambiguation
|
|
513
564
|
// list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
|
|
514
565
|
// intentionally returns every rule's content).
|
|
515
|
-
transform: function transform(
|
|
516
|
-
var data =
|
|
517
|
-
input =
|
|
566
|
+
transform: function transform(_ref6) {
|
|
567
|
+
var data = _ref6.data,
|
|
568
|
+
input = _ref6.input;
|
|
518
569
|
var terms = input.positionals;
|
|
519
570
|
if (terms.length === 0) {
|
|
520
571
|
return data;
|
|
@@ -592,10 +643,18 @@ export var commands = [{
|
|
|
592
643
|
name: 'docs',
|
|
593
644
|
description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
|
|
594
645
|
usage: "docs <topic...> | docs a11y [".concat(A11Y_TOPICS.join('|'), "] | docs migration <").concat(MIGRATION_IDS.join('|'), ">"),
|
|
646
|
+
arguments: [{
|
|
647
|
+
name: 'topic',
|
|
648
|
+
type: 'string',
|
|
649
|
+
required: false,
|
|
650
|
+
variadic: true,
|
|
651
|
+
description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
|
|
652
|
+
}],
|
|
595
653
|
// No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
|
|
596
654
|
// guide, or a migration guide), so there is nothing to limit.
|
|
597
655
|
flags: [],
|
|
598
656
|
examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
|
|
657
|
+
responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
|
|
599
658
|
envelopeType: function envelopeType(input) {
|
|
600
659
|
var namespace = input.positionals[0];
|
|
601
660
|
if (namespace === 'a11y') {
|
|
@@ -705,4 +764,24 @@ export var commands = [{
|
|
|
705
764
|
meta: args
|
|
706
765
|
});
|
|
707
766
|
}
|
|
767
|
+
}, {
|
|
768
|
+
name: 'manifest',
|
|
769
|
+
description: 'Describe every CLI command, argument, flag, and JSON response type.',
|
|
770
|
+
usage: 'manifest',
|
|
771
|
+
arguments: [],
|
|
772
|
+
flags: [],
|
|
773
|
+
examples: ['manifest --json'],
|
|
774
|
+
responseTypes: ['ads-cli/manifest'],
|
|
775
|
+
envelopeType: function envelopeType() {
|
|
776
|
+
return 'manifest';
|
|
777
|
+
},
|
|
778
|
+
formatHuman: formatManifest,
|
|
779
|
+
resolve: function resolve() {
|
|
780
|
+
return {
|
|
781
|
+
data: buildManifest(commands, getVersion()),
|
|
782
|
+
meta: {
|
|
783
|
+
schemaVersion: 1
|
|
784
|
+
}
|
|
785
|
+
};
|
|
786
|
+
}
|
|
708
787
|
}];
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve the CLI version from package.json.
|
|
3
|
+
*
|
|
4
|
+
* A failed package lookup must not prevent the CLI from running, so fall back to the development
|
|
5
|
+
* version used by the package source.
|
|
6
|
+
*/
|
|
7
|
+
export var getVersion = function getVersion() {
|
|
8
|
+
try {
|
|
9
|
+
var _pkgJson$version;
|
|
10
|
+
// Read our own package.json at runtime via the package-name subpath. This is depth-independent,
|
|
11
|
+
// so it resolves in both the source layout and the published build.
|
|
12
|
+
// 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
|
|
13
|
+
var pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
14
|
+
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
15
|
+
} catch (_unused) {
|
|
16
|
+
return '0.0.0';
|
|
17
|
+
}
|
|
18
|
+
};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import _defineProperty from "@babel/runtime/helpers/defineProperty";
|
|
2
|
+
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; }
|
|
3
|
+
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; }
|
|
4
|
+
/**
|
|
5
|
+
* A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
|
|
6
|
+
*
|
|
7
|
+
* Search only surfaces this summary. The `docs` command remains the detail view for the full
|
|
8
|
+
* Markdown content.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Truncate a one-line description so compact rows stay on a single line.
|
|
13
|
+
*/
|
|
14
|
+
var truncate = function truncate(text, max) {
|
|
15
|
+
return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Remove common Markdown formatting before showing documentation content in one row.
|
|
20
|
+
*/
|
|
21
|
+
var toPlainText = function toPlainText(text) {
|
|
22
|
+
return text.replace(/!\[[^\]]*]\([^)]*\)/g, '').replace(/\[([^\]]+)]\([^)]*\)/g, '$1').replace(/^\s{0,3}#{1,6}\s+/gm, '').replace(/<[^>]+>/g, ' ').replace(/[*_`~]/g, '').replace(/\s+/g, ' ').trim();
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Turn a full foundations-doc Markdown match into the concise record used by `search`.
|
|
27
|
+
*
|
|
28
|
+
* `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
|
|
29
|
+
* highest-ranked match is represented by the query and a preview of its leading textual content;
|
|
30
|
+
* the full payload remains available through the follow-up `docs <query>` command.
|
|
31
|
+
*/
|
|
32
|
+
export var createDocSearchResults = function createDocSearchResults(_ref) {
|
|
33
|
+
var data = _ref.data,
|
|
34
|
+
query = _ref.query;
|
|
35
|
+
if (typeof data !== 'string' || data.trim() === '') {
|
|
36
|
+
return [];
|
|
37
|
+
}
|
|
38
|
+
var normalizedQuery = query.replace(/\s+/g, ' ').trim();
|
|
39
|
+
var title = normalizedQuery ? "".concat(normalizedQuery.charAt(0).toUpperCase()).concat(normalizedQuery.slice(1)) : 'Documentation';
|
|
40
|
+
var preview = toPlainText(data);
|
|
41
|
+
return [_objectSpread(_objectSpread({
|
|
42
|
+
title: truncate(title, 80)
|
|
43
|
+
}, preview ? {
|
|
44
|
+
summary: truncate(preview, 100)
|
|
45
|
+
} : {}), {}, {
|
|
46
|
+
followUp: "docs ".concat(query)
|
|
47
|
+
})];
|
|
48
|
+
};
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Sectioned compact renderer for grouped (multi-kind) results, e.g. unified `search`.
|
|
3
3
|
*
|
|
4
|
-
* Prints
|
|
5
|
-
*
|
|
6
|
-
* kind.
|
|
4
|
+
* Prints Components, Tokens, Icons, and Docs sections using the per-kind compact renderer. Empty
|
|
5
|
+
* groups are skipped, so one command surfaces whatever kinds match, grouped by kind.
|
|
7
6
|
*/
|
|
8
7
|
|
|
9
8
|
import { formatCompactResults } from './format-results';
|
|
@@ -24,6 +23,9 @@ export var formatGroupedResults = function formatGroupedResults(_ref) {
|
|
|
24
23
|
}, {
|
|
25
24
|
kind: 'icons',
|
|
26
25
|
title: 'Icons'
|
|
26
|
+
}, {
|
|
27
|
+
kind: 'docs',
|
|
28
|
+
title: 'Docs'
|
|
27
29
|
}];
|
|
28
30
|
var blocks = ["Results (".concat(totalCount, "):")];
|
|
29
31
|
for (var _i = 0, _sections = sections; _i < _sections.length; _i++) {
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import _typeof from "@babel/runtime/helpers/typeof";
|
|
2
|
+
/**
|
|
3
|
+
* Format a scannable human catalog of the ADS CLI capability manifest.
|
|
4
|
+
*/
|
|
5
|
+
export var formatManifest = function formatManifest(data) {
|
|
6
|
+
if (_typeof(data) !== 'object' || data === null || !('bin' in data) || typeof data.bin !== 'string' || !('version' in data) || typeof data.version !== 'string' || !('invocation' in data) || typeof data.invocation !== 'string' || !('commands' in data) || !Array.isArray(data.commands)) {
|
|
7
|
+
return null;
|
|
8
|
+
}
|
|
9
|
+
var commands = data.commands.flatMap(function (command) {
|
|
10
|
+
if (_typeof(command) !== 'object' || command === null || !('name' in command) || typeof command.name !== 'string' || !('description' in command) || typeof command.description !== 'string') {
|
|
11
|
+
return [];
|
|
12
|
+
}
|
|
13
|
+
var jsonFlag = 'jsonSupported' in command && command.jsonSupported === true ? ' [--json]' : '';
|
|
14
|
+
return [" ".concat(command.name).concat(jsonFlag, "\n ").concat(command.description)];
|
|
15
|
+
});
|
|
16
|
+
var commandCount = commands.length;
|
|
17
|
+
var commandLabel = commandCount === 1 ? 'command' : 'commands';
|
|
18
|
+
return ["".concat(data.bin, " v").concat(data.version, " \u2014 ").concat(commandCount, " ").concat(commandLabel), '', commands.join('\n'), '', "Run `".concat(data.invocation, " manifest --json` for the full structured manifest.")].join('\n');
|
|
19
|
+
};
|
|
@@ -48,9 +48,8 @@ var truncate = function truncate(text) {
|
|
|
48
48
|
/**
|
|
49
49
|
* Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
|
|
50
50
|
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
* for the whole list, so echoing each row's own name back would just be noise.
|
|
51
|
+
* Used for every `search` result, where the natural next step is to view that match in full.
|
|
52
|
+
* `--all` listings omit it because echoing every row's own name would just be noise.
|
|
54
53
|
*/
|
|
55
54
|
var withFollowUp = function withFollowUp(_ref) {
|
|
56
55
|
var line = _ref.line,
|
|
@@ -115,13 +114,21 @@ var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
|
|
|
115
114
|
});
|
|
116
115
|
};
|
|
117
116
|
|
|
117
|
+
/**
|
|
118
|
+
* Render one foundations-document match without dumping its full Markdown body.
|
|
119
|
+
*/
|
|
120
|
+
var formatDocLine = function formatDocLine(doc, showFollowUp) {
|
|
121
|
+
var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
|
|
122
|
+
var line = "".concat(doc.title).concat(summary);
|
|
123
|
+
return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(doc.followUp) : line;
|
|
124
|
+
};
|
|
125
|
+
|
|
118
126
|
/**
|
|
119
127
|
* Render an array of results as compact lines for the given kind. Returns `null` when the data
|
|
120
128
|
* is not an array (so the caller can fall back to generic JSON rendering).
|
|
121
129
|
*
|
|
122
130
|
* `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
|
|
123
|
-
* row.
|
|
124
|
-
* off so the output stays terse.
|
|
131
|
+
* row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
|
|
125
132
|
*/
|
|
126
133
|
export var formatCompactResults = function formatCompactResults(_ref2) {
|
|
127
134
|
var kind = _ref2.kind,
|
|
@@ -142,6 +149,8 @@ export var formatCompactResults = function formatCompactResults(_ref2) {
|
|
|
142
149
|
return formatTokenLine(entry, showFollowUp);
|
|
143
150
|
case 'icons':
|
|
144
151
|
return formatIconLine(entry, showFollowUp);
|
|
152
|
+
case 'docs':
|
|
153
|
+
return formatDocLine(entry, showFollowUp);
|
|
145
154
|
default:
|
|
146
155
|
return JSON.stringify(entry);
|
|
147
156
|
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Build machine-readable metadata for the ADS CLI.
|
|
3
|
+
*
|
|
4
|
+
* The manifest is projected from the same command definitions used for dispatch and help, so it
|
|
5
|
+
* does not duplicate the runnable command surface.
|
|
6
|
+
*/
|
|
7
|
+
import { CLI_BIN_NAME, CLI_NAME } from './cli-metadata';
|
|
8
|
+
import type { CommandDefinition, CommandFlag } from './types';
|
|
9
|
+
export type ManifestCommand = Pick<CommandDefinition, 'name' | 'description' | 'usage' | 'arguments' | 'flags' | 'examples' | 'responseTypes'> & {
|
|
10
|
+
jsonSupported: true;
|
|
11
|
+
};
|
|
12
|
+
export type Manifest = {
|
|
13
|
+
schemaVersion: 1;
|
|
14
|
+
name: typeof CLI_NAME;
|
|
15
|
+
bin: typeof CLI_BIN_NAME;
|
|
16
|
+
version: string;
|
|
17
|
+
description: string;
|
|
18
|
+
invocation: string;
|
|
19
|
+
commands: ManifestCommand[];
|
|
20
|
+
globalFlags: CommandFlag[];
|
|
21
|
+
errorResponseType: 'ads-cli/error';
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Build a serializable capability manifest from the live command registry.
|
|
25
|
+
*/
|
|
26
|
+
export declare const buildManifest: (commands: CommandDefinition[], version: string) => Manifest;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared top-level ADS CLI metadata used by help and the capability manifest.
|
|
3
|
+
*/
|
|
4
|
+
import type { CommandFlag } from './types';
|
|
5
|
+
export declare const CLI_NAME = "@atlaskit/ads-cli";
|
|
6
|
+
export declare const CLI_BIN_NAME = "ads-cli";
|
|
7
|
+
export declare const CLI_DESCRIPTION = "Query Atlassian Design System (ADS) structured content \u2014 components, tokens, icons, and guidelines \u2014 from the terminal.";
|
|
8
|
+
export declare const globalFlags: CommandFlag[];
|