@atlaskit/ads-cli 0.7.0 → 0.8.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 (34) hide show
  1. package/CHANGELOG.md +63 -0
  2. package/README.md +35 -7
  3. package/bin/ads-cli.js +6 -4
  4. package/dist/cjs/cli.js +19 -3
  5. package/dist/cjs/commands/definitions.js +29 -3
  6. package/dist/cjs/output/compact-results.js +119 -0
  7. package/dist/cjs/output/format-doc-object.js +18 -5
  8. package/dist/cjs/output/format-icon.js +2 -1
  9. package/dist/cjs/output/format-results.js +37 -71
  10. package/dist/cjs/output/format-token.js +19 -5
  11. package/dist/cjs/output/write-json-envelope.js +2 -1
  12. package/dist/es2019/cli.js +19 -3
  13. package/dist/es2019/commands/definitions.js +31 -3
  14. package/dist/es2019/output/compact-results.js +104 -0
  15. package/dist/es2019/output/format-doc-object.js +12 -4
  16. package/dist/es2019/output/format-icon.js +2 -1
  17. package/dist/es2019/output/format-results.js +37 -66
  18. package/dist/es2019/output/format-token.js +14 -5
  19. package/dist/es2019/output/write-json-envelope.js +2 -1
  20. package/dist/esm/cli.js +19 -3
  21. package/dist/esm/commands/definitions.js +29 -3
  22. package/dist/esm/output/compact-results.js +112 -0
  23. package/dist/esm/output/format-doc-object.js +18 -5
  24. package/dist/esm/output/format-icon.js +2 -1
  25. package/dist/esm/output/format-results.js +37 -71
  26. package/dist/esm/output/format-token.js +19 -5
  27. package/dist/esm/output/write-json-envelope.js +2 -1
  28. package/dist/types/commands/types.d.ts +8 -8
  29. package/dist/types/envelope/types.d.ts +3 -2
  30. package/dist/types/output/compact-results.d.ts +41 -0
  31. package/dist/types/output/format-results.d.ts +3 -3
  32. package/dist/types/output/format-token.d.ts +3 -3
  33. package/dist/types/output/write-json-envelope.d.ts +2 -1
  34. package/package.json +2 -2
@@ -294,6 +294,28 @@ var EXAMPLE_NAME = {
294
294
  icons: 'AddIcon'
295
295
  };
296
296
 
