@atlaskit/ads-cli 0.6.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 (38) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +51 -14
  3. package/bin/ads-cli.js +6 -4
  4. package/dist/cjs/cli.js +23 -4
  5. package/dist/cjs/commands/definitions.js +46 -15
  6. package/dist/cjs/commands/normalize-batch-request.js +176 -0
  7. package/dist/cjs/output/compact-results.js +119 -0
  8. package/dist/cjs/output/format-doc-object.js +18 -5
  9. package/dist/cjs/output/format-icon.js +2 -1
  10. package/dist/cjs/output/format-results.js +37 -71
  11. package/dist/cjs/output/format-token.js +19 -5
  12. package/dist/cjs/output/write-json-envelope.js +2 -1
  13. package/dist/es2019/cli.js +23 -4
  14. package/dist/es2019/commands/definitions.js +48 -15
  15. package/dist/es2019/commands/normalize-batch-request.js +142 -0
  16. package/dist/es2019/output/compact-results.js +104 -0
  17. package/dist/es2019/output/format-doc-object.js +12 -4
  18. package/dist/es2019/output/format-icon.js +2 -1
  19. package/dist/es2019/output/format-results.js +37 -66
  20. package/dist/es2019/output/format-token.js +14 -5
  21. package/dist/es2019/output/write-json-envelope.js +2 -1
  22. package/dist/esm/cli.js +23 -4
  23. package/dist/esm/commands/definitions.js +46 -15
  24. package/dist/esm/commands/normalize-batch-request.js +169 -0
  25. package/dist/esm/output/compact-results.js +112 -0
  26. package/dist/esm/output/format-doc-object.js +18 -5
  27. package/dist/esm/output/format-icon.js +2 -1
  28. package/dist/esm/output/format-results.js +37 -71
  29. package/dist/esm/output/format-token.js +19 -5
  30. package/dist/esm/output/write-json-envelope.js +2 -1
  31. package/dist/types/commands/normalize-batch-request.d.ts +16 -0
  32. package/dist/types/commands/types.d.ts +8 -8
  33. package/dist/types/envelope/types.d.ts +3 -2
  34. package/dist/types/output/compact-results.d.ts +41 -0
  35. package/dist/types/output/format-results.d.ts +3 -3
  36. package/dist/types/output/format-token.d.ts +3 -3
  37. package/dist/types/output/write-json-envelope.d.ts +2 -1
  38. package/package.json +2 -2
