@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
@@ -9,7 +9,7 @@
9
9
  * `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
10
10
  */
11
11
 
12
- import { CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
12
+ import { CLI_BIN_NAME, CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
13
13
  import { commands } from './commands/definitions';
14
14
  import { getCommand } from './commands/get-command';
15
15
  import { getVersion } from './commands/get-version';
@@ -18,7 +18,9 @@ import { runTool } from './commands/run-tool';
18
18
  import { createErrorEnvelope } from './envelope/create-error-envelope';
19
19
  import { createSuccessEnvelope } from './envelope/create-success-envelope';
20
20
  import { createDocSearchResults } from './output/create-doc-search-results';
21
+ import { isDisambiguation } from './output/disambiguation';
21
22
  import { formatGroupedResults } from './output/format-grouped-results';
23
+ import { formatHumanResult } from './output/format-human-result';
22
24
  import { formatCompactResults } from './output/format-results';
23
25
  import { writeHumanError } from './output/write-human-error';
24
26
  import { writeHumanResult } from './output/write-human-result';
@@ -31,7 +33,7 @@ import { ExitCode } from './types';
31
33
  * Build the top-level help text from the command registry so it can never drift from the
32
34
  * runnable surface.
33
35
  */
34
- const buildHelpText = () => {
36
+ const buildHelpText = invocation => {
35
37
  // Width of the usage "gutter"; descriptions align to this column. Usages longer than the
36
38
  // gutter wrap onto their own line with the description indented beneath, so a long usage
37
39
  // (e.g. `docs`, which lists every topic) never produces a single 130-column line.
@@ -49,7 +51,49 @@ const buildHelpText = () => {
49
51
  const aliases = flag.alias ? `, -${flag.alias}` : '';
50
52
  return ` --${flag.name}${aliases}`.padEnd(18) + flag.description;
51
53
  }).join('\n');
52
- 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');
54
+ const examples = [{
55
+ command: 'search contrast',
56
+ comment: 'unified: components, tokens, icons & docs'
57
+ }, {
58
+ command: 'batch --command search button --type icon --command token space.200',
59
+ comment: 'independent commands in one process'
60
+ }, {
61
+ command: 'search button --type component'
62
+ }, {
63
+ command: 'search contrast --type docs'
64
+ }, {
65
+ command: 'component Button',
66
+ comment: 'detail for one component'
67
+ }, {
68
+ command: 'token space.100',
69
+ comment: 'detail for one token'
70
+ }, {
71
+ command: 'icon --all',
72
+ comment: 'list every icon'
73
+ }, {
74
+ command: 'docs spacing',
75
+ comment: 'foundations docs'
76
+ }, {
77
+ command: 'docs a11y buttons',
78
+ comment: 'accessibility guidance'
79
+ }, {
80
+ command: 'docs migration motion',
81
+ comment: 'migration guide'
82
+ }, {
83
+ command: 'manifest --json',
84
+ comment: 'machine-readable CLI contract'
85
+ }];
86
+ const exampleCommands = examples.map(({
87
+ command
88
+ }) => `$ ${invocation} ${command}`);
89
+ const exampleWidth = Math.max(...exampleCommands.map(command => command.length));
90
+ const exampleLines = examples.map(({
91
+ comment
92
+ }, index) => {
93
+ const command = exampleCommands[index];
94
+ return ` ${comment ? `${command.padEnd(exampleWidth)} # ${comment}` : command}`;
95
+ }).join('\n');
96
+ return [CLI_DESCRIPTION, '', 'Usage', ` $ ${invocation} <command> [options]`, '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', exampleLines].join('\n');
53
97
  };
54
98
 
55
99
  /**
@@ -59,7 +103,8 @@ const runRegistryCommand = async ({
59
103
  command,
60
104
  input,
61
105
  json,
62
- writer
106
+ writer,
107
+ invocation
63
108
  }) => {
64
109
  var _resolved$meta3;
65
110
  const resolved = command.resolve(input);
@@ -99,7 +144,20 @@ const runRegistryCommand = async ({
99
144
  },
100
145
  meta: (_resolved$meta = resolved.meta) !== null && _resolved$meta !== void 0 ? _resolved$meta : {},
101
146
  json,
102
- writer
147
+ writer,
148
+ invocation
149
+ });
150
+ }
151
+
152
+ // Batch requests re-enter the same command registry in-process. Dynamic imports stay cached,
153
+ // requests run concurrently, and each child retains its normal envelope semantics.
154
+ if (resolved.batch) {
155
+ return runBatchRequests({
156
+ command,
157
+ requests: resolved.batch,
158
+ json,
159
+ writer,
160
+ invocation
103
161
  });
104
162
  }
105
163
 
@@ -126,7 +184,8 @@ const runRegistryCommand = async ({
126
184
  results,
127
185
  meta: (_resolved$meta2 = resolved.meta) !== null && _resolved$meta2 !== void 0 ? _resolved$meta2 : {},
128
186
  json,
129
- writer
187
+ writer,
188
+ invocation
130
189
  });
131
190
  }
132
191
  return renderSingleResult({
@@ -135,10 +194,41 @@ const runRegistryCommand = async ({
135
194
  result: results[0],
136
195
  meta: (_resolved$meta3 = resolved.meta) !== null && _resolved$meta3 !== void 0 ? _resolved$meta3 : {},
137
196
  json,
138
- writer
197
+ writer,
198
+ invocation
139
199
  });
140
200
  };
141
201
 
202
+ /**
203
+ * Render a command's already-transformed payload as human-readable text.
204
+ *
205
+ * Tried in order:
206
+ * 1. Compact per-row view when the command declares a result kind (search/list).
207
+ * 2. The command's own `formatHuman` renderer for rich single-object payloads
208
+ * (component docs, a11y/migration guides, lint-rule markdown).
209
+ *
210
+ * Returns `null` when neither step applies, leaving the caller to choose its own last-resort
211
+ * fallback. Shared by the single-command path and `batch` so the two cannot drift apart.
212
+ */
213
+ const formatCommandHuman = ({
214
+ command,
215
+ input,
216
+ data,
217
+ invocation
218
+ }) => {
219
+ var _command$resultKind, _ref, _command$formatHuman;
220
+ const resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
221
+ const compact = resultKind ? formatCompactResults({
222
+ kind: resultKind,
223
+ data,
224
+ showFollowUp: command.name === 'search',
225
+ invocation
226
+ }) : null;
227
+ return (_ref = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data, {
228
+ invocation
229
+ })) !== null && _ref !== void 0 ? _ref : null;
230
+ };
231
+
142
232
  /**
143
233
  * Render a single-tool command result (the common case).
144
234
  */
@@ -148,9 +238,9 @@ const renderSingleResult = ({
148
238
  result,
149
239
  meta,
150
240
  json,
151
- writer
241
+ writer,
242
+ invocation
152
243
  }) => {
153
- var _command$resultKind, _ref, _command$formatHuman;
154
244
  const {
155
245
  isError
156
246
  } = result;
@@ -218,19 +308,14 @@ const renderSingleResult = ({
218
308
  return ExitCode.Ok;
219
309
  }
220
310
 
221
- // Default (human) output, tried in order:
222
- // 1. Compact per-row view when the command declares a result kind (search/list).
223
- // 2. The command's own `formatHuman` renderer for rich single-object payloads
224
- // (component docs, a11y/migration guides, lint-rule markdown).
225
- // 3. The generic fallback: verbatim strings (e.g. foundations markdown) or pretty JSON.
226
- // Each step returns `null` to defer to the next, so a raw JSON dump is only ever a last resort.
227
- const resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
228
- const compact = resultKind ? formatCompactResults({
229
- kind: resultKind,
311
+ // Default (human) output: the shared renderer, falling back to verbatim strings (e.g.
312
+ // foundations markdown) or pretty JSON so a raw dump is only ever a last resort.
313
+ const human = formatCommandHuman({
314
+ command,
315
+ input,
230
316
  data,
231
- showFollowUp: command.name === 'search'
232
- }) : null;
233
- const human = (_ref = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref !== void 0 ? _ref : null;
317
+ invocation
318
+ });
234
319
  if (human !== null) {
235
320
  writer.out(human);
236
321
  } else {
@@ -241,6 +326,159 @@ const renderSingleResult = ({
241
326
  }
242
327
  return ExitCode.Ok;
243
328
  };
329
+ const classifyBatchResponse = response => {
330
+ if (!response.ok) {
331
+ return 'failure';
332
+ }
333
+ return isDisambiguation(response.data) ? 'ambiguous' : 'success';
334
+ };
335
+ const createCapturedWriter = () => {
336
+ const stdout = [];
337
+ const stderr = [];
338
+ return {
339
+ stdout,
340
+ stderr,
341
+ out: line => stdout.push(line),
342
+ err: line => stderr.push(line)
343
+ };
344
+ };
345
+
346
+ /**
347
+ * Execute one child argv through the normal CLI pipeline, forcing JSON so the parent can preserve
348
+ * the child's stable envelope without scraping human-readable output.
349
+ *
350
+ * There is deliberately no `--help`/`--version` guard here. Every child token is also a top-level
351
+ * token, so {@link run} already short-circuits the whole invocation to help/version text before a
352
+ * batch is ever resolved — a guard at this level would be unreachable.
353
+ */
354
+ const runBatchChild = async ({
355
+ request,
356
+ invocation
357
+ }) => {
358
+ const parsed = parseArgs(request.argv);
359
+ let response;
360
+ if (!parsed.command) {
361
+ response = createErrorEnvelope({
362
+ command: 'batch',
363
+ code: 'USAGE_ERROR',
364
+ message: 'A batch request must start with a command name.'
365
+ });
366
+ } else if (parsed.command === 'batch') {
367
+ response = createErrorEnvelope({
368
+ command: 'batch',
369
+ code: 'USAGE_ERROR',
370
+ message: 'Nested batch requests are not supported.'
371
+ });
372
+ } else {
373
+ const captured = createCapturedWriter();
374
+ await run([...request.argv, '--json'], captured, {
375
+ invocation
376
+ });
377
+ try {
378
+ response = JSON.parse(captured.stdout.join('\n'));
379
+ } catch {
380
+ response = createErrorEnvelope({
381
+ command: parsed.command,
382
+ code: 'RUNTIME_ERROR',
383
+ message: 'The child command did not produce a valid JSON envelope.'
384
+ });
385
+ }
386
+ }
387
+ return {
388
+ request: request.argv,
389
+ status: classifyBatchResponse(response),
390
+ response
391
+ };
392
+ };
393
+
394
+ /**
395
+ * Render an already-transformed child success envelope with the same human format as its command.
396
+ */
397
+ const formatBatchChildHuman = ({
398
+ item,
399
+ invocation
400
+ }) => {
401
+ if (!item.response.ok) {
402
+ return `Error: ${item.response.error.message}`;
403
+ }
404
+ const parsed = parseArgs(item.request);
405
+ const definition = parsed.command ? getCommand(parsed.command) : undefined;
406
+ if (!definition) {
407
+ return formatHumanResult({
408
+ data: item.response.data
409
+ });
410
+ }
411
+
412
+ // A unified search spans every kind, so it has no single result kind and needs the grouped
413
+ // formatter instead. This is the same condition `search`'s own resolver uses to choose the
414
+ // grouped path, so the two cannot disagree.
415
+ if (definition.name === 'search' && parsed.flags.type === undefined && typeof item.response.data === 'object' && item.response.data !== null) {
416
+ var _item$response$meta$c;
417
+ return formatGroupedResults({
418
+ groups: item.response.data,
419
+ totalCount: Number((_item$response$meta$c = item.response.meta.count) !== null && _item$response$meta$c !== void 0 ? _item$response$meta$c : 0),
420
+ invocation
421
+ });
422
+ }
423
+ const human = formatCommandHuman({
424
+ command: definition,
425
+ input: {
426
+ positionals: parsed.positionals,
427
+ flags: parsed.flags
428
+ },
429
+ data: item.response.data,
430
+ invocation
431
+ });
432
+ return human !== null && human !== void 0 ? human : formatHumanResult({
433
+ data: item.response.data
434
+ });
435
+ };
436
+
437
+ /**
438
+ * Execute heterogeneous registered commands concurrently in the current process and aggregate
439
+ * their existing envelopes. A valid batch exits zero even when individual child commands fail.
440
+ */
441
+ const runBatchRequests = async ({
442
+ command,
443
+ requests,
444
+ json,
445
+ writer,
446
+ invocation
447
+ }) => {
448
+ const items = await Promise.all(requests.map(request => runBatchChild({
449
+ request,
450
+ invocation
451
+ })));
452
+ const succeeded = items.filter(item => item.status === 'success').length;
453
+ const ambiguous = items.filter(item => item.status === 'ambiguous').length;
454
+ const failed = items.length - succeeded - ambiguous;
455
+ if (json) {
456
+ writeJsonEnvelope({
457
+ envelope: createSuccessEnvelope({
458
+ envelopeType: command.envelopeType({
459
+ positionals: [],
460
+ flags: {}
461
+ }),
462
+ command: command.name,
463
+ data: items,
464
+ meta: {
465
+ succeeded,
466
+ ambiguous,
467
+ failed
468
+ }
469
+ }),
470
+ writer
471
+ });
472
+ return ExitCode.Ok;
473
+ }
474
+ const summary = `Batch results: ${succeeded} succeeded, ${ambiguous} ambiguous, ${failed} failed`;
475
+ const sections = items.map(item => `Request: ${item.request.join(' ')}\n${formatBatchChildHuman({
476
+ item,
477
+ invocation
478
+ })}`);
479
+ writer.out([summary, ...sections].join('\n\n'));
480
+ return ExitCode.Ok;
481
+ };
244
482
 
245
483
  /**
246
484
  * Render a grouped (multi-tool) command result, e.g. unified `search`.
@@ -254,7 +492,8 @@ const renderGroupedResult = ({
254
492
  results,
255
493
  meta,
256
494
  json,
257
- writer
495
+ writer,
496
+ invocation
258
497
  }) => {
259
498
  // Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
260
499
  // empty domain does not blank out the others. The guidelines tool returns full Markdown, so
@@ -313,19 +552,22 @@ const renderGroupedResult = ({
313
552
  }
314
553
  writer.out(formatGroupedResults({
315
554
  groups: grouped,
316
- totalCount
555
+ totalCount,
556
+ invocation
317
557
  }));
318
558
  return ExitCode.Ok;
319
559
  };
320
-
321
560
  /**
322
561
  * Parse and execute a single CLI invocation.
323
562
  *
324
563
  * @param argv - Arguments after `node <script>` (i.e. `process.argv.slice(2)`).
325
564
  * @param writer - Injectable output sink; defaults to console-backed stdout/stderr.
565
+ * @param options - Distribution-specific rendering options.
326
566
  * @returns The process exit code. The bin wrapper maps this onto `process.exit`.
327
567
  */
328
- export const run = async (argv = process.argv.slice(2), writer = defaultWriter) => {
568
+ export const run = async (argv = process.argv.slice(2), writer = defaultWriter, {
569
+ invocation = CLI_BIN_NAME
570
+ } = {}) => {
329
571
  const {
330
572
  command,
331
573
  positionals,
@@ -342,7 +584,7 @@ export const run = async (argv = process.argv.slice(2), writer = defaultWriter)
342
584
  // `--help` / `-h`, or no command at all, prints help. No command is a usage error so
343
585
  // scripts can detect a missing invocation via the exit code.
344
586
  if (flags.help === true || command === undefined) {
345
- writer.out(buildHelpText());
587
+ writer.out(buildHelpText(invocation));
346
588
  return command === undefined && flags.help !== true ? ExitCode.UsageError : ExitCode.Ok;
347
589
  }
348
590
  const definition = getCommand(command);
@@ -362,7 +604,7 @@ export const run = async (argv = process.argv.slice(2), writer = defaultWriter)
362
604
  message,
363
605
  writer
364
606
  });
365
- writer.err('Run `ads-cli --help` to see available commands.');
607
+ writer.err(`Run \`${invocation} --help\` to see available commands.`);
366
608
  }
