@atlaskit/ads-cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.3.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`d678f1fec09ca`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/d678f1fec09ca) -
8
+ Include concise, query-labelled foundations docs in unified search results, with leading-text
9
+ previews, docs filtering, and detail commands. For example:
10
+
11
+ ```sh
12
+ npx @atlaskit/ads-cli search contrast --type docs
13
+ ```
14
+
3
15
  ## 0.2.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -23,7 +23,7 @@ The CLI has these commands:
23
23
 
24
24
  | Command | Description |
25
25
  | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
- | `search <query...>` | **Unified** fuzzy-search across components, tokens, and icons at once. Narrow with `--type component\|token\|icon`; limit with `--limit N`. |
26
+ | `search <query...>` | **Unified** fuzzy-search across components, tokens, icons, and foundations docs at once. Narrow results with `--type component\|token\|icon\|docs`; limit with `--limit N`. |
27
27
  | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
28
28
  | `token <name>` | Detail for a single token. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token. |
29
29
  | `icon <name>` | Detail for a single icon (with a copy-paste import). Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every icon. |
@@ -40,11 +40,12 @@ The CLI has these commands:
40
40
  ## Examples
41
41
 
42
42
  ```sh
43
- # Unified human-readable search — components, tokens, and icons grouped together
44
- npx @atlaskit/ads-cli search button
43
+ # Unified human-readable search — components, tokens, icons, and docs grouped together
44
+ npx @atlaskit/ads-cli search contrast
45
45
 
46
46
  # Narrow to a single kind
47
47
  npx @atlaskit/ads-cli search space color --type token
48
+ npx @atlaskit/ads-cli search contrast --type docs
48
49
 
49
50
  # Detail for a single component, token, or icon
50
51
  npx @atlaskit/ads-cli component Avatar
@@ -71,11 +72,13 @@ npx @atlaskit/ads-cli manifest --json
71
72
  - **Every command is human-readable by default; `--json` is the only path to structured output.**
72
73
  `search` and the `--all` listings print one compact line per result (e.g.
73
74
  `Avatar @atlaskit/avatar (42 props, 1 example)`), and unified `search` groups results into
74
- `Components` / `Tokens` / `Icons` sections with a `→ ads-cli component Avatar` follow-up hint per
75
- row. `component`/`token`/`icon` print a readable detail view (the icon view includes a copy-paste
76
- `import` line); `docs` (foundations, `a11y`, and `migration`) and `lint-rules` print
77
- prose/Markdown. A raw JSON dump is only ever a last-resort fallback for an unrecognised shape. For
78
- the **full structured payload**, use `--json`.
75
+ `Components` / `Tokens` / `Icons` / `Docs` sections. Every `search` row includes a follow-up
76
+ command, such as `→ ads-cli component Avatar` or `→ ads-cli docs contrast`; this also applies to
77
+ narrowed `search --type` output. Documentation search results stay concise, while `docs <query>`
78
+ prints the full matched Markdown. `component`/`token`/`icon` print a readable detail view (the
79
+ icon view includes a copy-paste `import` line); `docs` (`foundations`, `a11y`, and `migration`)
80
+ and `lint-rules` print prose/Markdown. A raw JSON dump is only ever a last-resort fallback for an
81
+ unrecognised shape. For the **full structured payload**, use `--json`.
79
82
  - **Lookups never silently guess.** `component`/`token`/`icon <name>` — and a fuzzy
80
83
  `lint-rules <term>` — render the entry whose name matches exactly (case-insensitively). If there
81
84
  is no exact match but several candidates, they print a `Did you mean?` list (each with a
@@ -95,7 +98,18 @@ npx @atlaskit/ads-cli manifest --json
95
98
  "type": "ads-cli/search",
96
99
  "command": "search",
97
100
  "ok": true,
98
- "data": { "components": [ /* … */ ], "tokens": [ /* … */ ], "icons": [ /* … */ ] },
101
+ "data": {
102
+ "components": [ /* … */ ],
103
+ "tokens": [ /* … */ ],
104
+ "icons": [ /* … */ ],
105
+ "docs": [
106
+ {
107
+ "title": "Button",
108
+ "summary": "A concise preview of the leading textual content.",
109
+ "followUp": "docs button"
110
+ }
111
+ ]
112
+ },
99
113
  "meta": { "terms": ["button"], "count": 12 }
100
114
  }
101
115
 
package/dist/cjs/cli.js CHANGED
@@ -16,6 +16,7 @@ var _importToolHandler = require("./commands/import-tool-handler");
16
16
  var _runTool = require("./commands/run-tool");
17
17
  var _createErrorEnvelope = require("./envelope/create-error-envelope");
18
18
  var _createSuccessEnvelope = require("./envelope/create-success-envelope");
19
+ var _createDocSearchResults = require("./output/create-doc-search-results");
19
20
  var _formatGroupedResults = require("./output/format-grouped-results");
20
21
  var _formatResults = require("./output/format-results");
21
22
  var _writeHumanError = require("./output/write-human-error");
@@ -62,7 +63,7 @@ var buildHelpText = function buildHelpText() {
62
63
  var aliases = flag.alias ? ", -".concat(flag.alias) : '';
63
64
  return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
64
65
  }).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');
66
+ return [_cliMetadata.CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search contrast # unified: components, tokens, icons & docs', ' $ npx @atlaskit/ads-cli search button --type component', ' $ npx @atlaskit/ads-cli search contrast --type docs', ' $ npx @atlaskit/ads-cli component Button # detail for one component', ' $ npx @atlaskit/ads-cli token space.100 # detail for one token', ' $ npx @atlaskit/ads-cli icon --all # list every icon', ' $ npx @atlaskit/ads-cli docs spacing # foundations docs', ' $ npx @atlaskit/ads-cli docs a11y buttons # accessibility guidance', ' $ npx @atlaskit/ads-cli docs migration motion # migration guide', ' $ npx @atlaskit/ads-cli manifest --json # machine-readable CLI contract'].join('\n');
66
67
  };
67
68
 
68
69
  /**
@@ -269,7 +270,8 @@ var renderSingleResult = function renderSingleResult(_ref4) {
269
270
  var resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
270
271
  var compact = resultKind ? (0, _formatResults.formatCompactResults)({
271
272
  kind: resultKind,
272
- data: data
273
+ data: data,
274
+ showFollowUp: command.name === 'search'
273
275
  }) : null;
274
276
  var human = (_ref5 = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref5 !== void 0 ? _ref5 : null;
275
277
  if (human !== null) {
@@ -297,7 +299,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
297
299
  json = _ref6.json,
298
300
  writer = _ref6.writer;
299
301
  // Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
300
- // empty domain does not blank out the others.
302
+ // empty domain does not blank out the others. The guidelines tool returns full Markdown, so
303
+ // summarize its highest-ranked match for search; `docs <query>` remains the detail view.
301
304
  var grouped = {};
302
305
  var _iterator = _createForOfIteratorHelper(results),
303
306
  _step;
@@ -307,7 +310,14 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
307
310
  key = _step$value.key,
308
311
  data = _step$value.data,
309
312
  isError = _step$value.isError;
310
- grouped[key] = isError || !Array.isArray(data) ? [] : data;
313
+ if (key === 'docs' && !isError && typeof data === 'string' && data.trim() !== '') {
314
+ grouped[key] = (0, _createDocSearchResults.createDocSearchResults)({
315
+ data: data,
316
+ query: input.positionals.join(' ')
317
+ });
318
+ } else {
319
+ grouped[key] = isError || !Array.isArray(data) ? [] : data;
320
+ }
311
321
  }
312
322
  } catch (err) {
313
323
  _iterator.e(err);
@@ -318,7 +328,7 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
318
328
  return sum + arr.length;
319
329
  }, 0);
320
330
  if (totalCount === 0) {
321
- var message = 'No components, tokens, or icons found.';
331
+ var message = "No components, tokens, icons, or docs found for \"".concat(input.positionals.join(' '), "\".");
322
332
  if (json) {
323
333
  (0, _writeJsonEnvelope.writeJsonEnvelope)({
324
334
  envelope: (0, _createErrorEnvelope.createErrorEnvelope)({
@@ -341,8 +351,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
341
351
  envelope: (0, _createSuccessEnvelope.createSuccessEnvelope)({
342
352
  envelopeType: command.envelopeType(input),
343
353
  command: command.name,
344
- // `data` for grouped commands is `{ components, tokens, icons }` (already counted
345
- // per group), so `count` is the combined total across groups.
354
+ // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
355
+ // counted per group), so `count` is the combined total across groups.
346
356
  data: grouped,
347
357
  meta: _objectSpread(_objectSpread({}, meta), {}, {
348
358
  count: totalCount
@@ -11,6 +11,7 @@ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers
11
11
  var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
12
12
  var _a11yGuidelines = require("@atlaskit/ads-mcp/a11y-guidelines");
13
13
  var _migrationRegistry = require("@atlaskit/ads-mcp/migration-registry");
14
+ var _createDocSearchResults = require("../output/create-doc-search-results");
14
15
  var _disambiguation = require("../output/disambiguation");
15
16
  var _formatComponent = require("../output/format-component");
16
17
  var _formatDisambiguation = require("../output/format-disambiguation");
@@ -68,7 +69,7 @@ var parseLimit = function parseLimit(flags) {
68
69
  };
69
70
 
70
71
  /**
71
- * Map of the three `search --type` variants to their ADS MCP tool exports.
72
+ * Map of the `search --type` variants to their ADS MCP tool exports.
72
73
  */
73
74
  var searchKindTools = {
74
75
  components: {
@@ -85,17 +86,22 @@ var searchKindTools = {
85
86
  importPath: '@atlaskit/ads-mcp/tools/search-icons',
86
87
  handlerName: 'searchIconsTool',
87
88
  envelopeType: 'search-icons'
89
+ },
90
+ docs: {
91
+ importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
92
+ handlerName: 'getGuidelinesTool',
93
+ envelopeType: 'search-docs'
88
94
  }
89
95
  };
90
96
  /**
91
- * Accepted `--type` values (singular, matching the item command names) → the internal (plural)
92
- * {@link SearchKind}. Everything downstream keys off the plural `SearchKind` (envelope types,
93
- * grouped JSON keys), so the singular input normalises to it here.
97
+ * Accepted `--type` values → the internal {@link SearchKind}. Entity inputs are singular to match
98
+ * their item commands; `docs` matches the dedicated documentation command.
94
99
  */
95
100
  var SEARCH_TYPE_VALUES = {
96
101
  component: 'components',
97
102
  token: 'tokens',
98
- icon: 'icons'
103
+ icon: 'icons',
104
+ docs: 'docs'
99
105
  };
100
106
  var isSearchTypeValue = function isSearchTypeValue(value) {
101
107
  return value in SEARCH_TYPE_VALUES;
@@ -416,10 +422,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
416
422
  };
417
423
 
418
424
  /**
419
- * Resolver for the unified `search` (no `--type`): fan out to all three search tools in one
420
- * command. The results are grouped by kind (components/tokens/icons) rather than merged into a
421
- * single ranked list — each tool ranks its own domain, and re-ranking across domains would
422
- * mean duplicating ranking logic here (breaking the zero-drift contract with `@atlaskit/ads-mcp`).
425
+ * Resolver for the unified `search` (no `--type`): fan out to the three entity search tools and
426
+ * foundations documentation search in one command. The results are grouped by kind
427
+ * (components/tokens/icons/docs) rather than merged into a single ranked list — each tool ranks its
428
+ * own domain, and re-ranking across domains would mean duplicating ranking logic here (breaking the
429
+ * zero-drift contract with `@atlaskit/ads-mcp`).
423
430
  */
424
431
  var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
425
432
  var terms = input.positionals;
@@ -451,6 +458,10 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
451
458
  key: 'icons'
452
459
  }, searchKindTools.icons), {}, {
453
460
  args: args
461
+ }), _objectSpread(_objectSpread({
462
+ key: 'docs'
463
+ }, searchKindTools.docs), {}, {
464
+ args: args
454
465
  })],
455
466
  meta: args
456
467
  };
@@ -461,7 +472,7 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
461
472
  */
462
473
  var commands = exports.commands = [{
463
474
  name: 'search',
464
- description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
475
+ description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type).',
465
476
  usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
466
477
  arguments: [{
467
478
  name: 'query',
@@ -477,7 +488,7 @@ var commands = exports.commands = [{
477
488
  choices: Object.keys(SEARCH_TYPE_VALUES),
478
489
  description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
479
490
  }, limitFlag],
480
- examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
491
+ examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5', 'search contrast --type docs'],
481
492
  responseTypes: ['ads-cli/search'].concat((0, _toConsumableArray2.default)(Object.values(searchKindTools).map(function (tool) {
482
493
  return "ads-cli/".concat(tool.envelopeType);
483
494
  }))),
@@ -488,12 +499,20 @@ var commands = exports.commands = [{
488
499
  var _resolveSearchType;
489
500
  return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
490
501
  },
502
+ transform: function transform(_ref5) {
503
+ var data = _ref5.data,
504
+ input = _ref5.input;
505
+ return resolveSearchType(input.flags) === 'docs' ? (0, _createDocSearchResults.createDocSearchResults)({
506
+ data: data,
507
+ query: input.positionals.join(' ')
508
+ }) : data;
509
+ },
491
510
  envelopeType: function envelopeType(input) {
492
511
  var searchType = resolveSearchType(input.flags);
493
512
  return searchType ? searchKindTools[searchType].envelopeType : 'search';
494
513
  },
495
514
  resolve: function resolve(input) {
496
- // No `--type`: unified search across all three kinds.
515
+ // No `--type`: unified search across all three entity kinds and foundations docs.
497
516
  if (input.flags.type === undefined) {
498
517
  return resolveUnifiedSearch(input);
499
518
  }
@@ -549,9 +568,9 @@ var commands = exports.commands = [{
549
568
  // shows that rule's docs, but several matches with no exact name surface a disambiguation
550
569
  // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
551
570
  // intentionally returns every rule's content).
552
- transform: function transform(_ref5) {
553
- var data = _ref5.data,
554
- input = _ref5.input;
571
+ transform: function transform(_ref6) {
572
+ var data = _ref6.data,
573
+ input = _ref6.input;
555
574
  var terms = input.positionals;
556
575
  if (terms.length === 0) {
557
576
  return data;
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.createDocSearchResults = void 0;
8
+ var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
9
+ function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
10
+ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
11
+ /**
12
+ * A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
13
+ *
14
+ * Search only surfaces this summary. The `docs` command remains the detail view for the full
15
+ * Markdown content.
16
+ */
17
+
18
+ /**
19
+ * Truncate a one-line description so compact rows stay on a single line.
20
+ */
21
+ var truncate = function truncate(text, max) {
22
+ return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
23
+ };
24
+
25
+ /**
26
+ * Remove common Markdown formatting before showing documentation content in one row.
27
+ */
28
+ var toPlainText = function toPlainText(text) {
29
+ return text.replace(/!\[[^\]]*]\([^)]*\)/g, '').replace(/\[([^\]]+)]\([^)]*\)/g, '$1').replace(/^\s{0,3}#{1,6}\s+/gm, '').replace(/<[^>]+>/g, ' ').replace(/[*_`~]/g, '').replace(/\s+/g, ' ').trim();
30
+ };
31
+
32
+ /**
33
+ * Turn a full foundations-doc Markdown match into the concise record used by `search`.
34
+ *
35
+ * `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
36
+ * highest-ranked match is represented by the query and a preview of its leading textual content;
37
+ * the full payload remains available through the follow-up `docs <query>` command.
38
+ */
39
+ var createDocSearchResults = exports.createDocSearchResults = function createDocSearchResults(_ref) {
40
+ var data = _ref.data,
41
+ query = _ref.query;
42
+ if (typeof data !== 'string' || data.trim() === '') {
43
+ return [];
44
+ }
45
+ var normalizedQuery = query.replace(/\s+/g, ' ').trim();
46
+ var title = normalizedQuery ? "".concat(normalizedQuery.charAt(0).toUpperCase()).concat(normalizedQuery.slice(1)) : 'Documentation';
47
+ var preview = toPlainText(data);
48
+ return [_objectSpread(_objectSpread({
49
+ title: truncate(title, 80)
50
+ }, preview ? {
51
+ summary: truncate(preview, 100)
52
+ } : {}), {}, {
53
+ followUp: "docs ".concat(query)
54
+ })];
55
+ };
@@ -8,9 +8,8 @@ var _formatResults = require("./format-results");
8
8
  /**
9
9
  * Sectioned compact renderer for grouped (multi-kind) results, e.g. unified `search`.
10
10
  *
11
- * Prints a Components section, then Tokens, then Icons — reusing the per-kind compact renderer
12
- * for each. Empty groups are skipped, so one command surfaces whatever kinds match, grouped by
13
- * kind.
11
+ * Prints Components, Tokens, Icons, and Docs sections using the per-kind compact renderer. Empty
12
+ * groups are skipped, so one command surfaces whatever kinds match, grouped by kind.
14
13
  */