@@ -0,0 +1,119 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.compactResults = void 0;
8
+ var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
9
+ var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
10
+ 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; }
11
+ 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; }
12
+ /**
13
+ * Shared compact projections for ADS search and list results.
14
+ *
15
+ * Human-readable rows and `--json` responses both consume these records. Keeping the projection in
16
+ * one place prevents the machine-readable output from silently expanding back to the underlying
17
+ * MCP payload (for example, every component prop and example during discovery).
18
+ */
19
+
20
+ var countOf = function countOf(value) {
21
+ return Array.isArray(value) ? value.length : 0;
22
+ };
23
+
24
+ /**
25
+ * Truncate a one-line value so discovery results stay bounded. Exact detail commands preserve the
26
+ * full value.
27
+ */
28
+ var truncateCompactText = function truncateCompactText(text) {
29
+ var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 80;
30
+ var oneLine = text.replace(/\s+/g, ' ').trim();
31
+ return oneLine.length > max ? "".concat(oneLine.slice(0, max - 1).trimEnd(), "\u2026") : oneLine;
32
+ };
33
+ var asRecord = function asRecord(value) {
34
+ return value !== null && (0, _typeof2.default)(value) === 'object' ? value : {};
35
+ };
36
+ var optionalString = function optionalString(value) {
37
+ return typeof value === 'string' && value.length > 0 ? value : undefined;
38
+ };
39
+ var withFollowUp = function withFollowUp(result, showFollowUp, followUp) {
40
+ return showFollowUp ? _objectSpread(_objectSpread({}, result), {}, {
41
+ followUp: followUp
42
+ }) : result;
43
+ };
44
+ var compactComponent = function compactComponent(value, showFollowUp) {
45
+ var _optionalString, _optionalString2;
46
+ var record = asRecord(value);
47
+ var name = (_optionalString = optionalString(record.name)) !== null && _optionalString !== void 0 ? _optionalString : '(unknown)';
48
+ var propCount = typeof record.propCount === 'number' ? record.propCount : countOf(record.props);
49
+ var exampleCount = typeof record.exampleCount === 'number' ? record.exampleCount : countOf(record.examples);
50
+ return withFollowUp(_objectSpread(_objectSpread({
51
+ name: name
52
+ }, optionalString(record.package) ? {
53
+ package: String(record.package)
54
+ } : {}), {}, {
55
+ propCount: propCount,
56
+ exampleCount: exampleCount
57
+ }), showFollowUp, (_optionalString2 = optionalString(record.followUp)) !== null && _optionalString2 !== void 0 ? _optionalString2 : "component ".concat(name));
58
+ };
59
+ var compactToken = function compactToken(value, showFollowUp) {
60
+ var _optionalString3, _optionalString4;
61
+ var record = asRecord(value);
62
+ var name = (_optionalString3 = optionalString(record.name)) !== null && _optionalString3 !== void 0 ? _optionalString3 : '(unknown)';
63
+ var exampleValue = optionalString(record.exampleValue);
64
+ return withFollowUp(_objectSpread({
65
+ name: name
66
+ }, exampleValue ? {
67
+ exampleValue: truncateCompactText(exampleValue)
68
+ } : {}), showFollowUp, (_optionalString4 = optionalString(record.followUp)) !== null && _optionalString4 !== void 0 ? _optionalString4 : "token ".concat(name));
69
+ };
70
+ var compactIcon = function compactIcon(value, showFollowUp) {
71
+ var _optionalString5, _optionalString6;
72
+ var record = asRecord(value);
73
+ var componentName = (_optionalString5 = optionalString(record.componentName)) !== null && _optionalString5 !== void 0 ? _optionalString5 : '(unknown)';
74
+ var usage = optionalString(record.usage);
75
+ return withFollowUp(_objectSpread(_objectSpread({
76
+ componentName: componentName
77
+ }, optionalString(record.package) ? {
78
+ package: String(record.package)
79
+ } : {}), usage ? {
80
+ usage: truncateCompactText(usage)
81
+ } : {}), showFollowUp, (_optionalString6 = optionalString(record.followUp)) !== null && _optionalString6 !== void 0 ? _optionalString6 : "icon ".concat(componentName));
82
+ };
83
+ var compactDoc = function compactDoc(value, showFollowUp) {
84
+ var _optionalString7, _optionalString8;
85
+ var record = asRecord(value);
86
+ var title = (_optionalString7 = optionalString(record.title)) !== null && _optionalString7 !== void 0 ? _optionalString7 : '(unknown)';
87
+ var summary = optionalString(record.summary);
88
+ return withFollowUp(_objectSpread({
89
+ title: title
90
+ }, summary ? {
91
+ summary: truncateCompactText(summary)
92
+ } : {}), showFollowUp, (_optionalString8 = optionalString(record.followUp)) !== null && _optionalString8 !== void 0 ? _optionalString8 : "docs ".concat(title.toLowerCase()));
93
+ };
94
+
95
+ /**
96
+ * Project raw MCP rows into the compact records shared by human and JSON output. The function is
97
+ * idempotent so batch rendering can safely receive child envelopes that were already compacted.
98
+ */
99
+ var compactResults = exports.compactResults = function compactResults(_ref) {
100
+ var kind = _ref.kind,
101
+ data = _ref.data,
102
+ _ref$showFollowUp = _ref.showFollowUp,
103
+ showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp;
104
+ if (!Array.isArray(data)) {
105
+ return null;
106
+ }
107
+ return data.map(function (entry) {
108
+ switch (kind) {
109
+ case 'components':
110
+ return compactComponent(entry, showFollowUp);
111
+ case 'tokens':
112
+ return compactToken(entry, showFollowUp);
113
+ case 'icons':
114
+ return compactIcon(entry, showFollowUp);
115
+ case 'docs':
116
+ return compactDoc(entry, showFollowUp);
117
+ }
118
+ });
119
+ };
@@ -5,8 +5,8 @@ Object.defineProperty(exports, "__esModule", {
5
5
  value: true
6
6
  });
