@atlaskit/ads-cli 0.1.0 → 0.2.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 +7 -0
- package/README.md +7 -0
- package/dist/cjs/cli.js +8 -26
- package/dist/cjs/commands/build-manifest.js +48 -0
- package/dist/cjs/commands/cli-metadata.js +31 -0
- package/dist/cjs/commands/definitions.js +63 -3
- package/dist/cjs/commands/get-version.js +24 -0
- package/dist/cjs/output/format-manifest.js +26 -0
- package/dist/es2019/cli.js +7 -25
- package/dist/es2019/commands/build-manifest.js +39 -0
- package/dist/es2019/commands/cli-metadata.js +25 -0
- package/dist/es2019/commands/definitions.js +56 -3
- package/dist/es2019/commands/get-version.js +18 -0
- package/dist/es2019/output/format-manifest.js +18 -0
- package/dist/esm/cli.js +7 -25
- package/dist/esm/commands/build-manifest.js +42 -0
- package/dist/esm/commands/cli-metadata.js +25 -0
- package/dist/esm/commands/definitions.js +63 -3
- package/dist/esm/commands/get-version.js +18 -0
- package/dist/esm/output/format-manifest.js +19 -0
- 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 +25 -5
- package/dist/types/output/format-manifest.d.ts +4 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @atlaskit/ads-cli
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [`f37252516ee5d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f37252516ee5d) -
|
|
8
|
+
Add a `manifest` command for discovering ADS CLI commands in human-readable or JSON format.
|
|
9
|
+
|
|
3
10
|
## 0.1.0
|
|
4
11
|
|
|
5
12
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -29,6 +29,7 @@ The CLI has these commands:
|
|
|
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
|
|
|
@@ -60,6 +61,9 @@ npx @atlaskit/ads-cli docs migration motion
|
|
|
60
61
|
|
|
61
62
|
# Machine-readable envelope for agents / jq
|
|
62
63
|
npx @atlaskit/ads-cli search button --json
|
|
64
|
+
|
|
65
|
+
# Discover the complete CLI contract
|
|
66
|
+
npx @atlaskit/ads-cli manifest --json
|
|
63
67
|
```
|
|
64
68
|
|
|
65
69
|
## Output contract
|
|
@@ -79,6 +83,9 @@ npx @atlaskit/ads-cli search button --json
|
|
|
79
83
|
`{ "ambiguous": true, "query", "noun", "candidates": [...] }`.
|
|
80
84
|
- **Data is written to stdout only.** Logs, hints, and errors go to **stderr**. This keeps `--json`
|
|
81
85
|
output clean for piping.
|
|
86
|
+
- **The manifest is derived from the live command registry.** `manifest --json` lists every command,
|
|
87
|
+
positional argument, flag, example, and success response type without maintaining a separate copy
|
|
88
|
+
of the CLI surface.
|
|
82
89
|
- With `--json`, every success prints a `SuccessEnvelope` and every failure prints an
|
|
83
90
|
`ErrorEnvelope`:
|
|
84
91
|
|
package/dist/cjs/cli.js
CHANGED
|
@@ -8,8 +8,10 @@ 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");
|
|
@@ -36,30 +38,6 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
|
|
|
36
38
|
* It never reimplements search ranking or bundles a dataset copy — all query logic lives in
|
|
37
39
|
* `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
|
|
38
40
|
*/
|
|
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
41
|
/**
|
|
64
42
|
* Build the top-level help text from the command registry so it can never drift from the
|
|
65
43
|
* runnable surface.
|
|
@@ -80,7 +58,11 @@ var buildHelpText = function buildHelpText() {
|
|
|
80
58
|
}).join('\n');
|
|
81
59
|
return "".concat(usageLines, "\n ").concat(command.description);
|
|
82
60
|
}).join('\n');
|
|
83
|
-
|
|
61
|
+
var globalFlagLines = _cliMetadata.globalFlags.map(function (flag) {
|
|
62
|
+
var aliases = flag.alias ? ", -".concat(flag.alias) : '';
|
|
63
|
+
return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
|
|
64
|
+
}).join('\n');
|
|
65
|
+
return [_cliMetadata.CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search button # unified: components, tokens & icons', ' $ npx @atlaskit/ads-cli search button --type component', ' $ 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
66
|
};
|
|
85
67
|
|
|
86
68
|
/**
|
|
@@ -409,7 +391,7 @@ var run = exports.run = /*#__PURE__*/function () {
|
|
|
409
391
|
_context3.next = 1;
|
|
410
392
|
break;
|
|
411
393
|
}
|
|
412
|
-
writer.out(getVersion());
|
|
394
|
+
writer.out((0, _getVersion.getVersion)());
|
|
413
395
|
return _context3.abrupt("return", _types.ExitCode.Ok);
|
|
414
396
|
case 1:
|
|
415
397
|
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,6 +7,7 @@ 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");
|
|
@@ -16,20 +17,24 @@ var _formatDisambiguation = require("../output/format-disambiguation");
|
|
|
16
17
|
var _formatDocObject = require("../output/format-doc-object");
|
|
17
18
|
var _formatIcon = require("../output/format-icon");
|
|
18
19
|
var _formatLintRules = require("../output/format-lint-rules");
|
|
20
|
+
var _formatManifest = require("../output/format-manifest");
|
|
19
21
|
var _formatToken = require("../output/format-token");
|
|
20
22
|
var _parseLintRuleRecords = require("../output/parse-lint-rule-records");
|
|
23
|
+
var _buildManifest = require("./build-manifest");
|
|
24
|
+
var _getVersion = require("./get-version");
|
|
21
25
|
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
26
|
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
27
|
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
28
|
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
25
29
|
*
|
|
26
|
-
*
|
|
30
|
+
* Command dispatch, top-level `--help`, and the self-describing manifest are derived
|
|
27
31
|
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
28
32
|
* to drift apart. Each entry declares:
|
|
29
33
|
*
|
|
30
34
|
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
31
35
|
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
32
|
-
* - the metadata (
|
|
36
|
+
* - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
|
|
37
|
+
* `--help`.
|
|
33
38
|
*
|
|
34
39
|
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
35
40
|
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
@@ -217,6 +222,7 @@ var resolveSearch = function resolveSearch(_ref2) {
|
|
|
217
222
|
var allFlag = {
|
|
218
223
|
name: 'all',
|
|
219
224
|
type: 'boolean',
|
|
225
|
+
default: false,
|
|
220
226
|
description: 'List every entry of this kind instead of looking up a single name.'
|
|
221
227
|
};
|
|
222
228
|
|
|
@@ -311,8 +317,15 @@ var makeItemCommand = function makeItemCommand(_ref3) {
|
|
|
311
317
|
name: name,
|
|
312
318
|
description: "Get details for a single ADS ".concat(name, ", or list all with --all."),
|
|
313
319
|
usage: "".concat(name, " <name> | ").concat(name, " --all"),
|
|
320
|
+
arguments: [{
|
|
321
|
+
name: 'name',
|
|
322
|
+
type: 'string',
|
|
323
|
+
required: false,
|
|
324
|
+
description: "Exact or fuzzy ADS ".concat(name, " name. Omit when using --all.")
|
|
325
|
+
}],
|
|
314
326
|
flags: [allFlag],
|
|
315
327
|
examples: ["".concat(name, " ").concat(EXAMPLE_NAME[kind]), "".concat(name, " --all")],
|
|
328
|
+
responseTypes: ["ads-cli/".concat(name), "ads-cli/".concat(listTool.envelopeType)],
|
|
316
329
|
// `--all` returns an array → render it as the compact per-row list for this kind. A single
|
|
317
330
|
// `<name>` lookup is post-processed by `transform` into either one detail object or a
|
|
318
331
|
// disambiguation marker, both handled by `formatHuman`.
|
|
@@ -444,19 +457,30 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
|
|
|
444
457
|
};
|
|
445
458
|
|
|
446
459
|
/**
|
|
447
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
460
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
448
461
|
*/
|
|
449
462
|
var commands = exports.commands = [{
|
|
450
463
|
name: 'search',
|
|
451
464
|
description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
|
|
452
465
|
usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
|
|
466
|
+
arguments: [{
|
|
467
|
+
name: 'query',
|
|
468
|
+
type: 'string',
|
|
469
|
+
required: true,
|
|
470
|
+
variadic: true,
|
|
471
|
+
description: 'One or more terms to search for.'
|
|
472
|
+
}],
|
|
453
473
|
flags: [{
|
|
454
474
|
name: 'type',
|
|
455
475
|
type: 'string',
|
|
456
476
|
alias: 't',
|
|
477
|
+
choices: Object.keys(SEARCH_TYPE_VALUES),
|
|
457
478
|
description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
|
|
458
479
|
}, limitFlag],
|
|
459
480
|
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
|
|
481
|
+
responseTypes: ['ads-cli/search'].concat((0, _toConsumableArray2.default)(Object.values(searchKindTools).map(function (tool) {
|
|
482
|
+
return "ads-cli/".concat(tool.envelopeType);
|
|
483
|
+
}))),
|
|
460
484
|
// With `--type`, the result is a single kind (compact per-row rendering). Without it, the
|
|
461
485
|
// result is grouped across all kinds, so there is no single result kind — the grouped
|
|
462
486
|
// formatter handles rendering instead.
|
|
@@ -503,8 +527,16 @@ var commands = exports.commands = [{
|
|
|
503
527
|
name: 'lint-rules',
|
|
504
528
|
description: 'Get ADS ESLint lint rules, optionally filtered by term.',
|
|
505
529
|
usage: 'lint-rules [term...] [--limit N]',
|
|
530
|
+
arguments: [{
|
|
531
|
+
name: 'term',
|
|
532
|
+
type: 'string',
|
|
533
|
+
required: false,
|
|
534
|
+
variadic: true,
|
|
535
|
+
description: 'Terms used to filter lint rules.'
|
|
536
|
+
}],
|
|
506
537
|
flags: [limitFlag],
|
|
507
538
|
examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
|
|
539
|
+
responseTypes: ['ads-cli/lint-rules'],
|
|
508
540
|
envelopeType: function envelopeType() {
|
|
509
541
|
return 'lint-rules';
|
|
510
542
|
},
|
|
@@ -597,10 +629,18 @@ var commands = exports.commands = [{
|
|
|
597
629
|
name: 'docs',
|
|
598
630
|
description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
|
|
599
631
|
usage: "docs <topic...> | docs a11y [".concat(A11Y_TOPICS.join('|'), "] | docs migration <").concat(MIGRATION_IDS.join('|'), ">"),
|
|
632
|
+
arguments: [{
|
|
633
|
+
name: 'topic',
|
|
634
|
+
type: 'string',
|
|
635
|
+
required: false,
|
|
636
|
+
variadic: true,
|
|
637
|
+
description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
|
|
638
|
+
}],
|
|
600
639
|
// No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
|
|
601
640
|
// guide, or a migration guide), so there is nothing to limit.
|
|
602
641
|
flags: [],
|
|
603
642
|
examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
|
|
643
|
+
responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
|
|
604
644
|
envelopeType: function envelopeType(input) {
|
|
605
645
|
var namespace = input.positionals[0];
|
|
606
646
|
if (namespace === 'a11y') {
|
|
@@ -710,4 +750,24 @@ var commands = exports.commands = [{
|
|
|
710
750
|
meta: args
|
|
711
751
|
});
|
|
712
752
|
}
|
|
753
|
+
}, {
|
|
754
|
+
name: 'manifest',
|
|
755
|
+
description: 'Describe every CLI command, argument, flag, and JSON response type.',
|
|
756
|
+
usage: 'manifest',
|
|
757
|
+
arguments: [],
|
|
758
|
+
flags: [],
|
|
759
|
+
examples: ['manifest --json'],
|
|
760
|
+
responseTypes: ['ads-cli/manifest'],
|
|
761
|
+
envelopeType: function envelopeType() {
|
|
762
|
+
return 'manifest';
|
|
763
|
+
},
|
|
764
|
+
formatHuman: _formatManifest.formatManifest,
|
|
765
|
+
resolve: function resolve() {
|
|
766
|
+
return {
|
|
767
|
+
data: (0, _buildManifest.buildManifest)(commands, (0, _getVersion.getVersion)()),
|
|
768
|
+
meta: {
|
|
769
|
+
schemaVersion: 1
|
|
770
|
+
}
|
|
771
|
+
};
|
|
772
|
+
}
|
|
713
773
|
}];
|
|
@@ -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,26 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
|
|
4
|
+
Object.defineProperty(exports, "__esModule", {
|
|
5
|
+
value: true
|
|
6
|
+
});
|
|
7
|
+
exports.formatManifest = void 0;
|
|
8
|
+
var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
|
|
9
|
+
/**
|
|
10
|
+
* Format a scannable human catalog of the ADS CLI capability manifest.
|
|
11
|
+
*/
|
|
12
|
+
var formatManifest = exports.formatManifest = function formatManifest(data) {
|
|
13
|
+
if ((0, _typeof2.default)(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)) {
|
|
14
|
+
return null;
|
|
15
|
+
}
|
|
16
|
+
var commands = data.commands.flatMap(function (command) {
|
|
17
|
+
if ((0, _typeof2.default)(command) !== 'object' || command === null || !('name' in command) || typeof command.name !== 'string' || !('description' in command) || typeof command.description !== 'string') {
|
|
18
|
+
return [];
|
|
19
|
+
}
|
|
20
|
+
var jsonFlag = 'jsonSupported' in command && command.jsonSupported === true ? ' [--json]' : '';
|
|
21
|
+
return [" ".concat(command.name).concat(jsonFlag, "\n ").concat(command.description)];
|
|
22
|
+
});
|
|
23
|
+
var commandCount = commands.length;
|
|
24
|
+
var commandLabel = commandCount === 1 ? 'command' : 'commands';
|
|
25
|
+
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');
|
|
26
|
+
};
|
package/dist/es2019/cli.js
CHANGED
|
@@ -9,8 +9,10 @@
|
|
|
9
9
|
* `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
+
import { CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
|
|
12
13
|
import { commands } from './commands/definitions';
|
|
13
14
|
import { getCommand } from './commands/get-command';
|
|
15
|
+
import { getVersion } from './commands/get-version';
|
|
14
16
|
import { importToolHandler } from './commands/import-tool-handler';
|
|
15
17
|
import { runTool } from './commands/run-tool';
|
|
16
18
|
import { createErrorEnvelope } from './envelope/create-error-envelope';
|
|
@@ -24,30 +26,6 @@ import { defaultWriter } from './output/writer';
|
|
|
24
26
|
import { parseArgs } from './parse-args';
|
|
25
27
|
import { ExitCode } from './types';
|
|
26
28
|
|
|
27
|
-
/**
|
|
28
|
-
* Resolve the CLI version from package.json. Kept in a function so a failure to read it never
|
|
29
|
-
* crashes the CLI (it falls back to `0.0.0`).
|
|
30
|
-
*/
|
|
31
|
-
const getVersion = () => {
|
|
32
|
-
try {
|
|
33
|
-
var _pkgJson$version;
|
|
34
|
-
// Read our own package.json at runtime via the package-name subpath. This mirrors
|
|
35
|
-
// the sibling `@atlaskit/ads-mcp` package and is depth-independent, so it resolves
|
|
36
|
-
// correctly in both the in-repo source layout (`src/cli`) and the published build
|
|
37
|
-
// (`dist/cjs/cli`). Requires the `./package.json` subpath in this package's exports.
|
|
38
|
-
// 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
|
|
39
|
-
const pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
40
|
-
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
41
|
-
} catch {
|
|
42
|
-
return '0.0.0';
|
|
43
|
-
}
|
|
44
|
-
};
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* One-line description of the CLI, shown at the top of `--help`.
|
|
48
|
-
*/
|
|
49
|
-
const CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
50
|
-
|
|
51
29
|
/**
|
|
52
30
|
* Build the top-level help text from the command registry so it can never drift from the
|
|
53
31
|
* runnable surface.
|
|
@@ -66,7 +44,11 @@ const buildHelpText = () => {
|
|
|
66
44
|
const usageLines = command.usage.split(' | ').map((part, index) => index === 0 ? ` ${part}` : ` | ${part}`).join('\n');
|
|
67
45
|
return `${usageLines}\n ${command.description}`;
|
|
68
46
|
}).join('\n');
|
|
69
|
-
|
|
47
|
+
const globalFlagLines = globalFlags.map(flag => {
|
|
48
|
+
const aliases = flag.alias ? `, -${flag.alias}` : '';
|
|
49
|
+
return ` --${flag.name}${aliases}`.padEnd(18) + flag.description;
|
|
50
|
+
}).join('\n');
|
|
51
|
+
return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search button # unified: components, tokens & icons', ' $ npx @atlaskit/ads-cli search button --type component', ' $ 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');
|
|
70
52
|
};
|
|
71
53
|
|
|
72
54
|
/**
|
|
@@ -0,0 +1,39 @@
|
|
|
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 const buildManifest = (commands, version) => ({
|
|
13
|
+
schemaVersion: 1,
|
|
14
|
+
name: CLI_NAME,
|
|
15
|
+
bin: CLI_BIN_NAME,
|
|
16
|
+
version,
|
|
17
|
+
description: CLI_DESCRIPTION,
|
|
18
|
+
invocation: `npx ${CLI_NAME}`,
|
|
19
|
+
commands: commands.map(({
|
|
20
|
+
name,
|
|
21
|
+
description,
|
|
22
|
+
usage,
|
|
23
|
+
arguments: commandArguments,
|
|
24
|
+
flags,
|
|
25
|
+
examples,
|
|
26
|
+
responseTypes
|
|
27
|
+
}) => ({
|
|
28
|
+
name,
|
|
29
|
+
description,
|
|
30
|
+
usage,
|
|
31
|
+
arguments: commandArguments,
|
|
32
|
+
flags,
|
|
33
|
+
examples,
|
|
34
|
+
jsonSupported: true,
|
|
35
|
+
responseTypes
|
|
36
|
+
})),
|
|
37
|
+
globalFlags,
|
|
38
|
+
errorResponseType: 'ads-cli/error'
|
|
39
|
+
});
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared top-level ADS CLI metadata used by help and the capability manifest.
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
export const CLI_NAME = '@atlaskit/ads-cli';
|
|
6
|
+
export const CLI_BIN_NAME = 'ads-cli';
|
|
7
|
+
export const CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
8
|
+
export const 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,13 +1,14 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
4
|
+
* Command dispatch, top-level `--help`, and the self-describing manifest are derived
|
|
5
5
|
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
6
6
|
* to drift apart. Each entry declares:
|
|
7
7
|
*
|
|
8
8
|
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
9
9
|
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
10
|
-
* - the metadata (
|
|
10
|
+
* - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
|
|
11
|
+
* `--help`.
|
|
11
12
|
*
|
|
12
13
|
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
13
14
|
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
@@ -21,8 +22,11 @@ import { formatDisambiguation } from '../output/format-disambiguation';
|
|
|
21
22
|
import { formatDocObject } from '../output/format-doc-object';
|
|
22
23
|
import { formatIcon } from '../output/format-icon';
|
|
23
24
|
import { formatLintRules } from '../output/format-lint-rules';
|
|
25
|
+
import { formatManifest } from '../output/format-manifest';
|
|
24
26
|
import { formatToken } from '../output/format-token';
|
|
25
27
|
import { parseLintRuleRecords } from '../output/parse-lint-rule-records';
|
|
28
|
+
import { buildManifest } from './build-manifest';
|
|
29
|
+
import { getVersion } from './get-version';
|
|
26
30
|
/**
|
|
27
31
|
* Shared `--limit` flag definition reused across the search-style commands.
|
|
28
32
|
*/
|
|
@@ -203,6 +207,7 @@ const resolveSearch = ({
|
|
|
203
207
|
const allFlag = {
|
|
204
208
|
name: 'all',
|
|
205
209
|
type: 'boolean',
|
|
210
|
+
default: false,
|
|
206
211
|
description: 'List every entry of this kind instead of looking up a single name.'
|
|
207
212
|
};
|
|
208
213
|
|
|
@@ -292,8 +297,15 @@ const makeItemCommand = ({
|
|
|
292
297
|
name,
|
|
293
298
|
description: `Get details for a single ADS ${name}, or list all with --all.`,
|
|
294
299
|
usage: `${name} <name> | ${name} --all`,
|
|
300
|
+
arguments: [{
|
|
301
|
+
name: 'name',
|
|
302
|
+
type: 'string',
|
|
303
|
+
required: false,
|
|
304
|
+
description: `Exact or fuzzy ADS ${name} name. Omit when using --all.`
|
|
305
|
+
}],
|
|
295
306
|
flags: [allFlag],
|
|
296
307
|
examples: [`${name} ${EXAMPLE_NAME[kind]}`, `${name} --all`],
|
|
308
|
+
responseTypes: [`ads-cli/${name}`, `ads-cli/${listTool.envelopeType}`],
|
|
297
309
|
// `--all` returns an array → render it as the compact per-row list for this kind. A single
|
|
298
310
|
// `<name>` lookup is post-processed by `transform` into either one detail object or a
|
|
299
311
|
// disambiguation marker, both handled by `formatHuman`.
|
|
@@ -421,19 +433,28 @@ const resolveUnifiedSearch = input => {
|
|
|
421
433
|
};
|
|
422
434
|
|
|
423
435
|
/**
|
|
424
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
436
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
425
437
|
*/
|
|
426
438
|
export const commands = [{
|
|
427
439
|
name: 'search',
|
|
428
440
|
description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
|
|
429
441
|
usage: `search <query...> [--type ${Object.keys(SEARCH_TYPE_VALUES).join('|')}] [--limit N]`,
|
|
442
|
+
arguments: [{
|
|
443
|
+
name: 'query',
|
|
444
|
+
type: 'string',
|
|
445
|
+
required: true,
|
|
446
|
+
variadic: true,
|
|
447
|
+
description: 'One or more terms to search for.'
|
|
448
|
+
}],
|
|
430
449
|
flags: [{
|
|
431
450
|
name: 'type',
|
|
432
451
|
type: 'string',
|
|
433
452
|
alias: 't',
|
|
453
|
+
choices: Object.keys(SEARCH_TYPE_VALUES),
|
|
434
454
|
description: `Narrow the search to a single kind: ${Object.keys(SEARCH_TYPE_VALUES).join(', ')}.`
|
|
435
455
|
}, limitFlag],
|
|
436
456
|
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
|
|
457
|
+
responseTypes: ['ads-cli/search', ...Object.values(searchKindTools).map(tool => `ads-cli/${tool.envelopeType}`)],
|
|
437
458
|
// With `--type`, the result is a single kind (compact per-row rendering). Without it, the
|
|
438
459
|
// result is grouped across all kinds, so there is no single result kind — the grouped
|
|
439
460
|
// formatter handles rendering instead.
|
|
@@ -480,8 +501,16 @@ export const commands = [{
|
|
|
480
501
|
name: 'lint-rules',
|
|
481
502
|
description: 'Get ADS ESLint lint rules, optionally filtered by term.',
|
|
482
503
|
usage: 'lint-rules [term...] [--limit N]',
|
|
504
|
+
arguments: [{
|
|
505
|
+
name: 'term',
|
|
506
|
+
type: 'string',
|
|
507
|
+
required: false,
|
|
508
|
+
variadic: true,
|
|
509
|
+
description: 'Terms used to filter lint rules.'
|
|
510
|
+
}],
|
|
483
511
|
flags: [limitFlag],
|
|
484
512
|
examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
|
|
513
|
+
responseTypes: ['ads-cli/lint-rules'],
|
|
485
514
|
envelopeType: () => 'lint-rules',
|
|
486
515
|
// Ambiguous fuzzy lookup → render the "did you mean?" list; otherwise print each rule's
|
|
487
516
|
// Markdown `content` verbatim rather than JSON.
|
|
@@ -569,10 +598,18 @@ export const commands = [{
|
|
|
569
598
|
name: 'docs',
|
|
570
599
|
description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
|
|
571
600
|
usage: `docs <topic...> | docs a11y [${A11Y_TOPICS.join('|')}] | docs migration <${MIGRATION_IDS.join('|')}>`,
|
|
601
|
+
arguments: [{
|
|
602
|
+
name: 'topic',
|
|
603
|
+
type: 'string',
|
|
604
|
+
required: false,
|
|
605
|
+
variadic: true,
|
|
606
|
+
description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
|
|
607
|
+
}],
|
|
572
608
|
// No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
|
|
573
609
|
// guide, or a migration guide), so there is nothing to limit.
|
|
574
610
|
flags: [],
|
|
575
611
|
examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
|
|
612
|
+
responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
|
|
576
613
|
envelopeType: input => {
|
|
577
614
|
const namespace = input.positionals[0];
|
|
578
615
|
if (namespace === 'a11y') {
|
|
@@ -680,4 +717,20 @@ export const commands = [{
|
|
|
680
717
|
meta: args
|
|
681
718
|
});
|
|
682
719
|
}
|
|
720
|
+
}, {
|
|
721
|
+
name: 'manifest',
|
|
722
|
+
description: 'Describe every CLI command, argument, flag, and JSON response type.',
|
|
723
|
+
usage: 'manifest',
|
|
724
|
+
arguments: [],
|
|
725
|
+
flags: [],
|
|
726
|
+
examples: ['manifest --json'],
|
|
727
|
+
responseTypes: ['ads-cli/manifest'],
|
|
728
|
+
envelopeType: () => 'manifest',
|
|
729
|
+
formatHuman: formatManifest,
|
|
730
|
+
resolve: () => ({
|
|
731
|
+
data: buildManifest(commands, getVersion()),
|
|
732
|
+
meta: {
|
|
733
|
+
schemaVersion: 1
|
|
734
|
+
}
|
|
735
|
+
})
|
|
683
736
|
}];
|
|
@@ -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 const 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
|
+
const 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 {
|
|
16
|
+
return '0.0.0';
|
|
17
|
+
}
|
|
18
|
+
};
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Format a scannable human catalog of the ADS CLI capability manifest.
|
|
3
|
+
*/
|
|
4
|
+
export const formatManifest = data => {
|
|
5
|
+
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)) {
|
|
6
|
+
return null;
|
|
7
|
+
}
|
|
8
|
+
const commands = data.commands.flatMap(command => {
|
|
9
|
+
if (typeof command !== 'object' || command === null || !('name' in command) || typeof command.name !== 'string' || !('description' in command) || typeof command.description !== 'string') {
|
|
10
|
+
return [];
|
|
11
|
+
}
|
|
12
|
+
const jsonFlag = 'jsonSupported' in command && command.jsonSupported === true ? ' [--json]' : '';
|
|
13
|
+
return [` ${command.name}${jsonFlag}\n ${command.description}`];
|
|
14
|
+
});
|
|
15
|
+
const commandCount = commands.length;
|
|
16
|
+
const commandLabel = commandCount === 1 ? 'command' : 'commands';
|
|
17
|
+
return [`${data.bin} v${data.version} — ${commandCount} ${commandLabel}`, '', commands.join('\n'), '', `Run \`${data.invocation} manifest --json\` for the full structured manifest.`].join('\n');
|
|
18
|
+
};
|
package/dist/esm/cli.js
CHANGED
|
@@ -17,8 +17,10 @@ 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';
|
|
@@ -32,30 +34,6 @@ import { defaultWriter } from './output/writer';
|
|
|
32
34
|
import { parseArgs } from './parse-args';
|
|
33
35
|
import { ExitCode } from './types';
|
|
34
36
|
|
|
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
37
|
/**
|
|
60
38
|
* Build the top-level help text from the command registry so it can never drift from the
|
|
61
39
|
* runnable surface.
|
|
@@ -76,7 +54,11 @@ var buildHelpText = function buildHelpText() {
|
|
|
76
54
|
}).join('\n');
|
|
77
55
|
return "".concat(usageLines, "\n ").concat(command.description);
|
|
78
56
|
}).join('\n');
|
|
79
|
-
|
|
57
|
+
var globalFlagLines = globalFlags.map(function (flag) {
|
|
58
|
+
var aliases = flag.alias ? ", -".concat(flag.alias) : '';
|
|
59
|
+
return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
|
|
60
|
+
}).join('\n');
|
|
61
|
+
return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search button # unified: components, tokens & icons', ' $ npx @atlaskit/ads-cli search button --type component', ' $ 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
62
|
};
|
|
81
63
|
|
|
82
64
|
/**
|
|
@@ -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`.
|
|
@@ -27,8 +29,11 @@ import { formatDisambiguation } from '../output/format-disambiguation';
|
|
|
27
29
|
import { formatDocObject } from '../output/format-doc-object';
|
|
28
30
|
import { formatIcon } from '../output/format-icon';
|
|
29
31
|
import { formatLintRules } from '../output/format-lint-rules';
|
|
32
|
+
import { formatManifest } from '../output/format-manifest';
|
|
30
33
|
import { formatToken } from '../output/format-token';
|
|
31
34
|
import { parseLintRuleRecords } from '../output/parse-lint-rule-records';
|
|
35
|
+
import { buildManifest } from './build-manifest';
|
|
36
|
+
import { getVersion } from './get-version';
|
|
32
37
|
/**
|
|
33
38
|
* Shared `--limit` flag definition reused across the search-style commands.
|
|
34
39
|
*/
|
|
@@ -212,6 +217,7 @@ var resolveSearch = function resolveSearch(_ref2) {
|
|
|
212
217
|
var allFlag = {
|
|
213
218
|
name: 'all',
|
|
214
219
|
type: 'boolean',
|
|
220
|
+
default: false,
|
|
215
221
|
description: 'List every entry of this kind instead of looking up a single name.'
|
|
216
222
|
};
|
|
217
223
|
|
|
@@ -306,8 +312,15 @@ var makeItemCommand = function makeItemCommand(_ref3) {
|
|
|
306
312
|
name: name,
|
|
307
313
|
description: "Get details for a single ADS ".concat(name, ", or list all with --all."),
|
|
308
314
|
usage: "".concat(name, " <name> | ").concat(name, " --all"),
|
|
315
|
+
arguments: [{
|
|
316
|
+
name: 'name',
|
|
317
|
+
type: 'string',
|
|
318
|
+
required: false,
|
|
319
|
+
description: "Exact or fuzzy ADS ".concat(name, " name. Omit when using --all.")
|
|
320
|
+
}],
|
|
309
321
|
flags: [allFlag],
|
|
310
322
|
examples: ["".concat(name, " ").concat(EXAMPLE_NAME[kind]), "".concat(name, " --all")],
|
|
323
|
+
responseTypes: ["ads-cli/".concat(name), "ads-cli/".concat(listTool.envelopeType)],
|
|
311
324
|
// `--all` returns an array → render it as the compact per-row list for this kind. A single
|
|
312
325
|
// `<name>` lookup is post-processed by `transform` into either one detail object or a
|
|
313
326
|
// disambiguation marker, both handled by `formatHuman`.
|
|
@@ -439,19 +452,30 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
|
|
|
439
452
|
};
|
|
440
453
|
|
|
441
454
|
/**
|
|
442
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
455
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
443
456
|
*/
|
|
444
457
|
export var commands = [{
|
|
445
458
|
name: 'search',
|
|
446
459
|
description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
|
|
447
460
|
usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
|
|
461
|
+
arguments: [{
|
|
462
|
+
name: 'query',
|
|
463
|
+
type: 'string',
|
|
464
|
+
required: true,
|
|
465
|
+
variadic: true,
|
|
466
|
+
description: 'One or more terms to search for.'
|
|
467
|
+
}],
|
|
448
468
|
flags: [{
|
|
449
469
|
name: 'type',
|
|
450
470
|
type: 'string',
|
|
451
471
|
alias: 't',
|
|
472
|
+
choices: Object.keys(SEARCH_TYPE_VALUES),
|
|
452
473
|
description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
|
|
453
474
|
}, limitFlag],
|
|
454
475
|
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
|
|
476
|
+
responseTypes: ['ads-cli/search'].concat(_toConsumableArray(Object.values(searchKindTools).map(function (tool) {
|
|
477
|
+
return "ads-cli/".concat(tool.envelopeType);
|
|
478
|
+
}))),
|
|
455
479
|
// With `--type`, the result is a single kind (compact per-row rendering). Without it, the
|
|
456
480
|
// result is grouped across all kinds, so there is no single result kind — the grouped
|
|
457
481
|
// formatter handles rendering instead.
|
|
@@ -498,8 +522,16 @@ export var commands = [{
|
|
|
498
522
|
name: 'lint-rules',
|
|
499
523
|
description: 'Get ADS ESLint lint rules, optionally filtered by term.',
|
|
500
524
|
usage: 'lint-rules [term...] [--limit N]',
|
|
525
|
+
arguments: [{
|
|
526
|
+
name: 'term',
|
|
527
|
+
type: 'string',
|
|
528
|
+
required: false,
|
|
529
|
+
variadic: true,
|
|
530
|
+
description: 'Terms used to filter lint rules.'
|
|
531
|
+
}],
|
|
501
532
|
flags: [limitFlag],
|
|
502
533
|
examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
|
|
534
|
+
responseTypes: ['ads-cli/lint-rules'],
|
|
503
535
|
envelopeType: function envelopeType() {
|
|
504
536
|
return 'lint-rules';
|
|
505
537
|
},
|
|
@@ -592,10 +624,18 @@ export var commands = [{
|
|
|
592
624
|
name: 'docs',
|
|
593
625
|
description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
|
|
594
626
|
usage: "docs <topic...> | docs a11y [".concat(A11Y_TOPICS.join('|'), "] | docs migration <").concat(MIGRATION_IDS.join('|'), ">"),
|
|
627
|
+
arguments: [{
|
|
628
|
+
name: 'topic',
|
|
629
|
+
type: 'string',
|
|
630
|
+
required: false,
|
|
631
|
+
variadic: true,
|
|
632
|
+
description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
|
|
633
|
+
}],
|
|
595
634
|
// No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
|
|
596
635
|
// guide, or a migration guide), so there is nothing to limit.
|
|
597
636
|
flags: [],
|
|
598
637
|
examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
|
|
638
|
+
responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
|
|
599
639
|
envelopeType: function envelopeType(input) {
|
|
600
640
|
var namespace = input.positionals[0];
|
|
601
641
|
if (namespace === 'a11y') {
|
|
@@ -705,4 +745,24 @@ export var commands = [{
|
|
|
705
745
|
meta: args
|
|
706
746
|
});
|
|
707
747
|
}
|
|
748
|
+
}, {
|
|
749
|
+
name: 'manifest',
|
|
750
|
+
description: 'Describe every CLI command, argument, flag, and JSON response type.',
|
|
751
|
+
usage: 'manifest',
|
|
752
|
+
arguments: [],
|
|
753
|
+
flags: [],
|
|
754
|
+
examples: ['manifest --json'],
|
|
755
|
+
responseTypes: ['ads-cli/manifest'],
|
|
756
|
+
envelopeType: function envelopeType() {
|
|
757
|
+
return 'manifest';
|
|
758
|
+
},
|
|
759
|
+
formatHuman: formatManifest,
|
|
760
|
+
resolve: function resolve() {
|
|
761
|
+
return {
|
|
762
|
+
data: buildManifest(commands, getVersion()),
|
|
763
|
+
meta: {
|
|
764
|
+
schemaVersion: 1
|
|
765
|
+
}
|
|
766
|
+
};
|
|
767
|
+
}
|
|
708
768
|
}];
|
|
@@ -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,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
|
+
};
|
|
@@ -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[];
|
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
4
|
+
* Command dispatch, top-level `--help`, and the self-describing manifest are derived
|
|
5
5
|
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
6
6
|
* to drift apart. Each entry declares:
|
|
7
7
|
*
|
|
8
8
|
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
9
9
|
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
10
|
-
* - the metadata (
|
|
10
|
+
* - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
|
|
11
|
+
* `--help`.
|
|
11
12
|
*
|
|
12
13
|
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
13
14
|
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
14
15
|
*/
|
|
15
16
|
import type { CommandDefinition } from './types';
|
|
16
17
|
/**
|
|
17
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
18
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
18
19
|
*/
|
|
19
20
|
export declare const commands: CommandDefinition[];
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Types for the ADS CLI command registry.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* from the single set of {@link CommandDefinition}s, so the runnable
|
|
6
|
-
*
|
|
4
|
+
* Command dispatch, the top-level `--help` text, and the self-describing `manifest` command are
|
|
5
|
+
* derived from the single set of {@link CommandDefinition}s, so the runnable and documented
|
|
6
|
+
* surfaces cannot drift apart.
|
|
7
7
|
*/
|
|
8
8
|
/**
|
|
9
9
|
* Parsed CLI input handed to a command's `resolve` function.
|
|
@@ -19,7 +19,18 @@ export type CommandInput = {
|
|
|
19
19
|
flags: Record<string, unknown>;
|
|
20
20
|
};
|
|
21
21
|
/**
|
|
22
|
-
* A documented
|
|
22
|
+
* A documented positional argument for a command, surfaced by `manifest`.
|
|
23
|
+
*/
|
|
24
|
+
export type CommandArgument = {
|
|
25
|
+
name: string;
|
|
26
|
+
type: 'string';
|
|
27
|
+
description: string;
|
|
28
|
+
required: boolean;
|
|
29
|
+
variadic?: boolean;
|
|
30
|
+
choices?: string[];
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* A documented flag for a command, surfaced by `manifest` and `--help`.
|
|
23
34
|
*/
|
|
24
35
|
export type CommandFlag = {
|
|
25
36
|
name: string;
|
|
@@ -27,6 +38,7 @@ export type CommandFlag = {
|
|
|
27
38
|
description: string;
|
|
28
39
|
alias?: string;
|
|
29
40
|
default?: string | number | boolean;
|
|
41
|
+
choices?: string[];
|
|
30
42
|
};
|
|
31
43
|
/**
|
|
32
44
|
* A single ADS MCP tool invocation. `importPath`/`handlerName` are used to dynamically import
|
|
@@ -99,13 +111,17 @@ export type CommandDefinition = {
|
|
|
99
111
|
*/
|
|
100
112
|
resultKind?: (input: CommandInput) => RowKind | undefined;
|
|
101
113
|
/**
|
|
102
|
-
* One-line summary for `--help`.
|
|
114
|
+
* One-line summary for `manifest` and `--help`.
|
|
103
115
|
*/
|
|
104
116
|
description: string;
|
|
105
117
|
/**
|
|
106
118
|
* Usage string, e.g. `search <query...> [--type components|tokens|icons] [--limit N]`.
|
|
107
119
|
*/
|
|
108
120
|
usage: string;
|
|
121
|
+
/**
|
|
122
|
+
* Structured positional argument metadata for agent discovery.
|
|
123
|
+
*/
|
|
124
|
+
arguments: CommandArgument[];
|
|
109
125
|
/**
|
|
110
126
|
* Documented flags.
|
|
111
127
|
*/
|
|
@@ -114,6 +130,10 @@ export type CommandDefinition = {
|
|
|
114
130
|
* Example invocations.
|
|
115
131
|
*/
|
|
116
132
|
examples: string[];
|
|
133
|
+
/**
|
|
134
|
+
* Full success-envelope `type` discriminators this command can emit with `--json`.
|
|
135
|
+
*/
|
|
136
|
+
responseTypes: string[];
|
|
117
137
|
/**
|
|
118
138
|
* The envelope `type` suffix used for this command's JSON output, e.g. `search-components`
|
|
119
139
|
* produces `type: "ads-cli/search-components"`. May depend on input (e.g. `search --type
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/ads-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "An npx-runnable command-line tool to query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.",
|
|
5
5
|
"author": "Atlassian Pty Ltd",
|
|
6
6
|
"license": "Apache-2.0",
|