@atlaskit/ads-cli 0.8.2 → 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,23 @@
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
+
12
+ ## 0.9.0
13
+
14
+ ### Minor Changes
15
+
16
+ - [`3d3cd51d49e72`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/3d3cd51d49e72) -
17
+ Add an init command that installs the repository-local ADS, UI Styling Standard, and Accessibility
18
+ Foundation skills and configures the Atlas ADS plugin. When `@atlassian/skills` is unavailable,
19
+ initialization skips skills and continues with Atlas setup.
20
+
3
21
  ## 0.8.2
4
22
 
5
23
  ### Patch Changes
package/README.md CHANGED
@@ -23,6 +23,7 @@ The CLI has these commands:
23
23
 
24
24
  | Command | Description |
25
25
  | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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. |
26
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`. |
27
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. |
28
29
  | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
@@ -41,6 +42,9 @@ The CLI has these commands:
41
42
  ## Examples
42
43
 
43
44
  ```sh
45
+ # Set up ADS guidance for coding agents in the current Git repository
46
+ npx @atlaskit/ads-cli init
47
+
44
48
  # Unified human-readable search — components, tokens, icons, and docs grouped together
45
49
  npx @atlaskit/ads-cli search contrast
46
50
 
@@ -82,6 +86,40 @@ npx @atlaskit/ads-cli manifest --json
82
86
 
83
87
  ## Output contract
84
88
 
89
+ `init` resolves the Git repository root from the current directory. When `@atlassian/skills` can be
90
+ resolved and run, it installs three repository-local skills under `.agents/skills`:
91
+ `atlassian-design-system`, `ui-styling-standard`, and `a11y-foundation`. Each is installed with
92
+ `npx --yes @atlassian/skills add <skill> --universal --yes`. The command is idempotent and leaves
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.
97
+
98
+ If `@atlassian/skills` cannot be resolved or run—for example because the package registry is
99
+ unavailable or requires Atlassian authentication—`init` skips all repository-local skills after the
100
+ first availability failure and continues successfully. `npx @atlaskit/ads-cli` remains available,
101
+ and Atlas plugin setup still runs. JSON output reports each skipped skill as `not-installed` with
102
+ the stable reason `skills-installer-unavailable`.
103
+
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.
122
+
85
123
  - **Every command is human-readable by default; `--json` is the only path to structured output.**
86
124
  `search` and the `--all` listings print one compact line per result (e.g.
87
125
  `Avatar @atlaskit/avatar (42 props, 1 example)`), and unified `search` groups results into
package/dist/cjs/cli.js CHANGED
@@ -12,9 +12,10 @@ var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/
12
12
  var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
13
13
  var _cliMetadata = require("./commands/cli-metadata");
14
14
  var _definitions = require("./commands/definitions");
15
- var _getCommand = require("./commands/get-command");
15
+ var _getCommand2 = require("./commands/get-command");
16
16
  var _getVersion = require("./commands/get-version");
17
17
  var _importToolHandler = require("./commands/import-tool-handler");
18
+ var _init = require("./commands/init");
18
19
  var _runTool = require("./commands/run-tool");
19
20
  var _createErrorEnvelope = require("./envelope/create-error-envelope");
20
21
  var _createSuccessEnvelope = require("./envelope/create-success-envelope");
@@ -69,6 +70,9 @@ var buildHelpText = function buildHelpText(invocation) {
69
70
  return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
70
71
  }).join('\n');
