@atlaskit/ads-cli 0.7.0 → 0.8.1

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 +70 -0
  2. package/README.md +35 -7
  3. package/bin/ads-cli.js +6 -4
  4. package/dist/cjs/cli.js +18 -2
  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 +18 -2
  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 +18 -2
  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
@@ -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';
@@ -299,11 +300,18 @@ const renderSingleResult = ({
299
300
  input
300
301
  }) : result.data;
301
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;
302
310
  writeJsonEnvelope({
303
311
  envelope: createSuccessEnvelope({
304
312
  envelopeType: command.envelopeType(input),
305
313
  command: command.name,
306
- data,
314
+ data: outputData,
307
315
  meta
308
316
  }),
309
317
  writer
@@ -537,13 +545,21 @@ const renderGroupedResult = ({
537
545
  return ExitCode.NotFound;
538
546
  }
539
547
  if (json) {
548
+ const compactGrouped = Object.fromEntries(['components', 'tokens', 'icons', 'docs'].map(kind => {
549
+ var _compactResults2, _grouped$kind;
550
+ return [kind, (_compactResults2 = compactResults({
551
+ kind,
552
+ data: (_grouped$kind = grouped[kind]) !== null && _grouped$kind !== void 0 ? _grouped$kind : [],
553
+ showFollowUp: true
554
+ })) !== null && _compactResults2 !== void 0 ? _compactResults2 : []];
555
+ }));
540
556
  writeJsonEnvelope({
541
557
  envelope: createSuccessEnvelope({
542
558
  envelopeType: command.envelopeType(input),
543
559
  command: command.name,
544
560
  // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
545
561
  // counted per group), so `count` is the combined total across groups.
546
- data: grouped,
562
+ data: compactGrouped,
547
563
  meta: {
548
564
  ...meta,
549
565
  count: totalCount
@@ -275,6 +275,30 @@ const EXAMPLE_NAME = {
275
275
  icons: 'AddIcon'
276
276
  };
277
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
+
278
302
  /**
279
303
  * Build one of the singular item commands (`component <name>`, `token <name>`, `icon <name>`).
280
304
  *
@@ -343,11 +367,11 @@ const makeItemCommand = ({
343
367
  // Prefer an exact, case-insensitive name match from the tool's own results.
344
368
  const exact = candidates.find(item => nameOf(item).toLowerCase() === query.toLowerCase());
345
369
  if (exact) {
346
- return exact;
370
+ return addActionableDetail(kind, exact);
347
371
  }
348
372
  // A single candidate is unambiguous — show it.
349
373
  if (candidates.length === 1) {
350
- return candidates[0];
374
+ return addActionableDetail(kind, candidates[0]);
351
375
  }
352
376
  // Otherwise do not guess: surface a disambiguation list.
353
377
  return {
@@ -387,7 +411,11 @@ const makeItemCommand = ({
387
411
  return singleTool({
388
412
  importPath: searchTool.importPath,
389
413
  handlerName: searchTool.handlerName,
390
- args: {
414
+ args: kind === 'tokens' ? {
415
+ terms: [name_],
416
+ limit: ITEM_LOOKUP_LIMIT,
417
+ includeMetadata: true
418
+ } : {
391
419
  terms: [name_],
392
420
  limit: ITEM_LOOKUP_LIMIT
393
421
  },
@@ -0,0 +1,104 @@
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
+
9
+ const countOf = value => Array.isArray(value) ? value.length : 0;
10
+
11
+ /**
12
+ * Truncate a one-line value so discovery results stay bounded. Exact detail commands preserve the
13
+ * full value.
14
+ */
15
+ const truncateCompactText = (text, max = 80) => {
16
+ const oneLine = text.replace(/\s+/g, ' ').trim();
17
+ return oneLine.length > max ? `${oneLine.slice(0, max - 1).trimEnd()}…` : oneLine;
18
+ };
19
+ const asRecord = value => value !== null && typeof value === 'object' ? value : {};
20
+ const optionalString = value => typeof value === 'string' && value.length > 0 ? value : undefined;
21
+ const withFollowUp = (result, showFollowUp, followUp) => showFollowUp ? {
22
+ ...result,
23
+ followUp
24
+ } : result;
25
+ const compactComponent = (value, showFollowUp) => {
26
+ var _optionalString, _optionalString2;
27
+ const record = asRecord(value);
28
+ const name = (_optionalString = optionalString(record.name)) !== null && _optionalString !== void 0 ? _optionalString : '(unknown)';
29
+ const propCount = typeof record.propCount === 'number' ? record.propCount : countOf(record.props);
30
+ const exampleCount = typeof record.exampleCount === 'number' ? record.exampleCount : countOf(record.examples);
31
+ return withFollowUp({
32
+ name,
33
+ ...(optionalString(record.package) ? {
34
+ package: String(record.package)
35
+ } : {}),
36
+ propCount,
37
+ exampleCount
38
+ }, showFollowUp, (_optionalString2 = optionalString(record.followUp)) !== null && _optionalString2 !== void 0 ? _optionalString2 : `component ${name}`);
39
+ };
40
+ const compactToken = (value, showFollowUp) => {
41
+ var _optionalString3, _optionalString4;
42
+ const record = asRecord(value);
43
+ const name = (_optionalString3 = optionalString(record.name)) !== null && _optionalString3 !== void 0 ? _optionalString3 : '(unknown)';
44
+ const exampleValue = optionalString(record.exampleValue);
45
+ return withFollowUp({
46
+ name,
47
+ ...(exampleValue ? {
48
+ exampleValue: truncateCompactText(exampleValue)
49
+ } : {})
50
+ }, showFollowUp, (_optionalString4 = optionalString(record.followUp)) !== null && _optionalString4 !== void 0 ? _optionalString4 : `token ${name}`);
51
+ };
52
+ const compactIcon = (value, showFollowUp) => {
53
+ var _optionalString5, _optionalString6;
54
+ const record = asRecord(value);
55
+ const componentName = (_optionalString5 = optionalString(record.componentName)) !== null && _optionalString5 !== void 0 ? _optionalString5 : '(unknown)';
56
+ const usage = optionalString(record.usage);
57
+ return withFollowUp({
58
+ componentName,
59
+ ...(optionalString(record.package) ? {
60
+ package: String(record.package)
61
+ } : {}),
62
+ ...(usage ? {
63
+ usage: truncateCompactText(usage)
64
+ } : {})
65
+ }, showFollowUp, (_optionalString6 = optionalString(record.followUp)) !== null && _optionalString6 !== void 0 ? _optionalString6 : `icon ${componentName}`);
66
+ };
67
+ const compactDoc = (value, showFollowUp) => {
68
+ var _optionalString7, _optionalString8;
69
+ const record = asRecord(value);
70
+ const title = (_optionalString7 = optionalString(record.title)) !== null && _optionalString7 !== void 0 ? _optionalString7 : '(unknown)';
71
+ const summary = optionalString(record.summary);
72
+ return withFollowUp({
73
+ title,
74
+ ...(summary ? {
75
+ summary: truncateCompactText(summary)
76
+ } : {})
77
+ }, showFollowUp, (_optionalString8 = optionalString(record.followUp)) !== null && _optionalString8 !== void 0 ? _optionalString8 : `docs ${title.toLowerCase()}`);
78
+ };
79
+
80
+ /**
81
+ * Project raw MCP rows into the compact records shared by human and JSON output. The function is
82
+ * idempotent so batch rendering can safely receive child envelopes that were already compacted.
83
+ */
84
+ export const compactResults = ({
85
+ kind,
86
+ data,
87
+ showFollowUp = false
88
+ }) => {
89
+ if (!Array.isArray(data)) {
90
+ return null;
91
+ }
92
+ return data.map(entry => {
93
+ switch (kind) {
94
+ case 'components':
95
+ return compactComponent(entry, showFollowUp);
96
+ case 'tokens':
97
+ return compactToken(entry, showFollowUp);
98
+ case 'icons':
99
+ return compactIcon(entry, showFollowUp);
100
+ case 'docs':
101
+ return compactDoc(entry, showFollowUp);
102
+ }
103
+ });
104
+ };
@@ -30,10 +30,18 @@ const formatListItem = item => {
30
30
  if (item !== null && typeof item === 'object') {
31
31
  const record = item;
32
32
  const title = typeof record.title === 'string' ? record.title : null;
33
- const code = ['code', 'before', 'after'].find(key => typeof record[key] === 'string');
34
- if (title && code) {
35
- const description = typeof record.description === 'string' ? `\n ${oneLine(record.description)}` : '';
36
- return ` - ${title}${description}\n \`\`\`tsx\n${record[code]}\n \`\`\``;
33
+ const codeKeys = ['code', 'before', 'after'].filter(key => typeof record[key] === 'string');
34
+ if (title && codeKeys.length > 0) {
35
+ const description = typeof record.description === 'string' ? [` ${oneLine(record.description)}`] : [];
36
+ const labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
37
+ const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []), ` \`\`\`tsx\n${record[key]}\n \`\`\``]);
38
+ const additionalFields = Object.entries(record).flatMap(([key, value]) => {
39
+ if (['title', 'description', ...codeKeys].includes(key) || value === null || value === undefined) {
40
+ return [];
41
+ }
42
+ return [` ${humanizeKey(key)}: ${typeof value === 'string' ? oneLine(value) : JSON.stringify(value)}`];
43
+ });
44
+ return [` - ${title}`, ...description, ...codeBlocks, ...additionalFields].join('\n');
37
45
  }
38
46
  if (title) {
39
47
  return ` - ${title}`;
@@ -28,9 +28,10 @@ export const formatIcon = data => {
28
28
  }
29
29
  const sections = [icon.componentName, '='.repeat(icon.componentName.length)];
30
30
  if (icon.package) {
31
+ var _icon$import;
31
32
  sections.push('', `Package: ${icon.package}`);
32
33
  // The actionable bit: the barrel-correct import for this icon.
33
- sections.push('', 'Import:', ` import ${icon.componentName} from '${icon.package}';`);
34
+ sections.push('', 'Import:', ` ${(_icon$import = icon.import) !== null && _icon$import !== void 0 ? _icon$import : `import ${icon.componentName} from '${icon.package}';`}`);
34
35
  }
35
36
  if (icon.usage) {
36
37
  sections.push('', `Usage: ${oneLine(icon.usage)}`);
@@ -1,33 +1,16 @@
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.
10
10
  */
11
11
 
12
12
  import { CLI_BIN_NAME } from '../commands/cli-metadata';
13
-
14
- /**
15
- * A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
16
- * Only the fields the compact view needs are modelled; others are ignored.
17
- */
18
-
19
- /**
20
- * A token result as returned by `searchTokensTool` / `getAllTokensTool`.
21
- */
22
-
23
- /**
24
- * An icon result as returned by `searchIconsTool` / `getAllIconsTool`.
25
- */
26
-
27
- /**
28
- * Count helper that is safe against non-array / missing fields.
29
- */
30
- const countOf = value => Array.isArray(value) ? value.length : 0;
13
+ import { compactResults } from './compact-results';
31
14
 
32
15
  /**
33
16
  * Pluralise a `count`-prefixed noun, e.g. `1 prop` / `2 props`.
@@ -35,23 +18,16 @@ const countOf = value => Array.isArray(value) ? value.length : 0;
35
18
  const pluralize = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
36
19
 
37
20
  /**
38
- * Truncate a one-line description so compact rows stay on a single line.
39
- */
40
- const truncate = (text, max = 80) => text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
41
-
42
- /**
43
- * Append a `→ <invocation> <command> <name>` drill-in hint beneath a row.
21
+ * Append a distribution-specific invocation to a compact row's follow-up command.
44
22
  *
45
23
  * Used for every `search` result, where the natural next step is to view that match in full.
46
24
  * `--all` listings omit it because echoing every row's own name would just be noise.
47
25
  */
48
26
  const withFollowUp = ({
49
27
  line,
50
- command,
51
- name,
52
- showFollowUp,
28
+ followUp,
53
29
  invocation
54
- }) => showFollowUp ? `${line}\n → ${invocation} ${command} ${name}` : line;
30
+ }) => followUp ? `${line}\n → ${invocation} ${followUp}` : line;
55
31
 
56
32
  /**
57
33
  * Render one component as a compact line.
@@ -60,18 +36,13 @@ const withFollowUp = ({
60
36
  * (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
61
37
  * context and a tag would just be noise.
62
38
  */
63
- const formatComponentLine = (component, showFollowUp, invocation) => {
64
- var _component$name;
65
- const name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
39
+ const formatComponentLine = (component, invocation) => {
40
+ const name = component.name;
66
41
  const pkg = component.package ? ` ${component.package}` : '';
67
- const propCount = countOf(component.props);
68
- const exampleCount = countOf(component.examples);
69
- const meta = [pluralize(propCount, 'prop'), pluralize(exampleCount, 'example')].join(', ');
42
+ const meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
70
43
  return withFollowUp({
71
44
  line: `${name}${pkg} (${meta})`,
72
- command: 'component',
73
- name,
74
- showFollowUp,
45
+ followUp: component.followUp,
75
46
  invocation
76
47
  });
77
48
  };
@@ -79,17 +50,11 @@ const formatComponentLine = (component, showFollowUp, invocation) => {
79
50
  /**
80
51
  * Render one token as a compact `name = value` line.
81
52
  */
82
- const formatTokenLine = (tokenResult, showFollowUp, invocation) => {
83
- var _tokenResult$name;
84
- const name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
85
- // Some token values (e.g. motion easing curves) are very long; truncate so each token stays
86
- // on a single readable line. The full value is always available via `--json`.
87
- const line = tokenResult.exampleValue ? `${name} = ${truncate(tokenResult.exampleValue)}` : name;
53
+ const formatTokenLine = (tokenResult, invocation) => {
54
+ const line = tokenResult.exampleValue ? `${tokenResult.name} = ${tokenResult.exampleValue}` : tokenResult.name;
88
55
  return withFollowUp({
89
56
  line,
90
- command: 'token',
91
- name,
92
- showFollowUp,
57
+ followUp: tokenResult.followUp,
93
58
  invocation
94
59
  });
95
60
  };
@@ -97,16 +62,13 @@ const formatTokenLine = (tokenResult, showFollowUp, invocation) => {
97
62
  /**
98
63
  * Render one icon as a compact line with its import package and short usage note.
99
64
  */
100
- const formatIconLine = (iconResult, showFollowUp, invocation) => {
101
- var _iconResult$component;
102
- const name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
65
+ const formatIconLine = (iconResult, invocation) => {
66
+ const name = iconResult.componentName;
103
67
  const pkg = iconResult.package ? ` ${iconResult.package}` : '';
104
- const usage = iconResult.usage ? ` — ${truncate(iconResult.usage)}` : '';
68
+ const usage = iconResult.usage ? ` — ${iconResult.usage}` : '';
105
69
  return withFollowUp({
106
70
  line: `${name}${pkg}${usage}`,
107
- command: 'icon',
108
- name,
109
- showFollowUp,
71
+ followUp: iconResult.followUp,
110
72
  invocation
111
73
  });
112
74
  };
@@ -114,10 +76,14 @@ const formatIconLine = (iconResult, showFollowUp, invocation) => {
114
76
  /**
115
77
  * Render one foundations-document match without dumping its full Markdown body.
116
78
  */
117
- const formatDocLine = (doc, showFollowUp, invocation) => {
79
+ const formatDocLine = (doc, invocation) => {
118
80
  const summary = doc.summary ? ` — ${doc.summary}` : '';
119
81
  const line = `${doc.title}${summary}`;
120
- return showFollowUp ? `${line}\n → ${invocation} ${doc.followUp}` : line;
82
+ return withFollowUp({
83
+ line,
84
+ followUp: doc.followUp,
85
+ invocation
86
+ });
121
87
  };
122
88
 
123
89
  /**
@@ -133,26 +99,31 @@ export const formatCompactResults = ({
133
99
  showFollowUp = false,
134
100
  invocation = CLI_BIN_NAME
135
101
  }) => {
136
- if (!Array.isArray(data)) {
102
+ const compact = compactResults({
103
+ kind,
104
+ data,
105
+ showFollowUp
106
+ });
107
+ if (compact === null) {
137
108
  return null;
138
109
  }
139
- if (data.length === 0) {
110
+ if (compact.length === 0) {
140
111
  return 'No results.';
141
112
  }
142
- const lines = data.map(entry => {
113
+ const lines = compact.map(entry => {
143
114
  switch (kind) {
144
115
  case 'components':
145
- return formatComponentLine(entry, showFollowUp, invocation);
116
+ return formatComponentLine(entry, invocation);
146
117
  case 'tokens':
147
- return formatTokenLine(entry, showFollowUp, invocation);
118
+ return formatTokenLine(entry, invocation);
148
119
  case 'icons':
149
- return formatIconLine(entry, showFollowUp, invocation);
120
+ return formatIconLine(entry, invocation);
150
121
  case 'docs':
151
- return formatDocLine(entry, showFollowUp, invocation);
122
+ return formatDocLine(entry, invocation);
152
123
  default:
153
124
  return JSON.stringify(entry);
154
125
  }
155
126
  });
156
- const header = `Results (${data.length}):`;
127
+ const header = `Results (${compact.length}):`;
157
128
  return [header, '', ...lines].join('\n');
158
129
  };
@@ -1,21 +1,24 @@
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
  /**
10
10
  * A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
11
11
  */
12
12
 
13
+ const oneLine = text => text.replace(/\s+/g, ' ').trim();
14
+
13
15
  /**
14
16
  * Render a single token payload as a detail view. Returns `null` when the data is not a
15
17
  * recognisable token object, so the caller can fall back to generic rendering.
16
18
  */
17
19
  export const formatToken = data => {
18
- // `token <name>` reuses token search with limit 1, so `data` is a one-element array.
20
+ var _token$usageGuideline, _token$usageGuideline2, _token$usageGuideline3, _token$usage;
21
+ // `token <name>` returns a ranked candidate array; the command transform selects the detail.
19
22
  const token = Array.isArray(data) ? data[0] : data;
20
23
  if (!token || typeof token !== 'object' || typeof token.name !== 'string') {
21
24
  return null;
@@ -24,8 +27,14 @@ export const formatToken = data => {
24
27
  if (token.exampleValue) {
25
28
  sections.push('', `Example value: ${token.exampleValue}`);
26
29
  }
30
+ if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
31
+ sections.push('', 'Guidelines:', ` ${oneLine(token.usageGuidelines.usage)}`);
32
+ }
33
+ if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline3 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline3 !== void 0 && _token$usageGuideline3.length) {
34
+ sections.push('', 'CSS properties:', ...token.usageGuidelines.cssProperties.map(item => ` ${item}`));
35
+ }
27
36
 
28
37
  // The actionable bit: how to consume the token from `@atlaskit/tokens`.
29
- sections.push('', 'Usage:', ` token('${token.name}')`);
38
+ sections.push('', 'Usage:', ` ${(_token$usage = token.usage) !== null && _token$usage !== void 0 ? _token$usage : `token('${token.name}')`}`);
30
39
  return sections.join('\n');
31
40
  };
@@ -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 const writeJsonEnvelope = ({
11
12
  envelope,
package/dist/esm/cli.js CHANGED
@@ -27,6 +27,7 @@ import { importToolHandler } from './commands/import-tool-handler';
27
27
  import { runTool } from './commands/run-tool';
28
28
  import { createErrorEnvelope } from './envelope/create-error-envelope';
29
29
  import { createSuccessEnvelope } from './envelope/create-success-envelope';
30
+ import { compactResults } from './output/compact-results';
30
31
  import { createDocSearchResults } from './output/create-doc-search-results';
31
32
  import { isDisambiguation } from './output/disambiguation';
32
33
  import { formatGroupedResults } from './output/format-grouped-results';
@@ -340,11 +341,18 @@ var renderSingleResult = function renderSingleResult(_ref8) {
340
341
  input: input
341
342
  }) : result.data;
342
343
  if (json) {
344
+ var _command$resultKind2, _compactResults;
345
+ var resultKind = (_command$resultKind2 = command.resultKind) === null || _command$resultKind2 === void 0 ? void 0 : _command$resultKind2.call(command, input);
346
+ var outputData = resultKind ? (_compactResults = compactResults({
347
+ kind: resultKind,
348
+ data: data,
349
+ showFollowUp: command.name === 'search'
350
+ })) !== null && _compactResults !== void 0 ? _compactResults : data : data;
343
351
  writeJsonEnvelope({
344
352
  envelope: createSuccessEnvelope({
345
353
  envelopeType: command.envelopeType(input),
346
354
  command: command.name,
347
- data: data,
355
+ data: outputData,
348
356
  meta: meta
349
357
  }),
350
358
  writer: writer
@@ -637,13 +645,21 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
637
645
  return ExitCode.NotFound;
638
646
  }
639
647
  if (json) {
648
+ var compactGrouped = Object.fromEntries(['components', 'tokens', 'icons', 'docs'].map(function (kind) {
649
+ var _compactResults2, _grouped$kind;
650
+ return [kind, (_compactResults2 = compactResults({
651
+ kind: kind,
652
+ data: (_grouped$kind = grouped[kind]) !== null && _grouped$kind !== void 0 ? _grouped$kind : [],
653
+ showFollowUp: true
654
+ })) !== null && _compactResults2 !== void 0 ? _compactResults2 : []];
655
+ }));
640
656
  writeJsonEnvelope({
641
657
  envelope: createSuccessEnvelope({
642
658
  envelopeType: command.envelopeType(input),
643
659
  command: command.name,
644
660
  // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
645
661
  // counted per group), so `count` is the combined total across groups.
646
- data: grouped,
662
+ data: compactGrouped,
647
663
  meta: _objectSpread(_objectSpread({}, meta), {}, {
648
664
  count: totalCount
649
665
  })