@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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.11.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`9a9bcd8b61613`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/9a9bcd8b61613) -
8
+ Unify ADS and Platform CLI discovery with shared search formatting, ADS foundation catalogs,
9
+ aligned property tables, dark code blocks, and invocation-aware follow-up commands.
10
+
11
+ ### Patch Changes
12
+
13
+ - Updated dependencies
14
+
15
+ ## 0.10.0
16
+
17
+ ### Minor Changes
18
+
19
+ - [`537518b083114`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/537518b083114) -
20
+ Extend `init` with a repository-local ADS setup reference and a managed `AGENTS.md` block. The
21
+ guidance links installed skills when available and documents hosted ADS MCP setup without writing
22
+ MCP client configuration files.
23
+
3
24
  ## 0.9.0
4
25
 
5
26
  ### Minor Changes
package/README.md CHANGED
@@ -15,7 +15,8 @@ reimplements search ranking or bundles its own copy of the dataset — there is
15
15
 
16
16
  Distributing ADS structured content through a CLI lets developers **and coding agents** query
17
17
  components from the terminal without configuring an MCP client. Human-readable output is the
18
- default; `--json` emits a stable, self-describing envelope for machine consumers.
18
+ default, with the same highlighted property tables and GitHub-dark-like code blocks used by Platform
19
+ CLI; `--json` emits a stable, self-describing envelope for machine consumers.
19
20
 
20
21
  ## Commands
21
22
 
@@ -23,7 +24,7 @@ The CLI has these commands:
23
24
 
24
25
  | Command | Description |
25
26
  | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
- | `init` | Install the repository-local ADS, UI Styling Standard, and Accessibility Foundation skills and set up the Atlas CLI ADS plugin. If `@atlassian/skills` is unavailable, skill installation is skipped and Atlas setup continues. |
27
+ | `init` | Set up repository-local ADS guidance and the Atlas CLI ADS plugin. Installs the ADS, UI Styling Standard, and Accessibility Foundation skills when `@atlassian/skills` is available, with a public guidance fallback when it is not. |
27
28
  | `search <query...>` | **Unified** fuzzy-search across components, tokens, icons, and foundations docs at once. Narrow results with `--type component\|token\|icon\|docs`; limit with `--limit N`. |
28
29
  | `batch --command <command> [args...]...` | Run multiple ADS CLI queries, including different command types, in one process. Repeat `--command` once per child; each keeps its normal arguments, flags, and response envelope. Tokenized requests are canonical; complete quoted requests are also accepted. |
29
30
  | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
@@ -42,7 +43,7 @@ The CLI has these commands:
42
43
  ## Examples
43
44
 
