@atlaskit/ads-cli 0.1.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 +34 -0
- package/README.md +134 -0
- package/bin/ads-cli.js +40 -0
- package/compass.yml +25 -0
- package/dist/cjs/cli.js +488 -0
- package/dist/cjs/commands/definitions.js +713 -0
- package/dist/cjs/commands/get-command.js +19 -0
- package/dist/cjs/commands/import-tool-handler.js +57 -0
- package/dist/cjs/commands/run-tool.js +106 -0
- package/dist/cjs/commands/types.js +1 -0
- package/dist/cjs/envelope/create-error-envelope.js +27 -0
- package/dist/cjs/envelope/create-success-envelope.js +38 -0
- package/dist/cjs/envelope/types.js +1 -0
- package/dist/cjs/output/disambiguation.js +31 -0
- package/dist/cjs/output/format-component.js +99 -0
- package/dist/cjs/output/format-disambiguation.js +29 -0
- package/dist/cjs/output/format-doc-object.js +115 -0
- package/dist/cjs/output/format-grouped-results.js +55 -0
- package/dist/cjs/output/format-icon.js +49 -0
- package/dist/cjs/output/format-lint-rules.js +52 -0
- package/dist/cjs/output/format-results.js +158 -0
- package/dist/cjs/output/format-token.js +39 -0
- package/dist/cjs/output/parse-lint-rule-records.js +47 -0
- package/dist/cjs/output/write-human-error.js +20 -0
- package/dist/cjs/output/write-human-result.js +31 -0
- package/dist/cjs/output/write-json-envelope.js +20 -0
- package/dist/cjs/output/writer.js +32 -0
- package/dist/cjs/parse-args.js +106 -0
- package/dist/cjs/types.js +53 -0
- package/dist/es2019/cli.js +406 -0
- package/dist/es2019/commands/definitions.js +683 -0
- package/dist/es2019/commands/get-command.js +9 -0
- package/dist/es2019/commands/import-tool-handler.js +22 -0
- package/dist/es2019/commands/run-tool.js +73 -0
- package/dist/es2019/commands/types.js +0 -0
- package/dist/es2019/envelope/create-error-envelope.js +20 -0
- package/dist/es2019/envelope/create-success-envelope.js +31 -0
- package/dist/es2019/envelope/types.js +0 -0
- package/dist/es2019/output/disambiguation.js +21 -0
- package/dist/es2019/output/format-component.js +88 -0
- package/dist/es2019/output/format-disambiguation.js +22 -0
- package/dist/es2019/output/format-doc-object.js +94 -0
- package/dist/es2019/output/format-grouped-results.js +51 -0
- package/dist/es2019/output/format-icon.js +39 -0
- package/dist/es2019/output/format-lint-rules.js +43 -0
- package/dist/es2019/output/format-results.js +142 -0
- package/dist/es2019/output/format-token.js +31 -0
- package/dist/es2019/output/parse-lint-rule-records.js +41 -0
- package/dist/es2019/output/write-human-error.js +14 -0
- package/dist/es2019/output/write-human-result.js +25 -0
- package/dist/es2019/output/write-json-envelope.js +15 -0
- package/dist/es2019/output/writer.js +22 -0
- package/dist/es2019/parse-args.js +100 -0
- package/dist/es2019/types.js +47 -0
- package/dist/esm/cli.js +484 -0
- package/dist/esm/commands/definitions.js +708 -0
- package/dist/esm/commands/get-command.js +13 -0
- package/dist/esm/commands/import-tool-handler.js +42 -0
- package/dist/esm/commands/run-tool.js +99 -0
- package/dist/esm/commands/types.js +0 -0
- package/dist/esm/envelope/create-error-envelope.js +21 -0
- package/dist/esm/envelope/create-success-envelope.js +31 -0
- package/dist/esm/envelope/types.js +0 -0
- package/dist/esm/output/disambiguation.js +24 -0
- package/dist/esm/output/format-component.js +92 -0
- package/dist/esm/output/format-disambiguation.js +22 -0
- package/dist/esm/output/format-doc-object.js +108 -0
- package/dist/esm/output/format-grouped-results.js +50 -0
- package/dist/esm/output/format-icon.js +42 -0
- package/dist/esm/output/format-lint-rules.js +46 -0
- package/dist/esm/output/format-results.js +151 -0
- package/dist/esm/output/format-token.js +32 -0
- package/dist/esm/output/parse-lint-rule-records.js +41 -0
- package/dist/esm/output/write-human-error.js +13 -0
- package/dist/esm/output/write-human-result.js +24 -0
- package/dist/esm/output/write-json-envelope.js +14 -0
- package/dist/esm/output/writer.js +26 -0
- package/dist/esm/parse-args.js +100 -0
- package/dist/esm/types.js +47 -0
- package/dist/types/cli.d.ts +20 -0
- package/dist/types/commands/definitions.d.ts +19 -0
- package/dist/types/commands/get-command.d.ts +8 -0
- package/dist/types/commands/import-tool-handler.d.ts +14 -0
- package/dist/types/commands/run-tool.d.ts +37 -0
- package/dist/types/commands/types.d.ts +149 -0
- package/dist/types/envelope/create-error-envelope.d.ts +12 -0
- package/dist/types/envelope/create-success-envelope.d.ts +16 -0
- package/dist/types/envelope/types.d.ts +60 -0
- package/dist/types/output/disambiguation.d.ts +50 -0
- package/dist/types/output/format-component.d.ts +12 -0
- package/dist/types/output/format-disambiguation.d.ts +11 -0
- package/dist/types/output/format-doc-object.d.ts +15 -0
- package/dist/types/output/format-grouped-results.d.ts +14 -0
- package/dist/types/output/format-icon.d.ts +13 -0
- package/dist/types/output/format-lint-rules.d.ts +14 -0
- package/dist/types/output/format-results.d.ts +24 -0
- package/dist/types/output/format-token.d.ts +12 -0
- package/dist/types/output/parse-lint-rule-records.d.ts +26 -0
- package/dist/types/output/write-human-error.d.ts +11 -0
- package/dist/types/output/write-human-result.d.ts +14 -0
- package/dist/types/output/write-json-envelope.d.ts +14 -0
- package/dist/types/output/writer.d.ts +25 -0
- package/dist/types/parse-args.d.ts +29 -0
- package/dist/types/types.d.ts +53 -0
- package/index.js +31 -0
- package/package.json +30 -0
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ADS CLI entrypoint.
|
|
3
|
+
*
|
|
4
|
+
* `run(argv)` parses arguments, resolves the requested command from the shared
|
|
5
|
+
* {@link commands} registry, dispatches to the underlying `@atlaskit/ads-mcp/tools/*`
|
|
6
|
+
* handler, and formats the result (human-readable by default, JSON with `--json`).
|
|
7
|
+
*
|
|
8
|
+
* It never reimplements search ranking or bundles a dataset copy — all query logic lives in
|
|
9
|
+
* `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { commands } from './commands/definitions';
|
|
13
|
+
import { getCommand } from './commands/get-command';
|
|
14
|
+
import { importToolHandler } from './commands/import-tool-handler';
|
|
15
|
+
import { runTool } from './commands/run-tool';
|
|
16
|
+
import { createErrorEnvelope } from './envelope/create-error-envelope';
|
|
17
|
+
import { createSuccessEnvelope } from './envelope/create-success-envelope';
|
|
18
|
+
import { formatGroupedResults } from './output/format-grouped-results';
|
|
19
|
+
import { formatCompactResults } from './output/format-results';
|
|
20
|
+
import { writeHumanError } from './output/write-human-error';
|
|
21
|
+
import { writeHumanResult } from './output/write-human-result';
|
|
22
|
+
import { writeJsonEnvelope } from './output/write-json-envelope';
|
|
23
|
+
import { defaultWriter } from './output/writer';
|
|
24
|
+
import { parseArgs } from './parse-args';
|
|
25
|
+
import { ExitCode } from './types';
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Resolve the CLI version from package.json. Kept in a function so a failure to read it never
|
|
29
|
+
* crashes the CLI (it falls back to `0.0.0`).
|
|
30
|
+
*/
|
|
31
|
+
const getVersion = () => {
|
|
32
|
+
try {
|
|
33
|
+
var _pkgJson$version;
|
|
34
|
+
// Read our own package.json at runtime via the package-name subpath. This mirrors
|
|
35
|
+
// the sibling `@atlaskit/ads-mcp` package and is depth-independent, so it resolves
|
|
36
|
+
// correctly in both the in-repo source layout (`src/cli`) and the published build
|
|
37
|
+
// (`dist/cjs/cli`). Requires the `./package.json` subpath in this package's exports.
|
|
38
|
+
// eslint-disable-next-line import/no-extraneous-dependencies, @typescript-eslint/no-var-requires -- this uses require because not all supported node versions use the same import assertions/attributes
|
|
39
|
+
const pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
40
|
+
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
41
|
+
} catch {
|
|
42
|
+
return '0.0.0';
|
|
43
|
+
}
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* One-line description of the CLI, shown at the top of `--help`.
|
|
48
|
+
*/
|
|
49
|
+
const CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Build the top-level help text from the command registry so it can never drift from the
|
|
53
|
+
* runnable surface.
|
|
54
|
+
*/
|
|
55
|
+
const buildHelpText = () => {
|
|
56
|
+
// Width of the usage "gutter"; descriptions align to this column. Usages longer than the
|
|
57
|
+
// gutter wrap onto their own line with the description indented beneath, so a long usage
|
|
58
|
+
// (e.g. `docs`, which lists every topic) never produces a single 130-column line.
|
|
59
|
+
const gutter = 56;
|
|
60
|
+
const commandLines = commands.map(command => {
|
|
61
|
+
if (command.usage.length <= gutter) {
|
|
62
|
+
return ` ${command.usage.padEnd(gutter)} ${command.description}`;
|
|
63
|
+
}
|
|
64
|
+
// Long usage: print it on its own line(s), then the description indented beneath so the
|
|
65
|
+
// two stay visually associated instead of the description drifting far to the right.
|
|
66
|
+
const usageLines = command.usage.split(' | ').map((part, index) => index === 0 ? ` ${part}` : ` | ${part}`).join('\n');
|
|
67
|
+
return `${usageLines}\n ${command.description}`;
|
|
68
|
+
}).join('\n');
|
|
69
|
+
return [CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', ' --json Emit a machine-readable JSON envelope on stdout.', ' --help, -h Show this help.', ' --version, -v Show the CLI version.', '', 'Examples', ' $ npx @atlaskit/ads-cli search button # unified: components, tokens & icons', ' $ npx @atlaskit/ads-cli search button --type component', ' $ 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'].join('\n');
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Execute a registry-backed command: resolve its tool + args, dispatch, and format output.
|
|
74
|
+
*/
|
|
75
|
+
const runRegistryCommand = async ({
|
|
76
|
+
command,
|
|
77
|
+
input,
|
|
78
|
+
json,
|
|
79
|
+
writer
|
|
80
|
+
}) => {
|
|
81
|
+
var _resolved$meta3;
|
|
82
|
+
const resolved = command.resolve(input);
|
|
83
|
+
|
|
84
|
+
// A resolver returning `{ error }` indicates invalid input (a usage error).
|
|
85
|
+
if ('error' in resolved) {
|
|
86
|
+
if (json) {
|
|
87
|
+
writeJsonEnvelope({
|
|
88
|
+
envelope: createErrorEnvelope({
|
|
89
|
+
command: command.name,
|
|
90
|
+
code: 'USAGE_ERROR',
|
|
91
|
+
message: resolved.error
|
|
92
|
+
}),
|
|
93
|
+
writer
|
|
94
|
+
});
|
|
95
|
+
} else {
|
|
96
|
+
writeHumanError({
|
|
97
|
+
message: resolved.error,
|
|
98
|
+
writer
|
|
99
|
+
});
|
|
100
|
+
writer.err(`Usage: ${command.usage}`);
|
|
101
|
+
}
|
|
102
|
+
return ExitCode.UsageError;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// A resolver returning pre-computed `data` (no tool calls) is a friendly, exit-0 static
|
|
106
|
+
// response — e.g. bare `docs` listing the available namespaces. Route it through the same
|
|
107
|
+
// single-result renderer so it honours `formatHuman` and `--json` identically.
|
|
108
|
+
if ('data' in resolved) {
|
|
109
|
+
var _resolved$meta;
|
|
110
|
+
return renderSingleResult({
|
|
111
|
+
command,
|
|
112
|
+
input,
|
|
113
|
+
result: {
|
|
114
|
+
data: resolved.data,
|
|
115
|
+
isError: false
|
|
116
|
+
},
|
|
117
|
+
meta: (_resolved$meta = resolved.meta) !== null && _resolved$meta !== void 0 ? _resolved$meta : {},
|
|
118
|
+
json,
|
|
119
|
+
writer
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// Run every tool call the command resolved to. Single-tool commands have one; unified
|
|
124
|
+
// commands (e.g. `search` with no `--type`) have several that run in parallel.
|
|
125
|
+
const results = await Promise.all(resolved.tools.map(async tool => {
|
|
126
|
+
const handler = await importToolHandler({
|
|
127
|
+
importPath: tool.importPath,
|
|
128
|
+
handlerName: tool.handlerName
|
|
129
|
+
});
|
|
130
|
+
return {
|
|
131
|
+
key: tool.key,
|
|
132
|
+
...(await runTool({
|
|
133
|
+
handler,
|
|
134
|
+
args: tool.args
|
|
135
|
+
}))
|
|
136
|
+
};
|
|
137
|
+
}));
|
|
138
|
+
if (resolved.grouped) {
|
|
139
|
+
var _resolved$meta2;
|
|
140
|
+
return renderGroupedResult({
|
|
141
|
+
command,
|
|
142
|
+
input,
|
|
143
|
+
results,
|
|
144
|
+
meta: (_resolved$meta2 = resolved.meta) !== null && _resolved$meta2 !== void 0 ? _resolved$meta2 : {},
|
|
145
|
+
json,
|
|
146
|
+
writer
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
return renderSingleResult({
|
|
150
|
+
command,
|
|
151
|
+
input,
|
|
152
|
+
result: results[0],
|
|
153
|
+
meta: (_resolved$meta3 = resolved.meta) !== null && _resolved$meta3 !== void 0 ? _resolved$meta3 : {},
|
|
154
|
+
json,
|
|
155
|
+
writer
|
|
156
|
+
});
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Render a single-tool command result (the common case).
|
|
161
|
+
*/
|
|
162
|
+
const renderSingleResult = ({
|
|
163
|
+
command,
|
|
164
|
+
input,
|
|
165
|
+
result,
|
|
166
|
+
meta,
|
|
167
|
+
json,
|
|
168
|
+
writer
|
|
169
|
+
}) => {
|
|
170
|
+
var _command$resultKind, _ref, _command$formatHuman;
|
|
171
|
+
const {
|
|
172
|
+
isError
|
|
173
|
+
} = result;
|
|
174
|
+
|
|
175
|
+
// The ADS search tools return an `Error: No … found` text block when nothing matches.
|
|
176
|
+
if (isError) {
|
|
177
|
+
const message = typeof result.data === 'string' ? result.data.replace(/^Error:\s*/, '') : 'No results found.';
|
|
178
|
+
if (json) {
|
|
179
|
+
writeJsonEnvelope({
|
|
180
|
+
envelope: createErrorEnvelope({
|
|
181
|
+
command: command.name,
|
|
182
|
+
code: 'NOT_FOUND',
|
|
183
|
+
message
|
|
184
|
+
}),
|
|
185
|
+
writer
|
|
186
|
+
});
|
|
187
|
+
} else {
|
|
188
|
+
writeHumanError({
|
|
189
|
+
message,
|
|
190
|
+
writer
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
return ExitCode.NotFound;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
// Some tools signal "no match" by returning an empty (or whitespace-only) string rather than
|
|
197
|
+
// an `Error:` block — e.g. `docs <term>` for an unknown foundation. Treat that as NOT_FOUND so
|
|
198
|
+
// the user gets a clear miss instead of a silent, empty, exit-0 response.
|
|
199
|
+
if (typeof result.data === 'string' && result.data.trim() === '') {
|
|
200
|
+
const message = `No results found${input.positionals.length > 0 ? ` for "${input.positionals.join(' ')}"` : ''}.`;
|
|
201
|
+
if (json) {
|
|
202
|
+
writeJsonEnvelope({
|
|
203
|
+
envelope: createErrorEnvelope({
|
|
204
|
+
command: command.name,
|
|
205
|
+
code: 'NOT_FOUND',
|
|
206
|
+
message
|
|
207
|
+
}),
|
|
208
|
+
writer
|
|
209
|
+
});
|
|
210
|
+
} else {
|
|
211
|
+
writeHumanError({
|
|
212
|
+
message,
|
|
213
|
+
writer
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
return ExitCode.NotFound;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// Optional post-processing (e.g. exact-match vs disambiguation for item commands). Applied
|
|
220
|
+
// before both JSON and human rendering so the envelope and the terminal view stay in sync.
|
|
221
|
+
const data = command.transform ? command.transform({
|
|
222
|
+
data: result.data,
|
|
223
|
+
input
|
|
224
|
+
}) : result.data;
|
|
225
|
+
if (json) {
|
|
226
|
+
writeJsonEnvelope({
|
|
227
|
+
envelope: createSuccessEnvelope({
|
|
228
|
+
envelopeType: command.envelopeType(input),
|
|
229
|
+
command: command.name,
|
|
230
|
+
data,
|
|
231
|
+
meta
|
|
232
|
+
}),
|
|
233
|
+
writer
|
|
234
|
+
});
|
|
235
|
+
return ExitCode.Ok;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
// Default (human) output, tried in order:
|
|
239
|
+
// 1. Compact per-row view when the command declares a result kind (search/list).
|
|
240
|
+
// 2. The command's own `formatHuman` renderer for rich single-object payloads
|
|
241
|
+
// (component docs, a11y/migration guides, lint-rule markdown).
|
|
242
|
+
// 3. The generic fallback: verbatim strings (e.g. foundations markdown) or pretty JSON.
|
|
243
|
+
// Each step returns `null` to defer to the next, so a raw JSON dump is only ever a last resort.
|
|
244
|
+
const resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
|
|
245
|
+
const compact = resultKind ? formatCompactResults({
|
|
246
|
+
kind: resultKind,
|
|
247
|
+
data
|
|
248
|
+
}) : null;
|
|
249
|
+
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;
|
|
250
|
+
if (human !== null) {
|
|
251
|
+
writer.out(human);
|
|
252
|
+
} else {
|
|
253
|
+
writeHumanResult({
|
|
254
|
+
data,
|
|
255
|
+
writer
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
return ExitCode.Ok;
|
|
259
|
+
};
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* Render a grouped (multi-tool) command result, e.g. unified `search`.
|
|
263
|
+
*
|
|
264
|
+
* Each sub-result is keyed by its {@link ToolCall.key}. A sub-search that finds nothing simply
|
|
265
|
+
* contributes an empty array; the command is only treated as NOT_FOUND when every group is empty.
|
|
266
|
+
*/
|
|
267
|
+
const renderGroupedResult = ({
|
|
268
|
+
command,
|
|
269
|
+
input,
|
|
270
|
+
results,
|
|
271
|
+
meta,
|
|
272
|
+
json,
|
|
273
|
+
writer
|
|
274
|
+
}) => {
|
|
275
|
+
// Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
|
|
276
|
+
// empty domain does not blank out the others.
|
|
277
|
+
const grouped = {};
|
|
278
|
+
for (const {
|
|
279
|
+
key,
|
|
280
|
+
data,
|
|
281
|
+
isError
|
|
282
|
+
} of results) {
|
|
283
|
+
grouped[key] = isError || !Array.isArray(data) ? [] : data;
|
|
284
|
+
}
|
|
285
|
+
const totalCount = Object.values(grouped).reduce((sum, arr) => sum + arr.length, 0);
|
|
286
|
+
if (totalCount === 0) {
|
|
287
|
+
const message = 'No components, tokens, or icons found.';
|
|
288
|
+
if (json) {
|
|
289
|
+
writeJsonEnvelope({
|
|
290
|
+
envelope: createErrorEnvelope({
|
|
291
|
+
command: command.name,
|
|
292
|
+
code: 'NOT_FOUND',
|
|
293
|
+
message
|
|
294
|
+
}),
|
|
295
|
+
writer
|
|
296
|
+
});
|
|
297
|
+
} else {
|
|
298
|
+
writeHumanError({
|
|
299
|
+
message,
|
|
300
|
+
writer
|
|
301
|
+
});
|
|
302
|
+
}
|
|
303
|
+
return ExitCode.NotFound;
|
|
304
|
+
}
|
|
305
|
+
if (json) {
|
|
306
|
+
writeJsonEnvelope({
|
|
307
|
+
envelope: createSuccessEnvelope({
|
|
308
|
+
envelopeType: command.envelopeType(input),
|
|
309
|
+
command: command.name,
|
|
310
|
+
// `data` for grouped commands is `{ components, tokens, icons }` (already counted
|
|
311
|
+
// per group), so `count` is the combined total across groups.
|
|
312
|
+
data: grouped,
|
|
313
|
+
meta: {
|
|
314
|
+
...meta,
|
|
315
|
+
count: totalCount
|
|
316
|
+
}
|
|
317
|
+
}),
|
|
318
|
+
writer
|
|
319
|
+
});
|
|
320
|
+
return ExitCode.Ok;
|
|
321
|
+
}
|
|
322
|
+
writer.out(formatGroupedResults({
|
|
323
|
+
groups: grouped,
|
|
324
|
+
totalCount
|
|
325
|
+
}));
|
|
326
|
+
return ExitCode.Ok;
|
|
327
|
+
};
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Parse and execute a single CLI invocation.
|
|
331
|
+
*
|
|
332
|
+
* @param argv - Arguments after `node <script>` (i.e. `process.argv.slice(2)`).
|
|
333
|
+
* @param writer - Injectable output sink; defaults to console-backed stdout/stderr.
|
|
334
|
+
* @returns The process exit code. The bin wrapper maps this onto `process.exit`.
|
|
335
|
+
*/
|
|
336
|
+
export const run = async (argv = process.argv.slice(2), writer = defaultWriter) => {
|
|
337
|
+
const {
|
|
338
|
+
command,
|
|
339
|
+
positionals,
|
|
340
|
+
flags
|
|
341
|
+
} = parseArgs(argv);
|
|
342
|
+
const json = flags.json === true;
|
|
343
|
+
|
|
344
|
+
// `--version` / `-v` takes precedence and short-circuits.
|
|
345
|
+
if (flags.version === true) {
|
|
346
|
+
writer.out(getVersion());
|
|
347
|
+
return ExitCode.Ok;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
// `--help` / `-h`, or no command at all, prints help. No command is a usage error so
|
|
351
|
+
// scripts can detect a missing invocation via the exit code.
|
|
352
|
+
if (flags.help === true || command === undefined) {
|
|
353
|
+
writer.out(buildHelpText());
|
|
354
|
+
return command === undefined && flags.help !== true ? ExitCode.UsageError : ExitCode.Ok;
|
|
355
|
+
}
|
|
356
|
+
const definition = getCommand(command);
|
|
357
|
+
if (!definition) {
|
|
358
|
+
const message = `Unknown command "${command}".`;
|
|
359
|
+
if (json) {
|
|
360
|
+
writeJsonEnvelope({
|
|
361
|
+
envelope: createErrorEnvelope({
|
|
362
|
+
command,
|
|
363
|
+
code: 'USAGE_ERROR',
|
|
364
|
+
message
|
|
365
|
+
}),
|
|
366
|
+
writer
|
|
367
|
+
});
|
|
368
|
+
} else {
|
|
369
|
+
writeHumanError({
|
|
370
|
+
message,
|
|
371
|
+
writer
|
|
372
|
+
});
|
|
373
|
+
writer.err('Run `ads-cli --help` to see available commands.');
|
|
374
|
+
}
|
|
375
|
+
return ExitCode.UsageError;
|
|
376
|
+
}
|
|
377
|
+
try {
|
|
378
|
+
return await runRegistryCommand({
|
|
379
|
+
command: definition,
|
|
380
|
+
input: {
|
|
381
|
+
positionals,
|
|
382
|
+
flags
|
|
383
|
+
},
|
|
384
|
+
json,
|
|
385
|
+
writer
|
|
386
|
+
});
|
|
387
|
+
} catch (error) {
|
|
388
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
389
|
+
if (json) {
|
|
390
|
+
writeJsonEnvelope({
|
|
391
|
+
envelope: createErrorEnvelope({
|
|
392
|
+
command: definition.name,
|
|
393
|
+
code: 'RUNTIME_ERROR',
|
|
394
|
+
message
|
|
395
|
+
}),
|
|
396
|
+
writer
|
|
397
|
+
});
|
|
398
|
+
} else {
|
|
399
|
+
writeHumanError({
|
|
400
|
+
message,
|
|
401
|
+
writer
|
|
402
|
+
});
|
|
403
|
+
}
|
|
404
|
+
return ExitCode.RuntimeError;
|
|
405
|
+
}
|
|
406
|
+
};
|