@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.
- package/CHANGELOG.md +30 -0
- package/README.md +62 -10
- package/bin/ads-cli.js +5 -1
- package/dist/cjs/atlas-cli.js +4 -1
- package/dist/cjs/cli.js +368 -70
- package/dist/cjs/commands/build-manifest.js +1 -2
- package/dist/cjs/commands/cli-metadata.js +2 -1
- package/dist/cjs/commands/definitions.js +100 -16
- package/dist/cjs/output/format-disambiguation.js +3 -1
- package/dist/cjs/output/format-grouped-results.js +6 -2
- package/dist/cjs/output/format-human-result.js +33 -0
- package/dist/cjs/output/format-manifest.js +5 -3
- package/dist/cjs/output/format-results.js +25 -18
- package/dist/cjs/output/write-human-result.js +8 -10
- package/dist/es2019/atlas-cli.js +4 -1
- package/dist/es2019/cli.js +273 -29
- package/dist/es2019/commands/build-manifest.js +1 -2
- package/dist/es2019/commands/cli-metadata.js +1 -0
- package/dist/es2019/commands/definitions.js +77 -6
- package/dist/es2019/output/format-disambiguation.js +3 -2
- package/dist/es2019/output/format-grouped-results.js +5 -2
- package/dist/es2019/output/format-human-result.js +28 -0
- package/dist/es2019/output/format-manifest.js +6 -3
- package/dist/es2019/output/format-results.js +25 -18
- package/dist/es2019/output/write-human-result.js +8 -9
- package/dist/esm/atlas-cli.js +4 -1
- package/dist/esm/cli.js +369 -71
- package/dist/esm/commands/build-manifest.js +1 -2
- package/dist/esm/commands/cli-metadata.js +1 -0
- package/dist/esm/commands/definitions.js +100 -16
- package/dist/esm/output/format-disambiguation.js +3 -1
- package/dist/esm/output/format-grouped-results.js +6 -2
- package/dist/esm/output/format-human-result.js +27 -0
- package/dist/esm/output/format-manifest.js +5 -3
- package/dist/esm/output/format-results.js +26 -18
- package/dist/esm/output/write-human-result.js +8 -9
- package/dist/types/cli.d.ts +10 -1
- package/dist/types/commands/build-manifest.d.ts +1 -2
- package/dist/types/commands/cli-metadata.d.ts +1 -0
- package/dist/types/commands/types.d.ts +28 -1
- package/dist/types/output/format-disambiguation.d.ts +1 -1
- package/dist/types/output/format-grouped-results.d.ts +2 -1
- package/dist/types/output/format-human-result.d.ts +17 -0
- package/dist/types/output/format-manifest.d.ts +2 -1
- package/dist/types/output/format-results.d.ts +4 -3
- package/dist/types/output/write-human-result.d.ts +2 -2
- package/dist/types/parse-args.d.ts +1 -1
- package/package.json +1 -1
package/dist/es2019/cli.js
CHANGED
|
@@ -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
|
-
|
|
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,
|
|
222
|
-
//
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
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
|
-
|
|
232
|
-
})
|
|
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(
|
|
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:
|
|
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:
|
|
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 →
|
|
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
|
-
|
|
5
|
-
|
|
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 \`${
|
|
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
|
};
|