@atlaskit/ads-cli 0.9.0 → 0.10.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,14 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.10.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`537518b083114`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/537518b083114) -
8
+ Extend `init` with a repository-local ADS setup reference and a managed `AGENTS.md` block. The
9
+ guidance links installed skills when available and documents hosted ADS MCP setup without writing
10
+ MCP client configuration files.
11
+
3
12
  ## 0.9.0
4
13
 
5
14
  ### Minor Changes
package/README.md CHANGED
@@ -23,7 +23,7 @@ The CLI has these commands:
23
23
 
24
24
  | Command | Description |
25
25
  | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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. |
26
+ | `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
27
  | `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
28
  | `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
29
  | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
@@ -42,7 +42,7 @@ The CLI has these commands:
42
42
  ## Examples
43
43
 
44
44
  ```sh
45
- # Set up ADS skills and the Atlas plugin for the current Git repository
45
+ # Set up ADS guidance for coding agents in the current Git repository
46
46
  npx @atlaskit/ads-cli init
47
47
 
48
48
  # Unified human-readable search — components, tokens, icons, and docs grouped together
@@ -90,8 +90,10 @@ npx @atlaskit/ads-cli manifest --json
90
90
  resolved and run, it installs three repository-local skills under `.agents/skills`:
91
91
  `atlassian-design-system`, `ui-styling-standard`, and `a11y-foundation`. Each is installed with
92
92
  `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.
93
+ current skills untouched. An older ADS skill missing `references/get-started.md` is updated when the
94
+ published skill provides that reference. If the installed skill still lacks the reference, `init`
95
+ continues with public repository guidance rather than failing. If a destination exists without a
96
+ `SKILL.md`, `init` refuses to overwrite it and continues attempting the other skills.
95
97
 
96
98
  If `@atlassian/skills` cannot be resolved or run—for example because the package registry is
97
99
  unavailable or requires Atlassian authentication—`init` skips all repository-local skills after the
@@ -99,11 +101,24 @@ first availability failure and continues successfully. `npx @atlaskit/ads-cli` r
99
101
  and Atlas plugin setup still runs. JSON output reports each skipped skill as `not-installed` with
100
102
  the stable reason `skills-installer-unavailable`.
101
103
 
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.
104
+ In a Git repository, `init` creates or safely updates a marked ADS initialization block in the root
105
+ `AGENTS.md`, preserving user-authored content. When skills are installed, the block points to the
106
+ three skill entrypoints and the repository-local setup workflow. In public fallback mode, it omits
107
+ paths that were not installed. Both modes prefer `atlas ads`, document the `npx @atlaskit/ads-cli`
108
+ fallback, and include merge-safe setup snippets for the hosted ADS MCP server for Cursor, VS Code,
109
+ and Codex. `init` does not create or merge `.cursor/mcp.json`, `.vscode/mcp.json`, or
110
+ `.codex/config.toml`; agents apply those instructions only when a repository does not already
111
+ configure ADS MCP. Re-running `init` updates only the marked block and skips the write when it is
112
+ already current. Malformed markers and symlinked or non-regular `AGENTS.md` targets are refused
113
+ rather than overwritten.
114
+
115
+ Running `init` outside a Git repository skips the repository-local skills and `AGENTS.md` update and
116
+ reports why, but still performs Atlas setup. `init` installs the Atlas CLI ADS plugin whenever Atlas
117
+ is available and the plugin is missing. Atlas setup is also attempted before reporting a failure to
118
+ install or update the repository-local guidance. When Atlas itself is unavailable, repository setup
119
+ still succeeds and the CLI explains that `npx @atlaskit/ads-cli` remains available. Human output
120
+ includes the repository-local `references/get-started.md` next step only when that skill workflow
121
+ exists; JSON output reports the skills, `AGENTS.md`, Atlas, and next-step status.
107
122
 
108
123
  - **Every command is human-readable by default; `--json` is the only path to structured output.**
109
124
  `search` and the `--all` listings print one compact line per result (e.g.
@@ -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 @@ 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
+ };
@@ -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
+ };
@@ -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;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.9.0",
3
+ "version": "0.10.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",