7
7
  exports.formatDocObject = void 0;
8
- var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
8
  var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
9
+ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
10
10
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
11
11
  /**
12
12
  * Human-readable renderer for a single "doc object" payload — the shape returned by the
@@ -46,12 +46,25 @@ var formatListItem = function formatListItem(item) {
46
46
  if (item !== null && (0, _typeof2.default)(item) === 'object') {
47
47
  var record = item;
48
48
  var title = typeof record.title === 'string' ? record.title : null;
49
- var code = ['code', 'before', 'after'].find(function (key) {
49
+ var codeKeys = ['code', 'before', 'after'].filter(function (key) {
50
50
  return typeof record[key] === 'string';
51
51
  });
52
- if (title && code) {
53
- var description = typeof record.description === 'string' ? "\n ".concat(oneLine(record.description)) : '';
54
- return " - ".concat(title).concat(description, "\n ```tsx\n").concat(record[code], "\n ```");
52
+ if (title && codeKeys.length > 0) {
53
+ var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
54
+ var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
55
+ var codeBlocks = codeKeys.flatMap(function (key) {
56
+ return [].concat((0, _toConsumableArray2.default)(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [" ```tsx\n".concat(record[key], "\n ```")]);
57
+ });
58
+ var additionalFields = Object.entries(record).flatMap(function (_ref) {
59
+ var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
60
+ key = _ref2[0],
61
+ value = _ref2[1];
62
+ if (['title', 'description'].concat((0, _toConsumableArray2.default)(codeKeys)).includes(key) || value === null || value === undefined) {
63
+ return [];
64
+ }
65
+ return [" ".concat(humanizeKey(key), ": ").concat(typeof value === 'string' ? oneLine(value) : JSON.stringify(value))];
66
+ });
67
+ return [" - ".concat(title)].concat(description, (0, _toConsumableArray2.default)(codeBlocks), (0, _toConsumableArray2.default)(additionalFields)).join('\n');
55
68
  }
56
69
  if (title) {
57
70
  return " - ".concat(title);
@@ -38,9 +38,10 @@ var formatIcon = exports.formatIcon = function formatIcon(data) {
38
38
  }
39
39
  var sections = [icon.componentName, '='.repeat(icon.componentName.length)];
40
40
  if (icon.package) {
41
+ var _icon$import;
41
42
  sections.push('', "Package: ".concat(icon.package));
42
43
  // The actionable bit: the barrel-correct import for this icon.
43
- sections.push('', 'Import:', " import ".concat(icon.componentName, " from '").concat(icon.package, "';"));
44
+ sections.push('', 'Import:', " ".concat((_icon$import = icon.import) !== null && _icon$import !== void 0 ? _icon$import : "import ".concat(icon.componentName, " from '").concat(icon.package, "';")));
44
45
  }
45
46
  if (icon.usage) {
46
47
  sections.push('', "Usage: ".concat(oneLine(icon.usage)));
@@ -7,37 +7,18 @@ Object.defineProperty(exports, "__esModule", {
7
7
  exports.formatCompactResults = void 0;
8
8
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
9
  var _cliMetadata = require("../commands/cli-metadata");
10
+ var _compactResults = require("./compact-results");
10
11
  /**
11
12
  * Compact, human-readable renderers for the structured search/list results.
12
13
  *
13
- * The underlying ADS MCP tools return rich JSON arrays. Dumping that raw is unreadable at a
14
- * terminal, so the default (non-`--json`) output renders a compact one line per result. Full
15
- * structured data remains available via `--json`.
14
+ * The underlying ADS MCP tools return rich JSON arrays. Search and list commands first project
15
+ * those arrays into shared compact records, then both human and `--json` output consume the same
16
+ * data. Exact detail commands retain the full structured payload.
16
17
  *
17
18
  * Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
18
19
  * left to the caller's generic fallback.
19
20
  */