15
14
 
16
15
  /**
@@ -29,6 +28,9 @@ var formatGroupedResults = exports.formatGroupedResults = function formatGrouped
29
28
  }, {
30
29
  kind: 'icons',
31
30
  title: 'Icons'
31
+ }, {
32
+ kind: 'docs',
33
+ title: 'Docs'
32
34
  }];
33
35
  var blocks = ["Results (".concat(totalCount, "):")];
34
36
  for (var _i = 0, _sections = sections; _i < _sections.length; _i++) {
@@ -55,9 +55,8 @@ var truncate = function truncate(text) {
55
55
  /**
56
56
  * Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
57
57
  *
58
- * Only used in unified `search`, where a row is one of many mixed results and the natural next
59
- * step is to view that one in full. Single-kind listings (`--all`, `--type`) omit it — you asked
60
- * for the whole list, so echoing each row's own name back would just be noise.
58
+ * Used for every `search` result, where the natural next step is to view that match in full.
59
+ * `--all` listings omit it because echoing every row's own name would just be noise.
61
60
  */
62
61
  var withFollowUp = function withFollowUp(_ref) {
63
62
  var line = _ref.line,
@@ -122,13 +121,21 @@ var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
122
121
  });
123
122
  };
124
123
 
124
+ /**
125
+ * Render one foundations-document match without dumping its full Markdown body.
126
+ */
127
+ var formatDocLine = function formatDocLine(doc, showFollowUp) {
128
+ var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
129
+ var line = "".concat(doc.title).concat(summary);
130
+ return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(doc.followUp) : line;
131
+ };
132
+
125
133
  /**
126
134
  * Render an array of results as compact lines for the given kind. Returns `null` when the data
127
135
  * is not an array (so the caller can fall back to generic JSON rendering).
128
136
  *
129
137
  * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
130
- * row. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
131
- * off so the output stays terse.
138
+ * row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
132
139
  */
