@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.
Files changed (106) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +134 -0
  3. package/bin/ads-cli.js +40 -0
  4. package/compass.yml +25 -0
  5. package/dist/cjs/cli.js +488 -0
  6. package/dist/cjs/commands/definitions.js +713 -0
  7. package/dist/cjs/commands/get-command.js +19 -0
  8. package/dist/cjs/commands/import-tool-handler.js +57 -0
  9. package/dist/cjs/commands/run-tool.js +106 -0
  10. package/dist/cjs/commands/types.js +1 -0
  11. package/dist/cjs/envelope/create-error-envelope.js +27 -0
  12. package/dist/cjs/envelope/create-success-envelope.js +38 -0
  13. package/dist/cjs/envelope/types.js +1 -0
  14. package/dist/cjs/output/disambiguation.js +31 -0
  15. package/dist/cjs/output/format-component.js +99 -0
  16. package/dist/cjs/output/format-disambiguation.js +29 -0
  17. package/dist/cjs/output/format-doc-object.js +115 -0
  18. package/dist/cjs/output/format-grouped-results.js +55 -0
  19. package/dist/cjs/output/format-icon.js +49 -0
  20. package/dist/cjs/output/format-lint-rules.js +52 -0
  21. package/dist/cjs/output/format-results.js +158 -0
  22. package/dist/cjs/output/format-token.js +39 -0
  23. package/dist/cjs/output/parse-lint-rule-records.js +47 -0
  24. package/dist/cjs/output/write-human-error.js +20 -0
  25. package/dist/cjs/output/write-human-result.js +31 -0
  26. package/dist/cjs/output/write-json-envelope.js +20 -0
  27. package/dist/cjs/output/writer.js +32 -0
  28. package/dist/cjs/parse-args.js +106 -0
  29. package/dist/cjs/types.js +53 -0
  30. package/dist/es2019/cli.js +406 -0
  31. package/dist/es2019/commands/definitions.js +683 -0
  32. package/dist/es2019/commands/get-command.js +9 -0
  33. package/dist/es2019/commands/import-tool-handler.js +22 -0
  34. package/dist/es2019/commands/run-tool.js +73 -0
  35. package/dist/es2019/commands/types.js +0 -0
  36. package/dist/es2019/envelope/create-error-envelope.js +20 -0
  37. package/dist/es2019/envelope/create-success-envelope.js +31 -0
  38. package/dist/es2019/envelope/types.js +0 -0
  39. package/dist/es2019/output/disambiguation.js +21 -0
  40. package/dist/es2019/output/format-component.js +88 -0
  41. package/dist/es2019/output/format-disambiguation.js +22 -0
  42. package/dist/es2019/output/format-doc-object.js +94 -0
  43. package/dist/es2019/output/format-grouped-results.js +51 -0
  44. package/dist/es2019/output/format-icon.js +39 -0
  45. package/dist/es2019/output/format-lint-rules.js +43 -0
  46. package/dist/es2019/output/format-results.js +142 -0
  47. package/dist/es2019/output/format-token.js +31 -0
  48. package/dist/es2019/output/parse-lint-rule-records.js +41 -0
  49. package/dist/es2019/output/write-human-error.js +14 -0
  50. package/dist/es2019/output/write-human-result.js +25 -0
  51. package/dist/es2019/output/write-json-envelope.js +15 -0
  52. package/dist/es2019/output/writer.js +22 -0
  53. package/dist/es2019/parse-args.js +100 -0
  54. package/dist/es2019/types.js +47 -0
  55. package/dist/esm/cli.js +484 -0
  56. package/dist/esm/commands/definitions.js +708 -0
  57. package/dist/esm/commands/get-command.js +13 -0
  58. package/dist/esm/commands/import-tool-handler.js +42 -0
  59. package/dist/esm/commands/run-tool.js +99 -0
  60. package/dist/esm/commands/types.js +0 -0
  61. package/dist/esm/envelope/create-error-envelope.js +21 -0
  62. package/dist/esm/envelope/create-success-envelope.js +31 -0
  63. package/dist/esm/envelope/types.js +0 -0
  64. package/dist/esm/output/disambiguation.js +24 -0
  65. package/dist/esm/output/format-component.js +92 -0
  66. package/dist/esm/output/format-disambiguation.js +22 -0
  67. package/dist/esm/output/format-doc-object.js +108 -0
  68. package/dist/esm/output/format-grouped-results.js +50 -0
  69. package/dist/esm/output/format-icon.js +42 -0
  70. package/dist/esm/output/format-lint-rules.js +46 -0
  71. package/dist/esm/output/format-results.js +151 -0
  72. package/dist/esm/output/format-token.js +32 -0
  73. package/dist/esm/output/parse-lint-rule-records.js +41 -0
  74. package/dist/esm/output/write-human-error.js +13 -0
  75. package/dist/esm/output/write-human-result.js +24 -0
  76. package/dist/esm/output/write-json-envelope.js +14 -0
  77. package/dist/esm/output/writer.js +26 -0
  78. package/dist/esm/parse-args.js +100 -0
  79. package/dist/esm/types.js +47 -0
  80. package/dist/types/cli.d.ts +20 -0
  81. package/dist/types/commands/definitions.d.ts +19 -0
  82. package/dist/types/commands/get-command.d.ts +8 -0
  83. package/dist/types/commands/import-tool-handler.d.ts +14 -0
  84. package/dist/types/commands/run-tool.d.ts +37 -0
  85. package/dist/types/commands/types.d.ts +149 -0
  86. package/dist/types/envelope/create-error-envelope.d.ts +12 -0
  87. package/dist/types/envelope/create-success-envelope.d.ts +16 -0
  88. package/dist/types/envelope/types.d.ts +60 -0
  89. package/dist/types/output/disambiguation.d.ts +50 -0
  90. package/dist/types/output/format-component.d.ts +12 -0
  91. package/dist/types/output/format-disambiguation.d.ts +11 -0
  92. package/dist/types/output/format-doc-object.d.ts +15 -0
  93. package/dist/types/output/format-grouped-results.d.ts +14 -0
  94. package/dist/types/output/format-icon.d.ts +13 -0
  95. package/dist/types/output/format-lint-rules.d.ts +14 -0
  96. package/dist/types/output/format-results.d.ts +24 -0
  97. package/dist/types/output/format-token.d.ts +12 -0
  98. package/dist/types/output/parse-lint-rule-records.d.ts +26 -0
  99. package/dist/types/output/write-human-error.d.ts +11 -0
  100. package/dist/types/output/write-human-result.d.ts +14 -0
  101. package/dist/types/output/write-json-envelope.d.ts +14 -0
  102. package/dist/types/output/writer.d.ts +25 -0
  103. package/dist/types/parse-args.d.ts +29 -0
  104. package/dist/types/types.d.ts +53 -0
  105. package/index.js +31 -0
  106. 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
+ };