20
21
 
21
- /**
22
- * A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
23
- * Only the fields the compact view needs are modelled; others are ignored.
24
- */
25
-
26
- /**
27
- * A token result as returned by `searchTokensTool` / `getAllTokensTool`.
28
- */
29
-
30
- /**
31
- * An icon result as returned by `searchIconsTool` / `getAllIconsTool`.
32
- */
33
-
34
- /**
35
- * Count helper that is safe against non-array / missing fields.
36
- */
37
- var countOf = function countOf(value) {
38
- return Array.isArray(value) ? value.length : 0;
39
- };
40
-
41
22
  /**
42
23
  * Pluralise a `count`-prefixed noun, e.g. `1 prop` / `2 props`.
43
24
  */
@@ -46,26 +27,16 @@ var pluralize = function pluralize(count, noun) {
46
27
  };
47
28
 
48
29
  /**
49
- * Truncate a one-line description so compact rows stay on a single line.
50
- */
51
- var truncate = function truncate(text) {
52
- var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 80;
53
- return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
54
- };
55
-
56
- /**
57
- * Append a `→ <invocation> <command> <name>` drill-in hint beneath a row.
30
+ * Append a distribution-specific invocation to a compact row's follow-up command.
58
31
  *
59
32
  * Used for every `search` result, where the natural next step is to view that match in full.
60
33
  * `--all` listings omit it because echoing every row's own name would just be noise.
61
34
  */
62
35
  var withFollowUp = function withFollowUp(_ref) {
63
36
  var line = _ref.line,
64
- command = _ref.command,
65
- name = _ref.name,
66
- showFollowUp = _ref.showFollowUp,
37
+ followUp = _ref.followUp,
67
38
  invocation = _ref.invocation;
68
- return showFollowUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(command, " ").concat(name) : line;
39
+ return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
69
40
  };
70
41
 
71
42
  /**
@@ -75,18 +46,13 @@ var withFollowUp = function withFollowUp(_ref) {
75
46
  * (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
76
47
  * context and a tag would just be noise.
77
48
  */