133
140
  var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref2) {
134
141
  var kind = _ref2.kind,
@@ -149,6 +156,8 @@ var formatCompactResults = exports.formatCompactResults = function formatCompact
149
156
  return formatTokenLine(entry, showFollowUp);
150
157
  case 'icons':
151
158
  return formatIconLine(entry, showFollowUp);
159
+ case 'docs':
160
+ return formatDocLine(entry, showFollowUp);
152
161
  default:
153
162
  return JSON.stringify(entry);
154
163
  }
@@ -17,6 +17,7 @@ import { importToolHandler } from './commands/import-tool-handler';
17
17
  import { runTool } from './commands/run-tool';
18
18
  import { createErrorEnvelope } from './envelope/create-error-envelope';
19
19
  import { createSuccessEnvelope } from './envelope/create-success-envelope';
20
+ import { createDocSearchResults } from './output/create-doc-search-results';
20
21
  import { formatGroupedResults } from './output/format-grouped-results';
21
22
  import { formatCompactResults } from './output/format-results';
22
23
  import { writeHumanError } from './output/write-human-error';
@@ -48,7 +49,7 @@ const buildHelpText = () => {
48
49
  const aliases = flag.alias ? `, -${flag.alias}` : '';
49
50
  return ` --${flag.name}${aliases}`.padEnd(18) + flag.description;
50
51
  }).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');