297
+ /**
298
+ * Add the actionable fields that exact human detail views derive from the raw record. Including
299
+ * them in JSON keeps both representations content-equivalent without requiring consumers to know
300
+ * ADS import or token-call conventions.
301
+ */
302
+ var addActionableDetail = function addActionableDetail(kind, item) {
303
+ if (kind === 'tokens') {
304
+ var name = itemFields.tokens.nameOf(item);
305
+ return name ? _objectSpread(_objectSpread({}, item), {}, {
306
+ usage: "token('".concat(name, "')")
307
+ }) : item;
308
+ }
309
+ if (kind === 'icons') {
310
+ var componentName = itemFields.icons.nameOf(item);
311
+ var packageName = typeof item.package === 'string' ? item.package : undefined;
312
+ return componentName && packageName ? _objectSpread(_objectSpread({}, item), {}, {
313
+ import: "import ".concat(componentName, " from '").concat(packageName, "';")
314
+ }) : item;
315
+ }
316
+ return item;
317
+ };
318
+
297
319
  /**
298
320
  * Build one of the singular item commands (`component <name>`, `token <name>`, `icon <name>`).
299
321
  *
@@ -364,11 +386,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
364
386
  return nameOf(item).toLowerCase() === query.toLowerCase();
365
387
  });
366
388
  if (exact) {
367
- return exact;
389
+ return addActionableDetail(kind, exact);
368
390
  }
369
391
  // A single candidate is unambiguous — show it.
370
392
  if (candidates.length === 1) {
371
- return candidates[0];
393
+ return addActionableDetail(kind, candidates[0]);
372
394
  }
373
395
  // Otherwise do not guess: surface a disambiguation list.
374
396
  return {
@@ -408,7 +430,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
408
430
  return singleTool({
409
431
  importPath: searchTool.importPath,
410
432
  handlerName: searchTool.handlerName,
411
- args: {
433
+ args: kind === 'tokens' ? {
434
+ terms: [name_],
435
+ limit: ITEM_LOOKUP_LIMIT,
436
+ includeMetadata: true
437
+ } : {
412
438
  terms: [name_],
413
439
  limit: ITEM_LOOKUP_LIMIT
414
440
  },
@@ -0,0 +1,112 @@
1
+ import _defineProperty from "@babel/runtime/helpers/defineProperty";
2
+ import _typeof from "@babel/runtime/helpers/typeof";
3
+ 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; }
4
+ 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; }
5
+ /**
6
+ * Shared compact projections for ADS search and list results.
7
+ *
8
+ * Human-readable rows and `--json` responses both consume these records. Keeping the projection in
9
+ * one place prevents the machine-readable output from silently expanding back to the underlying
10
+ * MCP payload (for example, every component prop and example during discovery).
11
+ */
12
+
13
+ var countOf = function countOf(value) {
14
+ return Array.isArray(value) ? value.length : 0;
15
+ };
16
+
17
+ /**
18
+ * Truncate a one-line value so discovery results stay bounded. Exact detail commands preserve the
19
+ * full value.
20
+ */
21
+ var truncateCompactText = function truncateCompactText(text) {
22
+ var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 80;
23
+ var oneLine = text.replace(/\s+/g, ' ').trim();
24
+ return oneLine.length > max ? "".concat(oneLine.slice(0, max - 1).trimEnd(), "\u2026") : oneLine;
25
+ };
26
+ var asRecord = function asRecord(value) {
27
+ return value !== null && _typeof(value) === 'object' ? value : {};
28
+ };
29
+ var optionalString = function optionalString(value) {
30
+ return typeof value === 'string' && value.length > 0 ? value : undefined;
31
+ };
32
+ var withFollowUp = function withFollowUp(result, showFollowUp, followUp) {
33
+ return showFollowUp ? _objectSpread(_objectSpread({}, result), {}, {
34
+ followUp: followUp
35
+ }) : result;
36
+ };
37
+ var compactComponent = function compactComponent(value, showFollowUp) {
38
+ var _optionalString, _optionalString2;
39
+ var record = asRecord(value);
40
+ var name = (_optionalString = optionalString(record.name)) !== null && _optionalString !== void 0 ? _optionalString : '(unknown)';
41
+ var propCount = typeof record.propCount === 'number' ? record.propCount : countOf(record.props);
42
+ var exampleCount = typeof record.exampleCount === 'number' ? record.exampleCount : countOf(record.examples);
43
+ return withFollowUp(_objectSpread(_objectSpread({
44
+ name: name
45
+ }, optionalString(record.package) ? {
46
+ package: String(record.package)
47
+ } : {}), {}, {
48
+ propCount: propCount,
49
+ exampleCount: exampleCount
50
+ }), showFollowUp, (_optionalString2 = optionalString(record.followUp)) !== null && _optionalString2 !== void 0 ? _optionalString2 : "component ".concat(name));
51
+ };
52
+ var compactToken = function compactToken(value, showFollowUp) {
53
+ var _optionalString3, _optionalString4;
54
+ var record = asRecord(value);
55
+ var name = (_optionalString3 = optionalString(record.name)) !== null && _optionalString3 !== void 0 ? _optionalString3 : '(unknown)';
56
+ var exampleValue = optionalString(record.exampleValue);
57
+ return withFollowUp(_objectSpread({
58
+ name: name
59
+ }, exampleValue ? {
60
+ exampleValue: truncateCompactText(exampleValue)
61
+ } : {}), showFollowUp, (_optionalString4 = optionalString(record.followUp)) !== null && _optionalString4 !== void 0 ? _optionalString4 : "token ".concat(name));
62
+ };
63
+ var compactIcon = function compactIcon(value, showFollowUp) {
64
+ var _optionalString5, _optionalString6;
65
+ var record = asRecord(value);
66
+ var componentName = (_optionalString5 = optionalString(record.componentName)) !== null && _optionalString5 !== void 0 ? _optionalString5 : '(unknown)';
67
+ var usage = optionalString(record.usage);
68
+ return withFollowUp(_objectSpread(_objectSpread({
69
+ componentName: componentName
70
+ }, optionalString(record.package) ? {
71
+ package: String(record.package)
72
+ } : {}), usage ? {
73
+ usage: truncateCompactText(usage)
74
+ } : {}), showFollowUp, (_optionalString6 = optionalString(record.followUp)) !== null && _optionalString6 !== void 0 ? _optionalString6 : "icon ".concat(componentName));
75
+ };
76
+ var compactDoc = function compactDoc(value, showFollowUp) {
77
+ var _optionalString7, _optionalString8;
78
+ var record = asRecord(value);
79
+ var title = (_optionalString7 = optionalString(record.title)) !== null && _optionalString7 !== void 0 ? _optionalString7 : '(unknown)';
80
+ var summary = optionalString(record.summary);
81
+ return withFollowUp(_objectSpread({
82
+ title: title
83
+ }, summary ? {
84
+ summary: truncateCompactText(summary)
85
+ } : {}), showFollowUp, (_optionalString8 = optionalString(record.followUp)) !== null && _optionalString8 !== void 0 ? _optionalString8 : "docs ".concat(title.toLowerCase()));
86
+ };
87
+
88
+ /**
89
+ * Project raw MCP rows into the compact records shared by human and JSON output. The function is
90
+ * idempotent so batch rendering can safely receive child envelopes that were already compacted.
91
+ */
92
+ export var compactResults = function compactResults(_ref) {
93
+ var kind = _ref.kind,
94
+ data = _ref.data,
95
+ _ref$showFollowUp = _ref.showFollowUp,
96
+ showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp;
97
+ if (!Array.isArray(data)) {
98
+ return null;
99
+ }
100
+ return data.map(function (entry) {
101
+ switch (kind) {
102
+ case 'components':
103
+ return compactComponent(entry, showFollowUp);
104
+ case 'tokens':
105
+ return compactToken(entry, showFollowUp);
106
+ case 'icons':
107
+ return compactIcon(entry, showFollowUp);
108
+ case 'docs':
109
+ return compactDoc(entry, showFollowUp);
110
+ }
111
+ });
112
+ };
@@ -1,5 +1,5 @@
1
- import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
2
1
  import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