78
- var formatComponentLine = function formatComponentLine(component, showFollowUp, invocation) {
79
- var _component$name;
80
- var name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
49
+ var formatComponentLine = function formatComponentLine(component, invocation) {
50
+ var name = component.name;
81
51
  var pkg = component.package ? " ".concat(component.package) : '';
82
- var propCount = countOf(component.props);
83
- var exampleCount = countOf(component.examples);
84
- var meta = [pluralize(propCount, 'prop'), pluralize(exampleCount, 'example')].join(', ');
52
+ var meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
85
53
  return withFollowUp({
86
54
  line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
87
- command: 'component',
88
- name: name,
89
- showFollowUp: showFollowUp,
55
+ followUp: component.followUp,
90
56
  invocation: invocation
91
57
  });
92
58
  };
@@ -94,17 +60,11 @@ var formatComponentLine = function formatComponentLine(component, showFollowUp,
94
60
  /**
95
61
  * Render one token as a compact `name = value` line.
96
62
  */
97
- var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp, invocation) {
98
- var _tokenResult$name;
99
- var name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
100
- // Some token values (e.g. motion easing curves) are very long; truncate so each token stays
101
- // on a single readable line. The full value is always available via `--json`.
102
- var line = tokenResult.exampleValue ? "".concat(name, " = ").concat(truncate(tokenResult.exampleValue)) : name;
63
+ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
64
+ var line = tokenResult.exampleValue ? "".concat(tokenResult.name, " = ").concat(tokenResult.exampleValue) : tokenResult.name;
103
65
  return withFollowUp({
104
66
  line: line,
105
- command: 'token',
106
- name: name,
107
- showFollowUp: showFollowUp,
67
+ followUp: tokenResult.followUp,
108
68
  invocation: invocation
109
69
  });
110
70
  };
@@ -112,16 +72,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp, invoca
112
72
  /**
113
73
  * Render one icon as a compact line with its import package and short usage note.
114
74
  */
115
- var formatIconLine = function formatIconLine(iconResult, showFollowUp, invocation) {
116
- var _iconResult$component;
117
- var name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
75
+ var formatIconLine = function formatIconLine(iconResult, invocation) {
76
+ var name = iconResult.componentName;
118
77
  var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
119
- var usage = iconResult.usage ? " \u2014 ".concat(truncate(iconResult.usage)) : '';
78
+ var usage = iconResult.usage ? " \u2014 ".concat(iconResult.usage) : '';
120
79
  return withFollowUp({
121
80
  line: "".concat(name).concat(pkg).concat(usage),
122
- command: 'icon',
123
- name: name,
124
- showFollowUp: showFollowUp,
81
+ followUp: iconResult.followUp,
125
82
  invocation: invocation
126
83
  });
127
84
  };
@@ -129,10 +86,14 @@ var formatIconLine = function formatIconLine(iconResult, showFollowUp, invocatio
129
86
  /**
130
87
  * Render one foundations-document match without dumping its full Markdown body.
131
88
  */
132
- var formatDocLine = function formatDocLine(doc, showFollowUp, invocation) {
89
+ var formatDocLine = function formatDocLine(doc, invocation) {
133
90
  var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
134
91
  var line = "".concat(doc.title).concat(summary);
135
- return showFollowUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(doc.followUp) : line;
92
+ return withFollowUp({
93
+ line: line,
94
+ followUp: doc.followUp,
95
+ invocation: invocation
96
+ });
136
97
  };
137
98
 
138
99
  /**
@@ -149,26 +110,31 @@ var formatCompactResults = exports.formatCompactResults = function formatCompact
149
110
  showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
150
111
  _ref2$invocation = _ref2.invocation,
151
112
  invocation = _ref2$invocation === void 0 ? _cliMetadata.CLI_BIN_NAME : _ref2$invocation;
152
- if (!Array.isArray(data)) {
113
+ var compact = (0, _compactResults.compactResults)({
114
+ kind: kind,
115
+ data: data,
116
+ showFollowUp: showFollowUp
117
+ });
118
+ if (compact === null) {
153
119
  return null;
154
120
  }
155
- if (data.length === 0) {
121
+ if (compact.length === 0) {
156
122
  return 'No results.';
157
123
  }
158
- var lines = data.map(function (entry) {
124
+ var lines = compact.map(function (entry) {
159
125
  switch (kind) {
160
126
  case 'components':
161
- return formatComponentLine(entry, showFollowUp, invocation);
127
+ return formatComponentLine(entry, invocation);
162
128
  case 'tokens':
163
- return formatTokenLine(entry, showFollowUp, invocation);
129
+ return formatTokenLine(entry, invocation);
164
130
  case 'icons':
165
- return formatIconLine(entry, showFollowUp, invocation);
131
+ return formatIconLine(entry, invocation);
166
132
  case 'docs':
167
- return formatDocLine(entry, showFollowUp, invocation);
133
+ return formatDocLine(entry, invocation);
168
134
  default:
169
135
  return JSON.stringify(entry);
170
136
  }
171
137
  });
172
- var header = "Results (".concat(data.length, "):");
138
+ var header = "Results (".concat(compact.length, "):");
173
139
  return [header, ''].concat((0, _toConsumableArray2.default)(lines)).join('\n');
174
140
  };
@@ -5,25 +5,31 @@ Object.defineProperty(exports, "__esModule", {
5
5
  value: true
6
6
  });
7
7
  exports.formatToken = void 0;
8
+ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
8
9
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
9
10
  /**
10
11
  * Human-readable renderer for a single ADS design token's detail view.
11
12
  *
12
- * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
13
- * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
14
- * Full structured data remains available via `--json`.
13
+ * Exact token lookups include the full metadata record. The detail view renders its guidance and
14
+ * adds an actionable `token('…')` usage line; the same structured fields remain available via
15
+ * `--json`.
15
16
  */
16
17
 
17
18
  /**
18
19
  * A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
19
20
  */
20
21
 
22
+ var oneLine = function oneLine(text) {
23
+ return text.replace(/\s+/g, ' ').trim();
24
+ };
25
+
21
26
  /**
22
27
  * Render a single token payload as a detail view. Returns `null` when the data is not a
23
28
  * recognisable token object, so the caller can fall back to generic rendering.
24
29
  */
25
30
  var formatToken = exports.formatToken = function formatToken(data) {
26
- // `token <name>` reuses token search with limit 1, so `data` is a one-element array.
31
+ var _token$usageGuideline, _token$usageGuideline2, _token$usage;
32
+ // `token <name>` returns a ranked candidate array; the command transform selects the detail.
27
33
  var token = Array.isArray(data) ? data[0] : data;
28
34
  if (!token || (0, _typeof2.default)(token) !== 'object' || typeof token.name !== 'string') {
29
35
  return null;
@@ -32,8 +38,16 @@ var formatToken = exports.formatToken = function formatToken(data) {
32
38
  if (token.exampleValue) {
33
39
  sections.push('', "Example value: ".concat(token.exampleValue));
34
40
  }
41
+ if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
42
+ sections.push('', 'Guidelines:', " ".concat(oneLine(token.usageGuidelines.usage)));
43
+ }
44
+ if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline2 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline2 !== void 0 && _token$usageGuideline2.length) {
45
+ sections.push.apply(sections, ['', 'CSS properties:'].concat((0, _toConsumableArray2.default)(token.usageGuidelines.cssProperties.map(function (item) {
46
+ return " ".concat(item);
47
+ }))));
48
+ }
35
49
 
36
50
  // The actionable bit: how to consume the token from `@atlaskit/tokens`.
37
- sections.push('', 'Usage:', " token('".concat(token.name, "')"));
51
+ sections.push('', 'Usage:', " ".concat((_token$usage = token.usage) !== null && _token$usage !== void 0 ? _token$usage : "token('".concat(token.name, "')")));
38
52
  return sections.join('\n');
39
53
  };
@@ -11,7 +11,8 @@ exports.writeJsonEnvelope = void 0;
11
11
  /**
12
12
  * Emit the JSON envelope to stdout.
13
13
  *
14
- * Always pretty-printed for readability; consumers that need compact output can re-serialise.
14
+ * JSON output is pretty-printed for terminal readability. Its retrieval payload stays compact
15
+ * because search and list commands project the MCP response before it reaches this serializer.
15
16
  */
16
17
  var writeJsonEnvelope = exports.writeJsonEnvelope = function writeJsonEnvelope(_ref) {
17
18
  var envelope = _ref.envelope,
@@ -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 { compactResults } from './output/compact-results';
20
21
  import { createDocSearchResults } from './output/create-doc-search-results';
21
22
  import { isDisambiguation } from './output/disambiguation';
22
23
  import { formatGroupedResults } from './output/format-grouped-results';
@@ -56,7 +57,10 @@ const buildHelpText = invocation => {
56
57
  comment: 'unified: components, tokens, icons & docs'
57
58
  }, {
58
59
  command: 'batch --command search button --type icon --command token space.200',
59
- comment: 'independent commands in one process'
60
+ comment: 'canonical tokenized batch form'
61
+ }, {
62
+ command: 'batch --command "search button" --type icon --command "token space.200"',
63
+ comment: 'complete-string compatibility form'
60
64
  }, {
61
65
  command: 'search button --type component'
62
66
  }, {
@@ -296,11 +300,18 @@ const renderSingleResult = ({
296
300
  input
297
301
  }) : result.data;
298
302
  if (json) {
303
+ var _command$resultKind2, _compactResults;
304
+ const resultKind = (_command$resultKind2 = command.resultKind) === null || _command$resultKind2 === void 0 ? void 0 : _command$resultKind2.call(command, input);
305
+ const outputData = resultKind ? (_compactResults = compactResults({
306
+ kind: resultKind,
307
+ data,
308
+ showFollowUp: command.name === 'search'
309
+ })) !== null && _compactResults !== void 0 ? _compactResults : data : data;
299
310
  writeJsonEnvelope({
300
311
  envelope: createSuccessEnvelope({
301
312
  envelopeType: command.envelopeType(input),
302
313
  command: command.name,
303
- data,
314
+ data: outputData,
304
315
  meta
305
316
  }),
306
317
  writer
@@ -533,6 +544,14 @@ const renderGroupedResult = ({
533
544
  }
534
545
  return ExitCode.NotFound;
535
546
  }
547
+ const compactGrouped = Object.fromEntries(['components', 'tokens', 'icons', 'docs'].map(kind => {
548
+ var _compactResults2, _grouped$kind;
549
+ return [kind, (_compactResults2 = compactResults({
550
+ kind,
551
+ data: (_grouped$kind = grouped[kind]) !== null && _grouped$kind !== void 0 ? _grouped$kind : [],
552
+ showFollowUp: true
553
+ })) !== null && _compactResults2 !== void 0 ? _compactResults2 : []];
554
+ }));
536
555
  if (json) {
537
556
  writeJsonEnvelope({
538
557
  envelope: createSuccessEnvelope({
@@ -540,7 +559,7 @@ const renderGroupedResult = ({
540
559
  command: command.name,
541
560
  // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
542
561
  // counted per group), so `count` is the combined total across groups.
543
- data: grouped,
562
+ data: compactGrouped,
544
563
  meta: {
545
564
  ...meta,
546
565
  count: totalCount
@@ -551,7 +570,7 @@ const renderGroupedResult = ({
551
570
  return ExitCode.Ok;
552
571
  }
553
572
  writer.out(formatGroupedResults({
554
- groups: grouped,
573
+ groups: compactGrouped,
555
574
  totalCount,
556
575
  invocation
557
576
  }));
@@ -28,6 +28,7 @@ import { formatToken } from '../output/format-token';
28
28
  import { parseLintRuleRecords } from '../output/parse-lint-rule-records';
29
29
  import { buildManifest } from './build-manifest';
30
30
  import { getVersion } from './get-version';
31
+ import { normalizeBatchRequest } from './normalize-batch-request';
31
32
  /**
32
33
  * Shared `--limit` flag definition reused across the search-style commands.
33
34
  */
@@ -274,6 +275,30 @@ const EXAMPLE_NAME = {
274
275
  icons: 'AddIcon'
275
276
  };
276
277
 
278
+ /**
279
+ * Add the actionable fields that exact human detail views derive from the raw record. Including
280
+ * them in JSON keeps both representations content-equivalent without requiring consumers to know
281
+ * ADS import or token-call conventions.
282
+ */
283
+ const addActionableDetail = (kind, item) => {
284
+ if (kind === 'tokens') {
285
+ const name = itemFields.tokens.nameOf(item);
286
+ return name ? {
287
+ ...item,
288
+ usage: `token('${name}')`
289
+ } : item;
290
+ }
291
+ if (kind === 'icons') {
292
+ const componentName = itemFields.icons.nameOf(item);
293
+ const packageName = typeof item.package === 'string' ? item.package : undefined;
294
+ return componentName && packageName ? {
295
+ ...item,
296
+ import: `import ${componentName} from '${packageName}';`
297
+ } : item;
298
+ }
299
+ return item;
300
+ };
301
+
277
302
  /**
278
303
  * Build one of the singular item commands (`component <name>`, `token <name>`, `icon <name>`).
279
304
  *
@@ -342,11 +367,11 @@ const makeItemCommand = ({
342
367
  // Prefer an exact, case-insensitive name match from the tool's own results.
343
368
  const exact = candidates.find(item => nameOf(item).toLowerCase() === query.toLowerCase());
344
369
  if (exact) {
345
- return exact;
370
+ return addActionableDetail(kind, exact);
346
371
  }
347
372
  // A single candidate is unambiguous — show it.
348
373
  if (candidates.length === 1) {
349
- return candidates[0];
374
+ return addActionableDetail(kind, candidates[0]);
350
375
  }
351
376
  // Otherwise do not guess: surface a disambiguation list.
352
377
  return {
@@ -386,7 +411,11 @@ const makeItemCommand = ({
386
411
  return singleTool({
387
412
  importPath: searchTool.importPath,
388
413
  handlerName: searchTool.handlerName,
389
- args: {
414
+ args: kind === 'tokens' ? {
415
+ terms: [name_],
416
+ limit: ITEM_LOOKUP_LIMIT,
417
+ includeMetadata: true
418
+ } : {
390
419
  terms: [name_],
391
420
  limit: ITEM_LOOKUP_LIMIT
392
421
  },
@@ -446,9 +475,9 @@ const resolveUnifiedSearch = input => {
446
475
  };
447
476
 
448
477
  /**
449
- * Split a batch invocation into argv groups introduced by repeated `--command` flags. The groups
450
- * remain tokenized, so child commands can be routed through the existing parser without evaluating
451
- * shell strings.
478
+ * Split a batch invocation into argv groups introduced by repeated `--command` flags. Canonical
479
+ * tokenized groups remain unchanged; a complete request in the first token is safely normalized
480
+ * to argv without evaluating shell strings.
452
481
  */
453
482
  const resolveBatch = input => {
454
483
  var _input$rawArgs;
@@ -477,9 +506,11 @@ const resolveBatch = input => {
477
506
  error: '`--command` must be followed by a non-empty command request.'
478
507
  };
479
508
  }
480
- requests.push({
481
- argv: current
482
- });
509
+ const normalized = normalizeBatchRequest(current);
510
+ if ('error' in normalized) {
511
+ return normalized;
512
+ }
513
+ requests.push(normalized);
483
514
  current = [];
484
515
  continue;
485
516
  }
@@ -490,9 +521,11 @@ const resolveBatch = input => {
490
521
  error: '`--command` must be followed by a non-empty command request.'
491
522
  };
492
523
  }
493
- requests.push({
494
- argv: current
495
- });
524
+ const normalized = normalizeBatchRequest(current);
525
+ if ('error' in normalized) {
526
+ return normalized;
527
+ }
528
+ requests.push(normalized);
496
529
  return {
497
530
  tools: [],
498
531
  batch: requests,
@@ -562,15 +595,15 @@ export const commands = [{
562
595
  }
563
596
  }, {
564
597
  name: 'batch',
565
- description: 'Run multiple ADS CLI queries, including different command types, in one process.',
598
+ description: 'Run multiple ADS CLI queries in one process. Tokenized child requests are canonical; complete-request strings are also accepted.',
566
599
  usage: 'batch [--json] --command <command> [args...] [--command <command> [args...]]...',
567
600
  arguments: [],
568
601
  flags: [{
569
602
  name: 'command',
570
603
  type: 'string[]',
571
- description: 'A child command name followed by its arguments. Repeat once per child command.'
604
+ description: 'Canonical: a tokenized child command and its arguments. A complete quoted request is also accepted. Repeat once per child command.'
572
605
  }],
573
- examples: ['batch --command search button --type icon --command token space.200', 'batch --json --command component Button --command docs spacing'],
606
+ examples: ['batch --command search button --type icon --command token space.200', 'batch --command "search button" --type icon --command "token space.200"', 'batch --json --command component Button --command docs spacing'],
574
607
  responseTypes: ['ads-cli/batch'],
575
608
  envelopeType: () => 'batch',
576
609
  resolve: resolveBatch