52
+ 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');
52
53
  };
53
54
 
54
55
  /**
@@ -226,7 +227,8 @@ const renderSingleResult = ({
226
227
  const resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
227
228
  const compact = resultKind ? formatCompactResults({
228
229
  kind: resultKind,
229
- data
230
+ data,
231
+ showFollowUp: command.name === 'search'
230
232
  }) : null;
231
233
  const human = (_ref = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref !== void 0 ? _ref : null;
232
234
  if (human !== null) {
@@ -255,18 +257,26 @@ const renderGroupedResult = ({
255
257
  writer
256
258
  }) => {
257
259
  // Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
258
- // empty domain does not blank out the others.
260
+ // empty domain does not blank out the others. The guidelines tool returns full Markdown, so
261
+ // summarize its highest-ranked match for search; `docs <query>` remains the detail view.
259
262
  const grouped = {};
260
263
  for (const {
261
264
  key,
262
265
  data,
263
266
  isError
264
267
  } of results) {
265
- grouped[key] = isError || !Array.isArray(data) ? [] : data;
268
+ if (key === 'docs' && !isError && typeof data === 'string' && data.trim() !== '') {
269
+ grouped[key] = createDocSearchResults({
270
+ data,
271
+ query: input.positionals.join(' ')
272
+ });
273
+ } else {
274
+ grouped[key] = isError || !Array.isArray(data) ? [] : data;
275
+ }
266
276
  }
267
277
  const totalCount = Object.values(grouped).reduce((sum, arr) => sum + arr.length, 0);
268
278
  if (totalCount === 0) {
269
- const message = 'No components, tokens, or icons found.';
279
+ const message = `No components, tokens, icons, or docs found for "${input.positionals.join(' ')}".`;
270
280
  if (json) {
271
281
  writeJsonEnvelope({
272
282
  envelope: createErrorEnvelope({
@@ -289,8 +299,8 @@ const renderGroupedResult = ({
289
299
  envelope: createSuccessEnvelope({
290
300
  envelopeType: command.envelopeType(input),
291
301
  command: command.name,
292
- // `data` for grouped commands is `{ components, tokens, icons }` (already counted
293
- // per group), so `count` is the combined total across groups.
302
+ // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
303
+ // counted per group), so `count` is the combined total across groups.
294
304
  data: grouped,
295
305
  meta: {
296
306
  ...meta,
@@ -16,6 +16,7 @@
16
16
 
17
17
  import { accessibilityGuidelines } from '@atlaskit/ads-mcp/a11y-guidelines';
18
18
  import { migrationRegistry } from '@atlaskit/ads-mcp/migration-registry';
19
+ import { createDocSearchResults } from '../output/create-doc-search-results';
19
20
  import { isDisambiguation } from '../output/disambiguation';
20
21
  import { formatComponent } from '../output/format-component';
21
22
  import { formatDisambiguation } from '../output/format-disambiguation';
@@ -56,7 +57,7 @@ const parseLimit = flags => {
56
57
  };
57
58
 
58
59
  /**
59
- * Map of the three `search --type` variants to their ADS MCP tool exports.
60
+ * Map of the `search --type` variants to their ADS MCP tool exports.
60
61
  */
