@atlaskit/ads-cli 0.9.0 → 0.11.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.
@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
6
6
  });
7
7
  exports.formatCompactResults = void 0;
8
8
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
+ var _humanFormat = require("@atlaskit/cli-output/human-format");
9
10
  var _cliMetadata = require("../commands/cli-metadata");
10
11
  var _compactResults = require("./compact-results");
11
12
  /**
@@ -26,19 +27,6 @@ var pluralize = function pluralize(count, noun) {
26
27
  return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
27
28
  };
28
29
 
29
- /**
30
- * Append a distribution-specific invocation to a compact row's follow-up command.
31
- *
32
- * Used for every `search` result, where the natural next step is to view that match in full.
33
- * `--all` listings omit it because echoing every row's own name would just be noise.
34
- */
35
- var withFollowUp = function withFollowUp(_ref) {
36
- var line = _ref.line,
37
- followUp = _ref.followUp,
38
- invocation = _ref.invocation;
39
- return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
40
- };
41
-
42
30
  /**
43
31
  * Render one component as a compact line.
44
32
  *
@@ -47,13 +35,13 @@ var withFollowUp = function withFollowUp(_ref) {
47
35
  * context and a tag would just be noise.
48
36
  */
49
37
  var formatComponentLine = function formatComponentLine(component, invocation) {
50
- var name = component.name;
51
- var pkg = component.package ? " ".concat(component.package) : '';
52
- var meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
53
- return withFollowUp({
54
- line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
55
- followUp: component.followUp,
56
- invocation: invocation
38
+ return _humanFormat.humanFormat.searchRow({
39
+ name: component.name,
40
+ package: component.package,
41
+ source: 'ads',
42
+ kind: 'component',
43
+ metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
44
+ followUp: component.followUp ? "".concat(invocation, " ").concat(component.followUp) : undefined
57
45
  });
58
46
  };
59
47
 
@@ -61,11 +49,12 @@ var formatComponentLine = function formatComponentLine(component, invocation) {
61
49
  * Render one token as a compact `name = value` line.
62
50
  */
63
51
  var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
64
- var line = tokenResult.exampleValue ? "".concat(tokenResult.name, " = ").concat(tokenResult.exampleValue) : tokenResult.name;
65
- return withFollowUp({
66
- line: line,
67
- followUp: tokenResult.followUp,
68
- invocation: invocation
52
+ return _humanFormat.humanFormat.searchRow({
53
+ name: tokenResult.name,
54
+ source: 'ads',
55
+ kind: 'token',
56
+ metadata: tokenResult.exampleValue ? ["= ".concat(tokenResult.exampleValue)] : undefined,
57
+ followUp: tokenResult.followUp ? "".concat(invocation, " ").concat(tokenResult.followUp) : undefined
69
58
  });
70
59
  };
71
60
 
@@ -73,13 +62,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
73
62
  * Render one icon as a compact line with its import package and short usage note.
74
63
  */
75
64
  var formatIconLine = function formatIconLine(iconResult, invocation) {
76
- var name = iconResult.componentName;
77
- var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
78
- var usage = iconResult.usage ? " \u2014 ".concat(iconResult.usage) : '';
79
- return withFollowUp({
80
- line: "".concat(name).concat(pkg).concat(usage),
81
- followUp: iconResult.followUp,
82
- invocation: invocation
65
+ return _humanFormat.humanFormat.searchRow({
66
+ name: iconResult.componentName,
67
+ package: iconResult.package,
68
+ source: 'ads',
69
+ kind: 'icon',
70
+ metadata: iconResult.usage ? [iconResult.usage] : undefined,
71
+ followUp: iconResult.followUp ? "".concat(invocation, " ").concat(iconResult.followUp) : undefined
83
72
  });
84
73
  };
85
74
 
@@ -87,12 +76,12 @@ var formatIconLine = function formatIconLine(iconResult, invocation) {
87
76
  * Render one foundations-document match without dumping its full Markdown body.
88
77
  */
89
78
  var formatDocLine = function formatDocLine(doc, invocation) {
90
- var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
91
- var line = "".concat(doc.title).concat(summary);
92
- return withFollowUp({
93
- line: line,
94
- followUp: doc.followUp,
95
- invocation: invocation
79
+ return _humanFormat.humanFormat.searchRow({
80
+ name: doc.title,
81
+ source: 'ads',
82
+ kind: 'docs',
83
+ description: doc.summary,
84
+ followUp: doc.followUp ? "".concat(invocation, " ").concat(doc.followUp) : undefined
96
85
  });
97
86
  };
98
87
 
@@ -103,13 +92,13 @@ var formatDocLine = function formatDocLine(doc, invocation) {
103
92
  * `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
104
93
  * each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
105
94
  */
106
- var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref2) {
107
- var kind = _ref2.kind,
108
- data = _ref2.data,
109
- _ref2$showFollowUp = _ref2.showFollowUp,
110
- showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
111
- _ref2$invocation = _ref2.invocation,
112
- invocation = _ref2$invocation === void 0 ? _cliMetadata.CLI_BIN_NAME : _ref2$invocation;
95
+ var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref) {
96
+ var kind = _ref.kind,
97
+ data = _ref.data,
98
+ _ref$showFollowUp = _ref.showFollowUp,
99
+ showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp,
100
+ _ref$invocation = _ref.invocation,
101
+ invocation = _ref$invocation === void 0 ? _cliMetadata.CLI_BIN_NAME : _ref$invocation;
113
102
  var compact = (0, _compactResults.compactResults)({
114
103
  kind: kind,
115
104
  data: data,
@@ -7,6 +7,7 @@ import { writeHumanError } from '../output/write-human-error';
7
7
  import { writeJsonEnvelope } from '../output/write-json-envelope';
8
8
  import { ExitCode } from '../types';
9
9
  import { CLI_ATLAS_INVOCATION } from './cli-metadata';
10
+ import { AGENTS_FILE_RELATIVE_PATH, updateAgentsFile } from './update-agents-file';
10
11
  const SKILL_ENTRYPOINT = 'SKILL.md';
11
12
  const SKILLS = [{
12
13
  name: 'atlassian-design-system',
@@ -24,6 +25,8 @@ const SKILLS = [{
24
25
  relativePath: '.agents/skills/a11y-foundation',
25
26
  requiredFiles: [SKILL_ENTRYPOINT]
26
27
  }];
28
+ const ADS_SKILL = SKILLS[0];
29
+ const SKILL_GET_STARTED_RELATIVE_PATH = `${ADS_SKILL.relativePath}/references/get-started.md`;
27
30
  const GIT_MARKER = '.git';
28
31
  const SKILLS_INSTALLER_PACKAGE = '@atlassian/skills';
29
32
  const SKILLS_INSTALLER_UNAVAILABLE_REASON = 'skills-installer-unavailable';
@@ -126,6 +129,27 @@ const validateInput = input => {
126
129
  }
127
130
  return undefined;
128
131
  };
132
+ const writeAgentsFileResult = ({
133
+ result,
134
+ writer
135
+ }) => {
136
+ switch (result.status) {
137
+ case 'created':
138
+ writer.out(`✓ Created ${AGENTS_FILE_RELATIVE_PATH} with ADS setup guidance`);
139
+ return;
140
+ case 'appended':
141
+ writer.out(`✓ Appended ADS setup guidance to ${AGENTS_FILE_RELATIVE_PATH}`);
142
+ return;
143
+ case 'updated':
144
+ writer.out(`✓ Updated ADS setup guidance in ${AGENTS_FILE_RELATIVE_PATH}`);
145
+ return;
146
+ case 'already-current':
147
+ writer.out(`✓ ADS setup guidance already current in ${AGENTS_FILE_RELATIVE_PATH}`);
148
+ return;
149
+ case 'not-written':
150
+ writer.out(`– ${AGENTS_FILE_RELATIVE_PATH} not updated because the current directory is not in a Git repository`);
151
+ }
152
+ };
129
153
  export const runInitCommand = async ({
130
154
  input,
131
155
  json,
@@ -143,12 +167,24 @@ export const runInitCommand = async ({
143
167
  }
144
168
  const projectRoot = findRepositoryRoot(cwd);
145
169
  const skills = [];
170
+ let agentsMd;
146
171
  const repositorySetupErrors = [];
147
172
  if (!projectRoot) {
148
173
  skills.push(...createNotInstalledSkillResults('not-in-git-repository'));
149
174
  if (!json) {
150
175
  writer.out('– Repository-local skills not installed because the current directory is not in a Git repository');
151
176
  }
177
+ agentsMd = {
178
+ status: 'not-written',
179
+ path: AGENTS_FILE_RELATIVE_PATH,
180
+ reason: 'not-in-git-repository'
181
+ };
182
+ if (!json) {
183
+ writeAgentsFileResult({
184
+ result: agentsMd,
185
+ writer
186
+ });
187
+ }
152
188
  } else {
153
189
  const npxCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
154
190
  let skillsInstallerUnavailable = false;
@@ -224,6 +260,30 @@ export const runInitCommand = async ({
224
260
  writer.out(skillHumanOutput.length > 0 ? '– Remaining repository-local skills skipped because @atlassian/skills is unavailable; npx @atlaskit/ads-cli remains available' : '– Repository-local skills skipped because @atlassian/skills is unavailable; npx @atlaskit/ads-cli remains available');
225
261
  }
226
262
  }
263
+ const installedSkills = skills.filter(skill => skill.status !== 'not-installed');
264
+ const adsSkillInstalled = installedSkills.some(skill => skill.name === ADS_SKILL.name);
265
+ if (skillsInstallerUnavailable || adsSkillInstalled) {
266
+ try {
267
+ agentsMd = updateAgentsFile({
268
+ projectRoot,
269
+ guidance: adsSkillInstalled ? {
270
+ mode: 'skills-installed',
271
+ skillEntrypoints: installedSkills.map(skill => `${skill.path}/${SKILL_ENTRYPOINT}`),
272
+ getStartedPath: SKILL_GET_STARTED_RELATIVE_PATH
273
+ } : {
274
+ mode: 'public'
275
+ }
276
+ });
277
+ if (!json) {
278
+ writeAgentsFileResult({
279
+ result: agentsMd,
280
+ writer
281
+ });
282
+ }
283
+ } catch (error) {
284
+ repositorySetupErrors.push(error instanceof Error ? error : new Error('Failed to set up the ADS repository guidance.'));
285
+ }
286
+ }
227
287
  }
228
288
  const atlasCwd = projectRoot !== null && projectRoot !== void 0 ? projectRoot : path.resolve(cwd);
229
289
  let atlasPluginStatus;
@@ -278,15 +338,23 @@ export const runInitCommand = async ({
278
338
  if (repositorySetupErrors.length > 0) {
279
339
  throw new Error(repositorySetupErrors.map(error => error.message).join('\n'));
280
340
  }
281
- if (skills.length !== SKILLS.length) {
341
+ // Keep the successful-path invariant explicit so future control-flow changes cannot return a partial result.
342
+ if (skills.length !== SKILLS.length || !agentsMd) {
282
343
  throw new Error('Failed to determine the ADS repository setup result.');
283
344
  }
345
+ const adsSkillInstalled = skills.some(skill => skill.name === ADS_SKILL.name && skill.status !== 'not-installed');
346
+ const nextStep = projectRoot && adsSkillInstalled ? SKILL_GET_STARTED_RELATIVE_PATH : null;
347
+ if (!json && nextStep) {
348
+ writer.out(`→ Next: follow ${nextStep} to complete repository setup`);
349
+ }
284
350
  const data = {
285
351
  projectRoot: projectRoot !== null && projectRoot !== void 0 ? projectRoot : null,
286
352
  skills,
353
+ agentsMd,
287
354
  atlas: {
288
355
  status: atlasPluginStatus
289
- }
356
+ },
357
+ nextStep
290
358
  };
291
359
  if (json) {
292
360
  writeJsonEnvelope({
@@ -0,0 +1,139 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ export const ADS_INIT_START_MARKER = '<!-- ADS:INIT:START -->';
5
+ export const ADS_INIT_END_MARKER = '<!-- ADS:INIT:END -->';
6
+ export const AGENTS_FILE_RELATIVE_PATH = 'AGENTS.md';
7
+ const markerError = () => new Error(`Cannot update ${AGENTS_FILE_RELATIVE_PATH} because the ${ADS_INIT_START_MARKER} and ${ADS_INIT_END_MARKER} markers are malformed or ambiguous. Repair or remove the markers, then run init again.`);
8
+ const countOccurrences = (content, value) => content.split(value).length - 1;
9
+ const isStandaloneMarker = (content, marker, index) => {
10
+ const beforeIsLineBoundary = index === 0 || content[index - 1] === '\n';
11
+ const afterIndex = index + marker.length;
12
+ const afterIsLineBoundary = afterIndex === content.length || content[afterIndex] === '\n' || content[afterIndex] === '\r' && content[afterIndex + 1] === '\n';
13
+ return beforeIsLineBoundary && afterIsLineBoundary;
14
+ };
15
+ const detectLineEnding = content => {
16
+ var _content$match$length, _content$match, _content$replace$matc, _content$replace$matc2;
17
+ const crlfCount = (_content$match$length = (_content$match = content.match(/\r\n/g)) === null || _content$match === void 0 ? void 0 : _content$match.length) !== null && _content$match$length !== void 0 ? _content$match$length : 0;
18
+ const lfOnlyCount = (_content$replace$matc = (_content$replace$matc2 = content.replace(/\r\n/g, '').match(/\n/g)) === null || _content$replace$matc2 === void 0 ? void 0 : _content$replace$matc2.length) !== null && _content$replace$matc !== void 0 ? _content$replace$matc : 0;
19
+ return crlfCount > lfOnlyCount ? '\r\n' : '\n';
20
+ };
21
+ const MCP_GUIDANCE = ['Use `atlas ads` first for structured ADS lookups. If Atlas is unavailable, use `npx @atlaskit/ads-cli` with the same trailing arguments.', '', '### Hosted ADS MCP fallback', '', 'Prefer the CLI first. Configure the hosted ADS MCP server only if this repository does not already configure `ads-mcp` or `atlassian-ads-mcp`. Merge the selected server into the existing configuration without replacing other servers, then reload the agent or IDE.', '', '**Cursor — `.cursor/mcp.json`:**', '', '```json', '{', ' "mcpServers": {', ' "ads-mcp": {', ' "url": "https://mcp.atlassian.com/v1/ads/public/mcp"', ' }', ' }', '}', '```', '', '**VS Code — `.vscode/mcp.json`:**', '', '```json', '{', ' "servers": {', ' "ads-mcp": {', ' "type": "http",', ' "url": "https://mcp.atlassian.com/v1/ads/public/mcp"', ' }', ' }', '}', '```', '', '**Codex — `.codex/config.toml`:**', '', '```toml', '[mcp_servers.atlassian-ads-mcp]', 'url = "https://mcp.atlassian.com/v1/ads/public/mcp"', '```', '', 'Do not add Rovo MCP configuration to the repository.'];
22
+ const renderManagedBlock = ({
23
+ lineEnding,
24
+ guidance
25
+ }) => {
26
+ const skillGuidance = guidance.mode === 'skills-installed' ? ['`init` installed repository-local guidance for setting up and using the Atlassian Design System.', '', 'For Atlassian frontend UI work—including component selection, tokens, icons, styling, accessibility, product content and ADS lint rules—follow:', '', ...guidance.skillEntrypoints.map(entrypoint => `- \`${entrypoint}\``), '', "Before starting frontend UI work, check and complete this repository's ADS setup by following:", '', `\`${guidance.getStartedPath}\``, '', 'Apply only the setup that is missing, and preserve equivalent existing configuration.', ''] : ['`init` did not install repository-local skills. Use the public ADS CLI and optional MCP guidance below.', ''];
27
+ return [ADS_INIT_START_MARKER, '## Getting started with the Atlassian Design System', '', ...skillGuidance, ...MCP_GUIDANCE, '', "This is a temporary initialization section. It may be removed or rephrased once this repository's ADS setup has been completed.", ADS_INIT_END_MARKER].join(lineEnding);
28
+ };
29
+ const readTargetStats = targetPath => {
30
+ try {
31
+ return lstatSync(targetPath);
32
+ } catch (error) {
33
+ if (error.code === 'ENOENT') {
34
+ return undefined;
35
+ }
36
+ throw error;
37
+ }
38
+ };
39
+ const atomicWriteFile = ({
40
+ targetPath,
41
+ content,
42
+ mode,
43
+ targetExists
44
+ }) => {
45
+ const temporaryPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
46
+ let temporaryFileExists = false;
47
+ try {
48
+ writeFileSync(temporaryPath, content, {
49
+ encoding: 'utf8',
50
+ flag: 'wx',
51
+ mode
52
+ });
53
+ temporaryFileExists = true;
54
+ try {
55
+ renameSync(temporaryPath, targetPath);
56
+ temporaryFileExists = false;
57
+ } catch (error) {
58
+ const code = error.code;
59
+ const canFallbackOnWindows = process.platform === 'win32' && targetExists && (code === 'EACCES' || code === 'EEXIST' || code === 'EPERM');
60
+ if (!canFallbackOnWindows) {
61
+ throw error;
62
+ }
63
+ writeFileSync(targetPath, content, {
64
+ encoding: 'utf8',
65
+ mode
66
+ });
67
+ unlinkSync(temporaryPath);
68
+ temporaryFileExists = false;
69
+ }
70
+ } finally {
71
+ if (temporaryFileExists) {
72
+ try {
73
+ unlinkSync(temporaryPath);
74
+ } catch {
75
+ // Preserve the original write failure if temporary cleanup also fails.
76
+ }
77
+ }
78
+ }
79
+ };
80
+ export const updateAgentsFile = ({
81
+ projectRoot,
82
+ guidance
83
+ }) => {
84
+ var _stats$mode;
85
+ const targetPath = path.join(projectRoot, AGENTS_FILE_RELATIVE_PATH);
86
+ const stats = readTargetStats(targetPath);
87
+ if (stats !== null && stats !== void 0 && stats.isSymbolicLink()) {
88
+ throw new Error(`Cannot update ${AGENTS_FILE_RELATIVE_PATH} because it is a symbolic link.`);
89
+ }
90
+ if (stats && !stats.isFile()) {
91
+ throw new Error(`Cannot update ${AGENTS_FILE_RELATIVE_PATH} because it is not a regular file.`);
92
+ }
93
+ const existingContent = stats ? readFileSync(targetPath, 'utf8') : '';
94
+ const lineEnding = detectLineEnding(existingContent);
95
+ const managedBlock = renderManagedBlock({
96
+ lineEnding,
97
+ guidance
98
+ });
99
+ const startCount = countOccurrences(existingContent, ADS_INIT_START_MARKER);
100
+ const endCount = countOccurrences(existingContent, ADS_INIT_END_MARKER);
101
+ let nextContent;
102
+ let status;
103
+ if (!stats) {
104
+ nextContent = `${managedBlock}${lineEnding}`;
105
+ status = 'created';
106
+ } else if (startCount === 0 && endCount === 0) {
107
+ const separator = existingContent.length === 0 ? '' : existingContent.endsWith(`${lineEnding}${lineEnding}`) ? '' : existingContent.endsWith(lineEnding) ? lineEnding : `${lineEnding}${lineEnding}`;
108
+ nextContent = `${existingContent}${separator}${managedBlock}${lineEnding}`;
109
+ status = 'appended';
110
+ } else {
111
+ if (startCount !== 1 || endCount !== 1) {
112
+ throw markerError();
113
+ }
114
+ const startIndex = existingContent.indexOf(ADS_INIT_START_MARKER);
115
+ const endIndex = existingContent.indexOf(ADS_INIT_END_MARKER);
116
+ if (startIndex > endIndex || !isStandaloneMarker(existingContent, ADS_INIT_START_MARKER, startIndex) || !isStandaloneMarker(existingContent, ADS_INIT_END_MARKER, endIndex)) {
117
+ throw markerError();
118
+ }
119
+ const afterManagedBlock = endIndex + ADS_INIT_END_MARKER.length;
120
+ nextContent = `${existingContent.slice(0, startIndex)}${managedBlock}${existingContent.slice(afterManagedBlock)}`;
121
+ if (nextContent === existingContent) {
122
+ return {
123
+ status: 'already-current',
124
+ path: AGENTS_FILE_RELATIVE_PATH
125
+ };
126
+ }
127
+ status = 'updated';
128
+ }
129
+ atomicWriteFile({
130
+ targetPath,
131
+ content: nextContent,
132
+ mode: (_stats$mode = stats === null || stats === void 0 ? void 0 : stats.mode) !== null && _stats$mode !== void 0 ? _stats$mode : 0o666,
133
+ targetExists: stats !== undefined
134
+ });
135
+ return {
136
+ status,
137
+ path: AGENTS_FILE_RELATIVE_PATH
138
+ };
139
+ };
@@ -15,35 +15,20 @@
15
15
  * A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
16
16
  */
17
17
 
18
- /**
19
- * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
20
- */
21
- const oneLine = text => text.replace(/\s+/g, ' ').trim();
18
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
22
19
 
23
20
  /**
24
- * Render the props section as an aligned two-column list: `name type`, with the description on
25
- * a wrapped continuation line. Returns an empty array when there are no props.
21
+ * Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
22
+ * names visually distinct, aligns columns, and bounds long generated type expressions.
26
23
  */
27
- const formatProps = props => {
28
- if (props.length === 0) {
29
- return ['Props: none'];
30
- }
31
-
32
- // Align the type column to the longest prop name for readability.
33
- const longestName = props.reduce((max, prop) => {
34
- var _prop$name;
35
- return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
36
- }, 0);
37
- const rows = props.flatMap(prop => {
38
- var _prop$name2;
39
- const name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
40
- const type = prop.type ? oneLine(prop.type) : '';
41
- const header = ` ${name} ${type}`.trimEnd();
42
- const description = prop.description ? ` ${oneLine(prop.description)}` : null;
43
- return description ? [header, description] : [header];
44
- });
45
- return [`Props (${props.length}):`, ...rows];
46
- };
24
+ const formatProps = props => humanFormat.propertyTable(props.map(prop => {
25
+ var _prop$name;
26
+ return {
27
+ name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
28
+ type: prop.type,
29
+ description: prop.description
30
+ };
31
+ }));
47
32
 
48
33
  /**
49
34
  * Render the examples section. Each example is a code snippet string; they are printed verbatim
@@ -55,7 +40,7 @@ const formatExamples = examples => {
55
40
  }
56
41
  const blocks = examples.map((example, index) => {
57
42
  const code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
58
- return [`Example ${index + 1}:`, '```tsx', code, '```'].join('\n');
43
+ return [humanFormat.section(`Example ${index + 1}`), humanFormat.codeBlock(code)].join('\n');
59
44
  });
60
45
  return [`Examples (${examples.length}):`, '', ...blocks];
61
46
  };
@@ -65,14 +50,20 @@ const formatExamples = examples => {
65
50
  * data is not a recognisable component object, so the caller can fall back to generic rendering.
66
51
  */
67
52
  export const formatComponent = data => {
68
- var _component$props, _component$examples, _component$designSour;
53
+ var _component$usageGuide, _component$props, _component$examples, _component$designSour;
69
54
  // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
70
55
  const component = Array.isArray(data) ? data[0] : data;
71
56
  if (!component || typeof component !== 'object' || typeof component.name !== 'string') {
72
57
  return null;
73
58
  }
74
- const header = component.package ? `${component.name} (${component.package})` : component.name;
75
- const sections = [header, '='.repeat(header.length), '', ...formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])];
59
+ const header = humanFormat.heading(component.name);
60
+ const metadata = humanFormat.metadata([component.status, component.category, component.package]);
61
+ const sections = [header, ...(metadata ? [metadata] : [])];
62
+ if (component.description) sections.push('', component.description);
63
+ if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
64
+ sections.push('', humanFormat.section('Use it well'), ...component.usageGuidelines.slice(0, 4).map(item => ` ${humanFormat.success('•')} ${item}`));
65
+ }
66
+ sections.push('', ...formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []));
76
67
  const examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
77
68
  if (examples.length > 0) {
78
69
  sections.push('', ...examples);
@@ -82,7 +73,7 @@ export const formatComponent = data => {
82
73
  // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
83
74
  // `Design: undefined`.
84
75
  if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
85
- sections.push('', `Design: ${component.designSource.figmaUrl}`);
76
+ sections.push('', `${humanFormat.section('Design:')} ${humanFormat.action(component.designSource.figmaUrl)}`);
86
77
  }
87
78
  return sections.join('\n');
88
79
  };
@@ -6,6 +6,7 @@
6
6
  * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
7
7
  * rather than raw JSON; `--json` still exposes the full structured payload.
8
8
  */
9
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
9
10
 
10
11
  /**
11
12
  * Convert a camelCase / snake_case field key into a human "Title Case" heading,
@@ -34,7 +35,7 @@ const formatListItem = item => {
34
35
  if (title && codeKeys.length > 0) {
35
36
  const description = typeof record.description === 'string' ? [` ${oneLine(record.description)}`] : [];
36
37
  const labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
37
- const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []), ` \`\`\`tsx\n${record[key]}\n \`\`\``]);
38
+ const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []), humanFormat.codeBlock(record[key])]);
38
39
  const additionalFields = Object.entries(record).flatMap(([key, value]) => {
39
40
  if (['title', 'description', ...codeKeys].includes(key) || value === null || value === undefined) {
40
41
  return [];
@@ -9,6 +9,7 @@
9
9
  * left to the caller's generic fallback.
10
10
  */
11
11
 
12
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
12
13
  import { CLI_BIN_NAME } from '../commands/cli-metadata';
13
14
  import { compactResults } from './compact-results';
14
15
 
@@ -17,18 +18,6 @@ import { compactResults } from './compact-results';
17
18
  */
18
19
  const pluralize = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
19
20
 
20
- /**
21
- * Append a distribution-specific invocation to a compact row's follow-up command.
22
- *
23
- * Used for every `search` result, where the natural next step is to view that match in full.
24
- * `--all` listings omit it because echoing every row's own name would just be noise.
25
- */
26
- const withFollowUp = ({
27
- line,
28
- followUp,
29
- invocation
30
- }) => followUp ? `${line}\n → ${invocation} ${followUp}` : line;
31
-
32
21
  /**
33
22
  * Render one component as a compact line.
34
23
  *
@@ -37,13 +26,13 @@ const withFollowUp = ({
37
26
  * context and a tag would just be noise.
38
27
  */
39
28
  const formatComponentLine = (component, invocation) => {
40
- const name = component.name;
41
- const pkg = component.package ? ` ${component.package}` : '';
42
- const meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
43
- return withFollowUp({
44
- line: `${name}${pkg} (${meta})`,
45
- followUp: component.followUp,
46
- invocation
29
+ return humanFormat.searchRow({
30
+ name: component.name,
31
+ package: component.package,
32
+ source: 'ads',
33
+ kind: 'component',
34
+ metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
35
+ followUp: component.followUp ? `${invocation} ${component.followUp}` : undefined
47
36
  });
48
37
  };
49
38
 
@@ -51,11 +40,12 @@ const formatComponentLine = (component, invocation) => {
51
40
  * Render one token as a compact `name = value` line.
52
41
  */
53
42
  const formatTokenLine = (tokenResult, invocation) => {
54
- const line = tokenResult.exampleValue ? `${tokenResult.name} = ${tokenResult.exampleValue}` : tokenResult.name;
55
- return withFollowUp({
56
- line,
57
- followUp: tokenResult.followUp,
58
- invocation
43
+ return humanFormat.searchRow({
44
+ name: tokenResult.name,
45
+ source: 'ads',
46
+ kind: 'token',
47
+ metadata: tokenResult.exampleValue ? [`= ${tokenResult.exampleValue}`] : undefined,
48
+ followUp: tokenResult.followUp ? `${invocation} ${tokenResult.followUp}` : undefined
59
49
  });
60
50
  };
61
51
 
@@ -63,13 +53,13 @@ const formatTokenLine = (tokenResult, invocation) => {
63
53
  * Render one icon as a compact line with its import package and short usage note.
64
54
  */
65
55
  const formatIconLine = (iconResult, invocation) => {
66
- const name = iconResult.componentName;
67
- const pkg = iconResult.package ? ` ${iconResult.package}` : '';
68
- const usage = iconResult.usage ? ` — ${iconResult.usage}` : '';
69
- return withFollowUp({
70
- line: `${name}${pkg}${usage}`,
71
- followUp: iconResult.followUp,
72
- invocation
56
+ return humanFormat.searchRow({
57
+ name: iconResult.componentName,
58
+ package: iconResult.package,
59
+ source: 'ads',
60
+ kind: 'icon',
61
+ metadata: iconResult.usage ? [iconResult.usage] : undefined,
62
+ followUp: iconResult.followUp ? `${invocation} ${iconResult.followUp}` : undefined
73
63
  });
74
64
  };
75
65
 
@@ -77,12 +67,12 @@ const formatIconLine = (iconResult, invocation) => {
77
67
  * Render one foundations-document match without dumping its full Markdown body.
78
68
  */
79
69
  const formatDocLine = (doc, invocation) => {
80
- const summary = doc.summary ? ` — ${doc.summary}` : '';
81
- const line = `${doc.title}${summary}`;
82
- return withFollowUp({
83
- line,
84
- followUp: doc.followUp,
85
- invocation
70
+ return humanFormat.searchRow({
71
+ name: doc.title,
72
+ source: 'ads',
73
+ kind: 'docs',
74
+ description: doc.summary,
75
+ followUp: doc.followUp ? `${invocation} ${doc.followUp}` : undefined
86
76
  });
87
77
  };
88
78