@atlaskit/ads-cli 0.4.2 → 0.6.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 (48) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +62 -10
  3. package/bin/ads-cli.js +5 -1
  4. package/dist/cjs/atlas-cli.js +4 -1
  5. package/dist/cjs/cli.js +368 -70
  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 +100 -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-human-result.js +33 -0
  12. package/dist/cjs/output/format-manifest.js +5 -3
  13. package/dist/cjs/output/format-results.js +25 -18
  14. package/dist/cjs/output/write-human-result.js +8 -10
  15. package/dist/es2019/atlas-cli.js +4 -1
  16. package/dist/es2019/cli.js +273 -29
  17. package/dist/es2019/commands/build-manifest.js +1 -2
  18. package/dist/es2019/commands/cli-metadata.js +1 -0
  19. package/dist/es2019/commands/definitions.js +77 -6
  20. package/dist/es2019/output/format-disambiguation.js +3 -2
  21. package/dist/es2019/output/format-grouped-results.js +5 -2
  22. package/dist/es2019/output/format-human-result.js +28 -0
  23. package/dist/es2019/output/format-manifest.js +6 -3
  24. package/dist/es2019/output/format-results.js +25 -18
  25. package/dist/es2019/output/write-human-result.js +8 -9
  26. package/dist/esm/atlas-cli.js +4 -1
  27. package/dist/esm/cli.js +369 -71
  28. package/dist/esm/commands/build-manifest.js +1 -2
  29. package/dist/esm/commands/cli-metadata.js +1 -0
  30. package/dist/esm/commands/definitions.js +100 -16
  31. package/dist/esm/output/format-disambiguation.js +3 -1
  32. package/dist/esm/output/format-grouped-results.js +6 -2
  33. package/dist/esm/output/format-human-result.js +27 -0
  34. package/dist/esm/output/format-manifest.js +5 -3
  35. package/dist/esm/output/format-results.js +26 -18
  36. package/dist/esm/output/write-human-result.js +8 -9
  37. package/dist/types/cli.d.ts +10 -1
  38. package/dist/types/commands/build-manifest.d.ts +1 -2
  39. package/dist/types/commands/cli-metadata.d.ts +1 -0
  40. package/dist/types/commands/types.d.ts +28 -1
  41. package/dist/types/output/format-disambiguation.d.ts +1 -1
  42. package/dist/types/output/format-grouped-results.d.ts +2 -1
  43. package/dist/types/output/format-human-result.d.ts +17 -0
  44. package/dist/types/output/format-manifest.d.ts +2 -1
  45. package/dist/types/output/format-results.d.ts +4 -3
  46. package/dist/types/output/write-human-result.d.ts +2 -2
  47. package/dist/types/parse-args.d.ts +1 -1
  48. package/package.json +1 -1
@@ -2,6 +2,8 @@ import _toArray from "@babel/runtime/helpers/toArray";
2
2
  import _typeof from "@babel/runtime/helpers/typeof";
3
3
  import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
4
4
  import _defineProperty from "@babel/runtime/helpers/defineProperty";
5
+ 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; } } }; }
6
+ 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
7
  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; }
6
8
  function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
7
9
  function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
