@atlaskit/ads-cli 0.1.0 → 0.3.0

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