@atlaskit/ads-cli 0.6.0 → 0.8.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 (38) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +51 -14
  3. package/bin/ads-cli.js +6 -4
  4. package/dist/cjs/cli.js +23 -4
  5. package/dist/cjs/commands/definitions.js +46 -15
  6. package/dist/cjs/commands/normalize-batch-request.js +176 -0
  7. package/dist/cjs/output/compact-results.js +119 -0
  8. package/dist/cjs/output/format-doc-object.js +18 -5
  9. package/dist/cjs/output/format-icon.js +2 -1
  10. package/dist/cjs/output/format-results.js +37 -71
  11. package/dist/cjs/output/format-token.js +19 -5
  12. package/dist/cjs/output/write-json-envelope.js +2 -1
  13. package/dist/es2019/cli.js +23 -4
  14. package/dist/es2019/commands/definitions.js +48 -15
  15. package/dist/es2019/commands/normalize-batch-request.js +142 -0
  16. package/dist/es2019/output/compact-results.js +104 -0
  17. package/dist/es2019/output/format-doc-object.js +12 -4
  18. package/dist/es2019/output/format-icon.js +2 -1
  19. package/dist/es2019/output/format-results.js +37 -66
  20. package/dist/es2019/output/format-token.js +14 -5
  21. package/dist/es2019/output/write-json-envelope.js +2 -1
  22. package/dist/esm/cli.js +23 -4
  23. package/dist/esm/commands/definitions.js +46 -15
  24. package/dist/esm/commands/normalize-batch-request.js +169 -0
  25. package/dist/esm/output/compact-results.js +112 -0
  26. package/dist/esm/output/format-doc-object.js +18 -5
  27. package/dist/esm/output/format-icon.js +2 -1
  28. package/dist/esm/output/format-results.js +37 -71
  29. package/dist/esm/output/format-token.js +19 -5
  30. package/dist/esm/output/write-json-envelope.js +2 -1
  31. package/dist/types/commands/normalize-batch-request.d.ts +16 -0
  32. package/dist/types/commands/types.d.ts +8 -8
  33. package/dist/types/envelope/types.d.ts +3 -2
  34. package/dist/types/output/compact-results.d.ts +41 -0
  35. package/dist/types/output/format-results.d.ts +3 -3
  36. package/dist/types/output/format-token.d.ts +3 -3
  37. package/dist/types/output/write-json-envelope.d.ts +2 -1
  38. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,88 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.8.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`7b42e3dbea8db`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/7b42e3dbea8db) -
8
+ Several updates to the ADS CLI output.
9
+
10
+ **`--json` contract change:** `search --json` and `component|token|icon --all --json` now return
11
+ concise summaries for each result.
12
+ - Component JSON summaries replace `props` and `examples` with `propCount` and `exampleCount`, and
13
+ omit `designSource` and other detail-only metadata.
14
+ - Token `--all --json` summaries omit `usageGuidelines`.
15
+ - Icon `--all --json` summaries omit fields such as `keywords`, `categorization`, `team`,
16
+ `status`, and `shouldRecommendSmallIcon`.
17
+
18
+ For example, a component result from `ads-cli search avatar --json` changes from a detailed
19
+ record:
20
+
21
+ ```jsonc
22
+ {
23
+ "name": "Avatar",
24
+ "package": "@atlaskit/avatar",
25
+ "props": [
26
+ /* ... */
27
+ ],
28
+ "examples": [
29
+ /* ... */
30
+ ],
31
+ "designSource": {
32
+ /* ... */
33
+ },
34
+ }
35
+ ```
36
+
37
+ to a compact summary:
38
+
39
+ ```json
40
+ {
41
+ "name": "Avatar",
42
+ "package": "@atlaskit/avatar",
43
+ "propCount": 21,
44
+ "exampleCount": 1,
45
+ "followUp": "component Avatar"
46
+ }
47
+ ```
48
+
49
+ The fields omitted from the summary are available by running the individual command, for example
50
+ `ads-cli component Avatar --json`.
51
+
52
+ Other changes:
53
+ - Search JSON summaries include a `followUp` command for retrieving the individual record.
54
+ - Individual token JSON (`token <name> --json`) now includes usage guidelines and an actionable
55
+ `usage` value. Previously, usage guidelines were only available through `token --all --json`.
56
+ - Human-readable token details now surface usage guidelines; the actionable usage line was already
57
+ present.
58
+ - Icon details (`icon <name>`) now include an import statement for `--json` mode.
59
+ - Human-readable migration guides now preserve before/after steps.
60
+ - Large JSON responses are allowed to drain before exit.
61
+
62
+ ### Patch Changes
63
+
64
+ - Updated dependencies
65
+
66
+ ## 0.7.0
67
+
68
+ ### Minor Changes
69
+
70
+ - [`70516acb1b138`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/70516acb1b138) -
71
+ Support complete-string child requests in `ads-cli batch` while preserving the canonical tokenized
72
+ form.
73
+
74
+ ```sh
75
+ # Canonical tokenized form
76
+ npx @atlaskit/ads-cli batch --command component "Inline Dialog"
77
+
78
+ # Complete-string compatibility form
79
+ npx @atlaskit/ads-cli batch --command 'component "Inline Dialog"'
80
+ ```
81
+
82
+ ### Patch Changes
83
+
84
+ - Updated dependencies
85
+
3
86
  ## 0.6.0
