@atlaskit/ads-cli 0.4.1 → 0.5.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.
Files changed (40) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +3 -5
  3. package/bin/ads-cli.js +6 -2
  4. package/dist/cjs/atlas-cli.js +4 -1
  5. package/dist/cjs/cli.js +91 -35
  6. package/dist/cjs/commands/build-manifest.js +1 -2
  7. package/dist/cjs/commands/cli-metadata.js +2 -1
  8. package/dist/cjs/commands/definitions.js +16 -16
  9. package/dist/cjs/output/format-disambiguation.js +3 -1
  10. package/dist/cjs/output/format-grouped-results.js +6 -2
  11. package/dist/cjs/output/format-manifest.js +5 -3
  12. package/dist/cjs/output/format-results.js +25 -18
  13. package/dist/es2019/atlas-cli.js +4 -1
  14. package/dist/es2019/cli.js +69 -17
  15. package/dist/es2019/commands/build-manifest.js +1 -2
  16. package/dist/es2019/commands/cli-metadata.js +1 -0
  17. package/dist/es2019/commands/definitions.js +8 -6
  18. package/dist/es2019/output/format-disambiguation.js +3 -2
  19. package/dist/es2019/output/format-grouped-results.js +5 -2
  20. package/dist/es2019/output/format-manifest.js +6 -3
  21. package/dist/es2019/output/format-results.js +25 -18
  22. package/dist/esm/atlas-cli.js +4 -1
  23. package/dist/esm/cli.js +92 -36
  24. package/dist/esm/commands/build-manifest.js +1 -2
  25. package/dist/esm/commands/cli-metadata.js +1 -0
  26. package/dist/esm/commands/definitions.js +16 -16
  27. package/dist/esm/output/format-disambiguation.js +3 -1
  28. package/dist/esm/output/format-grouped-results.js +6 -2
  29. package/dist/esm/output/format-manifest.js +5 -3
  30. package/dist/esm/output/format-results.js +26 -18
  31. package/dist/types/cli.d.ts +10 -1
  32. package/dist/types/commands/build-manifest.d.ts +1 -2
  33. package/dist/types/commands/cli-metadata.d.ts +1 -0
  34. package/dist/types/commands/types.d.ts +12 -1
  35. package/dist/types/output/format-disambiguation.d.ts +1 -1
  36. package/dist/types/output/format-grouped-results.d.ts +2 -1
  37. package/dist/types/output/format-manifest.d.ts +2 -1
  38. package/dist/types/output/format-results.d.ts +4 -3
  39. package/index.js +1 -1
  40. package/package.json +1 -1
package/dist/esm/cli.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import _defineProperty from "@babel/runtime/helpers/defineProperty";
2
2
  import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
3
+ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
3
4
  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; } } }; }
4
5
  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; } }
5
6
  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; }