2
+ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
3
3
  import _typeof from "@babel/runtime/helpers/typeof";
4
4
  /**
5
5
  * Human-readable renderer for a single "doc object" payload — the shape returned by the
@@ -39,12 +39,25 @@ var formatListItem = function formatListItem(item) {
39
39
  if (item !== null && _typeof(item) === 'object') {
40
40
  var record = item;
41
41
  var title = typeof record.title === 'string' ? record.title : null;
42
- var code = ['code', 'before', 'after'].find(function (key) {
42
+ var codeKeys = ['code', 'before', 'after'].filter(function (key) {
43
43
  return typeof record[key] === 'string';
44
44
  });
45
- if (title && code) {
46
- var description = typeof record.description === 'string' ? "\n ".concat(oneLine(record.description)) : '';
47
- return " - ".concat(title).concat(description, "\n ```tsx\n").concat(record[code], "\n ```");
45
+ if (title && codeKeys.length > 0) {
46
+ var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
47
+ var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
48
+ var codeBlocks = codeKeys.flatMap(function (key) {
49
+ return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [" ```tsx\n".concat(record[key], "\n ```")]);
50
+ });
51
+ var additionalFields = Object.entries(record).flatMap(function (_ref) {
52
+ var _ref2 = _slicedToArray(_ref, 2),
53
+ key = _ref2[0],
54
+ value = _ref2[1];
55
+ if (['title', 'description'].concat(_toConsumableArray(codeKeys)).includes(key) || value === null || value === undefined) {
56
+ return [];
57
+ }
58
+ return [" ".concat(humanizeKey(key), ": ").concat(typeof value === 'string' ? oneLine(value) : JSON.stringify(value))];
59
+ });
60
+ return [" - ".concat(title)].concat(description, _toConsumableArray(codeBlocks), _toConsumableArray(additionalFields)).join('\n');
48
61
  }
49
62
  if (title) {
50
63
  return " - ".concat(title);
@@ -31,9 +31,10 @@ export var formatIcon = function formatIcon(data) {
31
31
  }
32
32
  var sections = [icon.componentName, '='.repeat(icon.componentName.length)];
33
33
  if (icon.package) {
34
+ var _icon$import;
34
35
  sections.push('', "Package: ".concat(icon.package));
35
36
  // The actionable bit: the barrel-correct import for this icon.
36
- sections.push('', 'Import:', " import ".concat(icon.componentName, " from '").concat(icon.package, "';"));
37
+ sections.push('', 'Import:', " ".concat((_icon$import = icon.import) !== null && _icon$import !== void 0 ? _icon$import : "import ".concat(icon.componentName, " from '").concat(icon.package, "';")));
37
38
  }
38
39
  if (icon.usage) {
39
40
  sections.push('', "Usage: ".concat(oneLine(icon.usage)));
@@ -2,35 +2,16 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
2
2
  /**
3
3
  * Compact, human-readable renderers for the structured search/list results.
4
4
  *
5
- * The underlying ADS MCP tools return rich JSON arrays. Dumping that raw is unreadable at a
6
- * terminal, so the default (non-`--json`) output renders a compact one line per result. Full
7
- * structured data remains available via `--json`.
5
+ * The underlying ADS MCP tools return rich JSON arrays. Search and list commands first project
6
+ * those arrays into shared compact records, then both human and `--json` output consume the same
7
+ * data. Exact detail commands retain the full structured payload.
8
8
  *
9
9
  * Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
10
10
  * left to the caller's generic fallback.
11
11
  */