4
87
 
5
88
  ### Minor Changes
package/README.md CHANGED
@@ -24,9 +24,9 @@ The CLI has these commands:
24
24
  | Command | Description |
25
25
  | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
26
  | `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
- | `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. |
27
+ | `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
28
  | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
29
- | `token <name>` | Detail for a single token. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token. |
29
+ | `token <name>` | Full detail for a single token, including usage guidelines. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token as a concise summary. |
30
30
  | `icon <name>` | Detail for a single icon (with a copy-paste import). Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every icon. |
31
31
  | `lint-rules [term...]` | ADS ESLint rules. A term that matches one rule (exactly or uniquely) prints its docs; several matches show a "did you mean?" list. Bare `lint-rules` prints every rule; `--limit N` caps the candidate list. |
32
32
  | `docs <topic...>` | Read ADS reference docs. Three forms:<br>• `docs <term...>` — foundations guidelines (spacing, color, …)<br>• `docs a11y [topic]` — accessibility guidance (optional topic e.g. `buttons`, `forms`, `colors`)<br>• `docs migration <id>` — a structured migration guide |
@@ -55,6 +55,11 @@ npx @atlaskit/ads-cli batch \
55
55
  --command docs spacing \
56
56
  --command search contrast --type docs
57
57
 
58
+ # Complete-string compatibility form (tokenized input above remains canonical)
59
+ npx @atlaskit/ads-cli batch \
60
+ --command 'component "Inline Dialog"' \
61
+ --command "search contrast" --type docs
62
+
58
63
  # Detail for a single component, token, or icon
59
64
  npx @atlaskit/ads-cli component Avatar
60
65
  npx @atlaskit/ads-cli token space.100
@@ -86,18 +91,28 @@ npx @atlaskit/ads-cli manifest --json
86
91
  prints the full matched Markdown. `component`/`token`/`icon` print a readable detail view (the
87
92
  icon view includes a copy-paste `import` line); `docs` (`foundations`, `a11y`, and `migration`)
88
93
  and `lint-rules` print prose/Markdown. A raw JSON dump is only ever a last-resort fallback for an
89
- unrecognised shape. For the **full structured payload**, use `--json`.
94
+ unrecognised shape.
95
+ - **Structured output mirrors the human retrieval budget.** Search and `--all` responses contain the
96
+ same compact fields shown by the human rows rather than embedding every component prop and
97
+ example. Each search record includes a machine-readable `followUp`; run that exact detail command
98
+ for the full component, token, or icon data. Exact detail commands retain the information shown by
99
+ their human view, including token `usageGuidelines` and `usage`, and an icon `import`.
100
+ `manifest --json` is the intentional exception: it remains the full CLI contract.
90
101
  - **Lookups never silently guess.** `component`/`token`/`icon <name>` — and a fuzzy
91
102
  `lint-rules <term>` — render the entry whose name matches exactly (case-insensitively). If there
92
103
  is no exact match but several candidates, they print a `Did you mean?` list (each with a
93
104
  `→ ads-cli <command>` follow-up) and exit `0` — under `--json` this is
94
105
  `{ "ambiguous": true, "query", "noun", "candidates": [...] }`.
95
- - **Batch commands are independent.** Each repeated `--command` starts a tokenized child request;
96
- `batch` runs those commands concurrently through the existing command registry in one CLI process.
97
- Each item includes its original tokenized `request`, a `status` (`success`, `ambiguous`, or
98
- `failure`), and the child command's unchanged success or error `response` envelope. A failed or
99
- ambiguous child does not discard successful sibling results. A syntactically valid batch exits
100
- `0`; inspect each item's status or nested envelope.
106
+ - **Batch commands are independent.** Each repeated `--command` starts a child request. Passing its
107
+ command and arguments as separate, tokenized argv is the canonical form. A complete quoted request
108
+ is also accepted, including inner quoting and already-tokenized trailing flags; it is normalized
109
+ to argv without invoking a shell. Shell operators, pipes, redirects, environment expansion, and
110
+ command substitution are rejected with a usage error. `batch` runs valid commands concurrently
111
+ through the existing command registry in one CLI process. Each item includes its normalized
112
+ tokenized `request`, a `status` (`success`, `ambiguous`, or `failure`), and the child command's
113
+ unchanged success or error `response` envelope. A failed or ambiguous child does not discard
114
+ successful sibling results. A syntactically valid batch exits `0`; inspect each item's status or
115
+ nested envelope.
101
116
  - **Data is written to stdout only.** Logs, hints, and errors go to **stderr**. This keeps `--json`
102
117
  output clean for piping. `batch` is the one deliberate exception: a child's failure is part of the
103
118
  aggregate result rather than a failure of the batch itself, so per-child errors stay inline on
@@ -105,7 +120,7 @@ npx @atlaskit/ads-cli manifest --json
105
120
  - **The manifest is derived from the live command registry.** `manifest --json` lists every command,
106
121
  positional argument, flag, example, and success response type without maintaining a separate copy
107
122
  of the CLI surface.
108
- - With `--json`, every success prints a `SuccessEnvelope` and every failure prints an
123
+ - With `--json`, every success prints a formatted `SuccessEnvelope` and every failure prints an
109
124
  `ErrorEnvelope`:
110
125
 
111
126
  ```jsonc
