@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,52 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.formatLintRules = void 0;
8
+ var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
9
+ var _parseLintRuleRecords = require("./parse-lint-rule-records");
10
+ /**
11
+ * Human-readable renderer for the `lint-rules` payload.
12
+ *
13
+ * `getLintRulesTool` returns one record per matching ESLint rule, each with a `content` field
14
+ * that is already Markdown documentation for the rule. The default output prints that Markdown
15
+ * verbatim (joined across multiple rules) rather than dumping the raw JSON. Full structured data
16
+ * remains available via `--json`.
17
+ */
18
+
19
+ /**
20
+ * True when a value looks like a lint-rule record (an object carrying at least one known field).
21
+ */
22
+ var isLintRuleRecord = function isLintRuleRecord(rule) {
23
+ return rule !== null && (0, _typeof2.default)(rule) === 'object' && ('content' in rule || 'ruleName' in rule || 'description' in rule);
24
+ };
25
+
26
+ /**
27
+ * Render a single rule: prefer its Markdown `content`; fall back to `ruleName` + `description`
28
+ * when no content is present.
29
+ */
30
+ var formatRule = function formatRule(rule) {
31
+ var _rule$ruleName;
32
+ if (typeof rule.content === 'string' && rule.content.trim()) {
33
+ return rule.content.trim();
34
+ }
35
+ var name = (_rule$ruleName = rule.ruleName) !== null && _rule$ruleName !== void 0 ? _rule$ruleName : '(unknown rule)';
36
+ return rule.description ? "# ".concat(name, "\n\n").concat(rule.description) : "# ".concat(name);
37
+ };
38
+
39
+ /**
40
+ * Render the lint-rules payload as readable Markdown. Handles both the array form (multiple
41
+ * matching rules) and the single-object form. Returns `null` for unrecognised shapes so the
42
+ * caller can fall back to generic rendering.
43
+ */
44
+ var formatLintRules = exports.formatLintRules = function formatLintRules(data) {
45
+ var rules = (0, _parseLintRuleRecords.parseLintRuleRecords)(data);
46
+ if (rules.length === 0 || !rules.every(isLintRuleRecord)) {
47
+ return null;
48
+ }
49
+
50
+ // Separate multiple rules with a horizontal rule so they read as distinct docs.
51
+ return rules.map(formatRule).join('\n\n---\n\n');
52
+ };
@@ -0,0 +1,158 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.formatCompactResults = void 0;
8
+ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
9
+ /**
10
+ * Compact, human-readable renderers for the structured search/list results.
11
+ *
12
+ * The underlying ADS MCP tools return rich JSON arrays. Dumping that raw is unreadable at a
13
+ * terminal, so the default (non-`--json`) output renders a compact one line per result. Full
14
+ * structured data remains available via `--json`.
15
+ *
16
+ * Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
17
+ * left to the caller's generic fallback.
18
+ */
19
+
20
+ /**
21
+ * A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
22
+ * Only the fields the compact view needs are modelled; others are ignored.
23
+ */
24
+
25
+ /**
26
+ * A token result as returned by `searchTokensTool` / `getAllTokensTool`.
27
+ */
28
+
29
+ /**
30
+ * An icon result as returned by `searchIconsTool` / `getAllIconsTool`.
31
+ */
32
+
33
+ /**
34
+ * Count helper that is safe against non-array / missing fields.
35
+ */
36
+ var countOf = function countOf(value) {
37
+ return Array.isArray(value) ? value.length : 0;
38
+ };
39
+
40
+ /**
41
+ * Pluralise a `count`-prefixed noun, e.g. `1 prop` / `2 props`.
42
+ */
43
+ var pluralize = function pluralize(count, noun) {
44
+ return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
45
+ };
46
+
47
+ /**
48
+ * Truncate a one-line description so compact rows stay on a single line.
49
+ */
50
+ var truncate = function truncate(text) {
51
+ var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 80;
52
+ return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
53
+ };
54
+
55
+ /**
56
+ * Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
57
+ *
58
+ * Only used in unified `search`, where a row is one of many mixed results and the natural next
59
+ * step is to view that one in full. Single-kind listings (`--all`, `--type`) omit it — you asked
60
+ * for the whole list, so echoing each row's own name back would just be noise.
61
+ */
62
+ var withFollowUp = function withFollowUp(_ref) {
63
+ var line = _ref.line,
64
+ command = _ref.command,
65
+ name = _ref.name,
66
+ showFollowUp = _ref.showFollowUp;
67
+ return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(command, " ").concat(name) : line;
68
+ };
69
+
70
+ /**
71
+ * Render one component as a compact line.
72
+ *
73
+ * No `[kind]` tag is added: every caller renders a single kind at a time — a single-kind command
74
+ * (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
75
+ * context and a tag would just be noise.
76
+ */
77
+ var formatComponentLine = function formatComponentLine(component, showFollowUp) {
78
+ var _component$name;
79
+ var name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
80
+ var pkg = component.package ? " ".concat(component.package) : '';
81
+ var propCount = countOf(component.props);
82
+ var exampleCount = countOf(component.examples);
83
+ var meta = [pluralize(propCount, 'prop'), pluralize(exampleCount, 'example')].join(', ');
84
+ return withFollowUp({
85
+ line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
86
+ command: 'component',
87
+ name: name,
88
+ showFollowUp: showFollowUp
89
+ });
90
+ };
91
+
92
+ /**
93
+ * Render one token as a compact `name = value` line.
94
+ */
95
+ var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp) {
96
+ var _tokenResult$name;
97
+ var name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
98
+ // Some token values (e.g. motion easing curves) are very long; truncate so each token stays
99
+ // on a single readable line. The full value is always available via `--json`.
100
+ var line = tokenResult.exampleValue ? "".concat(name, " = ").concat(truncate(tokenResult.exampleValue)) : name;
101
+ return withFollowUp({
102
+ line: line,
103
+ command: 'token',
104
+ name: name,
105
+ showFollowUp: showFollowUp
106
+ });
107
+ };
108
+
109
+ /**
110
+ * Render one icon as a compact line with its import package and short usage note.
111
+ */
112
+ var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
113
+ var _iconResult$component;
114
+ var name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
115
+ var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
116
+ var usage = iconResult.usage ? " \u2014 ".concat(truncate(iconResult.usage)) : '';
117
+ return withFollowUp({
118
+ line: "".concat(name).concat(pkg).concat(usage),
119
+ command: 'icon',
120
+ name: name,
121
+ showFollowUp: showFollowUp
122
+ });
123
+ };
124
+
125
+ /**
126
+ * Render an array of results as compact lines for the given kind. Returns `null` when the data
127
+ * is not an array (so the caller can fall back to generic JSON rendering).
128
+ *
129
+ * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
130
+ * row. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
131
+ * off so the output stays terse.
132
+ */
133
+ var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref2) {
134
+ var kind = _ref2.kind,
135
+ data = _ref2.data,
136
+ _ref2$showFollowUp = _ref2.showFollowUp,
137
+ showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp;
138
+ if (!Array.isArray(data)) {
139
+ return null;
140
+ }
141
+ if (data.length === 0) {
142
+ return 'No results.';
143
+ }
144
+ var lines = data.map(function (entry) {
145
+ switch (kind) {
146
+ case 'components':
147
+ return formatComponentLine(entry, showFollowUp);
148
+ case 'tokens':
149
+ return formatTokenLine(entry, showFollowUp);
150
+ case 'icons':
151
+ return formatIconLine(entry, showFollowUp);
152
+ default:
153
+ return JSON.stringify(entry);
154
+ }
155
+ });
156
+ var header = "Results (".concat(data.length, "):");
157
+ return [header, ''].concat((0, _toConsumableArray2.default)(lines)).join('\n');
158
+ };
@@ -0,0 +1,39 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.formatToken = void 0;
8
+ var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
9
+ /**
10
+ * Human-readable renderer for a single ADS design token's detail view.
11
+ *
12
+ * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
13
+ * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
14
+ * Full structured data remains available via `--json`.
15
+ */
16
+
17
+ /**
18
+ * A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
19
+ */
20
+
21
+ /**
22
+ * Render a single token payload as a detail view. Returns `null` when the data is not a
23
+ * recognisable token object, so the caller can fall back to generic rendering.
24
+ */
25
+ var formatToken = exports.formatToken = function formatToken(data) {
26
+ // `token <name>` reuses token search with limit 1, so `data` is a one-element array.
27
+ var token = Array.isArray(data) ? data[0] : data;
28
+ if (!token || (0, _typeof2.default)(token) !== 'object' || typeof token.name !== 'string') {
29
+ return null;
30
+ }
31
+ var sections = [token.name, '='.repeat(token.name.length)];
32
+ if (token.exampleValue) {
33
+ sections.push('', "Example value: ".concat(token.exampleValue));
34
+ }
35
+
36
+ // The actionable bit: how to consume the token from `@atlaskit/tokens`.
37
+ sections.push('', 'Usage:', " token('".concat(token.name, "')"));
38
+ return sections.join('\n');
39
+ };
@@ -0,0 +1,47 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.parseLintRuleRecords = void 0;
7
+ /**
8
+ * Shared parser for the `get-lint-rules` payload.
9
+ *
10
+ * `getLintRulesTool` double-encodes its rule records: each is a JSON *string literal* (a bare
11
+ * string for a single match, or an array of such strings for multiple matches), so the generic
12
+ * unwrap yields a value that still looks like JSON. This module undoes that second layer so both
13
+ * the human renderer (`format-lint-rules`) and the `lint-rules` command's disambiguation logic
14
+ * work against real rule objects rather than raw strings.
15
+ */
16
+
17
+ /**
18
+ * A single lint-rule record as returned by `getLintRulesTool`. Only the fields the CLI needs are
19
+ * modelled.
20
+ */
21
+
22
+ /**
23
+ * Parse a value that may be a JSON string literal into its underlying object/array, leaving
24
+ * non-JSON strings (and non-strings) untouched.
25
+ */
26
+ var parseIfJsonString = function parseIfJsonString(value) {
27
+ if (typeof value === 'string' && /^\s*[[{]/.test(value)) {
28
+ try {
29
+ return JSON.parse(value);
30
+ } catch (_unused) {
31
+ // Leave as-is; callers guard the resulting shape.
32
+ }
33
+ }
34
+ return value;
35
+ };
36
+
37
+ /**
38
+ * Parse the get-lint-rules payload into rule records, undoing the double-encoded JSON layer.
39
+ *
40
+ * For a single match `data` is one JSON string literal; for multiple matches it is an array whose
41
+ * elements are each a JSON string literal — so parse both the top-level value and every array
42
+ * element. Elements that are not JSON strings are left untouched (callers guard the shape).
43
+ */
44
+ var parseLintRuleRecords = exports.parseLintRuleRecords = function parseLintRuleRecords(data) {
45
+ var normalised = parseIfJsonString(data);
46
+ return Array.isArray(normalised) ? normalised.map(parseIfJsonString) : [normalised];
47
+ };
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.writeHumanError = void 0;
8
+ var _chalk = _interopRequireDefault(require("chalk"));
9
+ /**
10
+ * Human-readable rendering of a command error.
11
+ */
12
+
13
+ /**
14
+ * Emit a human-readable error to stderr.
15
+ */
16
+ var writeHumanError = exports.writeHumanError = function writeHumanError(_ref) {
17
+ var message = _ref.message,
18
+ writer = _ref.writer;
19
+ writer.err(_chalk.default.red("Error: ".concat(message)));
20
+ };
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.writeHumanResult = void 0;
8
+ var _chalk = _interopRequireDefault(require("chalk"));
9
+ /**
10
+ * Human-readable rendering of a successful command result.
11
+ */
12
+
13
+ /**
14
+ * Emit a human-readable rendering of a successful result to stdout.
15
+ *
16
+ * Structured data is pretty-printed as JSON (the underlying tools already return rich
17
+ * objects), while plain-string payloads such as guideline markdown are printed verbatim.
18
+ */
19
+ var writeHumanResult = exports.writeHumanResult = function writeHumanResult(_ref) {
20
+ var data = _ref.data,
21
+ writer = _ref.writer;
22
+ if (typeof data === 'string') {
23
+ writer.out(data);
24
+ return;
25
+ }
26
+ if (data === null || data === undefined) {
27
+ writer.err(_chalk.default.yellow('No results.'));
28
+ return;
29
+ }
30
+ writer.out(JSON.stringify(data, null, 2));
31
+ };
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.writeJsonEnvelope = void 0;
7
+ /**
8
+ * Emit the JSON envelope to stdout.
9
+ */
10
+
11
+ /**
12
+ * Emit the JSON envelope to stdout.
13
+ *
14
+ * Always pretty-printed for readability; consumers that need compact output can re-serialise.
15
+ */
16
+ var writeJsonEnvelope = exports.writeJsonEnvelope = function writeJsonEnvelope(_ref) {
17
+ var envelope = _ref.envelope,
18
+ writer = _ref.writer;
19
+ writer.out(JSON.stringify(envelope, null, 2));
20
+ };
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.defaultWriter = void 0;
7
+ /**
8
+ * The output sink abstraction and its default console-backed implementation.
9
+ *
10
+ * Output contract (see README): data goes to stdout ONLY; all logs, hints, and errors go to
11
+ * stderr. Keeping the stdout/stderr split behind this small interface means `--json` output
12
+ * stays clean for piping, and tests can capture output deterministically.
13
+ */
14
+
15
+ /**
16
+ * Thin indirection over the console so tests can capture output and so we keep the
17
+ * stdout/stderr split in exactly one place.
18
+ */
19
+
20
+ /**
21
+ * The default writer, backed by `console.log` (stdout) and `console.error` (stderr).
22
+ */
23
+ var defaultWriter = exports.defaultWriter = {
24
+ // eslint-disable-next-line no-console
25
+ out: function out(line) {
26
+ return console.log(line);
27
+ },
28
+ // eslint-disable-next-line no-console
29
+ err: function err(line) {
30
+ return console.error(line);
31
+ }
32
+ };
@@ -0,0 +1,106 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.parseArgs = void 0;
7
+ /**
8
+ * Lightweight, dependency-free argument parser for the ADS CLI.
9
+ *
10
+ * We hand-roll parsing (rather than pulling in an argument-parsing library) so that `run(argv)`
11
+ * is deterministic and unit-testable with an explicit argv array, and so the exact flag semantics
12
+ * (value flags vs boolean flags, `--flag=value`, short aliases) stay under our control.
13
+ *
14
+ * The parser produces a normalised {@link ParsedArgs} that the CLI then routes through the
15
+ * command registry.
16
+ */
17
+
18
+ /**
19
+ * Flags that take a single value (the next token).
20
+ */
21
+ var VALUE_FLAGS = new Set(['limit', 'type']);
22
+
23
+ /**
24
+ * Boolean flags that take no value.
25
+ */
26
+ var BOOLEAN_FLAGS = new Set(['json', 'help', 'version', 'all']);
27
+
28
+ /**
29
+ * Short alias -> canonical flag name.
30
+ */
31
+ var ALIASES = {
32
+ h: 'help',
33
+ v: 'version',
34
+ l: 'limit',
35
+ t: 'type'
36
+ };
37
+ /**
38
+ * Normalise a raw token like `--limit`, `-l`, or `--json` to its canonical flag name,
39
+ * or `null` if the token is not a flag.
40
+ */
41
+ var toFlagName = function toFlagName(token) {
42
+ if (token.startsWith('--')) {
43
+ return token.slice(2);
44
+ }
45
+ if (token.startsWith('-') && token.length > 1) {
46
+ var _ALIASES$alias;
47
+ var alias = token.slice(1);
48
+ return (_ALIASES$alias = ALIASES[alias]) !== null && _ALIASES$alias !== void 0 ? _ALIASES$alias : alias;
49
+ }
50
+ return null;
51
+ };
52
+
53
+ /**
54
+ * Parse an argv array (already stripped of `node` and the script path) into a normalised
55
+ * command + positionals + flags structure.
56
+ */
57
+ var parseArgs = exports.parseArgs = function parseArgs(argv) {
58
+ var flags = {};
59
+ var positionals = [];
60
+ var command;
61
+ for (var index = 0; index < argv.length; index++) {
62
+ var token = argv[index];
63
+ var flagName = toFlagName(token);
64
+ if (flagName === null) {
65
+ // Positional. The very first positional is the command name.
66
+ if (command === undefined) {
67
+ command = token;
68
+ } else {
69
+ positionals.push(token);
70
+ }
71
+ continue;
72
+ }
73
+
74
+ // Support `--flag=value` form.
75
+ var equalsIndex = flagName.indexOf('=');
76
+ if (equalsIndex !== -1) {
77
+ var name = flagName.slice(0, equalsIndex);
78
+ flags[name] = flagName.slice(equalsIndex + 1);
79
+ continue;
80
+ }
81
+ if (BOOLEAN_FLAGS.has(flagName)) {
82
+ flags[flagName] = true;
83
+ continue;
84
+ }
85
+ if (VALUE_FLAGS.has(flagName)) {
86
+ var next = argv[index + 1];
87
+ if (next !== undefined && toFlagName(next) === null) {
88
+ flags[flagName] = next;
89
+ index++;
90
+ } else {
91
+ // Flag present with no value; record empty string so the command can report a
92
+ // usage error rather than silently ignoring it.
93
+ flags[flagName] = '';
94
+ }
95
+ continue;
96
+ }
97
+
98
+ // Unknown flag: record as a boolean so downstream validation can surface it.
99
+ flags[flagName] = true;
100
+ }
101
+ return {
102
+ command: command,
103
+ positionals: positionals,
104
+ flags: flags
105
+ };
106
+ };
@@ -0,0 +1,53 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.ExitCode = void 0;
7
+ /**
8
+ * Shared types for the ADS CLI.
9
+ *
10
+ * The CLI is a thin layer over the `@atlaskit/ads-mcp/tools/*` exports. Every underlying
11
+ * tool is an async function that resolves to an MCP-shaped result: `{ content: [...] }`
12
+ * where each content item is a `{ type: 'text', text: string }` block. These types model
13
+ * that contract plus the CLI's own command registry and JSON output envelope.
14
+ */
15
+
16
+ /**
17
+ * A single content block returned by an ADS MCP tool. Only the `text` variant is used by
18
+ * the tools this CLI wraps, but we keep the `type` field so the shape stays faithful to
19
+ * the MCP `CallToolResult` contract.
20
+ */
21
+
22
+ /**
23
+ * The MCP-shaped result returned by every `@atlaskit/ads-mcp/tools/*` handler.
24
+ */
25
+
26
+ /**
27
+ * Any ADS MCP tool handler: takes an optional arguments object and resolves to a
28
+ * {@link ToolResult}. Kept intentionally loose (`unknown` args) because each tool has its
29
+ * own zod input schema; the registry is responsible for building well-formed args.
30
+ */
31
+
32
+ /**
33
+ * Stable, documented process exit codes. Kept as a const enum-like object (not a TS enum)
34
+ * so the values are inlined and easy to assert against in tests.
35
+ */
36
+ var ExitCode = exports.ExitCode = {
37
+ /**
38
+ * Command completed successfully.
39
+ */
40
+ Ok: 0,
41
+ /**
42
+ * An unexpected runtime error occurred while executing a command.
43
+ */
44
+ RuntimeError: 1,
45
+ /**
46
+ * The user supplied invalid arguments or an unknown command.
47
+ */
48
+ UsageError: 2,
49
+ /**
50
+ * The command ran successfully but found no matching results.
51
+ */
52
+ NotFound: 3
53
+ };