12
12
 
13
13
  import { CLI_BIN_NAME } from '../commands/cli-metadata';
14
-
15
- /**
16
- * A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
17
- * Only the fields the compact view needs are modelled; others are ignored.
18
- */
19
-
20
- /**
21
- * A token result as returned by `searchTokensTool` / `getAllTokensTool`.
22
- */
23
-
24
- /**
25
- * An icon result as returned by `searchIconsTool` / `getAllIconsTool`.
26
- */
27
-
28
- /**
29
- * Count helper that is safe against non-array / missing fields.
30
- */
31
- var countOf = function countOf(value) {
32
- return Array.isArray(value) ? value.length : 0;
33
- };
14
+ import { compactResults } from './compact-results';
34
15
 
35
16
  /**
36
17
  * Pluralise a `count`-prefixed noun, e.g. `1 prop` / `2 props`.
@@ -40,26 +21,16 @@ var pluralize = function pluralize(count, noun) {
40
21
  };
41
22
 
42
23
  /**
43
- * Truncate a one-line description so compact rows stay on a single line.
44
- */
45
- var truncate = function truncate(text) {
46
- var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 80;
47
- return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
48
- };
49
-
50
- /**
51
- * Append a `→ <invocation> <command> <name>` drill-in hint beneath a row.
24
+ * Append a distribution-specific invocation to a compact row's follow-up command.
52
25
  *
53
26
  * Used for every `search` result, where the natural next step is to view that match in full.
54
27
  * `--all` listings omit it because echoing every row's own name would just be noise.
55
28
  */
56
29
  var withFollowUp = function withFollowUp(_ref) {
57
30
  var line = _ref.line,
58
- command = _ref.command,
59
- name = _ref.name,
60
- showFollowUp = _ref.showFollowUp,
31
+ followUp = _ref.followUp,
61
32
  invocation = _ref.invocation;
62
- return showFollowUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(command, " ").concat(name) : line;
33
+ return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
63
34
  };
64
35
 
65
36
  /**
@@ -69,18 +40,13 @@ var withFollowUp = function withFollowUp(_ref) {
69
40
  * (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
70
41
  * context and a tag would just be noise.
71
42
  */