@@ -115,9 +130,23 @@ npx @atlaskit/ads-cli manifest --json
115
130
  "command": "search",
116
131
  "ok": true,
117
132
  "data": {
118
- "components": [ /* … */ ],
119
- "tokens": [ /* … */ ],
120
- "icons": [ /* … */ ],
133
+ "components": [
134
+ {
135
+ "name": "Button",
136
+ "package": "@atlaskit/button",
137
+ "propCount": 13,
138
+ "exampleCount": 3,
139
+ "followUp": "component Button"
140
+ }
141
+ ],
142
+ "tokens": [
143
+ {
144
+ "name": "motion.button.hovered",
145
+ "exampleValue": "background-color 150ms cubic-bezier(0.4, 1, 0.6, 1)",
146
+ "followUp": "token motion.button.hovered"
147
+ }
148
+ ],
149
+ "icons": [],
121
150
  "docs": [
122
151
  {
123
152
  "title": "Button",
@@ -134,7 +163,15 @@ npx @atlaskit/ads-cli manifest --json
134
163
  "type": "ads-cli/search-components",
135
164
  "command": "search",
136
165
  "ok": true,
137
- "data": [ /* tool output */ ],
166
+ "data": [
167
+ {
168
+ "name": "Avatar",
169
+ "package": "@atlaskit/avatar",
170
+ "propCount": 7,
171
+ "exampleCount": 1,
172
+ "followUp": "component Avatar"
173
+ }
174
+ ],
138
175
  "meta": { "terms": ["avatar"], "limit": 5, "count": 2 }
139
176
  }
140
177
 
package/bin/ads-cli.js CHANGED
@@ -31,14 +31,16 @@ const invocation = process.env.ADS_CLI_DISPLAY_INVOCATION || 'npx @atlaskit/ads-
31
31
  require(path.join('..', isDev ? 'src/cli' : 'dist/cjs/cli'))
32
32
  .run(process.argv.slice(2), undefined, { invocation })
33
33
  .then((exitCode) => {
34
- // A resolved numeric value is treated as an explicit exit code.
35
- process.exit(typeof exitCode === 'number' ? exitCode : 0);
34
+ // Set the eventual exit code without forcing the process to stop. A forced `process.exit()` can
35
+ // truncate output that is still draining to a pipe (for example, `icon --all --json`).
36
+ process.exitCode = typeof exitCode === 'number' ? exitCode : 0;
36
37
  })
37
38
  .catch((error) => {
38
39
  // A thrown number is treated as an explicit exit code (e.g. usage errors).
39
40
  if (typeof error === 'number') {
40
- process.exit(error);
41
+ process.exitCode = error;
42
+ return;
41
43
  }
42
44
  console.error(error);
43
- process.exit(1);
45
+ process.exitCode = 1;
44
46
  });
package/dist/cjs/cli.js CHANGED
@@ -18,6 +18,7 @@ var _importToolHandler = require("./commands/import-tool-handler");
18
18
  var _runTool = require("./commands/run-tool");
19
19
  var _createErrorEnvelope = require("./envelope/create-error-envelope");
20
20
  var _createSuccessEnvelope = require("./envelope/create-success-envelope");
21
+ var _compactResults3 = require("./output/compact-results");
21
22
  var _createDocSearchResults = require("./output/create-doc-search-results");
22
23
  var _disambiguation = require("./output/disambiguation");
23
24
  var _formatGroupedResults = require("./output/format-grouped-results");
@@ -72,7 +73,10 @@ var buildHelpText = function buildHelpText(invocation) {
72
73
  comment: 'unified: components, tokens, icons & docs'
73
74
  }, {
74
75
  command: 'batch --command search button --type icon --command token space.200',
75
- comment: 'independent commands in one process'
76
+ comment: 'canonical tokenized batch form'
77
+ }, {
78
+ command: 'batch --command "search button" --type icon --command "token space.200"',
79
+ comment: 'complete-string compatibility form'
76
80
  }, {
77
81
  command: 'search button --type component'
78
82
  }, {
@@ -341,11 +345,18 @@ var renderSingleResult = function renderSingleResult(_ref8) {
341
345
  input: input
342
346
  }) : result.data;
343
347
  if (json) {
348
+ var _command$resultKind2, _compactResults;
349
+ var resultKind = (_command$resultKind2 = command.resultKind) === null || _command$resultKind2 === void 0 ? void 0 : _command$resultKind2.call(command, input);
350
+ var outputData = resultKind ? (_compactResults = (0, _compactResults3.compactResults)({
351
+ kind: resultKind,
352
+ data: data,
353
+ showFollowUp: command.name === 'search'
354
+ })) !== null && _compactResults !== void 0 ? _compactResults : data : data;
344
355
  (0, _writeJsonEnvelope.writeJsonEnvelope)({
345
356
  envelope: (0, _createSuccessEnvelope.createSuccessEnvelope)({
346
357
  envelopeType: command.envelopeType(input),
347
358
  command: command.name,
348
- data: data,
359
+ data: outputData,
349
360
  meta: meta
350
361
  }),
351
362
  writer: writer
@@ -637,6 +648,14 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
637
648
  }
638
649
  return _types.ExitCode.NotFound;
639
650
  }
651
+ var compactGrouped = Object.fromEntries(['components', 'tokens', 'icons', 'docs'].map(function (kind) {
652
+ var _compactResults2, _grouped$kind;
653
+ return [kind, (_compactResults2 = (0, _compactResults3.compactResults)({
654
+ kind: kind,
655
+ data: (_grouped$kind = grouped[kind]) !== null && _grouped$kind !== void 0 ? _grouped$kind : [],
656
+ showFollowUp: true
657
+ })) !== null && _compactResults2 !== void 0 ? _compactResults2 : []];
658
+ }));
640
659
  if (json) {
641
660
  (0, _writeJsonEnvelope.writeJsonEnvelope)({
642
661
  envelope: (0, _createSuccessEnvelope.createSuccessEnvelope)({
@@ -644,7 +663,7 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
644
663
  command: command.name,
645
664
  // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
646
665
  // counted per group), so `count` is the combined total across groups.
647
- data: grouped,
666
+ data: compactGrouped,
648
667
  meta: _objectSpread(_objectSpread({}, meta), {}, {
649
668
  count: totalCount
650
669
  })
@@ -654,7 +673,7 @@ var renderGroupedResult = function renderGroupedResult(_ref12) {
654
673
  return _types.ExitCode.Ok;
655
674
  }
656
675
  writer.out((0, _formatGroupedResults.formatGroupedResults)({
657
- groups: grouped,
676
+ groups: compactGrouped,
658
677
  totalCount: totalCount,
659
678
  invocation: invocation
660
679
  }));
@@ -23,6 +23,7 @@ var _formatToken = require("../output/format-token");
23
23
  var _parseLintRuleRecords = require("../output/parse-lint-rule-records");
24
24
  var _buildManifest = require("./build-manifest");
25
25
  var _getVersion = require("./get-version");
26
+ var _normalizeBatchRequest = require("./normalize-batch-request");
26
27
  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; } } }; }
27
28
  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; } }
28
29
  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; }
@@ -298,6 +299,28 @@ var EXAMPLE_NAME = {
298
299
  icons: 'AddIcon'
299
300
  };
300
301
 
302
+ /**
303
+ * Add the actionable fields that exact human detail views derive from the raw record. Including
304
+ * them in JSON keeps both representations content-equivalent without requiring consumers to know
305
+ * ADS import or token-call conventions.
306
+ */
307
+ var addActionableDetail = function addActionableDetail(kind, item) {
308
+ if (kind === 'tokens') {
309
+ var name = itemFields.tokens.nameOf(item);
310
+ return name ? _objectSpread(_objectSpread({}, item), {}, {
311
+ usage: "token('".concat(name, "')")
312
+ }) : item;
313
+ }
314
+ if (kind === 'icons') {
315
+ var componentName = itemFields.icons.nameOf(item);
316
+ var packageName = typeof item.package === 'string' ? item.package : undefined;
317
+ return componentName && packageName ? _objectSpread(_objectSpread({}, item), {}, {
318
+ import: "import ".concat(componentName, " from '").concat(packageName, "';")
319
+ }) : item;
320
+ }
321
+ return item;
322
+ };
323
+
301
324
  /**
302
325
  * Build one of the singular item commands (`component <name>`, `token <name>`, `icon <name>`).
303
326
  *
@@ -368,11 +391,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
368
391
  return nameOf(item).toLowerCase() === query.toLowerCase();
369
392
  });
370
393
  if (exact) {
371
- return exact;
394
+ return addActionableDetail(kind, exact);
372
395
  }
373
396
  // A single candidate is unambiguous — show it.
374
397
  if (candidates.length === 1) {
375
- return candidates[0];
398
+ return addActionableDetail(kind, candidates[0]);
376
399
  }
377
400
  // Otherwise do not guess: surface a disambiguation list.
378
401
  return {
@@ -412,7 +435,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
412
435
  return singleTool({
413
436
  importPath: searchTool.importPath,
414
437
  handlerName: searchTool.handlerName,
415
- args: {
438
+ args: kind === 'tokens' ? {
439
+ terms: [name_],
440
+ limit: ITEM_LOOKUP_LIMIT,
441
+ includeMetadata: true
442
+ } : {
416
443
  terms: [name_],
417
444
  limit: ITEM_LOOKUP_LIMIT
418
445
  },
@@ -471,9 +498,9 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
471
498
  };
472
499
 
473
500
  /**
474
- * Split a batch invocation into argv groups introduced by repeated `--command` flags. The groups
475
- * remain tokenized, so child commands can be routed through the existing parser without evaluating
476
- * shell strings.
501
+ * Split a batch invocation into argv groups introduced by repeated `--command` flags. Canonical
502
+ * tokenized groups remain unchanged; a complete request in the first token is safely normalized
503
+ * to argv without evaluating shell strings.
477
504
  */
478
505
  var resolveBatch = function resolveBatch(input) {
479
506
  var _input$rawArgs;
@@ -508,9 +535,11 @@ var resolveBatch = function resolveBatch(input) {
508
535
  error: '`--command` must be followed by a non-empty command request.'
509
536
  };
510
537
  }
511
- requests.push({
512
- argv: current
513
- });
538
+ var _normalized = (0, _normalizeBatchRequest.normalizeBatchRequest)(current);
539
+ if ('error' in _normalized) {
540
+ return _normalized;
541
+ }
542
+ requests.push(_normalized);
514
543
  current = [];
515
544
  continue;
516
545
  }