61
62
  const searchKindTools = {
62
63
  components: {
@@ -73,17 +74,22 @@ const searchKindTools = {
73
74
  importPath: '@atlaskit/ads-mcp/tools/search-icons',
74
75
  handlerName: 'searchIconsTool',
75
76
  envelopeType: 'search-icons'
77
+ },
78
+ docs: {
79
+ importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
80
+ handlerName: 'getGuidelinesTool',
81
+ envelopeType: 'search-docs'
76
82
  }
77
83
  };
78
84
  /**
79
- * Accepted `--type` values (singular, matching the item command names) → the internal (plural)
80
- * {@link SearchKind}. Everything downstream keys off the plural `SearchKind` (envelope types,
81
- * grouped JSON keys), so the singular input normalises to it here.
85
+ * Accepted `--type` values → the internal {@link SearchKind}. Entity inputs are singular to match
86
+ * their item commands; `docs` matches the dedicated documentation command.
82
87
  */
83
88
  const SEARCH_TYPE_VALUES = {
84
89
  component: 'components',
85
90
  token: 'tokens',
86
- icon: 'icons'
91
+ icon: 'icons',
92
+ docs: 'docs'
87
93
  };
88
94
  const isSearchTypeValue = value => value in SEARCH_TYPE_VALUES;
89
95
 
@@ -391,10 +397,11 @@ const makeItemCommand = ({
391
397
  };
392
398
 
393
399
  /**
394
- * Resolver for the unified `search` (no `--type`): fan out to all three search tools in one
395
- * command. The results are grouped by kind (components/tokens/icons) rather than merged into a
396
- * single ranked list — each tool ranks its own domain, and re-ranking across domains would
397
- * mean duplicating ranking logic here (breaking the zero-drift contract with `@atlaskit/ads-mcp`).
400
+ * Resolver for the unified `search` (no `--type`): fan out to the three entity search tools and
401
+ * foundations documentation search in one command. The results are grouped by kind
402
+ * (components/tokens/icons/docs) rather than merged into a single ranked list — each tool ranks its
403
+ * own domain, and re-ranking across domains would mean duplicating ranking logic here (breaking the
404
+ * zero-drift contract with `@atlaskit/ads-mcp`).
398
405
  */
399
406
  const resolveUnifiedSearch = input => {
400
407
  const terms = input.positionals;
@@ -427,6 +434,10 @@ const resolveUnifiedSearch = input => {
427
434
  key: 'icons',
428
435
  ...searchKindTools.icons,
429
436
  args
437
+ }, {
438
+ key: 'docs',
439
+ ...searchKindTools.docs,
440
+ args
430
441
  }],
431
442
  meta: args
432
443
  };
@@ -437,7 +448,7 @@ const resolveUnifiedSearch = input => {
437
448
  */
438
449
  export const commands = [{
439
450
  name: 'search',
440
- description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
451
+ description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type).',
441
452
  usage: `search <query...> [--type ${Object.keys(SEARCH_TYPE_VALUES).join('|')}] [--limit N]`,
442
453
  arguments: [{
443
454
  name: 'query',
@@ -453,7 +464,7 @@ export const commands = [{
453
464
  choices: Object.keys(SEARCH_TYPE_VALUES),
454
465
  description: `Narrow the search to a single kind: ${Object.keys(SEARCH_TYPE_VALUES).join(', ')}.`
455
466
  }, limitFlag],
456
- examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
467
+ examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5', 'search contrast --type docs'],
457
468
  responseTypes: ['ads-cli/search', ...Object.values(searchKindTools).map(tool => `ads-cli/${tool.envelopeType}`)],
458
469
  // With `--type`, the result is a single kind (compact per-row rendering). Without it, the
459
470
  // result is grouped across all kinds, so there is no single result kind — the grouped
@@ -462,12 +473,19 @@ export const commands = [{
462
473
  var _resolveSearchType;
463
474
  return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
464
475
  },
476
+ transform: ({
477
+ data,
478
+ input
479
+ }) => resolveSearchType(input.flags) === 'docs' ? createDocSearchResults({
480
+ data,
481
+ query: input.positionals.join(' ')
482
+ }) : data,
465
483
  envelopeType: input => {
466
484
  const searchType = resolveSearchType(input.flags);
467
485
  return searchType ? searchKindTools[searchType].envelopeType : 'search';
468
486
  },
469
487
  resolve: input => {
470
- // No `--type`: unified search across all three kinds.
488
+ // No `--type`: unified search across all three entity kinds and foundations docs.
471
489
  if (input.flags.type === undefined) {
472
490
  return resolveUnifiedSearch(input);
473
491
  }
@@ -0,0 +1,42 @@
1
+ /**
2
+ * A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
3
+ *
4
+ * Search only surfaces this summary. The `docs` command remains the detail view for the full
5
+ * Markdown content.
6
+ */
7
+
8
+ /**
9
+ * Truncate a one-line description so compact rows stay on a single line.
10
+ */
11
+ const truncate = (text, max) => text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
12
+
13
+ /**
14
+ * Remove common Markdown formatting before showing documentation content in one row.
15
+ */
16
+ const toPlainText = text => text.replace(/!\[[^\]]*]\([^)]*\)/g, '').replace(/\[([^\]]+)]\([^)]*\)/g, '$1').replace(/^\s{0,3}#{1,6}\s+/gm, '').replace(/<[^>]+>/g, ' ').replace(/[*_`~]/g, '').replace(/\s+/g, ' ').trim();
17
+
18
+ /**
19
+ * Turn a full foundations-doc Markdown match into the concise record used by `search`.
20
+ *
21
+ * `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
22
+ * highest-ranked match is represented by the query and a preview of its leading textual content;
23
+ * the full payload remains available through the follow-up `docs <query>` command.
24
+ */
25
+ export const createDocSearchResults = ({
26
+ data,
27
+ query
28
+ }) => {
29
+ if (typeof data !== 'string' || data.trim() === '') {
30
+ return [];
31
+ }
32
+ const normalizedQuery = query.replace(/\s+/g, ' ').trim();
33
+ const title = normalizedQuery ? `${normalizedQuery.charAt(0).toUpperCase()}${normalizedQuery.slice(1)}` : 'Documentation';
34
+ const preview = toPlainText(data);
35
+ return [{
36
+ title: truncate(title, 80),
37
+ ...(preview ? {
38
+ summary: truncate(preview, 100)
39
+ } : {}),
40
+ followUp: `docs ${query}`
41
+ }];
42
+ };
@@ -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';
@@ -25,6 +24,9 @@ export const formatGroupedResults = ({
25
24
  }, {
26
25
  kind: 'icons',
27
26
  title: 'Icons'
27
+ }, {
28
+ kind: 'docs',
29
+ title: 'Docs'
28
30
  }];
29
31
  const blocks = [`Results (${totalCount}):`];
30
32
  for (const {
@@ -40,9 +40,8 @@ const truncate = (text, max = 80) => text.length > max ? `${text.slice(0, max -
40
40
  /**
41
41
  * Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
42
42
  *
43
- * Only used in unified `search`, where a row is one of many mixed results and the natural next
44
- * step is to view that one in full. Single-kind listings (`--all`, `--type`) omit it — you asked
45
- * for the whole list, so echoing each row's own name back would just be noise.
43
+ * Used for every `search` result, where the natural next step is to view that match in full.
44
+ * `--all` listings omit it because echoing every row's own name would just be noise.
46
45
  */
47
46
  const withFollowUp = ({
48
47
  line,
@@ -106,13 +105,21 @@ const formatIconLine = (iconResult, showFollowUp) => {
106
105
  });
107
106
  };
108
107
 
108
+ /**
109
+ * Render one foundations-document match without dumping its full Markdown body.
110
+ */
111
+ const formatDocLine = (doc, showFollowUp) => {
112
+ const summary = doc.summary ? ` — ${doc.summary}` : '';
113
+ const line = `${doc.title}${summary}`;
114
+ return showFollowUp ? `${line}\n → ads-cli ${doc.followUp}` : line;
115
+ };
116
+
109
117
  /**
110
118
  * Render an array of results as compact lines for the given kind. Returns `null` when the data
111
119
  * is not an array (so the caller can fall back to generic JSON rendering).
112
120
  *
113
121
  * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
114
- * row. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
115
- * off so the output stays terse.
122
+ * row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
116
123
  */
117
124
  export const formatCompactResults = ({
118
125
  kind,
@@ -133,6 +140,8 @@ export const formatCompactResults = ({
133
140
  return formatTokenLine(entry, showFollowUp);
134
141
  case 'icons':
135
142
  return formatIconLine(entry, showFollowUp);
143
+ case 'docs':
144
+ return formatDocLine(entry, showFollowUp);
136
145
  default:
137
146
  return JSON.stringify(entry);
138
147
  }
package/dist/esm/cli.js CHANGED
@@ -25,6 +25,7 @@ import { importToolHandler } from './commands/import-tool-handler';
25
25
  import { runTool } from './commands/run-tool';
26
26
  import { createErrorEnvelope } from './envelope/create-error-envelope';
27
27
  import { createSuccessEnvelope } from './envelope/create-success-envelope';
28
+ import { createDocSearchResults } from './output/create-doc-search-results';
28
29
  import { formatGroupedResults } from './output/format-grouped-results';
29
30
  import { formatCompactResults } from './output/format-results';
30
31
  import { writeHumanError } from './output/write-human-error';
@@ -58,7 +59,7 @@ var buildHelpText = function buildHelpText() {
58
59
  var aliases = flag.alias ? ", -".concat(flag.alias) : '';
59
60
  return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
60
61
  }).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');
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');
62
63
  };
63
64
 
64
65
  /**
@@ -265,7 +266,8 @@ var renderSingleResult = function renderSingleResult(_ref4) {
265
266
  var resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
266
267
  var compact = resultKind ? formatCompactResults({
267
268
  kind: resultKind,
268
- data: data
269
+ data: data,
270
+ showFollowUp: command.name === 'search'
269
271
  }) : null;
270
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;
271
273
  if (human !== null) {
@@ -293,7 +295,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
293
295
  json = _ref6.json,
294
296
  writer = _ref6.writer;
295
297
  // Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
296
- // 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.
297
300
  var grouped = {};
298
301
  var _iterator = _createForOfIteratorHelper(results),
299
302
  _step;
@@ -303,7 +306,14 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
303
306
  key = _step$value.key,
304
307
  data = _step$value.data,
305
308
  isError = _step$value.isError;
306
- 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
+ }
307
317
  }
308
318
  } catch (err) {
309
319
  _iterator.e(err);
@@ -314,7 +324,7 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
314
324
  return sum + arr.length;
315
325
  }, 0);
316
326
  if (totalCount === 0) {
317
- var message = 'No components, tokens, or icons found.';
327
+ var message = "No components, tokens, icons, or docs found for \"".concat(input.positionals.join(' '), "\".");
318
328
  if (json) {
319
329
  writeJsonEnvelope({
320
330
  envelope: createErrorEnvelope({
@@ -337,8 +347,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
337
347
  envelope: createSuccessEnvelope({
338
348
  envelopeType: command.envelopeType(input),
339
349
  command: command.name,
340
- // `data` for grouped commands is `{ components, tokens, icons }` (already counted
341
- // 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.
342
352
  data: grouped,
343
353
  meta: _objectSpread(_objectSpread({}, meta), {}, {
344
354
  count: totalCount
@@ -23,6 +23,7 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
23
23
 
24
24
  import { accessibilityGuidelines } from '@atlaskit/ads-mcp/a11y-guidelines';
25
25
  import { migrationRegistry } from '@atlaskit/ads-mcp/migration-registry';
26
+ import { createDocSearchResults } from '../output/create-doc-search-results';
26
27
  import { isDisambiguation } from '../output/disambiguation';
27
28
  import { formatComponent } from '../output/format-component';
28
29
  import { formatDisambiguation } from '../output/format-disambiguation';
@@ -63,7 +64,7 @@ var parseLimit = function parseLimit(flags) {
63
64
  };
64
65
 
65
66
  /**
66
- * 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.
67
68
  */
68
69
  var searchKindTools = {
69
70
  components: {
@@ -80,17 +81,22 @@ var searchKindTools = {
80
81
  importPath: '@atlaskit/ads-mcp/tools/search-icons',
81
82
  handlerName: 'searchIconsTool',
82
83
  envelopeType: 'search-icons'
84
+ },
85
+ docs: {
86
+ importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
87
+ handlerName: 'getGuidelinesTool',
88
+ envelopeType: 'search-docs'
83
89
  }
84
90
  };
85
91
  /**
86
- * Accepted `--type` values (singular, matching the item command names) → the internal (plural)
87
- * {@link SearchKind}. Everything downstream keys off the plural `SearchKind` (envelope types,
88
- * 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.
89
94
  */
90
95
  var SEARCH_TYPE_VALUES = {
91
96
  component: 'components',
92
97
  token: 'tokens',
93
- icon: 'icons'
98
+ icon: 'icons',
99
+ docs: 'docs'
94
100
  };
95
101
  var isSearchTypeValue = function isSearchTypeValue(value) {
96
102
  return value in SEARCH_TYPE_VALUES;
@@ -411,10 +417,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
411
417
  };
412
418
 
413
419
  /**
414
- * Resolver for the unified `search` (no `--type`): fan out to all three search tools in one
415
- * command. The results are grouped by kind (components/tokens/icons) rather than merged into a
416
- * single ranked list — each tool ranks its own domain, and re-ranking across domains would
417
- * 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`).
418
425
  */
419
426
  var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
420
427
  var terms = input.positionals;
@@ -446,6 +453,10 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
446
453
  key: 'icons'
447
454
  }, searchKindTools.icons), {}, {
448
455
  args: args
456
+ }), _objectSpread(_objectSpread({
457
+ key: 'docs'
458
+ }, searchKindTools.docs), {}, {
459
+ args: args
449
460
  })],
450
461
  meta: args
451
462
  };