@@ -17,7 +18,7 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
17
18
  * `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
18
19
  */
19
20
 
20
- import { CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
21
+ import { CLI_BIN_NAME, CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
21
22
  import { commands } from './commands/definitions';
22
23
  import { getCommand } from './commands/get-command';
23
24
  import { getVersion } from './commands/get-version';
@@ -39,7 +40,7 @@ import { ExitCode } from './types';
39
40
  * Build the top-level help text from the command registry so it can never drift from the
40
41
  * runnable surface.
41
42
  */
42
- var buildHelpText = function buildHelpText() {
43
+ var buildHelpText = function buildHelpText(invocation) {
43
44
  // Width of the usage "gutter"; descriptions align to this column. Usages longer than the
44
45
  // gutter wrap onto their own line with the description indented beneath, so a long usage
45
46
  // (e.g. `docs`, which lists every topic) never produces a single 130-column line.
@@ -59,20 +60,61 @@ var buildHelpText = function buildHelpText() {
59
60
  var aliases = flag.alias ? ", -".concat(flag.alias) : '';
60
61
  return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
61
62
  }).join('\n');
62
- return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search contrast # unified: components, tokens, icons & docs', ' $ npx @atlaskit/ads-cli search button --type component', ' $ npx @atlaskit/ads-cli search contrast --type docs', ' $ npx @atlaskit/ads-cli component Button # detail for one component', ' $ npx @atlaskit/ads-cli token space.100 # detail for one token', ' $ npx @atlaskit/ads-cli icon --all # list every icon', ' $ npx @atlaskit/ads-cli docs spacing # foundations docs', ' $ npx @atlaskit/ads-cli docs a11y buttons # accessibility guidance', ' $ npx @atlaskit/ads-cli docs migration motion # migration guide', ' $ npx @atlaskit/ads-cli manifest --json # machine-readable CLI contract'].join('\n');
63
+ var examples = [{
64
+ command: 'search contrast',
65
+ comment: 'unified: components, tokens, icons & docs'
66
+ }, {
67
+ command: 'search button --type component'
68
+ }, {
69
+ command: 'search contrast --type docs'
70
+ }, {
71
+ command: 'component Button',
72
+ comment: 'detail for one component'
73
+ }, {
74
+ command: 'token space.100',
75
+ comment: 'detail for one token'
76
+ }, {
77
+ command: 'icon --all',
78
+ comment: 'list every icon'
79
+ }, {
80
+ command: 'docs spacing',
81
+ comment: 'foundations docs'
82
+ }, {
83
+ command: 'docs a11y buttons',
84
+ comment: 'accessibility guidance'
85
+ }, {
86
+ command: 'docs migration motion',
87
+ comment: 'migration guide'
88
+ }, {
89
+ command: 'manifest --json',
90
+ comment: 'machine-readable CLI contract'
91
+ }];
92
+ var exampleCommands = examples.map(function (_ref) {
93
+ var command = _ref.command;
94
+ return "$ ".concat(invocation, " ").concat(command);
95
+ });
96
+ var exampleWidth = Math.max.apply(Math, _toConsumableArray(exampleCommands.map(function (command) {
97
+ return command.length;
98
+ })));
99
+ var exampleLines = examples.map(function (_ref2, index) {
100
+ var comment = _ref2.comment;
101
+ var command = exampleCommands[index];
102
+ return " ".concat(comment ? "".concat(command.padEnd(exampleWidth), " # ").concat(comment) : command);
103
+ }).join('\n');
104
+ return [CLI_DESCRIPTION, '', 'Usage', " $ ".concat(invocation, " <command> [options]"), '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', exampleLines].join('\n');
63
105
  };
64
106
 
65
107
  /**
66
108
  * Execute a registry-backed command: resolve its tool + args, dispatch, and format output.
67
109
  */
68
110
  var runRegistryCommand = /*#__PURE__*/function () {
69
- var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee2(_ref) {
111
+ var _ref4 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee2(_ref3) {
70
112
  var _resolved$meta3;
71
- var command, input, json, writer, resolved, _resolved$meta, results, _resolved$meta2;
113
+ var command, input, json, writer, invocation, resolved, _resolved$meta, results, _resolved$meta2;
72
114
  return _regeneratorRuntime.wrap(function (_context2) {
73
115
  while (1) switch (_context2.prev = _context2.next) {
74
116
  case 0:
75
- command = _ref.command, input = _ref.input, json = _ref.json, writer = _ref.writer;
117
+ command = _ref3.command, input = _ref3.input, json = _ref3.json, writer = _ref3.writer, invocation = _ref3.invocation;
76
118
  resolved = command.resolve(input); // A resolver returning `{ error }` indicates invalid input (a usage error).
77
119
  if (!('error' in resolved)) {
78
120
  _context2.next = 1;
@@ -109,12 +151,13 @@ var runRegistryCommand = /*#__PURE__*/function () {
109
151
  },
110
152
  meta: (_resolved$meta = resolved.meta) !== null && _resolved$meta !== void 0 ? _resolved$meta : {},
111
153
  json: json,
112
- writer: writer
154
+ writer: writer,
155
+ invocation: invocation
113
156
  }));
114
157
  case 2:
115
158
  _context2.next = 3;
116
159
  return Promise.all(resolved.tools.map( /*#__PURE__*/function () {
117
- var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(tool) {
160
+ var _ref5 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(tool) {
118
161
  var handler, _t, _t2;
119
162
  return _regeneratorRuntime.wrap(function (_context) {
120
163
  while (1) switch (_context.prev = _context.next) {
@@ -144,7 +187,7 @@ var runRegistryCommand = /*#__PURE__*/function () {
144
187
  }, _callee);
145
188
  }));
146
189
  return function (_x2) {
147
- return _ref3.apply(this, arguments);
190
+ return _ref5.apply(this, arguments);
148
191
  };
149
192
  }()));
150
193
  case 3:
@@ -159,7 +202,8 @@ var runRegistryCommand = /*#__PURE__*/function () {
159
202
  results: results,
160
203
  meta: (_resolved$meta2 = resolved.meta) !== null && _resolved$meta2 !== void 0 ? _resolved$meta2 : {},
161
204
  json: json,
162
- writer: writer
205
+ writer: writer,
206
+ invocation: invocation
163
207
  }));
164
208
  case 4:
165
209
  return _context2.abrupt("return", renderSingleResult({
@@ -168,7 +212,8 @@ var runRegistryCommand = /*#__PURE__*/function () {
168
212
  result: results[0],
169
213
  meta: (_resolved$meta3 = resolved.meta) !== null && _resolved$meta3 !== void 0 ? _resolved$meta3 : {},
170
214
  json: json,
171
- writer: writer
215
+ writer: writer,
216
+ invocation: invocation
172
217
  }));
173
218
  case 5:
174
219
  case "end":
@@ -177,21 +222,22 @@ var runRegistryCommand = /*#__PURE__*/function () {
177
222
  }, _callee2);
178
223
  }));
179
224
  return function runRegistryCommand(_x) {
180
- return _ref2.apply(this, arguments);
225
+ return _ref4.apply(this, arguments);
181
226
  };
182
227
  }();
183
228
 
184
229
  /**
185
230
  * Render a single-tool command result (the common case).
186
231
  */
187
- var renderSingleResult = function renderSingleResult(_ref4) {
188
- var _command$resultKind, _ref5, _command$formatHuman;
189
- var command = _ref4.command,
190
- input = _ref4.input,
191
- result = _ref4.result,
192
- meta = _ref4.meta,
193
- json = _ref4.json,
194
- writer = _ref4.writer;
232
+ var renderSingleResult = function renderSingleResult(_ref6) {
233
+ var _command$resultKind, _ref7, _command$formatHuman;
234
+ var command = _ref6.command,
235
+ input = _ref6.input,
236
+ result = _ref6.result,
237
+ meta = _ref6.meta,
238
+ json = _ref6.json,
239
+ writer = _ref6.writer,
240
+ invocation = _ref6.invocation;
195
241
  var isError = result.isError;
196
242
 
197
243
  // The ADS search tools return an `Error: No … found` text block when nothing matches.
@@ -267,9 +313,12 @@ var renderSingleResult = function renderSingleResult(_ref4) {
267
313
  var compact = resultKind ? formatCompactResults({
268
314
  kind: resultKind,
269
315
  data: data,
270
- showFollowUp: command.name === 'search'
316
+ showFollowUp: command.name === 'search',
317
+ invocation: invocation
271
318
  }) : null;
272
- var human = (_ref5 = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref5 !== void 0 ? _ref5 : null;
319
+ var human = (_ref7 = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data, {
320
+ invocation: invocation
321
+ })) !== null && _ref7 !== void 0 ? _ref7 : null;
273
322
  if (human !== null) {
274
323
  writer.out(human);
275
324
  } else {
@@ -287,13 +336,14 @@ var renderSingleResult = function renderSingleResult(_ref4) {
287
336
  * Each sub-result is keyed by its {@link ToolCall.key}. A sub-search that finds nothing simply
288
337
  * contributes an empty array; the command is only treated as NOT_FOUND when every group is empty.
289
338
  */
290
- var renderGroupedResult = function renderGroupedResult(_ref6) {
291
- var command = _ref6.command,
292
- input = _ref6.input,
293
- results = _ref6.results,
294
- meta = _ref6.meta,
295
- json = _ref6.json,
296
- writer = _ref6.writer;
339
+ var renderGroupedResult = function renderGroupedResult(_ref8) {
340
+ var command = _ref8.command,
341
+ input = _ref8.input,
342
+ results = _ref8.results,
343
+ meta = _ref8.meta,
344
+ json = _ref8.json,
345
+ writer = _ref8.writer,
346
+ invocation = _ref8.invocation;
297
347
  // Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
298
348
  // empty domain does not blank out the others. The guidelines tool returns full Markdown, so
299
349
  // summarize its highest-ranked match for search; `docs <query>` remains the detail view.
@@ -360,22 +410,26 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
360
410
  }
361
411
  writer.out(formatGroupedResults({
362
412
  groups: grouped,
363
- totalCount: totalCount
413
+ totalCount: totalCount,
414
+ invocation: invocation
364
415
  }));
365
416
  return ExitCode.Ok;
366
417
  };
367
-
368
418
  /**
369
419
  * Parse and execute a single CLI invocation.
370
420
  *
371
421
  * @param argv - Arguments after `node <script>` (i.e. `process.argv.slice(2)`).
372
422
  * @param writer - Injectable output sink; defaults to console-backed stdout/stderr.
423
+ * @param options - Distribution-specific rendering options.
373
424
  * @returns The process exit code. The bin wrapper maps this onto `process.exit`.
374
425
  */
375
426
  export var run = /*#__PURE__*/function () {
376
- var _ref7 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee3() {
427
+ var _ref9 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee3() {
377
428
  var argv,
378
429
  writer,
430
+ _ref0,
431
+ _ref0$invocation,
432
+ invocation,
379
433
  _parseArgs,
380
434
  command,
381
435
  positionals,
@@ -391,6 +445,7 @@ export var run = /*#__PURE__*/function () {
391
445
  case 0:
392
446
  argv = _args3.length > 0 && _args3[0] !== undefined ? _args3[0] : process.argv.slice(2);
393
447
  writer = _args3.length > 1 && _args3[1] !== undefined ? _args3[1] : defaultWriter;
448
+ _ref0 = _args3.length > 2 && _args3[2] !== undefined ? _args3[2] : {}, _ref0$invocation = _ref0.invocation, invocation = _ref0$invocation === void 0 ? CLI_BIN_NAME : _ref0$invocation;
394
449
  _parseArgs = parseArgs(argv), command = _parseArgs.command, positionals = _parseArgs.positionals, flags = _parseArgs.flags;
395
450
  json = flags.json === true; // `--version` / `-v` takes precedence and short-circuits.
396
451
  if (!(flags.version === true)) {
@@ -404,7 +459,7 @@ export var run = /*#__PURE__*/function () {
404
459
  _context3.next = 2;
405
460
  break;
406
461
  }
407
- writer.out(buildHelpText());
462
+ writer.out(buildHelpText(invocation));
408
463
  return _context3.abrupt("return", command === undefined && flags.help !== true ? ExitCode.UsageError : ExitCode.Ok);
409
464
  case 2:
410
465
  definition = getCommand(command);
@@ -427,7 +482,7 @@ export var run = /*#__PURE__*/function () {
427
482
  message: message,
428
483
  writer: writer
429
484
  });
430
- writer.err('Run `ads-cli --help` to see available commands.');
485
+ writer.err("Run `".concat(invocation, " --help` to see available commands."));
431
486
  }
432
487
  return _context3.abrupt("return", ExitCode.UsageError);
433
488
  case 3:
@@ -440,7 +495,8 @@ export var run = /*#__PURE__*/function () {
440
495
  flags: flags
441
496
  },
442
497
  json: json,
443
- writer: writer
498
+ writer: writer,
499
+ invocation: invocation
444
500
  });
445
501
  case 4:
446
502
  return _context3.abrupt("return", _context3.sent);
@@ -471,6 +527,6 @@ export var run = /*#__PURE__*/function () {
471
527
  }, _callee3, null, [[3, 5]]);
472
528
  }));
473
529
  return function run() {
474
- return _ref7.apply(this, arguments);
530
+ return _ref9.apply(this, arguments);
475
531
  };
476
532
  }();
@@ -11,12 +11,11 @@ import { CLI_BIN_NAME, CLI_DESCRIPTION, CLI_NAME, globalFlags } from './cli-meta
11
11
  */
12
12
  export var buildManifest = function buildManifest(commands, version) {
13
13
  return {
14
- schemaVersion: 1,
14
+ schemaVersion: 2,
15
15
  name: CLI_NAME,
16
16
  bin: CLI_BIN_NAME,
17
17
  version: version,
18
18
  description: CLI_DESCRIPTION,
19
- invocation: "npx ".concat(CLI_NAME),
20
19
  commands: commands.map(function (_ref) {
21
20
  var name = _ref.name,
22
21
  description = _ref.description,
@@ -4,6 +4,7 @@
4
4
 
5
5
  export var CLI_NAME = '@atlaskit/ads-cli';
6
6
  export var CLI_BIN_NAME = 'ads-cli';
7
+ export var CLI_ATLAS_INVOCATION = 'atlas ads';
7
8
  export var CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
8
9
  export var globalFlags = [{
9
10
  name: 'json',
@@ -336,19 +336,20 @@ var makeItemCommand = function makeItemCommand(_ref3) {
336
336
  envelopeType: function envelopeType(input) {
337
337
  return input.flags.all ? listTool.envelopeType : name;
338
338
  },
339
- formatHuman: function formatHuman(data) {
339
+ formatHuman: function formatHuman(data, _ref4) {
340
+ var invocation = _ref4.invocation;
340
341
  // Ambiguous lookup → render the "did you mean?" list; otherwise the item detail view.
341
342
  if (isDisambiguation(data)) {
342
- return formatDisambiguation(data);
343
+ return formatDisambiguation(data, invocation);
343
344
  }
344
345
  return _formatHuman(data);
345
346
  },
346
347
  // Turn the ranked candidate window into an exact match, a lone match, or a disambiguation
347
348
  // marker. Skipped for `--all` (that path returns the full array untouched).
348
- transform: function transform(_ref4) {
349
+ transform: function transform(_ref5) {
349
350
  var _input$positionals$;
350
- var data = _ref4.data,
351
- input = _ref4.input;
351
+ var data = _ref5.data,
352
+ input = _ref5.input;
352
353
  if (input.flags.all) {
353
354
  return data;
354
355
  }
@@ -494,9 +495,9 @@ export var commands = [{
494
495
  var _resolveSearchType;
495
496
  return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
496
497
  },
497
- transform: function transform(_ref5) {
498
- var data = _ref5.data,
499
- input = _ref5.input;
498
+ transform: function transform(_ref6) {
499
+ var data = _ref6.data,
500
+ input = _ref6.input;
500
501
  return resolveSearchType(input.flags) === 'docs' ? createDocSearchResults({
501
502
  data: data,
502
503
  query: input.positionals.join(' ')
@@ -556,16 +557,17 @@ export var commands = [{
556
557
  },
557
558
  // Ambiguous fuzzy lookup → render the "did you mean?" list; otherwise print each rule's
558
559
  // Markdown `content` verbatim rather than JSON.
559
- formatHuman: function formatHuman(data) {
560
- return isDisambiguation(data) ? formatDisambiguation(data) : formatLintRules(data);
560
+ formatHuman: function formatHuman(data, _ref7) {
561
+ var invocation = _ref7.invocation;
562
+ return isDisambiguation(data) ? formatDisambiguation(data, invocation) : formatLintRules(data);
561
563
  },
562
564
  // Mirror the item commands: a fuzzy term that matches one rule exactly (or a lone match)
563
565
  // shows that rule's docs, but several matches with no exact name surface a disambiguation
564
566
  // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
565
567
  // intentionally returns every rule's content).
566
- transform: function transform(_ref6) {
567
- var data = _ref6.data,
568
- input = _ref6.input;
568
+ transform: function transform(_ref8) {
569
+ var data = _ref8.data,
570
+ input = _ref8.input;
569
571
  var terms = input.positionals;
570
572
  if (terms.length === 0) {
571
573
  return data;
@@ -779,9 +781,7 @@ export var commands = [{
779
781
  resolve: function resolve() {
780
782
  return {
781
783
  data: buildManifest(commands, getVersion()),
782
- meta: {
783
- schemaVersion: 1
784
- }
784
+ meta: {}
785
785
  };
786
786
  }
787
787
  }];
@@ -3,6 +3,7 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
3
3
  * Human-readable renderer for an ambiguous item lookup ("did you mean?").
4
4
  */
5
5
 
6
+ import { CLI_BIN_NAME } from '../commands/cli-metadata';
6
7
  /**
7
8
  * Render a "did you mean?" list for an ambiguous lookup.
8
9
  *
@@ -13,10 +14,11 @@ export var formatDisambiguation = function formatDisambiguation(_ref) {
13
14
  var query = _ref.query,
14
15
  noun = _ref.noun,
15
16
  candidates = _ref.candidates;
17
+ var invocation = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : CLI_BIN_NAME;
16
18
  var header = "Multiple ".concat(noun, "s match \"").concat(query, "\". Did you mean one of these?");
17
19
  var rows = candidates.map(function (candidate) {
18
20
  var hint = candidate.hint ? " ".concat(candidate.hint) : '';
19
- return " ".concat(candidate.name).concat(hint, "\n \u2192 ads-cli ").concat(candidate.followUp);
21
+ return " ".concat(candidate.name).concat(hint, "\n \u2192 ").concat(invocation, " ").concat(candidate.followUp);
20
22
  });
21
23
  return [header, ''].concat(_toConsumableArray(rows)).join('\n');
22
24
  };
@@ -5,6 +5,7 @@
5
5
  * groups are skipped, so one command surfaces whatever kinds match, grouped by kind.
6
6
  */
7
7
 
8
+ import { CLI_BIN_NAME } from '../commands/cli-metadata';
8
9
  import { formatCompactResults } from './format-results';
9
10
 
10
11
  /**
@@ -12,7 +13,9 @@ import { formatCompactResults } from './format-results';
12
13
  */
13
14
  export var formatGroupedResults = function formatGroupedResults(_ref) {
14
15
  var groups = _ref.groups,
15
- totalCount = _ref.totalCount;
16
+ totalCount = _ref.totalCount,
17
+ _ref$invocation = _ref.invocation,
18
+ invocation = _ref$invocation === void 0 ? CLI_BIN_NAME : _ref$invocation;
16
19
  // Fixed display order, with human-friendly section titles.
17
20
  var sections = [{
18
21
  kind: 'components',
@@ -43,7 +46,8 @@ export var formatGroupedResults = function formatGroupedResults(_ref) {
43
46
  var rendered = formatCompactResults({
44
47
  kind: kind,
45
48
  data: entries,
46
- showFollowUp: true
49
+ showFollowUp: true,
50
+ invocation: invocation
47
51
  });
48
52
  var body = rendered ? rendered.split('\n').slice(2).join('\n') : '';
49
53
  blocks.push('', "".concat(title, " (").concat(entries.length, "):"), '', body);
@@ -2,8 +2,10 @@ import _typeof from "@babel/runtime/helpers/typeof";
2
2
  /**
3
3
  * Format a scannable human catalog of the ADS CLI capability manifest.
4
4
  */
5
- export var formatManifest = function formatManifest(data) {
6
- if (_typeof(data) !== 'object' || data === null || !('bin' in data) || typeof data.bin !== 'string' || !('version' in data) || typeof data.version !== 'string' || !('invocation' in data) || typeof data.invocation !== 'string' || !('commands' in data) || !Array.isArray(data.commands)) {
5
+
6
+ export var formatManifest = function formatManifest(data, _ref) {
7
+ var invocation = _ref.invocation;
8
+ if (_typeof(data) !== 'object' || data === null || !('bin' in data) || typeof data.bin !== 'string' || !('version' in data) || typeof data.version !== 'string' || !('commands' in data) || !Array.isArray(data.commands)) {
7
9
  return null;
8
10
  }
9
11
  var commands = data.commands.flatMap(function (command) {
@@ -15,5 +17,5 @@ export var formatManifest = function formatManifest(data) {
15
17
  });
16
18
  var commandCount = commands.length;
17
19
  var commandLabel = commandCount === 1 ? 'command' : 'commands';
18
- return ["".concat(data.bin, " v").concat(data.version, " \u2014 ").concat(commandCount, " ").concat(commandLabel), '', commands.join('\n'), '', "Run `".concat(data.invocation, " manifest --json` for the full structured manifest.")].join('\n');
20
+ return ["".concat(data.bin, " v").concat(data.version, " \u2014 ").concat(commandCount, " ").concat(commandLabel), '', commands.join('\n'), '', "Run `".concat(invocation, " manifest --json` for the full structured manifest.")].join('\n');
19
21
  };
@@ -10,6 +10,8 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
10
10
  * left to the caller's generic fallback.
11
11
  */
12
12
 
13
+ import { CLI_BIN_NAME } from '../commands/cli-metadata';
14
+
13
15
  /**
14
16
  * A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
15
17
  * Only the fields the compact view needs are modelled; others are ignored.
@@ -46,7 +48,7 @@ var truncate = function truncate(text) {
46
48
  };
47
49
 
48
50
  /**
49
- * Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
51
+ * Append a `→ <invocation> <command> <name>` drill-in hint beneath a row.
50
52
  *
51
53
  * Used for every `search` result, where the natural next step is to view that match in full.
52
54
  * `--all` listings omit it because echoing every row's own name would just be noise.
@@ -55,8 +57,9 @@ var withFollowUp = function withFollowUp(_ref) {
55
57
  var line = _ref.line,
56
58
  command = _ref.command,
57
59
  name = _ref.name,
58
- showFollowUp = _ref.showFollowUp;
59
- return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(command, " ").concat(name) : line;
60
+ showFollowUp = _ref.showFollowUp,
61
+ invocation = _ref.invocation;
62
+ return showFollowUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(command, " ").concat(name) : line;
60
63
  };
61
64
 
62
65
  /**
@@ -66,7 +69,7 @@ var withFollowUp = function withFollowUp(_ref) {
66
69
  * (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
67
70
  * context and a tag would just be noise.
68
71
  */
69
- var formatComponentLine = function formatComponentLine(component, showFollowUp) {
72
+ var formatComponentLine = function formatComponentLine(component, showFollowUp, invocation) {
70
73
  var _component$name;
71
74
  var name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
72
75
  var pkg = component.package ? " ".concat(component.package) : '';
@@ -77,14 +80,15 @@ var formatComponentLine = function formatComponentLine(component, showFollowUp)
77
80
  line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
78
81
  command: 'component',
79
82
  name: name,
80
- showFollowUp: showFollowUp
83
+ showFollowUp: showFollowUp,
84
+ invocation: invocation
81
85
  });
82
86
  };
83
87
 
84
88
  /**
85
89
  * Render one token as a compact `name = value` line.
86
90
  */
87
- var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp) {
91
+ var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp, invocation) {
88
92
  var _tokenResult$name;
89
93
  var name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
90
94
  // Some token values (e.g. motion easing curves) are very long; truncate so each token stays
@@ -94,14 +98,15 @@ var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp) {
94
98
  line: line,
95
99
  command: 'token',
96
100
  name: name,
97
- showFollowUp: showFollowUp
101
+ showFollowUp: showFollowUp,
102
+ invocation: invocation
98
103
  });
99
104
  };
100
105
 
101
106
  /**
102
107
  * Render one icon as a compact line with its import package and short usage note.
103
108
  */
104
- var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
109
+ var formatIconLine = function formatIconLine(iconResult, showFollowUp, invocation) {
105
110
  var _iconResult$component;
106
111
  var name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
107
112
  var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
@@ -110,31 +115,34 @@ var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
110
115
  line: "".concat(name).concat(pkg).concat(usage),
111
116
  command: 'icon',
112
117
  name: name,
113
- showFollowUp: showFollowUp
118
+ showFollowUp: showFollowUp,
119
+ invocation: invocation
114
120
  });
115
121
  };
116
122
 
117
123
  /**
118
124
  * Render one foundations-document match without dumping its full Markdown body.
119
125
  */
120
- var formatDocLine = function formatDocLine(doc, showFollowUp) {
126
+ var formatDocLine = function formatDocLine(doc, showFollowUp, invocation) {
121
127
  var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
122
128
  var line = "".concat(doc.title).concat(summary);
123
- return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(doc.followUp) : line;
129
+ return showFollowUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(doc.followUp) : line;
124
130
  };
125
131
 
126
132
  /**
127
133
  * Render an array of results as compact lines for the given kind. Returns `null` when the data
128
134
  * is not an array (so the caller can fall back to generic JSON rendering).
129
135
  *
130
- * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
131
- * row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
136
+ * `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
137
+ * each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
132
138
  */