@@ -526,9 +555,11 @@ var resolveBatch = function resolveBatch(input) {
526
555
  error: '`--command` must be followed by a non-empty command request.'
527
556
  };
528
557
  }
529
- requests.push({
530
- argv: current
531
- });
558
+ var normalized = (0, _normalizeBatchRequest.normalizeBatchRequest)(current);
559
+ if ('error' in normalized) {
560
+ return normalized;
561
+ }
562
+ requests.push(normalized);
532
563
  return {
533
564
  tools: [],
534
565
  batch: requests,
@@ -601,15 +632,15 @@ var commands = exports.commands = [{
601
632
  }
602
633
  }, {
603
634
  name: 'batch',
604
- description: 'Run multiple ADS CLI queries, including different command types, in one process.',
635
+ description: 'Run multiple ADS CLI queries in one process. Tokenized child requests are canonical; complete-request strings are also accepted.',
605
636
  usage: 'batch [--json] --command <command> [args...] [--command <command> [args...]]...',
606
637
  arguments: [],
607
638
  flags: [{
608
639
  name: 'command',
609
640
  type: 'string[]',
610
- description: 'A child command name followed by its arguments. Repeat once per child command.'
641
+ description: 'Canonical: a tokenized child command and its arguments. A complete quoted request is also accepted. Repeat once per child command.'
611
642
  }],
612
- examples: ['batch --command search button --type icon --command token space.200', 'batch --json --command component Button --command docs spacing'],
643
+ examples: ['batch --command search button --type icon --command token space.200', 'batch --command "search button" --type icon --command "token space.200"', 'batch --json --command component Button --command docs spacing'],
613
644
  responseTypes: ['ads-cli/batch'],
614
645
  envelopeType: function envelopeType() {
615
646
  return 'batch';
@@ -0,0 +1,176 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.normalizeBatchRequest = void 0;
8
+ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
+ var _toArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toArray"));
10
+ 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; } } }; }
11
+ 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; } }
12
+ 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; }
13
+ /**
14
+ * Normalise one batch child request without involving a shell.
15
+ *
16
+ * The canonical form is already-tokenized argv, for example
17
+ * `['search', 'Grid', '--type', 'component']`. For compatibility with agent-generated commands,
18
+ * the first token may instead contain a complete request, for example `['search Grid', '--type',
19
+ * 'component']`. Only that first token is split; trailing tokens have already been tokenized by the
20
+ * caller and must remain unchanged so multi-word arguments keep their boundaries.
21
+ */
22
+
23
+ var shellSyntaxError = function shellSyntaxError(syntax) {
24
+ return {
25
+ error: "Shell syntax ".concat(syntax, " is not supported in batch requests. Pass child commands as argv only; pipes, redirects, expansion, and command substitution are not allowed.")
26
+ };
27
+ };
28
+
29
+ /**
30
+ * Reject syntax that would have special meaning to a shell even though this parser never invokes
31
+ * one. Failing closed gives callers an actionable error instead of accepting input that only looks
32
+ * safe because it currently remains an argv array.
33
+ */
34
+ var findShellSyntax = function findShellSyntax(value) {
35
+ var _value$match;
36
+ if (value.includes('$(')) {
37
+ return 'command substitution (`$(...)`)';
38
+ }
39
+ if (value.includes('`')) {
40
+ return 'command substitution (backticks)';
41
+ }
42
+ if (value.includes('$')) {
43
+ return 'environment expansion (`$`)';
44
+ }
45
+ if (/\r|\n/.test(value)) {
46
+ return 'a command separator (line break)';
47
+ }
48
+ if (value.includes('&&')) {
49
+ return 'the `&&` operator';
50
+ }
51
+ if (value.includes('||')) {
52
+ return 'the `||` operator';
53
+ }
54
+ var operator = (_value$match = value.match(/[|&;<>()]/)) === null || _value$match === void 0 ? void 0 : _value$match[0];
55
+ return operator ? "the `".concat(operator, "` operator") : null;
56
+ };
57
+
58
+ /**
59
+ * Split a complete child request into argv using quoting and escaping rules only. This is
60
+ * intentionally not a shell grammar: it performs no expansion, substitution, redirection, or
61
+ * operator evaluation.
62
+ */
63
+ var tokenizeCompleteRequest = function tokenizeCompleteRequest(value) {
64
+ var argv = [];
65
+ var current = '';
66
+ var quote = null;
67
+ var escaped = false;
68
+ var tokenStarted = false;
69
+ var _iterator = _createForOfIteratorHelper(value),
70
+ _step;
71
+ try {
72
+ for (_iterator.s(); !(_step = _iterator.n()).done;) {
73
+ var character = _step.value;
74
+ if (escaped) {
75
+ current += character;
76
+ escaped = false;
77
+ tokenStarted = true;
78
+ continue;
79
+ }
80
+ if (character === '\\') {
81
+ escaped = true;
82
+ tokenStarted = true;
83
+ continue;
84
+ }
85
+ if (quote !== null) {
86
+ if (character === quote) {
87
+ quote = null;
88
+ } else {
89
+ current += character;
90
+ }
91
+ continue;
92
+ }
93
+ if (character === "'" || character === '"') {
94
+ quote = character;
95
+ tokenStarted = true;
96
+ continue;
97
+ }
98
+ if (/\s/.test(character)) {
99
+ if (tokenStarted) {
100
+ argv.push(current);
101
+ current = '';
102
+ tokenStarted = false;
103
+ }
104
+ continue;
105
+ }
106
+ current += character;
107
+ tokenStarted = true;
108
+ }
109
+ } catch (err) {
110
+ _iterator.e(err);
111
+ } finally {
112
+ _iterator.f();
113
+ }
114
+ if (escaped) {
115
+ return {
116
+ error: 'Invalid complete batch request: it ends with an escape character.'
117
+ };
118
+ }
119
+ if (quote !== null) {
120
+ return {
121
+ error: "Invalid complete batch request: unterminated ".concat(quote, " quote.")
122
+ };
123
+ }
124
+ if (tokenStarted) {
125
+ argv.push(current);
126
+ }
127
+ if (argv.length === 0) {
128
+ return {
129
+ error: 'Invalid complete batch request: a command name is required.'
130
+ };
131
+ }
132
+ return {
133
+ argv: argv
134
+ };
135
+ };
136
+ var normalizeBatchRequest = exports.normalizeBatchRequest = function normalizeBatchRequest(argv) {
137
+ var _iterator2 = _createForOfIteratorHelper(argv),
138
+ _step2;
139
+ try {
140
+ for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
141
+ var token = _step2.value;
142
+ var syntax = findShellSyntax(token);
143
+ if (syntax !== null) {
144
+ return shellSyntaxError(syntax);
145
+ }
146
+ }
147
+ } catch (err) {
148
+ _iterator2.e(err);
149
+ } finally {
150
+ _iterator2.f();
151
+ }
152
+ var _argv = (0, _toArray2.default)(argv),
153
+ first = _argv[0],
154
+ trailing = _arrayLikeToArray(_argv).slice(1);
155
+ if (first === undefined) {
156
+ return {
157
+ error: '`--command` must be followed by a non-empty command request.'
158
+ };
159
+ }
160
+
161
+ // A normal command name cannot contain whitespace, quotes, or escapes. Their presence in the
162
+ // first argv entry therefore identifies the complete-string compatibility form. Tokenized
163
+ // trailing entries are never re-split.
164
+ if (!/[\s'"\\]/.test(first)) {
165
+ return {
166
+ argv: (0, _toConsumableArray2.default)(argv)
167
+ };
168
+ }
169
+ var normalized = tokenizeCompleteRequest(first);
170
+ if ('error' in normalized) {
171
+ return normalized;
172
+ }
173
+ return {
174
+ argv: [].concat((0, _toConsumableArray2.default)(normalized.argv), (0, _toConsumableArray2.default)(trailing))
175
+ };
176
+ };