@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 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
- return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', ' --json Emit a machine-readable JSON envelope on stdout.', ' --help, -h Show this help.', ' --version, -v Show the CLI version.', '', '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'].join('\n');
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
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
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 (description, flags, examples) surfaced by `--help`.
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
+ };
@@ -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
- return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', ' --json Emit a machine-readable JSON envelope on stdout.', ' --help, -h Show this help.', ' --version, -v Show the CLI version.', '', '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'].join('\n');
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
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
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 (description, flags, examples) surfaced by `--help`.
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
- return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', ' --json Emit a machine-readable JSON envelope on stdout.', ' --help, -h Show this help.', ' --version, -v Show the CLI version.', '', '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'].join('\n');
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
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
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 (description, flags, examples) surfaced by `--help`.
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
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
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 (description, flags, examples) surfaced by `--help`.
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[];
@@ -0,0 +1,7 @@
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 declare const getVersion: () => string;
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Types for the ADS CLI command registry.
3
3
  *
4
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
5
- * from the single set of {@link CommandDefinition}s, so the runnable surface and the
6
- * documented surface can never drift apart.
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 flag for a command, surfaced by `--help`.
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
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Format a scannable human catalog of the ADS CLI capability manifest.
3
+ */
4
+ export declare const formatManifest: (data: unknown) => string | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.1.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",