133
139
  export var formatCompactResults = function formatCompactResults(_ref2) {
134
140
  var kind = _ref2.kind,
135
141
  data = _ref2.data,
136
142
  _ref2$showFollowUp = _ref2.showFollowUp,
137
- showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp;
143
+ showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp,
144
+ _ref2$invocation = _ref2.invocation,
145
+ invocation = _ref2$invocation === void 0 ? CLI_BIN_NAME : _ref2$invocation;
138
146
  if (!Array.isArray(data)) {
139
147
  return null;
140
148
  }
@@ -144,13 +152,13 @@ export var formatCompactResults = function formatCompactResults(_ref2) {
144
152
  var lines = data.map(function (entry) {
145
153
  switch (kind) {
146
154
  case 'components':
147
- return formatComponentLine(entry, showFollowUp);
155
+ return formatComponentLine(entry, showFollowUp, invocation);
148
156
  case 'tokens':
149
- return formatTokenLine(entry, showFollowUp);
157
+ return formatTokenLine(entry, showFollowUp, invocation);
150
158
  case 'icons':
151
- return formatIconLine(entry, showFollowUp);
159
+ return formatIconLine(entry, showFollowUp, invocation);
152
160
  case 'docs':
153
- return formatDocLine(entry, showFollowUp);
161
+ return formatDocLine(entry, showFollowUp, invocation);
154
162
  default:
155
163
  return JSON.stringify(entry);
156
164
  }
@@ -8,13 +8,22 @@
8
8
  * It never reimplements search ranking or bundles a dataset copy — all query logic lives in
9
9
  * `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
10
10
  */
11
+ import type { RenderContext } from './commands/types';
11
12
  import { type Writer } from './output/writer';
12
13
  import { type ExitCodeValue } from './types';
14
+ type RunOptions = {
15
+ /**
16
+ * Exact command prefix to show in human-readable help and follow-up hints.
17
+ */
18
+ invocation?: RenderContext['invocation'];
19
+ };
13
20
  /**
14
21
  * Parse and execute a single CLI invocation.
15
22
  *
16
23
  * @param argv - Arguments after `node <script>` (i.e. `process.argv.slice(2)`).
17
24
  * @param writer - Injectable output sink; defaults to console-backed stdout/stderr.
25
+ * @param options - Distribution-specific rendering options.
18
26
  * @returns The process exit code. The bin wrapper maps this onto `process.exit`.
19
27
  */
20
- export declare const run: (argv?: string[], writer?: Writer) => Promise<ExitCodeValue>;
28
+ export declare const run: (argv?: string[], writer?: Writer, { invocation }?: RunOptions) => Promise<ExitCodeValue>;
29
+ export {};
@@ -10,12 +10,11 @@ export type ManifestCommand = Pick<CommandDefinition, 'name' | 'description' | '
10
10
  jsonSupported: true;
11
11
  };
12
12
  export type Manifest = {
13
- schemaVersion: 1;
13
+ schemaVersion: 2;
14
14
  name: typeof CLI_NAME;
15
15
  bin: typeof CLI_BIN_NAME;
16
16
  version: string;
17
17
  description: string;
18
- invocation: string;
19
18
  commands: ManifestCommand[];
20
19
  globalFlags: CommandFlag[];
21
20
  errorResponseType: 'ads-cli/error';
@@ -4,5 +4,6 @@
4
4
  import type { CommandFlag } from './types';
5
5
  export declare const CLI_NAME = "@atlaskit/ads-cli";
6
6
  export declare const CLI_BIN_NAME = "ads-cli";
7
+ export declare const CLI_ATLAS_INVOCATION = "atlas ads";
7
8
  export declare const CLI_DESCRIPTION = "Query Atlassian Design System (ADS) structured content \u2014 components, tokens, icons, and guidelines \u2014 from the terminal.";
8
9
  export declare const globalFlags: CommandFlag[];
@@ -94,6 +94,17 @@ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
94
94
  * {@link CommandDefinition.formatHuman} or the generic fallback.
95
95
  */
96
96
  export type RowKind = 'components' | 'tokens' | 'icons' | 'docs';
97
+ /**
98
+ * Distribution-specific context for human-readable output.
99
+ */
100
+ export type RenderContext = {
101
+ /**
102
+ * Exact command prefix the user can run, e.g. `ads-cli`, `npx @atlaskit/ads-cli`, or
103
+ * `atlas ads`. This is intentionally an open string so new wrappers can supply their own
104
+ * prefix without changing the shared CLI API.
105
+ */
106
+ invocation: string;
107
+ };
97
108
  /**
98
109
  * A single CLI command definition.
99
110
  */
@@ -147,7 +158,7 @@ export type CommandDefinition = {
147
158
  * doc, an a11y guide, or lint-rule markdown) instead of falling back to a raw JSON dump.
148
159
  * Returning `null` defers to the generic fallback. Never used for `--json` output.
149
160
  */
150
- formatHuman?: (data: unknown) => string | null;
161
+ formatHuman?: (data: unknown, context: RenderContext) => string | null;
151
162
  /**
152
163
  * Optional post-processor applied to a single-tool command's unwrapped result before
153
164
  * rendering (both human and `--json`). Used by the item commands (`component`/`token`/`icon`)