@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,31 @@
1
+ /**
2
+ * Human-readable renderer for a single ADS design token's detail view.
3
+ *
4
+ * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
5
+ * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
6
+ * Full structured data remains available via `--json`.
7
+ */
8
+
9
+ /**
10
+ * A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
11
+ */
12
+
13
+ /**
14
+ * Render a single token payload as a detail view. Returns `null` when the data is not a
15
+ * recognisable token object, so the caller can fall back to generic rendering.
16
+ */
17
+ export const formatToken = data => {
18
+ // `token <name>` reuses token search with limit 1, so `data` is a one-element array.
19
+ const token = Array.isArray(data) ? data[0] : data;
20
+ if (!token || typeof token !== 'object' || typeof token.name !== 'string') {
21
+ return null;
22
+ }
23
+ const sections = [token.name, '='.repeat(token.name.length)];
24
+ if (token.exampleValue) {
25
+ sections.push('', `Example value: ${token.exampleValue}`);
26
+ }
27
+
28
+ // The actionable bit: how to consume the token from `@atlaskit/tokens`.
29
+ sections.push('', 'Usage:', ` token('${token.name}')`);
30
+ return sections.join('\n');
31
+ };
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Shared parser for the `get-lint-rules` payload.
3
+ *
4
+ * `getLintRulesTool` double-encodes its rule records: each is a JSON *string literal* (a bare
5
+ * string for a single match, or an array of such strings for multiple matches), so the generic
6
+ * unwrap yields a value that still looks like JSON. This module undoes that second layer so both
7
+ * the human renderer (`format-lint-rules`) and the `lint-rules` command's disambiguation logic
8
+ * work against real rule objects rather than raw strings.
9
+ */
10
+
11
+ /**
12
+ * A single lint-rule record as returned by `getLintRulesTool`. Only the fields the CLI needs are
13
+ * modelled.
14
+ */
15
+
16
+ /**
17
+ * Parse a value that may be a JSON string literal into its underlying object/array, leaving
18
+ * non-JSON strings (and non-strings) untouched.
19
+ */
20
+ const parseIfJsonString = value => {
21
+ if (typeof value === 'string' && /^\s*[[{]/.test(value)) {
22
+ try {
23
+ return JSON.parse(value);
24
+ } catch {
25
+ // Leave as-is; callers guard the resulting shape.
26
+ }
27
+ }
28
+ return value;
29
+ };
30
+
31
+ /**
32
+ * Parse the get-lint-rules payload into rule records, undoing the double-encoded JSON layer.
33
+ *
34
+ * For a single match `data` is one JSON string literal; for multiple matches it is an array whose
35
+ * elements are each a JSON string literal — so parse both the top-level value and every array
36
+ * element. Elements that are not JSON strings are left untouched (callers guard the shape).
37
+ */
38
+ export const parseLintRuleRecords = data => {
39
+ const normalised = parseIfJsonString(data);
40
+ return Array.isArray(normalised) ? normalised.map(parseIfJsonString) : [normalised];
41
+ };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Human-readable rendering of a command error.
3
+ */
4
+
5
+ import chalk from 'chalk';
6
+ /**
7
+ * Emit a human-readable error to stderr.
8
+ */
9
+ export const writeHumanError = ({
10
+ message,
11
+ writer
12
+ }) => {
13
+ writer.err(chalk.red(`Error: ${message}`));
14
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Human-readable rendering of a successful command result.
3
+ */
4
+
5
+ import chalk from 'chalk';
6
+ /**
7
+ * Emit a human-readable rendering of a successful result to stdout.
8
+ *
9
+ * Structured data is pretty-printed as JSON (the underlying tools already return rich
10
+ * objects), while plain-string payloads such as guideline markdown are printed verbatim.
11
+ */
12
+ export const writeHumanResult = ({
13
+ data,
14
+ writer
15
+ }) => {
16
+ if (typeof data === 'string') {
17
+ writer.out(data);
18
+ return;
19
+ }
20
+ if (data === null || data === undefined) {
21
+ writer.err(chalk.yellow('No results.'));
22
+ return;
23
+ }
24
+ writer.out(JSON.stringify(data, null, 2));
25
+ };
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Emit the JSON envelope to stdout.
3
+ */
4
+
5
+ /**
6
+ * Emit the JSON envelope to stdout.
7
+ *
8
+ * Always pretty-printed for readability; consumers that need compact output can re-serialise.
9
+ */
10
+ export const writeJsonEnvelope = ({
11
+ envelope,
12
+ writer
13
+ }) => {
14
+ writer.out(JSON.stringify(envelope, null, 2));
15
+ };
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The output sink abstraction and its default console-backed implementation.
3
+ *
4
+ * Output contract (see README): data goes to stdout ONLY; all logs, hints, and errors go to
5
+ * stderr. Keeping the stdout/stderr split behind this small interface means `--json` output
6
+ * stays clean for piping, and tests can capture output deterministically.
7
+ */
8
+
9
+ /**
10
+ * Thin indirection over the console so tests can capture output and so we keep the
11
+ * stdout/stderr split in exactly one place.
12
+ */
13
+
14
+ /**
15
+ * The default writer, backed by `console.log` (stdout) and `console.error` (stderr).
16
+ */
17
+ export const defaultWriter = {
18
+ // eslint-disable-next-line no-console
19
+ out: line => console.log(line),
20
+ // eslint-disable-next-line no-console
21
+ err: line => console.error(line)
22
+ };
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Lightweight, dependency-free argument parser for the ADS CLI.
3
+ *
4
+ * We hand-roll parsing (rather than pulling in an argument-parsing library) so that `run(argv)`
5
+ * is deterministic and unit-testable with an explicit argv array, and so the exact flag semantics
6
+ * (value flags vs boolean flags, `--flag=value`, short aliases) stay under our control.
7
+ *
8
+ * The parser produces a normalised {@link ParsedArgs} that the CLI then routes through the
9
+ * command registry.
10
+ */
11
+
12
+ /**
13
+ * Flags that take a single value (the next token).
14
+ */
15
+ const VALUE_FLAGS = new Set(['limit', 'type']);
16
+
17
+ /**
18
+ * Boolean flags that take no value.
19
+ */
20
+ const BOOLEAN_FLAGS = new Set(['json', 'help', 'version', 'all']);
21
+
22
+ /**
23
+ * Short alias -> canonical flag name.
24
+ */
25
+ const ALIASES = {
26
+ h: 'help',
27
+ v: 'version',
28
+ l: 'limit',
29
+ t: 'type'
30
+ };
31
+ /**
32
+ * Normalise a raw token like `--limit`, `-l`, or `--json` to its canonical flag name,
33
+ * or `null` if the token is not a flag.
34
+ */
35
+ const toFlagName = token => {
36
+ if (token.startsWith('--')) {
37
+ return token.slice(2);
38
+ }
39
+ if (token.startsWith('-') && token.length > 1) {
40
+ var _ALIASES$alias;
41
+ const alias = token.slice(1);
42
+ return (_ALIASES$alias = ALIASES[alias]) !== null && _ALIASES$alias !== void 0 ? _ALIASES$alias : alias;
43
+ }
44
+ return null;
45
+ };
46
+
47
+ /**
48
+ * Parse an argv array (already stripped of `node` and the script path) into a normalised
49
+ * command + positionals + flags structure.
50
+ */
51
+ export const parseArgs = argv => {
52
+ const flags = {};
53
+ const positionals = [];
54
+ let command;
55
+ for (let index = 0; index < argv.length; index++) {
56
+ const token = argv[index];
57
+ const flagName = toFlagName(token);
58
+ if (flagName === null) {
59
+ // Positional. The very first positional is the command name.
60
+ if (command === undefined) {
61
+ command = token;
62
+ } else {
63
+ positionals.push(token);
64
+ }
65
+ continue;
66
+ }
67
+
68
+ // Support `--flag=value` form.
69
+ const equalsIndex = flagName.indexOf('=');
70
+ if (equalsIndex !== -1) {
71
+ const name = flagName.slice(0, equalsIndex);
72
+ flags[name] = flagName.slice(equalsIndex + 1);
73
+ continue;
74
+ }
75
+ if (BOOLEAN_FLAGS.has(flagName)) {
76
+ flags[flagName] = true;
77
+ continue;
78
+ }
79
+ if (VALUE_FLAGS.has(flagName)) {
80
+ const next = argv[index + 1];
81
+ if (next !== undefined && toFlagName(next) === null) {
82
+ flags[flagName] = next;
83
+ index++;
84
+ } else {
85
+ // Flag present with no value; record empty string so the command can report a
86
+ // usage error rather than silently ignoring it.
87
+ flags[flagName] = '';
88
+ }
89
+ continue;
90
+ }
91
+
92
+ // Unknown flag: record as a boolean so downstream validation can surface it.
93
+ flags[flagName] = true;
94
+ }
95
+ return {
96
+ command,
97
+ positionals,
98
+ flags
99
+ };
100
+ };
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Shared types for the ADS CLI.
3
+ *
4
+ * The CLI is a thin layer over the `@atlaskit/ads-mcp/tools/*` exports. Every underlying
5
+ * tool is an async function that resolves to an MCP-shaped result: `{ content: [...] }`
6
+ * where each content item is a `{ type: 'text', text: string }` block. These types model
7
+ * that contract plus the CLI's own command registry and JSON output envelope.
8
+ */
9
+
10
+ /**
11
+ * A single content block returned by an ADS MCP tool. Only the `text` variant is used by
12
+ * the tools this CLI wraps, but we keep the `type` field so the shape stays faithful to
13
+ * the MCP `CallToolResult` contract.
14
+ */
15
+
16
+ /**
17
+ * The MCP-shaped result returned by every `@atlaskit/ads-mcp/tools/*` handler.
18
+ */
19
+
20
+ /**
21
+ * Any ADS MCP tool handler: takes an optional arguments object and resolves to a
22
+ * {@link ToolResult}. Kept intentionally loose (`unknown` args) because each tool has its
23
+ * own zod input schema; the registry is responsible for building well-formed args.
24
+ */
25
+
26
+ /**
27
+ * Stable, documented process exit codes. Kept as a const enum-like object (not a TS enum)
28
+ * so the values are inlined and easy to assert against in tests.
29
+ */
30
+ export const ExitCode = {
31
+ /**
32
+ * Command completed successfully.
33
+ */
34
+ Ok: 0,
35
+ /**
36
+ * An unexpected runtime error occurred while executing a command.
37
+ */
38
+ RuntimeError: 1,
39
+ /**
40
+ * The user supplied invalid arguments or an unknown command.
41
+ */
42
+ UsageError: 2,
43
+ /**
44
+ * The command ran successfully but found no matching results.
45
+ */
46
+ NotFound: 3
47
+ };