@@ -456,7 +467,7 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
456
467
  */
457
468
  export var commands = [{
458
469
  name: 'search',
459
- 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).',
460
471
  usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
461
472
  arguments: [{
462
473
  name: 'query',
@@ -472,7 +483,7 @@ export var commands = [{
472
483
  choices: Object.keys(SEARCH_TYPE_VALUES),
473
484
  description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
474
485
  }, limitFlag],
475
- 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'],
476
487
  responseTypes: ['ads-cli/search'].concat(_toConsumableArray(Object.values(searchKindTools).map(function (tool) {
477
488
  return "ads-cli/".concat(tool.envelopeType);
478
489
  }))),
@@ -483,12 +494,20 @@ export var commands = [{
483
494
  var _resolveSearchType;
484
495
  return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
485
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
+ },
486
505
  envelopeType: function envelopeType(input) {
487
506
  var searchType = resolveSearchType(input.flags);
488
507
  return searchType ? searchKindTools[searchType].envelopeType : 'search';
489
508
  },
490
509
  resolve: function resolve(input) {
491
- // No `--type`: unified search across all three kinds.
510
+ // No `--type`: unified search across all three entity kinds and foundations docs.
492
511
  if (input.flags.type === undefined) {
493
512
  return resolveUnifiedSearch(input);
494
513
  }
@@ -544,9 +563,9 @@ export var commands = [{
544
563
  // shows that rule's docs, but several matches with no exact name surface a disambiguation
545
564
  // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
546
565
  // intentionally returns every rule's content).
547
- transform: function transform(_ref5) {
548
- var data = _ref5.data,
549
- input = _ref5.input;
566
+ transform: function transform(_ref6) {
567
+ var data = _ref6.data,
568
+ input = _ref6.input;
550
569
  var terms = input.positionals;
551
570
  if (terms.length === 0) {
552
571
  return data;
@@ -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++) {
@@ -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
  }
@@ -48,7 +48,7 @@ export type ToolCall = {
48
48
  /**
49
49
  * A stable key identifying this call within a multi-tool command. For grouped commands
50
50
  * (e.g. unified `search`) this becomes the key in the assembled data object, e.g.
51
- * `components` / `tokens` / `icons`. Ignored for single-tool commands.
51
+ * `components` / `tokens` / `icons` / `docs`. Ignored for single-tool commands.
52
52
  */
53
53
  key: string;
54
54
  importPath: string;
@@ -89,12 +89,11 @@ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
89
89
  };
90
90
  /**
91
91
  * The kind of *listable row* a command renders, used by the default (non-`--json`) formatter to
92
- * pick a compact per-row renderer. Scoped to the entity types the CLI returns as arrays of rows
93
- * (components, tokens, icons); it is intentionally NOT used for single-rich-object commands like
94
- * docs, a11y, or lint-rules — those render via {@link CommandDefinition.formatHuman} or the
95
- * generic fallback (pretty-printed JSON for objects, verbatim text for strings).
92
+ * pick a compact per-row renderer. Search results include concise documentation matches, while
93
+ * standalone docs, a11y, and lint-rules commands render their full content via
94
+ * {@link CommandDefinition.formatHuman} or the generic fallback.
96
95
  */
97
- export type RowKind = 'components' | 'tokens' | 'icons';
96
+ export type RowKind = 'components' | 'tokens' | 'icons' | 'docs';
98
97
  /**
99
98
  * A single CLI command definition.
100
99
  */
@@ -0,0 +1,22 @@
1
+ /**
2
+ * A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
3
+ *
4
+ * Search only surfaces this summary. The `docs` command remains the detail view for the full
5
+ * Markdown content.
6
+ */
7
+ export type DocSearchResult = {
8
+ title: string;
9
+ summary?: string;
10
+ followUp: string;
11
+ };
12
+ /**
13
+ * Turn a full foundations-doc Markdown match into the concise record used by `search`.
14
+ *
15
+ * `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
16
+ * highest-ranked match is represented by the query and a preview of its leading textual content;
17
+ * the full payload remains available through the follow-up `docs <query>` command.
18
+ */
19
+ export declare const createDocSearchResults: ({ data, query, }: {
20
+ data: unknown;
21
+ query: string;
22
+ }) => DocSearchResult[];
@@ -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
  * Render grouped results as sectioned compact output.
@@ -14,8 +14,7 @@ import type { RowKind } from '../commands/types';
14
14
  * is not an array (so the caller can fall back to generic JSON rendering).
15
15
  *
16
16
  * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
17
- * row. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
18
- * off so the output stays terse.
17
+ * row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
19
18
  */
20
19
  export declare const formatCompactResults: ({ kind, data, showFollowUp, }: {
21
20
  kind: RowKind;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.2.0",
3
+ "version": "0.3.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",