@@ -336,19 +338,20 @@ var makeItemCommand = function makeItemCommand(_ref3) {
336
338
  envelopeType: function envelopeType(input) {
337
339
  return input.flags.all ? listTool.envelopeType : name;
338
340
  },
339
- formatHuman: function formatHuman(data) {
341
+ formatHuman: function formatHuman(data, _ref4) {
342
+ var invocation = _ref4.invocation;
340
343
  // Ambiguous lookup → render the "did you mean?" list; otherwise the item detail view.
341
344
  if (isDisambiguation(data)) {
342
- return formatDisambiguation(data);
345
+ return formatDisambiguation(data, invocation);
343
346
  }
344
347
  return _formatHuman(data);
345
348
  },
346
349
  // Turn the ranked candidate window into an exact match, a lone match, or a disambiguation
347
350
  // marker. Skipped for `--all` (that path returns the full array untouched).
348
- transform: function transform(_ref4) {
351
+ transform: function transform(_ref5) {
349
352
  var _input$positionals$;
350
- var data = _ref4.data,
351
- input = _ref4.input;
353
+ var data = _ref5.data,
354
+ input = _ref5.input;
352
355
  if (input.flags.all) {
353
356
  return data;
354
357
  }
@@ -462,6 +465,72 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
462
465
  };
463
466
  };
464
467
 
468
+ /**
469
+ * Split a batch invocation into argv groups introduced by repeated `--command` flags. The groups
470
+ * remain tokenized, so child commands can be routed through the existing parser without evaluating
471
+ * shell strings.
472
+ */
473
+ var resolveBatch = function resolveBatch(input) {
474
+ var _input$rawArgs;
475
+ var rawArgs = (_input$rawArgs = input.rawArgs) !== null && _input$rawArgs !== void 0 ? _input$rawArgs : [];
476
+ var batchIndex = rawArgs.indexOf('batch');
477
+ var tokens = rawArgs.slice(batchIndex + 1).filter(function (token) {
478
+ return token !== '--json';
479
+ });
480
+ if (tokens.length === 0) {
481
+ return {
482
+ error: 'At least one command request is required.'
483
+ };
484
+ }
485
+ if (tokens[0] !== '--command') {
486
+ return {
487
+ error: 'Each batch request must start with `--command`.'
488
+ };
489
+ }
490
+ var requests = [];
491
+ // The leading `--command` is validated above, so every remaining token either closes the open
492
+ // request or appends to it. Seeding the accumulator here keeps it non-nullable, which is what
493
+ // lets the loop stay free of "no request open yet" checks.
494
+ var current = [];
495
+ var _iterator = _createForOfIteratorHelper(tokens.slice(1)),
496
+ _step;
497
+ try {
498
+ for (_iterator.s(); !(_step = _iterator.n()).done;) {
499
+ var token = _step.value;
500
+ if (token === '--command') {
501
+ if (current.length === 0) {
502
+ return {
503
+ error: '`--command` must be followed by a non-empty command request.'
504
+ };
505
+ }
506
+ requests.push({
507
+ argv: current
508
+ });
509
+ current = [];
510
+ continue;
511
+ }
512
+ current.push(token);
513
+ }
514
+ } catch (err) {
515
+ _iterator.e(err);
516
+ } finally {
517
+ _iterator.f();
518
+ }
519
+ if (current.length === 0) {
520
+ return {
521
+ error: '`--command` must be followed by a non-empty command request.'
522
+ };
523
+ }
524
+ requests.push({
525
+ argv: current
526
+ });
527
+ return {
528
+ tools: [],
529
+ batch: requests,
530
+ meta: {}
531
+ };
532
+ };
533
+
465
534
  /**
466
535
  * The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
467
536
  */
@@ -494,9 +563,9 @@ export var commands = [{
494
563
  var _resolveSearchType;
495
564
  return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
496
565
  },
497
- transform: function transform(_ref5) {
498
- var data = _ref5.data,
499
- input = _ref5.input;
566
+ transform: function transform(_ref6) {
567
+ var data = _ref6.data,
568
+ input = _ref6.input;
500
569
  return resolveSearchType(input.flags) === 'docs' ? createDocSearchResults({
501
570
  data: data,
502
571
  query: input.positionals.join(' ')
@@ -525,6 +594,22 @@ export var commands = [{
525
594
  tool: searchKindTools[searchType]
526
595
  });
527
596
  }
597
+ }, {
598
+ name: 'batch',
599
+ description: 'Run multiple ADS CLI queries, including different command types, in one process.',
600
+ usage: 'batch [--json] --command <command> [args...] [--command <command> [args...]]...',
601
+ arguments: [],
602
+ flags: [{
603
+ name: 'command',
604
+ type: 'string[]',
605
+ description: 'A child command name followed by its arguments. Repeat once per child command.'
606
+ }],
607
+ examples: ['batch --command search button --type icon --command token space.200', 'batch --json --command component Button --command docs spacing'],
608
+ responseTypes: ['ads-cli/batch'],
609
+ envelopeType: function envelopeType() {
610
+ return 'batch';
611
+ },
612
+ resolve: resolveBatch
528
613
  }, makeItemCommand({
529
614
  kind: 'components',
530
615
  name: 'component',
@@ -556,16 +641,17 @@ export var commands = [{
556
641
  },
557
642
  // Ambiguous fuzzy lookup → render the "did you mean?" list; otherwise print each rule's
558
643
  // Markdown `content` verbatim rather than JSON.
559
- formatHuman: function formatHuman(data) {
560
- return isDisambiguation(data) ? formatDisambiguation(data) : formatLintRules(data);
644
+ formatHuman: function formatHuman(data, _ref7) {
645
+ var invocation = _ref7.invocation;
646
+ return isDisambiguation(data) ? formatDisambiguation(data, invocation) : formatLintRules(data);
561
647
  },
562
648
  // Mirror the item commands: a fuzzy term that matches one rule exactly (or a lone match)
563
649
  // shows that rule's docs, but several matches with no exact name surface a disambiguation
564
650
  // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
565
651
  // intentionally returns every rule's content).
566
- transform: function transform(_ref6) {
567
- var data = _ref6.data,
568
- input = _ref6.input;
652
+ transform: function transform(_ref8) {
653
+ var data = _ref8.data,
654
+ input = _ref8.input;
569
655
  var terms = input.positionals;
570
656
  if (terms.length === 0) {
571
657
  return data;
@@ -779,9 +865,7 @@ export var commands = [{
779
865
  resolve: function resolve() {
780
866
  return {
781
867
  data: buildManifest(commands, getVersion()),
782
- meta: {
783
- schemaVersion: 1
784
- }
868
+ meta: {}
785
869
  };
786
870
  }
787
871
  }];
@@ -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);
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Generic last-resort human formatting for a successful command result.
3
+ */
4
+
5
+ import chalk from 'chalk';
6
+
7
+ /**
8
+ * Render a successful result with the generic last-resort formatting, used when a command
9
+ * declares neither a compact result kind nor its own `formatHuman`.
10
+ *
11
+ * Structured data is pretty-printed as JSON (the underlying tools already return rich objects),
12
+ * while plain-string payloads such as guideline markdown are returned verbatim.
13
+ *
14
+ * Kept separate from the writer so callers that compose text rather than write it — notably
15
+ * `batch`, which concatenates one section per child — produce byte-identical output without
16
+ * duplicating these rules.
17
+ */
18
+ export var formatHumanResult = function formatHumanResult(_ref) {
19
+ var data = _ref.data;
20
+ if (typeof data === 'string') {
21
+ return data;
22
+ }
23
+ if (data === null || data === undefined) {
24
+ return chalk.yellow('No results.');
25
+ }
26
+ return JSON.stringify(data, null, 2);
27
+ };
@@ -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
  }
@@ -2,23 +2,22 @@
2
2
  * Human-readable rendering of a successful command result.
3
3
  */
4
4
 
5
- import chalk from 'chalk';
5
+ import { formatHumanResult } from './format-human-result';
6
6
  /**
7
7
  * Emit a human-readable rendering of a successful result to stdout.
8
8
  *
9
- * Structured data is pretty-printed as JSON (the underlying tools already return rich
10
- * objects), while plain-string payloads such as guideline markdown are printed verbatim.
9
+ * An absent payload is a diagnostic rather than data, so it goes to stderr to keep stdout clean
10
+ * for piping.
11
11
  */
12
12
  export var writeHumanResult = function writeHumanResult(_ref) {
13
13
  var data = _ref.data,
14
14
  writer = _ref.writer;
15
- if (typeof data === 'string') {
16
- writer.out(data);
17
- return;
18
- }
15
+ var text = formatHumanResult({
16
+ data: data
17
+ });
19
18
  if (data === null || data === undefined) {
20
- writer.err(chalk.yellow('No results.'));
19
+ writer.err(text);
21
20
  return;
22
21
  }
23
- writer.out(JSON.stringify(data, null, 2));
22
+ writer.out(text);
24
23
  };
@@ -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[];
@@ -17,6 +17,11 @@ export type CommandInput = {
17
17
  * Parsed `--flag` values (numbers, strings, booleans, or repeated string arrays).
18
18
  */
19
19
  flags: Record<string, unknown>;
20
+ /**
21
+ * Original argv for commands whose grammar needs token boundaries that generic flag parsing
22
+ * intentionally discards (currently the batch command's repeated `--command` boundaries).
23
+ */
24
+ rawArgs?: string[];
20
25
  };
21
26
  /**
22
27
  * A documented positional argument for a command, surfaced by `manifest`.
@@ -55,6 +60,12 @@ export type ToolCall = {
55
60
  handlerName: string;
56
61
  args?: unknown;
57
62
  };
63
+ /**
64
+ * One independently-addressed command invocation in a composite batch.
65
+ */
66
+ export type BatchRequest = {
67
+ argv: string[];
68
+ };
58
69
  /**
59
70
  * The successful result of resolving a command: one or more ADS MCP tool calls.
60
71
  *
@@ -67,6 +78,11 @@ export type ToolCall = {
67
78
  export type ResolvedCommand = {
68
79
  tools: ToolCall[];
69
80
  grouped?: boolean;
81
+ /**
82
+ * When present, each request is executed through the command registry inside the current
83
+ * process. Its existing envelope and rendering semantics are preserved independently.
84
+ */
85
+ batch?: BatchRequest[];
70
86
  meta?: Record<string, unknown>;
71
87
  };
72
88
  /**
@@ -94,6 +110,17 @@ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
94
110
  * {@link CommandDefinition.formatHuman} or the generic fallback.
95
111
  */
96
112
  export type RowKind = 'components' | 'tokens' | 'icons' | 'docs';
113
+ /**
114
+ * Distribution-specific context for human-readable output.
115
+ */
116
+ export type RenderContext = {
117
+ /**
118
+ * Exact command prefix the user can run, e.g. `ads-cli`, `npx @atlaskit/ads-cli`, or
119
+ * `atlas ads`. This is intentionally an open string so new wrappers can supply their own
120
+ * prefix without changing the shared CLI API.
121
+ */
122
+ invocation: string;
123
+ };
97
124
  /**
98
125
  * A single CLI command definition.
99
126
  */
@@ -147,7 +174,7 @@ export type CommandDefinition = {
147
174
  * doc, an a11y guide, or lint-rule markdown) instead of falling back to a raw JSON dump.
148
175
  * Returning `null` defers to the generic fallback. Never used for `--json` output.
149
176
  */
150
- formatHuman?: (data: unknown) => string | null;
177
+ formatHuman?: (data: unknown, context: RenderContext) => string | null;
151
178
  /**
152
179
  * Optional post-processor applied to a single-tool command's unwrapped result before
153
180
  * rendering (both human and `--json`). Used by the item commands (`component`/`token`/`icon`)
@@ -8,4 +8,4 @@ import type { DisambiguationResult } from './disambiguation';
8
8
  * Mirrors the compact search rows (name, optional hint, and a `→ <follow-up>` command) so the
9
9
  * output is consistent with `search`, and tells the user how to disambiguate.
10
10
  */
11
- export declare const formatDisambiguation: ({ query, noun, candidates }: DisambiguationResult) => string;
11
+ export declare const formatDisambiguation: ({ query, noun, candidates }: DisambiguationResult, invocation?: string) => string;
@@ -7,7 +7,8 @@
7
7
  /**
8
8
  * Render grouped results as sectioned compact output.
9
9
  */
10
- export declare const formatGroupedResults: ({ groups, totalCount, }: {
10
+ export declare const formatGroupedResults: ({ groups, totalCount, invocation, }: {
11
11
  groups: Record<string, unknown[]>;
12
12
  totalCount: number;
13
+ invocation?: string;
13
14
  }) => string;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Generic last-resort human formatting for a successful command result.
3
+ */
4
+ /**
5
+ * Render a successful result with the generic last-resort formatting, used when a command
6
+ * declares neither a compact result kind nor its own `formatHuman`.
7
+ *
8
+ * Structured data is pretty-printed as JSON (the underlying tools already return rich objects),
9
+ * while plain-string payloads such as guideline markdown are returned verbatim.
10
+ *
11
+ * Kept separate from the writer so callers that compose text rather than write it — notably
12
+ * `batch`, which concatenates one section per child — produce byte-identical output without
13
+ * duplicating these rules.
14
+ */
15
+ export declare const formatHumanResult: ({ data }: {
16
+ data: unknown;
17
+ }) => string;
@@ -1,4 +1,5 @@
1
1
  /**
2
2
  * Format a scannable human catalog of the ADS CLI capability manifest.
3
3
  */
4
- export declare const formatManifest: (data: unknown) => string | null;
4
+ import type { RenderContext } from '../commands/types';
5
+ export declare const formatManifest: (data: unknown, { invocation }: RenderContext) => string | null;
@@ -13,11 +13,12 @@ import type { RowKind } from '../commands/types';
13
13
  * Render an array of results as compact lines for the given kind. Returns `null` when the data
14
14
  * is not an array (so the caller can fall back to generic JSON rendering).
15
15
  *
16
- * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
17
- * row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
16
+ * `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
17
+ * each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
18
18
  */
19
- export declare const formatCompactResults: ({ kind, data, showFollowUp, }: {
19
+ export declare const formatCompactResults: ({ kind, data, showFollowUp, invocation, }: {
20
20
  kind: RowKind;
21
21
  data: unknown;
22
22
  showFollowUp?: boolean;
23
+ invocation?: string;
23
24
  }) => string | null;
@@ -5,8 +5,8 @@ import type { Writer } from './writer';
5
5
  /**
6
6
  * Emit a human-readable rendering of a successful result to stdout.
7
7
  *
8
- * Structured data is pretty-printed as JSON (the underlying tools already return rich
9
- * objects), while plain-string payloads such as guideline markdown are printed verbatim.
8
+ * An absent payload is a diagnostic rather than data, so it goes to stderr to keep stdout clean
9
+ * for piping.
10
10
  */
11
11
  export declare const writeHumanResult: ({ data, writer }: {
12
12
  data: unknown;
@@ -18,7 +18,7 @@ export type ParsedArgs = {
18
18
  */
19
19
  positionals: string[];
20
20
  /**
21
- * Parsed flags. Values may be string, number-like string, boolean, or string[].
21
+ * Parsed flags. Values may be a string (including number-like strings) or a boolean.
22
22
  */
23
23
  flags: Record<string, unknown>;
24
24
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.4.2",
3
+ "version": "0.6.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",