@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 +21 -0
- package/README.md +26 -10
- package/bin/ads-cli.js +9 -2
- package/dist/cjs/commands/init.js +79 -6
- package/dist/cjs/commands/update-agents-file.js +150 -0
- package/dist/cjs/output/format-component.js +23 -31
- package/dist/cjs/output/format-doc-object.js +2 -1
- package/dist/cjs/output/format-results.js +34 -45
- package/dist/es2019/commands/init.js +70 -2
- package/dist/es2019/commands/update-agents-file.js +139 -0
- package/dist/es2019/output/format-component.js +22 -31
- package/dist/es2019/output/format-doc-object.js +2 -1
- package/dist/es2019/output/format-results.js +27 -37
- package/dist/esm/commands/init.js +79 -6
- package/dist/esm/commands/update-agents-file.js +143 -0
- package/dist/esm/output/format-component.js +23 -30
- package/dist/esm/output/format-doc-object.js +2 -1
- package/dist/esm/output/format-results.js +34 -45
- package/dist/types/commands/update-agents-file.d.ts +22 -0
- package/dist/types/output/format-doc-object.d.ts +0 -8
- package/package.json +2 -1
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
|
|
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` |
|
|
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
|
|
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.
|
|
94
|
-
|
|
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
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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.
|
|
29
|
-
|
|
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
|
|
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 =
|
|
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
|
|
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
|
-
*
|
|
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
|
-
|
|
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
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
|
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 =
|
|
86
|
-
var
|
|
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), ":")] : []), [
|
|
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),
|