367
609
  return ExitCode.UsageError;
368
610
  }
@@ -371,10 +613,12 @@ export const run = async (argv = process.argv.slice(2), writer = defaultWriter)
371
613
  command: definition,
372
614
  input: {
373
615
  positionals,
374
- flags
616
+ flags,
617
+ rawArgs: argv
375
618
  },
376
619
  json,
377
- writer
620
+ writer,
621
+ invocation
378
622
  });
379
623
  } catch (error) {
380
624
  const message = error instanceof Error ? error.message : String(error);
@@ -10,12 +10,11 @@ import { CLI_BIN_NAME, CLI_DESCRIPTION, CLI_NAME, globalFlags } from './cli-meta
10
10
  * Build a serializable capability manifest from the live command registry.
11
11
  */
12
12
  export const buildManifest = (commands, version) => ({
13
- schemaVersion: 1,
13
+ schemaVersion: 2,
14
14
  name: CLI_NAME,
15
15
  bin: CLI_BIN_NAME,
16
16
  version,
17
17
  description: CLI_DESCRIPTION,
18
- invocation: `npx ${CLI_NAME}`,
19
18
  commands: commands.map(({
20
19
  name,
21
20
  description,
@@ -4,6 +4,7 @@
4
4
 
5
5
  export const CLI_NAME = '@atlaskit/ads-cli';
6
6
  export const CLI_BIN_NAME = 'ads-cli';
7
+ export const CLI_ATLAS_INVOCATION = 'atlas ads';
7
8
  export const CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
8
9
  export const globalFlags = [{
9
10
  name: 'json',
@@ -317,10 +317,12 @@ const makeItemCommand = ({
317
317
  // disambiguation marker, both handled by `formatHuman`.
318
318
  resultKind: input => input.flags.all ? kind : undefined,
319
319
  envelopeType: input => input.flags.all ? listTool.envelopeType : name,
320
- formatHuman: data => {
320
+ formatHuman: (data, {
321
+ invocation
322
+ }) => {
321
323
  // Ambiguous lookup → render the "did you mean?" list; otherwise the item detail view.
322
324
  if (isDisambiguation(data)) {
323
- return formatDisambiguation(data);
325
+ return formatDisambiguation(data, invocation);
324
326
  }
325
327
  return formatHuman(data);
326
328
  },
@@ -443,6 +445,61 @@ const resolveUnifiedSearch = input => {
443
445
  };
444
446
  };
445
447
 
448
+ /**
449
+ * Split a batch invocation into argv groups introduced by repeated `--command` flags. The groups
450
+ * remain tokenized, so child commands can be routed through the existing parser without evaluating
451
+ * shell strings.
452
+ */
453
+ const resolveBatch = input => {
454
+ var _input$rawArgs;
455
+ const rawArgs = (_input$rawArgs = input.rawArgs) !== null && _input$rawArgs !== void 0 ? _input$rawArgs : [];
456
+ const batchIndex = rawArgs.indexOf('batch');
457
+ const tokens = rawArgs.slice(batchIndex + 1).filter(token => token !== '--json');
458
+ if (tokens.length === 0) {
459
+ return {
460
+ error: 'At least one command request is required.'
461
+ };
462
+ }
463
+ if (tokens[0] !== '--command') {
464
+ return {
465
+ error: 'Each batch request must start with `--command`.'
466
+ };
467
+ }
468
+ const requests = [];
469
+ // The leading `--command` is validated above, so every remaining token either closes the open
470
+ // request or appends to it. Seeding the accumulator here keeps it non-nullable, which is what
471
+ // lets the loop stay free of "no request open yet" checks.
472
+ let current = [];
473
+ for (const token of tokens.slice(1)) {
474
+ if (token === '--command') {
475
+ if (current.length === 0) {
476
+ return {
477
+ error: '`--command` must be followed by a non-empty command request.'
478
+ };
479
+ }
480
+ requests.push({
481
+ argv: current
482
+ });
483
+ current = [];
484
+ continue;
485
+ }
486
+ current.push(token);
487
+ }
488
+ if (current.length === 0) {
489
+ return {
490
+ error: '`--command` must be followed by a non-empty command request.'
491
+ };
492
+ }
493
+ requests.push({
494
+ argv: current
495
+ });
496
+ return {
497
+ tools: [],
498
+ batch: requests,
499
+ meta: {}
500
+ };
501
+ };
502
+
446
503
  /**
447
504
  * The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
448
505
  */
@@ -503,6 +560,20 @@ export const commands = [{
503
560
  tool: searchKindTools[searchType]
504
561
  });
505
562
  }
563
+ }, {
564
+ name: 'batch',
565
+ description: 'Run multiple ADS CLI queries, including different command types, in one process.',
566
+ usage: 'batch [--json] --command <command> [args...] [--command <command> [args...]]...',
567
+ arguments: [],
568
+ flags: [{
569
+ name: 'command',
570
+ type: 'string[]',
571
+ description: 'A child command name followed by its arguments. Repeat once per child command.'
572
+ }],
573
+ examples: ['batch --command search button --type icon --command token space.200', 'batch --json --command component Button --command docs spacing'],
574
+ responseTypes: ['ads-cli/batch'],
575
+ envelopeType: () => 'batch',
576
+ resolve: resolveBatch
506
577
  }, makeItemCommand({
507
578
  kind: 'components',
508
579
  name: 'component',
@@ -532,7 +603,9 @@ export const commands = [{
532
603
  envelopeType: () => 'lint-rules',
533
604
  // Ambiguous fuzzy lookup → render the "did you mean?" list; otherwise print each rule's
534
605
  // Markdown `content` verbatim rather than JSON.
535
- formatHuman: data => isDisambiguation(data) ? formatDisambiguation(data) : formatLintRules(data),
606
+ formatHuman: (data, {
607
+ invocation
608
+ }) => isDisambiguation(data) ? formatDisambiguation(data, invocation) : formatLintRules(data),
536
609
  // Mirror the item commands: a fuzzy term that matches one rule exactly (or a lone match)
537
610
  // shows that rule's docs, but several matches with no exact name surface a disambiguation
538
611
  // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
@@ -747,8 +820,6 @@ export const commands = [{
747
820
  formatHuman: formatManifest,
748
821
  resolve: () => ({
749
822
  data: buildManifest(commands, getVersion()),
750
- meta: {
751
- schemaVersion: 1
752
- }
823
+ meta: {}
753
824
  })
754
825
  }];
@@ -2,6 +2,7 @@
2
2
  * Human-readable renderer for an ambiguous item lookup ("did you mean?").
3
3
  */
4
4
 
5
+ import { CLI_BIN_NAME } from '../commands/cli-metadata';
5
6
  /**
6
7
  * Render a "did you mean?" list for an ambiguous lookup.
7
8
  *
@@ -12,11 +13,11 @@ export const formatDisambiguation = ({
12
13
  query,
13
14
  noun,
14
15
  candidates
15
- }) => {
16
+ }, invocation = CLI_BIN_NAME) => {
16
17
  const header = `Multiple ${noun}s match "${query}". Did you mean one of these?`;
17
18
  const rows = candidates.map(candidate => {
18
19
  const hint = candidate.hint ? ` ${candidate.hint}` : '';
19
- return ` ${candidate.name}${hint}\n → ads-cli ${candidate.followUp}`;
20
+ return ` ${candidate.name}${hint}\n → ${invocation} ${candidate.followUp}`;
20
21
  });
21
22
  return [header, '', ...rows].join('\n');
22
23
  };
@@ -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,8 @@ import { formatCompactResults } from './format-results';
12
13
  */
13
14
  export const formatGroupedResults = ({
14
15
  groups,
15
- totalCount
16
+ totalCount,
17
+ invocation = CLI_BIN_NAME
16
18
  }) => {
17
19
  // Fixed display order, with human-friendly section titles.
18
20
  const sections = [{
@@ -44,7 +46,8 @@ export const formatGroupedResults = ({
44
46
  const rendered = formatCompactResults({
45
47
  kind,
46
48
  data: entries,
47
- showFollowUp: true
49
+ showFollowUp: true,
50
+ invocation
48
51
  });
49
52
  const body = rendered ? rendered.split('\n').slice(2).join('\n') : '';
50
53
  blocks.push('', `${title} (${entries.length}):`, '', body);
@@ -0,0 +1,28 @@
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 const formatHumanResult = ({
19
+ data
20
+ }) => {
21
+ if (typeof data === 'string') {
22
+ return data;
23
+ }
24
+ if (data === null || data === undefined) {
25
+ return chalk.yellow('No results.');
26
+ }
27
+ return JSON.stringify(data, null, 2);
28
+ };
@@ -1,8 +1,11 @@
1
1
  /**
2
2
  * Format a scannable human catalog of the ADS CLI capability manifest.
3
3
  */
4
- export const formatManifest = data => {
5
- 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)) {
4
+
5
+ export const formatManifest = (data, {
6
+ invocation
7
+ }) => {
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)) {
6
9
  return null;
7
10
  }
8
11
  const commands = data.commands.flatMap(command => {
@@ -14,5 +17,5 @@ export const formatManifest = data => {
14
17
  });
15
18
  const commandCount = commands.length;
16
19
  const commandLabel = commandCount === 1 ? 'command' : 'commands';
17
- return [`${data.bin} v${data.version} — ${commandCount} ${commandLabel}`, '', commands.join('\n'), '', `Run \`${data.invocation} manifest --json\` for the full structured manifest.`].join('\n');
20
+ return [`${data.bin} v${data.version} — ${commandCount} ${commandLabel}`, '', commands.join('\n'), '', `Run \`${invocation} manifest --json\` for the full structured manifest.`].join('\n');
18
21
  };