@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,142 @@
1
+ /**
2
+ * Normalise one batch child request without involving a shell.
3
+ *
4
+ * The canonical form is already-tokenized argv, for example
5
+ * `['search', 'Grid', '--type', 'component']`. For compatibility with agent-generated commands,
6
+ * the first token may instead contain a complete request, for example `['search Grid', '--type',
7
+ * 'component']`. Only that first token is split; trailing tokens have already been tokenized by the
8
+ * caller and must remain unchanged so multi-word arguments keep their boundaries.
9
+ */
10
+
11
+ const shellSyntaxError = syntax => ({
12
+ error: `Shell syntax ${syntax} is not supported in batch requests. Pass child commands as argv only; pipes, redirects, expansion, and command substitution are not allowed.`
13
+ });
14
+
15
+ /**
16
+ * Reject syntax that would have special meaning to a shell even though this parser never invokes
17
+ * one. Failing closed gives callers an actionable error instead of accepting input that only looks
18
+ * safe because it currently remains an argv array.
19
+ */
20
+ const findShellSyntax = value => {
21
+ var _value$match;
22
+ if (value.includes('$(')) {
23
+ return 'command substitution (`$(...)`)';
24
+ }
25
+ if (value.includes('`')) {
26
+ return 'command substitution (backticks)';
27
+ }
28
+ if (value.includes('$')) {
29
+ return 'environment expansion (`$`)';
30
+ }
31
+ if (/\r|\n/.test(value)) {
32
+ return 'a command separator (line break)';
33
+ }
34
+ if (value.includes('&&')) {
35
+ return 'the `&&` operator';
36
+ }
37
+ if (value.includes('||')) {
38
+ return 'the `||` operator';
39
+ }
40
+ const operator = (_value$match = value.match(/[|&;<>()]/)) === null || _value$match === void 0 ? void 0 : _value$match[0];
41
+ return operator ? `the \`${operator}\` operator` : null;
42
+ };
43
+
44
+ /**
45
+ * Split a complete child request into argv using quoting and escaping rules only. This is
46
+ * intentionally not a shell grammar: it performs no expansion, substitution, redirection, or
47
+ * operator evaluation.
48
+ */
49
+ const tokenizeCompleteRequest = value => {
50
+ const argv = [];
51
+ let current = '';
52
+ let quote = null;
53
+ let escaped = false;
54
+ let tokenStarted = false;
55
+ for (const character of value) {
56
+ if (escaped) {
57
+ current += character;
58
+ escaped = false;
59
+ tokenStarted = true;
60
+ continue;
61
+ }
62
+ if (character === '\\') {
63
+ escaped = true;
64
+ tokenStarted = true;
65
+ continue;
66
+ }
67
+ if (quote !== null) {
68
+ if (character === quote) {
69
+ quote = null;
70
+ } else {
71
+ current += character;
72
+ }
73
+ continue;
74
+ }
75
+ if (character === "'" || character === '"') {
76
+ quote = character;
77
+ tokenStarted = true;
78
+ continue;
79
+ }
80
+ if (/\s/.test(character)) {
81
+ if (tokenStarted) {
82
+ argv.push(current);
83
+ current = '';
84
+ tokenStarted = false;
85
+ }
86
+ continue;
87
+ }
88
+ current += character;
89
+ tokenStarted = true;
90
+ }
91
+ if (escaped) {
92
+ return {
93
+ error: 'Invalid complete batch request: it ends with an escape character.'
94
+ };
95
+ }
96
+ if (quote !== null) {
97
+ return {
98
+ error: `Invalid complete batch request: unterminated ${quote} quote.`
99
+ };
100
+ }
101
+ if (tokenStarted) {
102
+ argv.push(current);
103
+ }
104
+ if (argv.length === 0) {
105
+ return {
106
+ error: 'Invalid complete batch request: a command name is required.'
107
+ };
108
+ }
109
+ return {
110
+ argv
111
+ };
112
+ };
113
+ export const normalizeBatchRequest = argv => {
114
+ for (const token of argv) {
115
+ const syntax = findShellSyntax(token);
116
+ if (syntax !== null) {
117
+ return shellSyntaxError(syntax);
118
+ }
119
+ }
120
+ const [first, ...trailing] = argv;
121
+ if (first === undefined) {
122
+ return {
123
+ error: '`--command` must be followed by a non-empty command request.'
124
+ };
125
+ }
126
+
127
+ // A normal command name cannot contain whitespace, quotes, or escapes. Their presence in the
128
+ // first argv entry therefore identifies the complete-string compatibility form. Tokenized
129
+ // trailing entries are never re-split.
130
+ if (!/[\s'"\\]/.test(first)) {
131
+ return {
132
+ argv: [...argv]
133
+ };
134
+ }
135
+ const normalized = tokenizeCompleteRequest(first);
136
+ if ('error' in normalized) {
137
+ return normalized;
138
+ }
139
+ return {
140
+ argv: [...normalized.argv, ...trailing]
141
+ };
142
+ };
@@ -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';
@@ -68,7 +69,10 @@ var buildHelpText = function buildHelpText(invocation) {
68
69
  comment: 'unified: components, tokens, icons & docs'
69
70
  }, {
70
71
  command: 'batch --command search button --type icon --command token space.200',
71
- comment: 'independent commands in one process'
72
+ comment: 'canonical tokenized batch form'
73
+ }, {
74
+ command: 'batch --command "search button" --type icon --command "token space.200"',
75
+ comment: 'complete-string compatibility form'
72
76
  }, {
73
77
  command: 'search button --type component'
74
78
  }, {
@@ -337,11 +341,18 @@ var renderSingleResult = function renderSingleResult(_ref8) {
337
341
  input: input
338
342
  }) : result.data;
339
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;
340
351
  writeJsonEnvelope({
341
352
  envelope: createSuccessEnvelope({
342
353
  envelopeType: command.envelopeType(input),
343
354
  command: command.name,
344
- data: data,
355
+ data: outputData,
345
356
  meta: meta
346
357
  }),
347
358
  writer: writer
@@ -633,6 +644,14 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
633
644
  }
634
645
  return ExitCode.NotFound;
635
646
  }
647
+ var compactGrouped = Object.fromEntries(['components', 'tokens', 'icons', 'docs'].map(function (kind) {
648
+ var _compactResults2, _grouped$kind;
649
+ return [kind, (_compactResults2 = compactResults({
650
+ kind: kind,
651
+ data: (_grouped$kind = grouped[kind]) !== null && _grouped$kind !== void 0 ? _grouped$kind : [],
652
+ showFollowUp: true
653
+ })) !== null && _compactResults2 !== void 0 ? _compactResults2 : []];
654
+ }));
636
655
  if (json) {
637
656
  writeJsonEnvelope({
638
657
  envelope: createSuccessEnvelope({
@@ -640,7 +659,7 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
640
659
  command: command.name,
641
660
  // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
642
661
  // counted per group), so `count` is the combined total across groups.
643
- data: grouped,
662
+ data: compactGrouped,
644
663
  meta: _objectSpread(_objectSpread({}, meta), {}, {
645
664
  count: totalCount
646
665
  })
@@ -650,7 +669,7 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
650
669
  return ExitCode.Ok;
651
670
  }
652
671
  writer.out(formatGroupedResults({
653
- groups: grouped,
672
+ groups: compactGrouped,
654
673
  totalCount: totalCount,
655
674
  invocation: invocation
656
675
  }));