72
- var formatComponentLine = function formatComponentLine(component, showFollowUp, invocation) {
73
- var _component$name;
74
- var name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
43
+ var formatComponentLine = function formatComponentLine(component, invocation) {
44
+ var name = component.name;
75
45
  var pkg = component.package ? " ".concat(component.package) : '';
76
- var propCount = countOf(component.props);
77
- var exampleCount = countOf(component.examples);
78
- var meta = [pluralize(propCount, 'prop'), pluralize(exampleCount, 'example')].join(', ');
46
+ var meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
79
47
  return withFollowUp({
80
48
  line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
81
- command: 'component',
82
- name: name,
83
- showFollowUp: showFollowUp,
49
+ followUp: component.followUp,
84
50
  invocation: invocation
85
51
  });
86
52
  };
@@ -88,17 +54,11 @@ var formatComponentLine = function formatComponentLine(component, showFollowUp,
88
54
  /**
89
55
  * Render one token as a compact `name = value` line.
90
56
  */
91
- var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp, invocation) {
92
- var _tokenResult$name;
93
- var name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
94
- // Some token values (e.g. motion easing curves) are very long; truncate so each token stays
95
- // on a single readable line. The full value is always available via `--json`.
96
- var line = tokenResult.exampleValue ? "".concat(name, " = ").concat(truncate(tokenResult.exampleValue)) : name;
57
+ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
58
+ var line = tokenResult.exampleValue ? "".concat(tokenResult.name, " = ").concat(tokenResult.exampleValue) : tokenResult.name;
97
59
  return withFollowUp({
98
60
  line: line,
99
- command: 'token',
100
- name: name,
101
- showFollowUp: showFollowUp,
61
+ followUp: tokenResult.followUp,
102
62
  invocation: invocation
103
63
  });
104
64
  };
@@ -106,16 +66,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp, invoca
106
66
  /**
107
67
  * Render one icon as a compact line with its import package and short usage note.
108
68
  */
109
- var formatIconLine = function formatIconLine(iconResult, showFollowUp, invocation) {
110
- var _iconResult$component;
111
- var name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
69
+ var formatIconLine = function formatIconLine(iconResult, invocation) {
70
+ var name = iconResult.componentName;
112
71
  var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
113
- var usage = iconResult.usage ? " \u2014 ".concat(truncate(iconResult.usage)) : '';
72
+ var usage = iconResult.usage ? " \u2014 ".concat(iconResult.usage) : '';
114
73
  return withFollowUp({
115
74
  line: "".concat(name).concat(pkg).concat(usage),
116
- command: 'icon',
117
- name: name,
118
- showFollowUp: showFollowUp,
75
+ followUp: iconResult.followUp,
119
76
  invocation: invocation
120
77
  });
121
78
  };
@@ -123,10 +80,14 @@ var formatIconLine = function formatIconLine(iconResult, showFollowUp, invocatio
123
80
  /**
124
81
  * Render one foundations-document match without dumping its full Markdown body.
125
82
  */
126
- var formatDocLine = function formatDocLine(doc, showFollowUp, invocation) {
83
+ var formatDocLine = function formatDocLine(doc, invocation) {
127
84
  var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
128
85
  var line = "".concat(doc.title).concat(summary);
129
- return showFollowUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(doc.followUp) : line;
86
+ return withFollowUp({
87
+ line: line,
88
+ followUp: doc.followUp,
89
+ invocation: invocation
90
+ });
130
91
  };
131
92
 
132
93
  /**
@@ -143,26 +104,31 @@ export var formatCompactResults = function formatCompactResults(_ref2) {
143
104
  showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
144
105
  _ref2$invocation = _ref2.invocation,
145
106
  invocation = _ref2$invocation === void 0 ? CLI_BIN_NAME : _ref2$invocation;
146
- if (!Array.isArray(data)) {
107
+ var compact = compactResults({
108
+ kind: kind,
109
+ data: data,
110
+ showFollowUp: showFollowUp
111
+ });
112
+ if (compact === null) {
147
113
  return null;
148
114
  }
149
- if (data.length === 0) {
115
+ if (compact.length === 0) {
150
116
  return 'No results.';
151
117
  }
152
- var lines = data.map(function (entry) {
118
+ var lines = compact.map(function (entry) {
153
119
  switch (kind) {
154
120
  case 'components':
155
- return formatComponentLine(entry, showFollowUp, invocation);
121
+ return formatComponentLine(entry, invocation);
156
122
  case 'tokens':
157
- return formatTokenLine(entry, showFollowUp, invocation);
123
+ return formatTokenLine(entry, invocation);
158
124
  case 'icons':
159
- return formatIconLine(entry, showFollowUp, invocation);
125
+ return formatIconLine(entry, invocation);
160
126
  case 'docs':
161
- return formatDocLine(entry, showFollowUp, invocation);
127
+ return formatDocLine(entry, invocation);
162
128
  default:
163
129
  return JSON.stringify(entry);
164
130
  }
165
131
  });
166
- var header = "Results (".concat(data.length, "):");
132
+ var header = "Results (".concat(compact.length, "):");
167
133
  return [header, ''].concat(_toConsumableArray(lines)).join('\n');
168
134
  };
@@ -1,22 +1,28 @@
1
+ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
1
2
  import _typeof from "@babel/runtime/helpers/typeof";
2
3
  /**
3
4
  * Human-readable renderer for a single ADS design token's detail view.
4
5
  *
5
- * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
6
- * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
7
- * Full structured data remains available via `--json`.
6
+ * Exact token lookups include the full metadata record. The detail view renders its guidance and
7
+ * adds an actionable `token('…')` usage line; the same structured fields remain available via
8
+ * `--json`.
8
9
  */
9
10
 
10
11
  /**
11
12
  * A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
12
13
  */
13
14
 
15
+ var oneLine = function oneLine(text) {
16
+ return text.replace(/\s+/g, ' ').trim();
17
+ };
18
+
14
19
  /**
15
20
  * Render a single token payload as a detail view. Returns `null` when the data is not a
16
21
  * recognisable token object, so the caller can fall back to generic rendering.
17
22
  */
18
23
  export var formatToken = function formatToken(data) {
19
- // `token <name>` reuses token search with limit 1, so `data` is a one-element array.
24
+ var _token$usageGuideline, _token$usageGuideline2, _token$usage;
25
+ // `token <name>` returns a ranked candidate array; the command transform selects the detail.
20
26
  var token = Array.isArray(data) ? data[0] : data;
21
27
  if (!token || _typeof(token) !== 'object' || typeof token.name !== 'string') {
22
28
  return null;
@@ -25,8 +31,16 @@ export var formatToken = function formatToken(data) {
25
31
  if (token.exampleValue) {
26
32
  sections.push('', "Example value: ".concat(token.exampleValue));
27
33
  }
34
+ if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
35
+ sections.push('', 'Guidelines:', " ".concat(oneLine(token.usageGuidelines.usage)));
36
+ }
37
+ if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline2 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline2 !== void 0 && _token$usageGuideline2.length) {
38
+ sections.push.apply(sections, ['', 'CSS properties:'].concat(_toConsumableArray(token.usageGuidelines.cssProperties.map(function (item) {
39
+ return " ".concat(item);
40
+ }))));
41
+ }
28
42
 
29
43
  // The actionable bit: how to consume the token from `@atlaskit/tokens`.
30
- sections.push('', 'Usage:', " token('".concat(token.name, "')"));
44
+ sections.push('', 'Usage:', " ".concat((_token$usage = token.usage) !== null && _token$usage !== void 0 ? _token$usage : "token('".concat(token.name, "')")));
31
45
  return sections.join('\n');
32
46
  };
@@ -5,7 +5,8 @@
5
5
  /**
6
6
  * Emit the JSON envelope to stdout.
7
7
  *
8
- * Always pretty-printed for readability; consumers that need compact output can re-serialise.
8
+ * JSON output is pretty-printed for terminal readability. Its retrieval payload stays compact
9
+ * because search and list commands project the MCP response before it reaches this serializer.
9
10
  */
10
11
  export var writeJsonEnvelope = function writeJsonEnvelope(_ref) {
11
12
  var envelope = _ref.envelope,
@@ -104,10 +104,10 @@ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
104
104
  error: string;
105
105
  };
106
106
  /**
107
- * The kind of *listable row* a command renders, used by the default (non-`--json`) formatter to
108
- * pick a compact per-row renderer. Search results include concise documentation matches, while
109
- * standalone docs, a11y, and lint-rules commands render their full content via
110
- * {@link CommandDefinition.formatHuman} or the generic fallback.
107
+ * The kind of *listable row* a command returns. Search and list results use it to create the shared
108
+ * compact projection consumed by both human and `--json` output. Standalone docs, a11y, and
109
+ * lint-rules commands render their full content via {@link CommandDefinition.formatHuman} or the
110
+ * generic fallback.
111
111
  */
112
112
  export type RowKind = 'components' | 'tokens' | 'icons' | 'docs';
113
113
  /**
@@ -130,10 +130,10 @@ export type CommandDefinition = {
130
130
  */
131
131
  name: string;
132
132
  /**
133
- * The compact result kind for human output. When set, the default renderer prints one
134
- * line per result; when omitted, the command uses the generic fallback (JSON for objects,
135
- * verbatim for strings — e.g. guideline markdown). May depend on input, so it is a function
136
- * of {@link CommandInput} (e.g. `search --type tokens` renders as tokens).
133
+ * The compact result kind for search/list output. When set, both JSON and the default human
134
+ * renderer consume the same bounded record per result. When omitted, the command uses its detail
135
+ * renderer or generic fallback. May depend on input, so it is a function of
136
+ * {@link CommandInput} (e.g. `search --type tokens` renders as tokens).
137
137
  */
138
138
  resultKind?: (input: CommandInput) => RowKind | undefined;
139
139
  /**
@@ -22,8 +22,9 @@ export type EnvelopeMeta = {
22
22
  /**
23
23
  * Successful command envelope.
24
24
  *
25
- * `data` holds the (already JSON-parsed where possible) payload returned by the underlying
26
- * ADS MCP tool.
25
+ * `data` holds the command's output payload. Search and list commands project underlying MCP data
26
+ * into the same compact records shown by human output; exact detail commands retain their detailed
27
+ * records.
27
28
  */
28
29
  export type SuccessEnvelope<Data = unknown> = {
29
30
  /**
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Shared compact projections for ADS search and list results.
3
+ *
4
+ * Human-readable rows and `--json` responses both consume these records. Keeping the projection in
5
+ * one place prevents the machine-readable output from silently expanding back to the underlying
6
+ * MCP payload (for example, every component prop and example during discovery).
7
+ */
8
+ import type { RowKind } from '../commands/types';
9
+ export type CompactComponentResult = {
10
+ name: string;
11
+ package?: string;
12
+ propCount: number;
13
+ exampleCount: number;
14
+ followUp?: string;
15
+ };
16
+ export type CompactTokenResult = {
17
+ name: string;
18
+ exampleValue?: string;
19
+ followUp?: string;
20
+ };
21
+ export type CompactIconResult = {
22
+ componentName: string;
23
+ package?: string;
24
+ usage?: string;
25
+ followUp?: string;
26
+ };
27
+ export type CompactDocResult = {
28
+ title: string;
29
+ summary?: string;
30
+ followUp?: string;
31
+ };
32
+ export type CompactResult = CompactComponentResult | CompactTokenResult | CompactIconResult | CompactDocResult;
33
+ /**
34
+ * Project raw MCP rows into the compact records shared by human and JSON output. The function is
35
+ * idempotent so batch rendering can safely receive child envelopes that were already compacted.
36
+ */
37
+ export declare const compactResults: ({ kind, data, showFollowUp, }: {
38
+ kind: RowKind;
39
+ data: unknown;
40
+ showFollowUp?: boolean;
41
+ }) => CompactResult[] | null;
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Compact, human-readable renderers for the structured search/list results.
3
3
  *
4
- * The underlying ADS MCP tools return rich JSON arrays. Dumping that raw is unreadable at a
5
- * terminal, so the default (non-`--json`) output renders a compact one line per result. Full
6
- * structured data remains available via `--json`.
4
+ * The underlying ADS MCP tools return rich JSON arrays. Search and list commands first project
5
+ * those arrays into shared compact records, then both human and `--json` output consume the same
6
+ * data. Exact detail commands retain the full structured payload.
7
7
  *
8
8
  * Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
9
9
  * left to the caller's generic fallback.
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Human-readable renderer for a single ADS design token's detail view.
3
3
  *
4
- * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
5
- * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
6
- * Full structured data remains available via `--json`.
4
+ * Exact token lookups include the full metadata record. The detail view renders its guidance and
5
+ * adds an actionable `token('…')` usage line; the same structured fields remain available via
6
+ * `--json`.
7
7
  */
8
8
  /**
9
9
  * Render a single token payload as a detail view. Returns `null` when the data is not a
@@ -6,7 +6,8 @@ import type { Writer } from './writer';
6
6
  /**
7
7
  * Emit the JSON envelope to stdout.
8
8
  *
9
- * Always pretty-printed for readability; consumers that need compact output can re-serialise.
9
+ * JSON output is pretty-printed for terminal readability. Its retrieval payload stays compact
10
+ * because search and list commands project the MCP response before it reaches this serializer.
10
11
  */
11
12
  export declare const writeJsonEnvelope: ({ envelope, writer, }: {
12
13
  envelope: Envelope;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.7.0",
3
+ "version": "0.8.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",
@@ -31,7 +31,7 @@
31
31
  "release:atlas:promote": "bash scripts/atlas/promote-stable.sh"
32
32
  },
33
33
  "dependencies": {
34
- "@atlaskit/ads-mcp": "^1.7.0",
34
+ "@atlaskit/ads-mcp": "^1.8.0",
35
35
  "@babel/runtime": "^7.0.0",
36
36
  "chalk": "^4.1.2"
37
37
  },