71
72
  var examples = [{
73
+ command: 'init',
74
+ comment: 'set up repository-local frontend skills and the Atlas plugin'
75
+ }, {
72
76
  command: 'search contrast',
73
77
  comment: 'unified: components, tokens, icons & docs'
74
78
  }, {
@@ -129,9 +133,21 @@ var runRegistryCommand = /*#__PURE__*/function () {
129
133
  while (1) switch (_context2.prev = _context2.next) {
130
134
  case 0:
131
135
  command = _ref3.command, input = _ref3.input, json = _ref3.json, writer = _ref3.writer, invocation = _ref3.invocation;
136
+ if (!(command.action === 'init')) {
137
+ _context2.next = 1;
138
+ break;
139
+ }
140
+ return _context2.abrupt("return", (0, _init.runInitCommand)({
141
+ input: input,
142
+ json: json,
143
+ writer: writer,
144
+ invocation: invocation,
145
+ cwd: process.cwd()
146
+ }));
147
+ case 1:
132
148
  resolved = command.resolve(input); // A resolver returning `{ error }` indicates invalid input (a usage error).
133
149
  if (!('error' in resolved)) {
134
- _context2.next = 1;
150
+ _context2.next = 2;
135
151
  break;
136
152
  }
137
153
  if (json) {
@@ -151,9 +167,9 @@ var runRegistryCommand = /*#__PURE__*/function () {
151
167
  writer.err("Usage: ".concat(command.usage));
152
168
  }
153
169
  return _context2.abrupt("return", _types.ExitCode.UsageError);
154
- case 1:
170
+ case 2:
155
171
  if (!('data' in resolved)) {
156
- _context2.next = 2;
172
+ _context2.next = 3;
157
173
  break;
158
174
  }
159
175
  return _context2.abrupt("return", renderSingleResult({
@@ -168,9 +184,9 @@ var runRegistryCommand = /*#__PURE__*/function () {
168
184
  writer: writer,
169
185
  invocation: invocation
170
186
  }));
171
- case 2:
187
+ case 3:
172
188
  if (!resolved.batch) {
173
- _context2.next = 3;
189
+ _context2.next = 4;
174
190
  break;
175
191
  }
176
192
  return _context2.abrupt("return", runBatchRequests({
@@ -180,8 +196,8 @@ var runRegistryCommand = /*#__PURE__*/function () {
180
196
  writer: writer,
181
197
  invocation: invocation
182
198
  }));
183
- case 3:
184
- _context2.next = 4;
199
+ case 4:
200
+ _context2.next = 5;
185
201
  return Promise.all(resolved.tools.map( /*#__PURE__*/function () {
186
202
  var _ref5 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(tool) {
187
203
  var handler, _t, _t2;
@@ -216,10 +232,10 @@ var runRegistryCommand = /*#__PURE__*/function () {
216
232
  return _ref5.apply(this, arguments);
217
233
  };
218
234
  }()));
219
- case 4:
235
+ case 5:
220
236
  results = _context2.sent;
221
237
  if (!resolved.grouped) {
222
- _context2.next = 5;
238
+ _context2.next = 6;
223
239
  break;
224
240
  }
225
241
  return _context2.abrupt("return", renderGroupedResult({
@@ -231,7 +247,7 @@ var runRegistryCommand = /*#__PURE__*/function () {
231
247
  writer: writer,
232
248
  invocation: invocation
233
249
  }));
234
- case 5:
250
+ case 6:
235
251
  return _context2.abrupt("return", renderSingleResult({
236
252
  command: command,
237
253
  input: input,
@@ -241,7 +257,7 @@ var runRegistryCommand = /*#__PURE__*/function () {
241
257
  writer: writer,
242
258
  invocation: invocation
243
259
  }));
244
- case 6:
260
+ case 7:
245
261
  case "end":
246
262
  return _context2.stop();
247
263
  }
@@ -413,6 +429,7 @@ var createCapturedWriter = function createCapturedWriter() {
413
429
  */
414
430
  var runBatchChild = /*#__PURE__*/function () {
415
431
  var _ref0 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee3(_ref9) {
432
+ var _getCommand;
416
433
  var request, invocation, parsed, response, captured;
417
434
  return _regenerator.default.wrap(function (_context3) {
418
435
  while (1) switch (_context3.prev = _context3.next) {
@@ -428,7 +445,7 @@ var runBatchChild = /*#__PURE__*/function () {
428
445
  code: 'USAGE_ERROR',
429
446
  message: 'A batch request must start with a command name.'
430
447
  });
431
- _context3.next = 4;
448
+ _context3.next = 5;
432
449
  break;
433
450
  case 1:
434
451
  if (!(parsed.command === 'batch')) {
@@ -440,15 +457,27 @@ var runBatchChild = /*#__PURE__*/function () {
440
457
  code: 'USAGE_ERROR',
441
458
  message: 'Nested batch requests are not supported.'
442
459
  });
443
- _context3.next = 4;
460
+ _context3.next = 5;
444
461
  break;
445
462
  case 2:
463
+ if (!((_getCommand = (0, _getCommand2.getCommand)(parsed.command)) !== null && _getCommand !== void 0 && _getCommand.action)) {
464
+ _context3.next = 3;
465
+ break;
466
+ }
467
+ response = (0, _createErrorEnvelope.createErrorEnvelope)({
468
+ command: parsed.command,
469
+ code: 'USAGE_ERROR',
470
+ message: "Action command \"".concat(parsed.command, "\" cannot run inside batch.")
471
+ });
472
+ _context3.next = 5;
473
+ break;
474
+ case 3:
446
475
  captured = createCapturedWriter();
447
- _context3.next = 3;
476
+ _context3.next = 4;
448
477
  return run([].concat((0, _toConsumableArray2.default)(request.argv), ['--json']), captured, {
449
478
  invocation: invocation
450
479
  });
451
- case 3:
480
+ case 4:
452
481
  try {
453
482
  response = JSON.parse(captured.stdout.join('\n'));
454
483
  } catch (_unused) {
@@ -458,13 +487,13 @@ var runBatchChild = /*#__PURE__*/function () {
458
487
  message: 'The child command did not produce a valid JSON envelope.'
459
488
  });
460
489
  }
461
- case 4:
490
+ case 5:
462
491
  return _context3.abrupt("return", {
463
492
  request: request.argv,
464
493
  status: classifyBatchResponse(response),
465
494
  response: response
466
495
  });
467
- case 5:
496
+ case 6:
468
497
  case "end":
469
498
  return _context3.stop();
470
499
  }
@@ -485,7 +514,7 @@ var formatBatchChildHuman = function formatBatchChildHuman(_ref1) {
485
514
  return "Error: ".concat(item.response.error.message);
486
515
  }
487
516
  var parsed = (0, _parseArgs2.parseArgs)(item.request);
488
- var definition = parsed.command ? (0, _getCommand.getCommand)(parsed.command) : undefined;
517
+ var definition = parsed.command ? (0, _getCommand2.getCommand)(parsed.command) : undefined;
489
518
  if (!definition) {
490
519
  return (0, _formatHumanResult.formatHumanResult)({
491
520
  data: item.response.data
@@ -726,7 +755,7 @@ var run = exports.run = /*#__PURE__*/function () {
726
755
  writer.out(buildHelpText(invocation));
727
756
  return _context5.abrupt("return", command === undefined && flags.help !== true ? _types.ExitCode.UsageError : _types.ExitCode.Ok);
728
757
  case 2:
729
- definition = (0, _getCommand.getCommand)(command);
758
+ definition = (0, _getCommand2.getCommand)(command);
730
759
  if (definition) {
731
760
  _context5.next = 3;
732
761
  break;
@@ -575,6 +575,18 @@ var resolveBatch = function resolveBatch(input) {
575
575
  * The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
576
576
  */
577
577
  var commands = exports.commands = [{
578
+ name: 'init',
579
+ action: 'init',
580
+ description: 'Set up the ADS, UI Styling Standard, and Accessibility Foundation skills at the Git repository root and install the Atlas CLI ADS plugin.',
581
+ usage: 'init',
582
+ arguments: [],
583
+ flags: [],
584
+ examples: ['init'],
585
+ responseTypes: ['ads-cli/init'],
586
+ envelopeType: function envelopeType() {
587
+ return 'init';
588
+ }
589
+ }, {
578
590
  name: 'search',
579
591
  description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type). Returns up to 2 matches per term, per result type by default; override with --limit.',
580
592
  usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),