@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.
@@ -13,6 +13,7 @@ import { writeHumanError } from '../output/write-human-error';
13
13
  import { writeJsonEnvelope } from '../output/write-json-envelope';
14
14
  import { ExitCode } from '../types';
15
15
  import { CLI_ATLAS_INVOCATION } from './cli-metadata';
16
+ import { AGENTS_FILE_RELATIVE_PATH, updateAgentsFile } from './update-agents-file';
16
17
  var SKILL_ENTRYPOINT = 'SKILL.md';
17
18
  var SKILLS = [{
18
19
  name: 'atlassian-design-system',
@@ -30,6 +31,8 @@ var SKILLS = [{
30
31
  relativePath: '.agents/skills/a11y-foundation',
31
32
  requiredFiles: [SKILL_ENTRYPOINT]
32
33
  }];
34
+ var ADS_SKILL = SKILLS[0];
35
+ var SKILL_GET_STARTED_RELATIVE_PATH = "".concat(ADS_SKILL.relativePath, "/references/get-started.md");
33
36
  var GIT_MARKER = '.git';
34
37
  var SKILLS_INSTALLER_PACKAGE = '@atlassian/skills';
35
38
  var SKILLS_INSTALLER_UNAVAILABLE_REASON = 'skills-installer-unavailable';
@@ -138,13 +141,33 @@ var validateInput = function validateInput(input) {
138
141
  }
139
142
  return undefined;
140
143
  };
144
+ var writeAgentsFileResult = function writeAgentsFileResult(_ref3) {
145
+ var result = _ref3.result,
146
+ writer = _ref3.writer;
147
+ switch (result.status) {
148
+ case 'created':
149
+ writer.out("\u2713 Created ".concat(AGENTS_FILE_RELATIVE_PATH, " with ADS setup guidance"));
150
+ return;
151
+ case 'appended':
152
+ writer.out("\u2713 Appended ADS setup guidance to ".concat(AGENTS_FILE_RELATIVE_PATH));
153
+ return;
154
+ case 'updated':
155
+ writer.out("\u2713 Updated ADS setup guidance in ".concat(AGENTS_FILE_RELATIVE_PATH));
156
+ return;
157
+ case 'already-current':
158
+ writer.out("\u2713 ADS setup guidance already current in ".concat(AGENTS_FILE_RELATIVE_PATH));
159
+ return;
160
+ case 'not-written':
161
+ writer.out("\u2013 ".concat(AGENTS_FILE_RELATIVE_PATH, " not updated because the current directory is not in a Git repository"));
162
+ }
163
+ };
141
164
  export var runInitCommand = /*#__PURE__*/function () {
142
- var _ref4 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(_ref3) {
143
- var input, json, writer, invocation, cwd, usageError, projectRoot, skills, repositorySetupErrors, npxCommand, skillsInstallerUnavailable, skillHumanOutput, _loop, _i, _SKILLS, skillResultsByName, _iterator, _step, line, atlasCwd, atlasPluginStatus, _atlasCheck$error, atlasCheck, installResult, verification, data;
165
+ var _ref5 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(_ref4) {
166
+ var input, json, writer, invocation, cwd, usageError, projectRoot, skills, agentsMd, repositorySetupErrors, npxCommand, skillsInstallerUnavailable, skillHumanOutput, _loop, _i, _SKILLS, skillResultsByName, _iterator, _step, line, installedSkills, _adsSkillInstalled, atlasCwd, atlasPluginStatus, _atlasCheck$error, atlasCheck, installResult, verification, adsSkillInstalled, nextStep, data;
144
167
  return _regeneratorRuntime.wrap(function (_context2) {
145
168
  while (1) switch (_context2.prev = _context2.next) {
146
169
  case 0:
147
- input = _ref3.input, json = _ref3.json, writer = _ref3.writer, invocation = _ref3.invocation, cwd = _ref3.cwd;
170
+ input = _ref4.input, json = _ref4.json, writer = _ref4.writer, invocation = _ref4.invocation, cwd = _ref4.cwd;
148
171
  usageError = validateInput(input);
149
172
  if (!usageError) {
150
173
  _context2.next = 1;
@@ -167,6 +190,17 @@ export var runInitCommand = /*#__PURE__*/function () {
167
190
  if (!json) {
168
191
  writer.out('– Repository-local skills not installed because the current directory is not in a Git repository');
169
192
  }
193
+ agentsMd = {
194
+ status: 'not-written',
195
+ path: AGENTS_FILE_RELATIVE_PATH,
196
+ reason: 'not-in-git-repository'
197
+ };
198
+ if (!json) {
199
+ writeAgentsFileResult({
200
+ result: agentsMd,
201
+ writer: writer
202
+ });
203
+ }
170
204
  _context2.next = 7;
171
205
  break;
172
206
  case 2:
@@ -305,6 +339,36 @@ export var runInitCommand = /*#__PURE__*/function () {
305
339
  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');
306
340
  }
307
341
  }
342
+ installedSkills = skills.filter(function (skill) {
343
+ return skill.status !== 'not-installed';
344
+ });
345
+ _adsSkillInstalled = installedSkills.some(function (skill) {
346
+ return skill.name === ADS_SKILL.name;
347
+ });
348
+ if (skillsInstallerUnavailable || _adsSkillInstalled) {
349
+ try {
350
+ agentsMd = updateAgentsFile({
351
+ projectRoot: projectRoot,
352
+ guidance: _adsSkillInstalled ? {
353
+ mode: 'skills-installed',
354
+ skillEntrypoints: installedSkills.map(function (skill) {
355
+ return "".concat(skill.path, "/").concat(SKILL_ENTRYPOINT);
356
+ }),
357
+ getStartedPath: SKILL_GET_STARTED_RELATIVE_PATH
358
+ } : {
359
+ mode: 'public'
360
+ }
361
+ });
362
+ if (!json) {
363
+ writeAgentsFileResult({
364
+ result: agentsMd,
365
+ writer: writer
366
+ });
367
+ }
368
+ } catch (error) {
369
+ repositorySetupErrors.push(error instanceof Error ? error : new Error('Failed to set up the ADS repository guidance.'));
370
+ }
371
+ }
308
372
  case 7:
309
373
  atlasCwd = projectRoot !== null && projectRoot !== void 0 ? projectRoot : path.resolve(cwd);
310
374
  if (!(invocation === CLI_ATLAS_INVOCATION)) {
@@ -383,18 +447,27 @@ export var runInitCommand = /*#__PURE__*/function () {
383
447
  return error.message;
384
448
  }).join('\n'));
385
449
  case 14:
386
- if (!(skills.length !== SKILLS.length)) {
450
+ if (!(skills.length !== SKILLS.length || !agentsMd)) {
387
451
  _context2.next = 15;
388
452
  break;
389
453
  }
390
454
  throw new Error('Failed to determine the ADS repository setup result.');
391
455
  case 15:
456
+ adsSkillInstalled = skills.some(function (skill) {
457
+ return skill.name === ADS_SKILL.name && skill.status !== 'not-installed';
458
+ });
459
+ nextStep = projectRoot && adsSkillInstalled ? SKILL_GET_STARTED_RELATIVE_PATH : null;
460
+ if (!json && nextStep) {
461
+ writer.out("\u2192 Next: follow ".concat(nextStep, " to complete repository setup"));
462
+ }
392
463
  data = {
393
464
  projectRoot: projectRoot !== null && projectRoot !== void 0 ? projectRoot : null,
394
465
  skills: skills,
466
+ agentsMd: agentsMd,
395
467
  atlas: {
396
468
  status: atlasPluginStatus
397
- }
469
+ },
470
+ nextStep: nextStep
398
471
  };
399
472
  if (json) {
400
473
  writeJsonEnvelope({
@@ -415,6 +488,6 @@ export var runInitCommand = /*#__PURE__*/function () {
415
488
  }, _callee);
416
489
  }));
417
490
  return function runInitCommand(_x) {
418
- return _ref4.apply(this, arguments);
491
+ return _ref5.apply(this, arguments);
419
492
  };
420
493
  }();
@@ -0,0 +1,143 @@
1
+ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
2
+ import { randomUUID } from 'node:crypto';
3
+ import { lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
4
+ import path from 'node:path';
5
+ export var ADS_INIT_START_MARKER = '<!-- ADS:INIT:START -->';
6
+ export var ADS_INIT_END_MARKER = '<!-- ADS:INIT:END -->';
7
+ export var AGENTS_FILE_RELATIVE_PATH = 'AGENTS.md';
8
+ var markerError = function markerError() {
9
+ return new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because the ").concat(ADS_INIT_START_MARKER, " and ").concat(ADS_INIT_END_MARKER, " markers are malformed or ambiguous. Repair or remove the markers, then run init again."));
10
+ };
11
+ var countOccurrences = function countOccurrences(content, value) {
12
+ return content.split(value).length - 1;
13
+ };
14
+ var isStandaloneMarker = function isStandaloneMarker(content, marker, index) {
15
+ var beforeIsLineBoundary = index === 0 || content[index - 1] === '\n';
16
+ var afterIndex = index + marker.length;
17
+ var afterIsLineBoundary = afterIndex === content.length || content[afterIndex] === '\n' || content[afterIndex] === '\r' && content[afterIndex + 1] === '\n';
18
+ return beforeIsLineBoundary && afterIsLineBoundary;
19
+ };
20
+ var detectLineEnding = function detectLineEnding(content) {
21
+ var _content$match$length, _content$match, _content$replace$matc, _content$replace$matc2;
22
+ var 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;
23
+ var 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;
24
+ return crlfCount > lfOnlyCount ? '\r\n' : '\n';
25
+ };
26
+ var 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.'];
27
+ var renderManagedBlock = function renderManagedBlock(_ref) {
28
+ var lineEnding = _ref.lineEnding,
29
+ guidance = _ref.guidance;
30
+ var 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:', ''].concat(_toConsumableArray(guidance.skillEntrypoints.map(function (entrypoint) {
31
+ return "- `".concat(entrypoint, "`");
32
+ })), ['', "Before starting frontend UI work, check and complete this repository's ADS setup by following:", '', "`".concat(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.', ''];
33
+ return [ADS_INIT_START_MARKER, '## Getting started with the Atlassian Design System', ''].concat(_toConsumableArray(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);
34
+ };
35
+ var readTargetStats = function readTargetStats(targetPath) {
36
+ try {
37
+ return lstatSync(targetPath);
38
+ } catch (error) {
39
+ if (error.code === 'ENOENT') {
40
+ return undefined;
41
+ }
42
+ throw error;
43
+ }
44
+ };
45
+ var atomicWriteFile = function atomicWriteFile(_ref2) {
46
+ var targetPath = _ref2.targetPath,
47
+ content = _ref2.content,
48
+ mode = _ref2.mode,
49
+ targetExists = _ref2.targetExists;
50
+ var temporaryPath = path.join(path.dirname(targetPath), ".".concat(path.basename(targetPath), ".").concat(process.pid, ".").concat(randomUUID(), ".tmp"));
51
+ var temporaryFileExists = false;
52
+ try {
53
+ writeFileSync(temporaryPath, content, {
54
+ encoding: 'utf8',
55
+ flag: 'wx',
56
+ mode: mode
57
+ });
58
+ temporaryFileExists = true;
59
+ try {
60
+ renameSync(temporaryPath, targetPath);
61
+ temporaryFileExists = false;
62
+ } catch (error) {
63
+ var code = error.code;
64
+ var canFallbackOnWindows = process.platform === 'win32' && targetExists && (code === 'EACCES' || code === 'EEXIST' || code === 'EPERM');
65
+ if (!canFallbackOnWindows) {
66
+ throw error;
67
+ }
68
+ writeFileSync(targetPath, content, {
69
+ encoding: 'utf8',
70
+ mode: mode
71
+ });
72
+ unlinkSync(temporaryPath);
73
+ temporaryFileExists = false;
74
+ }
75
+ } finally {
76
+ if (temporaryFileExists) {
77
+ try {
78
+ unlinkSync(temporaryPath);
79
+ } catch (_unused) {
80
+ // Preserve the original write failure if temporary cleanup also fails.
81
+ }
82
+ }
83
+ }
84
+ };
85
+ export var updateAgentsFile = function updateAgentsFile(_ref3) {
86
+ var _stats$mode;
87
+ var projectRoot = _ref3.projectRoot,
88
+ guidance = _ref3.guidance;
89
+ var targetPath = path.join(projectRoot, AGENTS_FILE_RELATIVE_PATH);
90
+ var stats = readTargetStats(targetPath);
91
+ if (stats !== null && stats !== void 0 && stats.isSymbolicLink()) {
92
+ throw new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because it is a symbolic link."));
93
+ }
94
+ if (stats && !stats.isFile()) {
95
+ throw new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because it is not a regular file."));
96
+ }
97
+ var existingContent = stats ? readFileSync(targetPath, 'utf8') : '';
98
+ var lineEnding = detectLineEnding(existingContent);
99
+ var managedBlock = renderManagedBlock({
100
+ lineEnding: lineEnding,
101
+ guidance: guidance
102
+ });
103
+ var startCount = countOccurrences(existingContent, ADS_INIT_START_MARKER);
104
+ var endCount = countOccurrences(existingContent, ADS_INIT_END_MARKER);
105
+ var nextContent;
106
+ var status;
107
+ if (!stats) {
108
+ nextContent = "".concat(managedBlock).concat(lineEnding);
109
+ status = 'created';
110
+ } else if (startCount === 0 && endCount === 0) {
111
+ var separator = existingContent.length === 0 ? '' : existingContent.endsWith("".concat(lineEnding).concat(lineEnding)) ? '' : existingContent.endsWith(lineEnding) ? lineEnding : "".concat(lineEnding).concat(lineEnding);
112
+ nextContent = "".concat(existingContent).concat(separator).concat(managedBlock).concat(lineEnding);
113
+ status = 'appended';
114
+ } else {
115
+ if (startCount !== 1 || endCount !== 1) {
116
+ throw markerError();
117
+ }
118
+ var startIndex = existingContent.indexOf(ADS_INIT_START_MARKER);
119
+ var endIndex = existingContent.indexOf(ADS_INIT_END_MARKER);
120
+ if (startIndex > endIndex || !isStandaloneMarker(existingContent, ADS_INIT_START_MARKER, startIndex) || !isStandaloneMarker(existingContent, ADS_INIT_END_MARKER, endIndex)) {
121
+ throw markerError();
122
+ }
123
+ var afterManagedBlock = endIndex + ADS_INIT_END_MARKER.length;
124
+ nextContent = "".concat(existingContent.slice(0, startIndex)).concat(managedBlock).concat(existingContent.slice(afterManagedBlock));
125
+ if (nextContent === existingContent) {
126
+ return {
127
+ status: 'already-current',
128
+ path: AGENTS_FILE_RELATIVE_PATH
129
+ };
130
+ }
131
+ status = 'updated';
132
+ }
133
+ atomicWriteFile({
134
+ targetPath: targetPath,
135
+ content: nextContent,
136
+ mode: (_stats$mode = stats === null || stats === void 0 ? void 0 : stats.mode) !== null && _stats$mode !== void 0 ? _stats$mode : 438,
137
+ targetExists: stats !== undefined
138
+ });
139
+ return {
140
+ status: status,
141
+ path: AGENTS_FILE_RELATIVE_PATH
142
+ };
143
+ };
@@ -17,36 +17,21 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
17
17
  * A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
18
18
  */
19
19
 
20
- /**
21
- * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
22
- */
23
- var oneLine = function oneLine(text) {
24
- return text.replace(/\s+/g, ' ').trim();
25
- };
20
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
26
21
 
27
22
  /**
28
- * Render the props section as an aligned two-column list: `name type`, with the description on
29
- * a wrapped continuation line. Returns an empty array when there are no props.
23
+ * Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
24
+ * names visually distinct, aligns columns, and bounds long generated type expressions.
30
25
  */
31
26
  var formatProps = function formatProps(props) {
32
- if (props.length === 0) {
33
- return ['Props: none'];
34
- }
35
-
36
- // Align the type column to the longest prop name for readability.
37
- var longestName = props.reduce(function (max, prop) {
27
+ return humanFormat.propertyTable(props.map(function (prop) {
38
28
  var _prop$name;
39
- return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
40
- }, 0);
41
- var rows = props.flatMap(function (prop) {
42
- var _prop$name2;
43
- var name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
44
- var type = prop.type ? oneLine(prop.type) : '';
45
- var header = " ".concat(name, " ").concat(type).trimEnd();
46
- var description = prop.description ? " ".concat(oneLine(prop.description)) : null;
47
- return description ? [header, description] : [header];
48
- });
49
- return ["Props (".concat(props.length, "):")].concat(_toConsumableArray(rows));
29
+ return {
30
+ name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
31
+ type: prop.type,
32
+ description: prop.description
33
+ };
34
+ }));
50
35
  };
51
36
 
52
37
  /**
@@ -59,7 +44,7 @@ var formatExamples = function formatExamples(examples) {
59
44
  }
60
45
  var blocks = examples.map(function (example, index) {
61
46
  var code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
62
- return ["Example ".concat(index + 1, ":"), '```tsx', code, '```'].join('\n');
47
+ return [humanFormat.section("Example ".concat(index + 1)), humanFormat.codeBlock(code)].join('\n');
63
48
  });
64
49
  return ["Examples (".concat(examples.length, "):"), ''].concat(_toConsumableArray(blocks));
65
50
  };
@@ -69,14 +54,22 @@ var formatExamples = function formatExamples(examples) {
69
54
  * data is not a recognisable component object, so the caller can fall back to generic rendering.
70
55
  */
71
56
  export var formatComponent = function formatComponent(data) {
72
- var _component$props, _component$examples, _component$designSour;
57
+ var _component$usageGuide, _component$props, _component$examples, _component$designSour;
73
58
  // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
74
59
  var component = Array.isArray(data) ? data[0] : data;
75
60
  if (!component || _typeof(component) !== 'object' || typeof component.name !== 'string') {
76
61
  return null;
77
62
  }
78
- var header = component.package ? "".concat(component.name, " (").concat(component.package, ")") : component.name;
79
- var sections = [header, '='.repeat(header.length), ''].concat(_toConsumableArray(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])));
63
+ var header = humanFormat.heading(component.name);
64
+ var metadata = humanFormat.metadata([component.status, component.category, component.package]);
65
+ var sections = [header].concat(_toConsumableArray(metadata ? [metadata] : []));
66
+ if (component.description) sections.push('', component.description);
67
+ if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
68
+ sections.push.apply(sections, ['', humanFormat.section('Use it well')].concat(_toConsumableArray(component.usageGuidelines.slice(0, 4).map(function (item) {
69
+ return " ".concat(humanFormat.success('•'), " ").concat(item);
70
+ }))));
71
+ }
72
+ sections.push.apply(sections, [''].concat(_toConsumableArray(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []))));
80
73
  var examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
81
74
  if (examples.length > 0) {
82
75
  sections.push.apply(sections, [''].concat(_toConsumableArray(examples)));
@@ -86,7 +79,7 @@ export var formatComponent = function formatComponent(data) {
86
79
  // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
87
80
  // `Design: undefined`.
88
81
  if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
89
- sections.push('', "Design: ".concat(component.designSource.figmaUrl));
82
+ sections.push('', "".concat(humanFormat.section('Design:'), " ").concat(humanFormat.action(component.designSource.figmaUrl)));
90
83
  }
91
84
  return sections.join('\n');
92
85
  };
@@ -9,6 +9,7 @@ import _typeof from "@babel/runtime/helpers/typeof";
9
9
  * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
10
10
  * rather than raw JSON; `--json` still exposes the full structured payload.
11
11
  */
12
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
12
13
 
13
14
  /**
14
15
  * Convert a camelCase / snake_case field key into a human "Title Case" heading,
@@ -46,7 +47,7 @@ var formatListItem = function formatListItem(item) {
46
47
  var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
47
48
  var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
48
49
  var codeBlocks = codeKeys.flatMap(function (key) {
49
- return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [" ```tsx\n".concat(record[key], "\n ```")]);
50
+ return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [humanFormat.codeBlock(record[key])]);
50
51
  });
51
52
  var additionalFields = Object.entries(record).flatMap(function (_ref) {
52
53
  var _ref2 = _slicedToArray(_ref, 2),
@@ -10,6 +10,7 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
10
10
  * left to the caller's generic fallback.
11
11
  */
12
12
 
13
+ import { humanFormat } from '@atlaskit/cli-output/human-format';
13
14
  import { CLI_BIN_NAME } from '../commands/cli-metadata';
14
15
  import { compactResults } from './compact-results';
15
16
 
@@ -20,19 +21,6 @@ var pluralize = function pluralize(count, noun) {
20
21
  return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
21
22
  };
22
23
 
23
- /**
24
- * Append a distribution-specific invocation to a compact row's follow-up command.
25
- *
26
- * Used for every `search` result, where the natural next step is to view that match in full.
27
- * `--all` listings omit it because echoing every row's own name would just be noise.
28
- */
29
- var withFollowUp = function withFollowUp(_ref) {
30
- var line = _ref.line,
31
- followUp = _ref.followUp,
32
- invocation = _ref.invocation;
33
- return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
34
- };
35
-
36
24
  /**
37
25
  * Render one component as a compact line.
38
26
  *
@@ -41,13 +29,13 @@ var withFollowUp = function withFollowUp(_ref) {
41
29
  * context and a tag would just be noise.
42
30
  */
43
31
  var formatComponentLine = function formatComponentLine(component, invocation) {
44
- var name = component.name;
45
- var pkg = component.package ? " ".concat(component.package) : '';
46
- var meta = [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')].join(', ');
47
- return withFollowUp({
48
- line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
49
- followUp: component.followUp,
50
- invocation: invocation
32
+ return humanFormat.searchRow({
33
+ name: component.name,
34
+ package: component.package,
35
+ source: 'ads',
36
+ kind: 'component',
37
+ metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
38
+ followUp: component.followUp ? "".concat(invocation, " ").concat(component.followUp) : undefined
51
39
  });
52
40
  };
53
41
 
@@ -55,11 +43,12 @@ var formatComponentLine = function formatComponentLine(component, invocation) {
55
43
  * Render one token as a compact `name = value` line.
56
44
  */
57
45
  var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
58
- var line = tokenResult.exampleValue ? "".concat(tokenResult.name, " = ").concat(tokenResult.exampleValue) : tokenResult.name;
59
- return withFollowUp({
60
- line: line,
61
- followUp: tokenResult.followUp,
62
- invocation: invocation
46
+ return humanFormat.searchRow({
47
+ name: tokenResult.name,
48
+ source: 'ads',
49
+ kind: 'token',
50
+ metadata: tokenResult.exampleValue ? ["= ".concat(tokenResult.exampleValue)] : undefined,
51
+ followUp: tokenResult.followUp ? "".concat(invocation, " ").concat(tokenResult.followUp) : undefined
63
52
  });
64
53
  };
65
54
 
@@ -67,13 +56,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
67
56
  * Render one icon as a compact line with its import package and short usage note.
68
57
  */
69
58
  var formatIconLine = function formatIconLine(iconResult, invocation) {
70
- var name = iconResult.componentName;
71
- var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
72
- var usage = iconResult.usage ? " \u2014 ".concat(iconResult.usage) : '';
73
- return withFollowUp({
74
- line: "".concat(name).concat(pkg).concat(usage),
75
- followUp: iconResult.followUp,
76
- invocation: invocation
59
+ return humanFormat.searchRow({
60
+ name: iconResult.componentName,
61
+ package: iconResult.package,
62
+ source: 'ads',
63
+ kind: 'icon',
64
+ metadata: iconResult.usage ? [iconResult.usage] : undefined,
65
+ followUp: iconResult.followUp ? "".concat(invocation, " ").concat(iconResult.followUp) : undefined
77
66
  });
78
67
  };
79
68
 
@@ -81,12 +70,12 @@ var formatIconLine = function formatIconLine(iconResult, invocation) {
81
70
  * Render one foundations-document match without dumping its full Markdown body.
82
71
  */
83
72
  var formatDocLine = function formatDocLine(doc, invocation) {
84
- var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
85
- var line = "".concat(doc.title).concat(summary);
86
- return withFollowUp({
87
- line: line,
88
- followUp: doc.followUp,
89
- invocation: invocation
73
+ return humanFormat.searchRow({
74
+ name: doc.title,
75
+ source: 'ads',
76
+ kind: 'docs',
77
+ description: doc.summary,
78
+ followUp: doc.followUp ? "".concat(invocation, " ").concat(doc.followUp) : undefined
90
79
  });
91
80
  };
92
81
 
@@ -97,13 +86,13 @@ var formatDocLine = function formatDocLine(doc, invocation) {
97
86
  * `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
98
87
  * each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
99
88
  */
100
- export var formatCompactResults = function formatCompactResults(_ref2) {
101
- var kind = _ref2.kind,
102
- data = _ref2.data,
103
- _ref2$showFollowUp = _ref2.showFollowUp,
104
- showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
105
- _ref2$invocation = _ref2.invocation,
106
- invocation = _ref2$invocation === void 0 ? CLI_BIN_NAME : _ref2$invocation;
89
+ export var formatCompactResults = function formatCompactResults(_ref) {
90
+ var kind = _ref.kind,
91
+ data = _ref.data,
92
+ _ref$showFollowUp = _ref.showFollowUp,
93
+ showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp,
94
+ _ref$invocation = _ref.invocation,
95
+ invocation = _ref$invocation === void 0 ? CLI_BIN_NAME : _ref$invocation;
107
96
  var compact = compactResults({
108
97
  kind: kind,
109
98
  data: data,
@@ -0,0 +1,22 @@
1
+ export declare const ADS_INIT_START_MARKER = "<!-- ADS:INIT:START -->";
2
+ export declare const ADS_INIT_END_MARKER = "<!-- ADS:INIT:END -->";
3
+ export declare const AGENTS_FILE_RELATIVE_PATH = "AGENTS.md";
4
+ export type AgentsFileResult = {
5
+ status: 'created' | 'appended' | 'updated' | 'already-current';
6
+ path: typeof AGENTS_FILE_RELATIVE_PATH;
7
+ } | {
8
+ status: 'not-written';
9
+ path: typeof AGENTS_FILE_RELATIVE_PATH;
10
+ reason: 'not-in-git-repository';
11
+ };
12
+ export type AgentsGuidance = {
13
+ mode: 'skills-installed';
14
+ skillEntrypoints: string[];
15
+ getStartedPath: string;
16
+ } | {
17
+ mode: 'public';
18
+ };
19
+ export declare const updateAgentsFile: ({ projectRoot, guidance, }: {
20
+ projectRoot: string;
21
+ guidance: AgentsGuidance;
22
+ }) => AgentsFileResult;
@@ -1,11 +1,3 @@
1
- /**
2
- * Human-readable renderer for a single "doc object" payload — the shape returned by the
3
- * accessibility (`docs a11y`) and migration (`docs migration`) tools.
4
- *
5
- * These tools return a structured object (title, description, and several labelled lists such
6
- * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
7
- * rather than raw JSON; `--json` still exposes the full structured payload.
8
- */
9
1
  /**
10
2
  * Render a doc-object payload as readable text. Handles both the full guide shape (a11y guidance,
11
3
  * migration guide — keyed by `title`) and the topic-index shape the a11y tool returns when no
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "An npx-runnable command-line tool to query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.",
5
5
  "author": "Atlassian Pty Ltd",
6
6
  "license": "Apache-2.0",
@@ -32,6 +32,7 @@
32
32
  },
33
33
  "dependencies": {
34
34
  "@atlaskit/ads-mcp": "^1.10.0",
35
+ "@atlaskit/cli-output": "^0.1.0",
35
36
  "@babel/runtime": "^7.0.0",
36
37
  "chalk": "^4.1.2"
37
38
  },