44
45
  ```sh
45
- # Set up ADS skills and the Atlas plugin for the current Git repository
46
+ # Set up ADS guidance for coding agents in the current Git repository
46
47
  npx @atlaskit/ads-cli init
47
48
 
48
49
  # Unified human-readable search — components, tokens, icons, and docs grouped together
@@ -90,8 +91,10 @@ npx @atlaskit/ads-cli manifest --json
90
91
  resolved and run, it installs three repository-local skills under `.agents/skills`:
91
92
  `atlassian-design-system`, `ui-styling-standard`, and `a11y-foundation`. Each is installed with
92
93
  `npx --yes @atlassian/skills add <skill> --universal --yes`. The command is idempotent and leaves
93
- current skills untouched. If a destination exists without a `SKILL.md`, `init` refuses to overwrite
94
- it and continues attempting the other skills.
94
+ current skills untouched. An older ADS skill missing `references/get-started.md` is updated when the
95
+ published skill provides that reference. If the installed skill still lacks the reference, `init`
96
+ continues with public repository guidance rather than failing. If a destination exists without a
97
+ `SKILL.md`, `init` refuses to overwrite it and continues attempting the other skills.
95
98
 
96
99
  If `@atlassian/skills` cannot be resolved or run—for example because the package registry is
97
100
  unavailable or requires Atlassian authentication—`init` skips all repository-local skills after the
@@ -99,11 +102,24 @@ first availability failure and continues successfully. `npx @atlaskit/ads-cli` r
99
102
  and Atlas plugin setup still runs. JSON output reports each skipped skill as `not-installed` with
100
103
  the stable reason `skills-installer-unavailable`.
101
104
 
102
- Running `init` outside a Git repository skips the repository-local skills and reports why, but still
103
- performs Atlas setup. `init` installs the Atlas CLI ADS plugin whenever Atlas is available and the
104
- plugin is missing. Atlas setup is also attempted before reporting a failure to install or update a
105
- skill. When Atlas itself is unavailable, skill setup still succeeds and the CLI explains that
106
- `npx @atlaskit/ads-cli` remains available. JSON output reports the skill and Atlas status.
105
+ In a Git repository, `init` creates or safely updates a marked ADS initialization block in the root
106
+ `AGENTS.md`, preserving user-authored content. When skills are installed, the block points to the
107
+ three skill entrypoints and the repository-local setup workflow. In public fallback mode, it omits
108
+ paths that were not installed. Both modes prefer `atlas ads`, document the `npx @atlaskit/ads-cli`
109
+ fallback, and include merge-safe setup snippets for the hosted ADS MCP server for Cursor, VS Code,
110
+ and Codex. `init` does not create or merge `.cursor/mcp.json`, `.vscode/mcp.json`, or
111
+ `.codex/config.toml`; agents apply those instructions only when a repository does not already
112
+ configure ADS MCP. Re-running `init` updates only the marked block and skips the write when it is
113
+ already current. Malformed markers and symlinked or non-regular `AGENTS.md` targets are refused
114
+ rather than overwritten.
115
+
116
+ Running `init` outside a Git repository skips the repository-local skills and `AGENTS.md` update and
117
+ reports why, but still performs Atlas setup. `init` installs the Atlas CLI ADS plugin whenever Atlas
118
+ is available and the plugin is missing. Atlas setup is also attempted before reporting a failure to
119
+ install or update the repository-local guidance. When Atlas itself is unavailable, repository setup
120
+ still succeeds and the CLI explains that `npx @atlaskit/ads-cli` remains available. Human output
121
+ includes the repository-local `references/get-started.md` next step only when that skill workflow
122
+ exists; JSON output reports the skills, `AGENTS.md`, Atlas, and next-step status.
107
123
 
108
124
  - **Every command is human-readable by default; `--json` is the only path to structured output.**
109
125
  `search` and the `--all` listings print one compact line per result (e.g.
package/bin/ads-cli.js CHANGED
@@ -25,8 +25,15 @@ if (isDev) {
25
25
  }
26
26
 
27
27
  // The AFM repo-root shell shim sets this display-only value because it delegates to this same
28
- // package entrypoint. Published package runs have no override and advertise their npx command.
29
- const invocation = process.env.ADS_CLI_DISPLAY_INVOCATION || 'npx @atlaskit/ads-cli';
28
+ // package entrypoint. A direct source invocation advertises the exact runnable command; published
29
+ // package runs retain the stable npx form.
30
+ const { resolveInvocation } = require('@atlaskit/cli-output/invocation');
31
+ const invocation = resolveInvocation({
32
+ argv1: process.argv[1],
33
+ isDev,
34
+ environmentVariable: 'ADS_CLI_DISPLAY_INVOCATION',
35
+ publishedInvocation: 'npx @atlaskit/ads-cli',
36
+ });
30
37
 
31
38
  require(path.join('..', isDev ? 'src/cli' : 'dist/cjs/cli'))
32
39
  .run(process.argv.slice(2), undefined, { invocation })
@@ -17,6 +17,7 @@ var _writeHumanError = require("../output/write-human-error");
17
17
  var _writeJsonEnvelope = require("../output/write-json-envelope");
18
18
  var _types = require("../types");
19
19
  var _cliMetadata = require("./cli-metadata");
20
+ var _updateAgentsFile = require("./update-agents-file");
20
21
  function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
21
22
  function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
22
23
  function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
@@ -37,6 +38,8 @@ var SKILLS = [{
37
38
  relativePath: '.agents/skills/a11y-foundation',
38
39
  requiredFiles: [SKILL_ENTRYPOINT]
39
40
  }];
41
+ var ADS_SKILL = SKILLS[0];
42
+ var SKILL_GET_STARTED_RELATIVE_PATH = "".concat(ADS_SKILL.relativePath, "/references/get-started.md");
40
43
  var GIT_MARKER = '.git';
41
44
  var SKILLS_INSTALLER_PACKAGE = '@atlassian/skills';
42
45
  var SKILLS_INSTALLER_UNAVAILABLE_REASON = 'skills-installer-unavailable';
@@ -145,13 +148,33 @@ var validateInput = function validateInput(input) {
145
148
  }
146
149
  return undefined;
147
150
  };
151
+ var writeAgentsFileResult = function writeAgentsFileResult(_ref3) {
152
+ var result = _ref3.result,
153
+ writer = _ref3.writer;
154
+ switch (result.status) {
155
+ case 'created':
156
+ writer.out("\u2713 Created ".concat(_updateAgentsFile.AGENTS_FILE_RELATIVE_PATH, " with ADS setup guidance"));
157
+ return;
158
+ case 'appended':
159
+ writer.out("\u2713 Appended ADS setup guidance to ".concat(_updateAgentsFile.AGENTS_FILE_RELATIVE_PATH));
160
+ return;
161
+ case 'updated':
162
+ writer.out("\u2713 Updated ADS setup guidance in ".concat(_updateAgentsFile.AGENTS_FILE_RELATIVE_PATH));
163
+ return;
164
+ case 'already-current':
165
+ writer.out("\u2713 ADS setup guidance already current in ".concat(_updateAgentsFile.AGENTS_FILE_RELATIVE_PATH));
166
+ return;
167
+ case 'not-written':
168
+ writer.out("\u2013 ".concat(_updateAgentsFile.AGENTS_FILE_RELATIVE_PATH, " not updated because the current directory is not in a Git repository"));
169
+ }
170
+ };
148
171
  var runInitCommand = exports.runInitCommand = /*#__PURE__*/function () {
149
- var _ref4 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(_ref3) {
150
- 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;
172
+ var _ref5 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(_ref4) {
173
+ 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;
151
174
  return _regenerator.default.wrap(function (_context2) {
152
175
  while (1) switch (_context2.prev = _context2.next) {
153
176
  case 0:
154
- input = _ref3.input, json = _ref3.json, writer = _ref3.writer, invocation = _ref3.invocation, cwd = _ref3.cwd;
177
+ input = _ref4.input, json = _ref4.json, writer = _ref4.writer, invocation = _ref4.invocation, cwd = _ref4.cwd;
155
178
  usageError = validateInput(input);
156
179
  if (!usageError) {
157
180
  _context2.next = 1;
@@ -174,6 +197,17 @@ var runInitCommand = exports.runInitCommand = /*#__PURE__*/function () {
174
197
  if (!json) {
175
198
  writer.out('– Repository-local skills not installed because the current directory is not in a Git repository');
176
199
  }
200
+ agentsMd = {
201
+ status: 'not-written',
202
+ path: _updateAgentsFile.AGENTS_FILE_RELATIVE_PATH,
203
+ reason: 'not-in-git-repository'
204
+ };
205
+ if (!json) {
206
+ writeAgentsFileResult({
207
+ result: agentsMd,
208
+ writer: writer
209
+ });
210
+ }
177
211
  _context2.next = 7;
178
212
  break;
179
213
  case 2:
@@ -312,6 +346,36 @@ var runInitCommand = exports.runInitCommand = /*#__PURE__*/function () {
312
346
  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');
313
347
  }
314
348
  }
349
+ installedSkills = skills.filter(function (skill) {
350
+ return skill.status !== 'not-installed';
351
+ });
352
+ _adsSkillInstalled = installedSkills.some(function (skill) {
353
+ return skill.name === ADS_SKILL.name;
354
+ });
355
+ if (skillsInstallerUnavailable || _adsSkillInstalled) {
356
+ try {
357
+ agentsMd = (0, _updateAgentsFile.updateAgentsFile)({
358
+ projectRoot: projectRoot,
359
+ guidance: _adsSkillInstalled ? {
360
+ mode: 'skills-installed',
361
+ skillEntrypoints: installedSkills.map(function (skill) {
362
+ return "".concat(skill.path, "/").concat(SKILL_ENTRYPOINT);
363
+ }),
364
+ getStartedPath: SKILL_GET_STARTED_RELATIVE_PATH
365
+ } : {
366
+ mode: 'public'
367
+ }
368
+ });
369
+ if (!json) {
370
+ writeAgentsFileResult({
371
+ result: agentsMd,
372
+ writer: writer
373
+ });
374
+ }
375
+ } catch (error) {
376
+ repositorySetupErrors.push(error instanceof Error ? error : new Error('Failed to set up the ADS repository guidance.'));
377
+ }
378
+ }
315
379
  case 7:
316
380
  atlasCwd = projectRoot !== null && projectRoot !== void 0 ? projectRoot : _nodePath.default.resolve(cwd);
317
381
  if (!(invocation === _cliMetadata.CLI_ATLAS_INVOCATION)) {
@@ -390,18 +454,27 @@ var runInitCommand = exports.runInitCommand = /*#__PURE__*/function () {
390
454
  return error.message;
391
455
  }).join('\n'));
392
456
  case 14:
393
- if (!(skills.length !== SKILLS.length)) {
457
+ if (!(skills.length !== SKILLS.length || !agentsMd)) {
394
458
  _context2.next = 15;
395
459
  break;
396
460
  }
397
461
  throw new Error('Failed to determine the ADS repository setup result.');
398
462
  case 15:
463
+ adsSkillInstalled = skills.some(function (skill) {
464
+ return skill.name === ADS_SKILL.name && skill.status !== 'not-installed';
465
+ });
466
+ nextStep = projectRoot && adsSkillInstalled ? SKILL_GET_STARTED_RELATIVE_PATH : null;
467
+ if (!json && nextStep) {
468
+ writer.out("\u2192 Next: follow ".concat(nextStep, " to complete repository setup"));
469
+ }
399
470
  data = {
400
471
  projectRoot: projectRoot !== null && projectRoot !== void 0 ? projectRoot : null,
401
472
  skills: skills,
473
+ agentsMd: agentsMd,
402
474
  atlas: {
403
475
  status: atlasPluginStatus
404
- }
476
+ },
477
+ nextStep: nextStep
405
478
  };
406
479
  if (json) {
407
480
  (0, _writeJsonEnvelope.writeJsonEnvelope)({
@@ -422,6 +495,6 @@ var runInitCommand = exports.runInitCommand = /*#__PURE__*/function () {
422
495
  }, _callee);
423
496
  }));
424
497
  return function runInitCommand(_x) {
425
- return _ref4.apply(this, arguments);
498
+ return _ref5.apply(this, arguments);
426
499
  };
427
500
  }();
@@ -0,0 +1,150 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.updateAgentsFile = exports.AGENTS_FILE_RELATIVE_PATH = exports.ADS_INIT_START_MARKER = exports.ADS_INIT_END_MARKER = void 0;
8
+ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
+ var _nodeCrypto = require("node:crypto");
10
+ var _nodeFs = require("node:fs");
11
+ var _nodePath = _interopRequireDefault(require("node:path"));
12
+ var ADS_INIT_START_MARKER = exports.ADS_INIT_START_MARKER = '<!-- ADS:INIT:START -->';
13
+ var ADS_INIT_END_MARKER = exports.ADS_INIT_END_MARKER = '<!-- ADS:INIT:END -->';
14
+ var AGENTS_FILE_RELATIVE_PATH = exports.AGENTS_FILE_RELATIVE_PATH = 'AGENTS.md';
15
+ var markerError = function markerError() {
16
+ 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."));
17
+ };
18
+ var countOccurrences = function countOccurrences(content, value) {
19
+ return content.split(value).length - 1;
20
+ };
21
+ var isStandaloneMarker = function isStandaloneMarker(content, marker, index) {
22
+ var beforeIsLineBoundary = index === 0 || content[index - 1] === '\n';
23
+ var afterIndex = index + marker.length;
24
+ var afterIsLineBoundary = afterIndex === content.length || content[afterIndex] === '\n' || content[afterIndex] === '\r' && content[afterIndex + 1] === '\n';
25
+ return beforeIsLineBoundary && afterIsLineBoundary;
26
+ };
27
+ var detectLineEnding = function detectLineEnding(content) {
28
+ var _content$match$length, _content$match, _content$replace$matc, _content$replace$matc2;
29
+ 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;
30
+ 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;
31
+ return crlfCount > lfOnlyCount ? '\r\n' : '\n';
32
+ };
33
+ 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.'];
34
+ var renderManagedBlock = function renderManagedBlock(_ref) {
35
+ var lineEnding = _ref.lineEnding,
36
+ guidance = _ref.guidance;
37
+ 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((0, _toConsumableArray2.default)(guidance.skillEntrypoints.map(function (entrypoint) {
38
+ return "- `".concat(entrypoint, "`");
39
+ })), ['', "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.', ''];
40
+ return [ADS_INIT_START_MARKER, '## Getting started with the Atlassian Design System', ''].concat((0, _toConsumableArray2.default)(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);
41
+ };
42
+ var readTargetStats = function readTargetStats(targetPath) {
43
+ try {
44
+ return (0, _nodeFs.lstatSync)(targetPath);
45
+ } catch (error) {
46
+ if (error.code === 'ENOENT') {
47
+ return undefined;
48
+ }
49
+ throw error;
50
+ }
51
+ };
52
+ var atomicWriteFile = function atomicWriteFile(_ref2) {
53
+ var targetPath = _ref2.targetPath,
54
+ content = _ref2.content,
55
+ mode = _ref2.mode,
56
+ targetExists = _ref2.targetExists;
57
+ var temporaryPath = _nodePath.default.join(_nodePath.default.dirname(targetPath), ".".concat(_nodePath.default.basename(targetPath), ".").concat(process.pid, ".").concat((0, _nodeCrypto.randomUUID)(), ".tmp"));
58
+ var temporaryFileExists = false;
59
+ try {
60
+ (0, _nodeFs.writeFileSync)(temporaryPath, content, {
61
+ encoding: 'utf8',
62
+ flag: 'wx',
63
+ mode: mode
64
+ });
65
+ temporaryFileExists = true;
66
+ try {
67
+ (0, _nodeFs.renameSync)(temporaryPath, targetPath);
68
+ temporaryFileExists = false;
69
+ } catch (error) {
70
+ var code = error.code;
71
+ var canFallbackOnWindows = process.platform === 'win32' && targetExists && (code === 'EACCES' || code === 'EEXIST' || code === 'EPERM');
72
+ if (!canFallbackOnWindows) {
73
+ throw error;
74
+ }
75
+ (0, _nodeFs.writeFileSync)(targetPath, content, {
76
+ encoding: 'utf8',
77
+ mode: mode
78
+ });
79
+ (0, _nodeFs.unlinkSync)(temporaryPath);
80
+ temporaryFileExists = false;
81
+ }
82
+ } finally {
83
+ if (temporaryFileExists) {
84
+ try {
85
+ (0, _nodeFs.unlinkSync)(temporaryPath);
86
+ } catch (_unused) {
87
+ // Preserve the original write failure if temporary cleanup also fails.
88
+ }
89
+ }
90
+ }
91
+ };
92
+ var updateAgentsFile = exports.updateAgentsFile = function updateAgentsFile(_ref3) {
93
+ var _stats$mode;
94
+ var projectRoot = _ref3.projectRoot,
95
+ guidance = _ref3.guidance;
96
+ var targetPath = _nodePath.default.join(projectRoot, AGENTS_FILE_RELATIVE_PATH);
97
+ var stats = readTargetStats(targetPath);
98
+ if (stats !== null && stats !== void 0 && stats.isSymbolicLink()) {
99
+ throw new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because it is a symbolic link."));
100
+ }
101
+ if (stats && !stats.isFile()) {
102
+ throw new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because it is not a regular file."));
103
+ }
104
+ var existingContent = stats ? (0, _nodeFs.readFileSync)(targetPath, 'utf8') : '';
105
+ var lineEnding = detectLineEnding(existingContent);
106
+ var managedBlock = renderManagedBlock({
107
+ lineEnding: lineEnding,
108
+ guidance: guidance
109
+ });
110
+ var startCount = countOccurrences(existingContent, ADS_INIT_START_MARKER);
111
+ var endCount = countOccurrences(existingContent, ADS_INIT_END_MARKER);
112
+ var nextContent;
113
+ var status;
114
+ if (!stats) {
115
+ nextContent = "".concat(managedBlock).concat(lineEnding);
116
+ status = 'created';
117
+ } else if (startCount === 0 && endCount === 0) {
118
+ var separator = existingContent.length === 0 ? '' : existingContent.endsWith("".concat(lineEnding).concat(lineEnding)) ? '' : existingContent.endsWith(lineEnding) ? lineEnding : "".concat(lineEnding).concat(lineEnding);
119
+ nextContent = "".concat(existingContent).concat(separator).concat(managedBlock).concat(lineEnding);
120
+ status = 'appended';
121
+ } else {
122
+ if (startCount !== 1 || endCount !== 1) {
123
+ throw markerError();
124
+ }
125
+ var startIndex = existingContent.indexOf(ADS_INIT_START_MARKER);
126
+ var endIndex = existingContent.indexOf(ADS_INIT_END_MARKER);
127
+ if (startIndex > endIndex || !isStandaloneMarker(existingContent, ADS_INIT_START_MARKER, startIndex) || !isStandaloneMarker(existingContent, ADS_INIT_END_MARKER, endIndex)) {
128
+ throw markerError();
129
+ }
130
+ var afterManagedBlock = endIndex + ADS_INIT_END_MARKER.length;
131
+ nextContent = "".concat(existingContent.slice(0, startIndex)).concat(managedBlock).concat(existingContent.slice(afterManagedBlock));
132
+ if (nextContent === existingContent) {
133
+ return {
134
+ status: 'already-current',
135
+ path: AGENTS_FILE_RELATIVE_PATH
136
+ };
137
+ }
138
+ status = 'updated';
139
+ }
140
+ atomicWriteFile({
141
+ targetPath: targetPath,
142
+ content: nextContent,
143
+ mode: (_stats$mode = stats === null || stats === void 0 ? void 0 : stats.mode) !== null && _stats$mode !== void 0 ? _stats$mode : 438,
144
+ targetExists: stats !== undefined
145
+ });
146
+ return {
147
+ status: status,
148
+ path: AGENTS_FILE_RELATIVE_PATH
149
+ };
150
+ };
@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", {
7
7
  exports.formatComponent = void 0;
8
8
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
9
9
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
10
+ var _humanFormat = require("@atlaskit/cli-output/human-format");
10
11
  /**
11
12
  * Human-readable renderer for a single ADS component's detailed docs.
12
13
  *
@@ -25,35 +26,18 @@ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers
25
26
  */
26
27
 
27
28
  /**
28
- * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
29
- */
30
- var oneLine = function oneLine(text) {
31
- return text.replace(/\s+/g, ' ').trim();
32
- };
33
-
34
- /**
35
- * Render the props section as an aligned two-column list: `name type`, with the description on
36
- * a wrapped continuation line. Returns an empty array when there are no props.
29
+ * Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
30
+ * names visually distinct, aligns columns, and bounds long generated type expressions.
37
31
  */
38
32
  var formatProps = function formatProps(props) {
39
- if (props.length === 0) {
40
- return ['Props: none'];
41
- }
42
-
43
- // Align the type column to the longest prop name for readability.
44
- var longestName = props.reduce(function (max, prop) {
33
+ return _humanFormat.humanFormat.propertyTable(props.map(function (prop) {
45
34
  var _prop$name;
46
- return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
47
- }, 0);
48
- var rows = props.flatMap(function (prop) {
49
- var _prop$name2;
50
- var name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
51
- var type = prop.type ? oneLine(prop.type) : '';
52
- var header = " ".concat(name, " ").concat(type).trimEnd();
53
- var description = prop.description ? " ".concat(oneLine(prop.description)) : null;
54
- return description ? [header, description] : [header];
55
- });
56
- return ["Props (".concat(props.length, "):")].concat((0, _toConsumableArray2.default)(rows));
35
+ return {
36
+ name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
37
+ type: prop.type,
38
+ description: prop.description
39
+ };
40
+ }));
57
41
  };
58
42
 
59
43
  /**
@@ -66,7 +50,7 @@ var formatExamples = function formatExamples(examples) {
66
50
  }
67
51
  var blocks = examples.map(function (example, index) {
68
52
  var code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
69
- return ["Example ".concat(index + 1, ":"), '```tsx', code, '```'].join('\n');
53
+ return [_humanFormat.humanFormat.section("Example ".concat(index + 1)), _humanFormat.humanFormat.codeBlock(code)].join('\n');
70
54
  });
71
55
  return ["Examples (".concat(examples.length, "):"), ''].concat((0, _toConsumableArray2.default)(blocks));
72
56
  };
@@ -76,14 +60,22 @@ var formatExamples = function formatExamples(examples) {
76
60
  * data is not a recognisable component object, so the caller can fall back to generic rendering.
77
61
  */
78
62
  var formatComponent = exports.formatComponent = function formatComponent(data) {
79
- var _component$props, _component$examples, _component$designSour;
63
+ var _component$usageGuide, _component$props, _component$examples, _component$designSour;
80
64
  // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
81
65
  var component = Array.isArray(data) ? data[0] : data;
82
66
  if (!component || (0, _typeof2.default)(component) !== 'object' || typeof component.name !== 'string') {
83
67
  return null;
84
68
  }
85
- var header = component.package ? "".concat(component.name, " (").concat(component.package, ")") : component.name;
86
- var sections = [header, '='.repeat(header.length), ''].concat((0, _toConsumableArray2.default)(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])));
69
+ var header = _humanFormat.humanFormat.heading(component.name);
70
+ var metadata = _humanFormat.humanFormat.metadata([component.status, component.category, component.package]);
71
+ var sections = [header].concat((0, _toConsumableArray2.default)(metadata ? [metadata] : []));
72
+ if (component.description) sections.push('', component.description);
73
+ if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
74
+ sections.push.apply(sections, ['', _humanFormat.humanFormat.section('Use it well')].concat((0, _toConsumableArray2.default)(component.usageGuidelines.slice(0, 4).map(function (item) {
75
+ return " ".concat(_humanFormat.humanFormat.success('•'), " ").concat(item);
76
+ }))));
77
+ }
78
+ sections.push.apply(sections, [''].concat((0, _toConsumableArray2.default)(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []))));
87
79
  var examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
88
80
  if (examples.length > 0) {
89
81
  sections.push.apply(sections, [''].concat((0, _toConsumableArray2.default)(examples)));
@@ -93,7 +85,7 @@ var formatComponent = exports.formatComponent = function formatComponent(data) {
93
85
  // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
94
86
  // `Design: undefined`.
95
87
  if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
96
- sections.push('', "Design: ".concat(component.designSource.figmaUrl));
88
+ sections.push('', "".concat(_humanFormat.humanFormat.section('Design:'), " ").concat(_humanFormat.humanFormat.action(component.designSource.figmaUrl)));
97
89
  }
98
90
  return sections.join('\n');
99
91
  };
@@ -8,6 +8,7 @@ exports.formatDocObject = void 0;
8
8
  var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
9
9
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
10
10
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
11
+ var _humanFormat = require("@atlaskit/cli-output/human-format");
11
12
  /**
12
13
  * Human-readable renderer for a single "doc object" payload — the shape returned by the
13
14
  * accessibility (`docs a11y`) and migration (`docs migration`) tools.
@@ -53,7 +54,7 @@ var formatListItem = function formatListItem(item) {
53
54
  var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
54
55
  var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
55
56
  var codeBlocks = codeKeys.flatMap(function (key) {
56
- return [].concat((0, _toConsumableArray2.default)(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [" ```tsx\n".concat(record[key], "\n ```")]);
57
+ return [].concat((0, _toConsumableArray2.default)(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [_humanFormat.humanFormat.codeBlock(record[key])]);
57
58
  });
58
59
  var additionalFields = Object.entries(record).flatMap(function (_ref) {
59
60
  var _ref2 = (0, _slicedToArray2.default)(_ref, 2),