@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,151 @@
|
|
|
1
|
+
import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
|
|
2
|
+
/**
|
|
3
|
+
* Compact, human-readable renderers for the structured search/list results.
|
|
4
|
+
*
|
|
5
|
+
* The underlying ADS MCP tools return rich JSON arrays. Dumping that raw is unreadable at a
|
|
6
|
+
* terminal, so the default (non-`--json`) output renders a compact one line per result. Full
|
|
7
|
+
* structured data remains available via `--json`.
|
|
8
|
+
*
|
|
9
|
+
* Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
|
|
10
|
+
* left to the caller's generic fallback.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
|
|
15
|
+
* Only the fields the compact view needs are modelled; others are ignored.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* A token result as returned by `searchTokensTool` / `getAllTokensTool`.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* An icon result as returned by `searchIconsTool` / `getAllIconsTool`.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Count helper that is safe against non-array / missing fields.
|
|
28
|
+
*/
|
|
29
|
+
var countOf = function countOf(value) {
|
|
30
|
+
return Array.isArray(value) ? value.length : 0;
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Pluralise a `count`-prefixed noun, e.g. `1 prop` / `2 props`.
|
|
35
|
+
*/
|
|
36
|
+
var pluralize = function pluralize(count, noun) {
|
|
37
|
+
return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Truncate a one-line description so compact rows stay on a single line.
|
|
42
|
+
*/
|
|
43
|
+
var truncate = function truncate(text) {
|
|
44
|
+
var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 80;
|
|
45
|
+
return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
|
|
50
|
+
*
|
|
51
|
+
* Only used in unified `search`, where a row is one of many mixed results and the natural next
|
|
52
|
+
* step is to view that one in full. Single-kind listings (`--all`, `--type`) omit it — you asked
|
|
53
|
+
* for the whole list, so echoing each row's own name back would just be noise.
|
|
54
|
+
*/
|
|
55
|
+
var withFollowUp = function withFollowUp(_ref) {
|
|
56
|
+
var line = _ref.line,
|
|
57
|
+
command = _ref.command,
|
|
58
|
+
name = _ref.name,
|
|
59
|
+
showFollowUp = _ref.showFollowUp;
|
|
60
|
+
return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(command, " ").concat(name) : line;
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Render one component as a compact line.
|
|
65
|
+
*
|
|
66
|
+
* No `[kind]` tag is added: every caller renders a single kind at a time — a single-kind command
|
|
67
|
+
* (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
|
|
68
|
+
* context and a tag would just be noise.
|
|
69
|
+
*/
|
|
70
|
+
var formatComponentLine = function formatComponentLine(component, showFollowUp) {
|
|
71
|
+
var _component$name;
|
|
72
|
+
var name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
|
|
73
|
+
var pkg = component.package ? " ".concat(component.package) : '';
|
|
74
|
+
var propCount = countOf(component.props);
|
|
75
|
+
var exampleCount = countOf(component.examples);
|
|
76
|
+
var meta = [pluralize(propCount, 'prop'), pluralize(exampleCount, 'example')].join(', ');
|
|
77
|
+
return withFollowUp({
|
|
78
|
+
line: "".concat(name).concat(pkg, " (").concat(meta, ")"),
|
|
79
|
+
command: 'component',
|
|
80
|
+
name: name,
|
|
81
|
+
showFollowUp: showFollowUp
|
|
82
|
+
});
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Render one token as a compact `name = value` line.
|
|
87
|
+
*/
|
|
88
|
+
var formatTokenLine = function formatTokenLine(tokenResult, showFollowUp) {
|
|
89
|
+
var _tokenResult$name;
|
|
90
|
+
var name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
|
|
91
|
+
// Some token values (e.g. motion easing curves) are very long; truncate so each token stays
|
|
92
|
+
// on a single readable line. The full value is always available via `--json`.
|
|
93
|
+
var line = tokenResult.exampleValue ? "".concat(name, " = ").concat(truncate(tokenResult.exampleValue)) : name;
|
|
94
|
+
return withFollowUp({
|
|
95
|
+
line: line,
|
|
96
|
+
command: 'token',
|
|
97
|
+
name: name,
|
|
98
|
+
showFollowUp: showFollowUp
|
|
99
|
+
});
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Render one icon as a compact line with its import package and short usage note.
|
|
104
|
+
*/
|
|
105
|
+
var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
|
|
106
|
+
var _iconResult$component;
|
|
107
|
+
var name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
|
|
108
|
+
var pkg = iconResult.package ? " ".concat(iconResult.package) : '';
|
|
109
|
+
var usage = iconResult.usage ? " \u2014 ".concat(truncate(iconResult.usage)) : '';
|
|
110
|
+
return withFollowUp({
|
|
111
|
+
line: "".concat(name).concat(pkg).concat(usage),
|
|
112
|
+
command: 'icon',
|
|
113
|
+
name: name,
|
|
114
|
+
showFollowUp: showFollowUp
|
|
115
|
+
});
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Render an array of results as compact lines for the given kind. Returns `null` when the data
|
|
120
|
+
* is not an array (so the caller can fall back to generic JSON rendering).
|
|
121
|
+
*
|
|
122
|
+
* `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
|
|
123
|
+
* row. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
|
|
124
|
+
* off so the output stays terse.
|
|
125
|
+
*/
|
|
126
|
+
export var formatCompactResults = function formatCompactResults(_ref2) {
|
|
127
|
+
var kind = _ref2.kind,
|
|
128
|
+
data = _ref2.data,
|
|
129
|
+
_ref2$showFollowUp = _ref2.showFollowUp,
|
|
130
|
+
showFollowUp = _ref2$showFollowUp === void 0 ? false : _ref2$showFollowUp;
|
|
131
|
+
if (!Array.isArray(data)) {
|
|
132
|
+
return null;
|
|
133
|
+
}
|
|
134
|
+
if (data.length === 0) {
|
|
135
|
+
return 'No results.';
|
|
136
|
+
}
|
|
137
|
+
var lines = data.map(function (entry) {
|
|
138
|
+
switch (kind) {
|
|
139
|
+
case 'components':
|
|
140
|
+
return formatComponentLine(entry, showFollowUp);
|
|
141
|
+
case 'tokens':
|
|
142
|
+
return formatTokenLine(entry, showFollowUp);
|
|
143
|
+
case 'icons':
|
|
144
|
+
return formatIconLine(entry, showFollowUp);
|
|
145
|
+
default:
|
|
146
|
+
return JSON.stringify(entry);
|
|
147
|
+
}
|
|
148
|
+
});
|
|
149
|
+
var header = "Results (".concat(data.length, "):");
|
|
150
|
+
return [header, ''].concat(_toConsumableArray(lines)).join('\n');
|
|
151
|
+
};
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import _typeof from "@babel/runtime/helpers/typeof";
|
|
2
|
+
/**
|
|
3
|
+
* Human-readable renderer for a single ADS design token's detail view.
|
|
4
|
+
*
|
|
5
|
+
* The token dataset is intentionally small — each record has only `name` and `exampleValue` —
|
|
6
|
+
* so the detail view adds the actionable `token('…')` usage line on top of those two fields.
|
|
7
|
+
* Full structured data remains available via `--json`.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Render a single token payload as a detail view. Returns `null` when the data is not a
|
|
16
|
+
* recognisable token object, so the caller can fall back to generic rendering.
|
|
17
|
+
*/
|
|
18
|
+
export var formatToken = function formatToken(data) {
|
|
19
|
+
// `token <name>` reuses token search with limit 1, so `data` is a one-element array.
|
|
20
|
+
var token = Array.isArray(data) ? data[0] : data;
|
|
21
|
+
if (!token || _typeof(token) !== 'object' || typeof token.name !== 'string') {
|
|
22
|
+
return null;
|
|
23
|
+
}
|
|
24
|
+
var sections = [token.name, '='.repeat(token.name.length)];
|
|
25
|
+
if (token.exampleValue) {
|
|
26
|
+
sections.push('', "Example value: ".concat(token.exampleValue));
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
// The actionable bit: how to consume the token from `@atlaskit/tokens`.
|
|
30
|
+
sections.push('', 'Usage:', " token('".concat(token.name, "')"));
|
|
31
|
+
return sections.join('\n');
|
|
32
|
+
};
|
|
@@ -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
|
+
var parseIfJsonString = function parseIfJsonString(value) {
|
|
21
|
+
if (typeof value === 'string' && /^\s*[[{]/.test(value)) {
|
|
22
|
+
try {
|
|
23
|
+
return JSON.parse(value);
|
|
24
|
+
} catch (_unused) {
|
|
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 var parseLintRuleRecords = function parseLintRuleRecords(data) {
|
|
39
|
+
var normalised = parseIfJsonString(data);
|
|
40
|
+
return Array.isArray(normalised) ? normalised.map(parseIfJsonString) : [normalised];
|
|
41
|
+
};
|
|
@@ -0,0 +1,13 @@
|
|
|
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 var writeHumanError = function writeHumanError(_ref) {
|
|
10
|
+
var message = _ref.message,
|
|
11
|
+
writer = _ref.writer;
|
|
12
|
+
writer.err(chalk.red("Error: ".concat(message)));
|
|
13
|
+
};
|
|
@@ -0,0 +1,24 @@
|
|
|
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 var writeHumanResult = function writeHumanResult(_ref) {
|
|
13
|
+
var data = _ref.data,
|
|
14
|
+
writer = _ref.writer;
|
|
15
|
+
if (typeof data === 'string') {
|
|
16
|
+
writer.out(data);
|
|
17
|
+
return;
|
|
18
|
+
}
|
|
19
|
+
if (data === null || data === undefined) {
|
|
20
|
+
writer.err(chalk.yellow('No results.'));
|
|
21
|
+
return;
|
|
22
|
+
}
|
|
23
|
+
writer.out(JSON.stringify(data, null, 2));
|
|
24
|
+
};
|
|
@@ -0,0 +1,14 @@
|
|
|
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 var writeJsonEnvelope = function writeJsonEnvelope(_ref) {
|
|
11
|
+
var envelope = _ref.envelope,
|
|
12
|
+
writer = _ref.writer;
|
|
13
|
+
writer.out(JSON.stringify(envelope, null, 2));
|
|
14
|
+
};
|
|
@@ -0,0 +1,26 @@
|
|
|
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 var defaultWriter = {
|
|
18
|
+
// eslint-disable-next-line no-console
|
|
19
|
+
out: function out(line) {
|
|
20
|
+
return console.log(line);
|
|
21
|
+
},
|
|
22
|
+
// eslint-disable-next-line no-console
|
|
23
|
+
err: function err(line) {
|
|
24
|
+
return console.error(line);
|
|
25
|
+
}
|
|
26
|
+
};
|
|
@@ -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
|
+
var VALUE_FLAGS = new Set(['limit', 'type']);
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Boolean flags that take no value.
|
|
19
|
+
*/
|
|
20
|
+
var BOOLEAN_FLAGS = new Set(['json', 'help', 'version', 'all']);
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Short alias -> canonical flag name.
|
|
24
|
+
*/
|
|
25
|
+
var 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
|
+
var toFlagName = function toFlagName(token) {
|
|
36
|
+
if (token.startsWith('--')) {
|
|
37
|
+
return token.slice(2);
|
|
38
|
+
}
|
|
39
|
+
if (token.startsWith('-') && token.length > 1) {
|
|
40
|
+
var _ALIASES$alias;
|
|
41
|
+
var 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 var parseArgs = function parseArgs(argv) {
|
|
52
|
+
var flags = {};
|
|
53
|
+
var positionals = [];
|
|
54
|
+
var command;
|
|
55
|
+
for (var index = 0; index < argv.length; index++) {
|
|
56
|
+
var token = argv[index];
|
|
57
|
+
var 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
|
+
var equalsIndex = flagName.indexOf('=');
|
|
70
|
+
if (equalsIndex !== -1) {
|
|
71
|
+
var 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
|
+
var 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: command,
|
|
97
|
+
positionals: positionals,
|
|
98
|
+
flags: 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 var 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
|
+
};
|
|
@@ -0,0 +1,20 @@
|
|
|
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
|
+
import { type Writer } from './output/writer';
|
|
12
|
+
import { type ExitCodeValue } from './types';
|
|
13
|
+
/**
|
|
14
|
+
* Parse and execute a single CLI invocation.
|
|
15
|
+
*
|
|
16
|
+
* @param argv - Arguments after `node <script>` (i.e. `process.argv.slice(2)`).
|
|
17
|
+
* @param writer - Injectable output sink; defaults to console-backed stdout/stderr.
|
|
18
|
+
* @returns The process exit code. The bin wrapper maps this onto `process.exit`.
|
|
19
|
+
*/
|
|
20
|
+
export declare const run: (argv?: string[], writer?: Writer) => Promise<ExitCodeValue>;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
3
|
+
*
|
|
4
|
+
* Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
|
|
5
|
+
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
6
|
+
* to drift apart. Each entry declares:
|
|
7
|
+
*
|
|
8
|
+
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
9
|
+
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
10
|
+
* - the metadata (description, flags, examples) surfaced by `--help`.
|
|
11
|
+
*
|
|
12
|
+
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
13
|
+
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
14
|
+
*/
|
|
15
|
+
import type { CommandDefinition } from './types';
|
|
16
|
+
/**
|
|
17
|
+
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
18
|
+
*/
|
|
19
|
+
export declare const commands: CommandDefinition[];
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Look up a command definition by name.
|
|
3
|
+
*/
|
|
4
|
+
import type { CommandDefinition } from './types';
|
|
5
|
+
/**
|
|
6
|
+
* Look up a command definition by name. Returns `undefined` for unknown commands.
|
|
7
|
+
*/
|
|
8
|
+
export declare const getCommand: (name: string) => CommandDefinition | undefined;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Dynamic-import indirection used to load an ADS MCP tool handler by subpath.
|
|
3
|
+
*/
|
|
4
|
+
import type { ToolHandler } from '../types';
|
|
5
|
+
/**
|
|
6
|
+
* Load an ADS MCP tool handler by subpath.
|
|
7
|
+
*
|
|
8
|
+
* Exposed as a single function so tests can mock it and assert which tool a command
|
|
9
|
+
* dispatched to, and so the dynamic `import()` lives in exactly one place.
|
|
10
|
+
*/
|
|
11
|
+
export declare const importToolHandler: ({ importPath, handlerName, }: {
|
|
12
|
+
importPath: string;
|
|
13
|
+
handlerName: string;
|
|
14
|
+
}) => Promise<ToolHandler>;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generic runner that invokes a single `@atlaskit/ads-mcp/tools/*` handler and unwraps its
|
|
3
|
+
* MCP-shaped result into plain data.
|
|
4
|
+
*
|
|
5
|
+
* This is the one place the CLI actually talks to the shared ADS query logic. Keeping the
|
|
6
|
+
* dispatch here (rather than reimplementing search/ranking) is what guarantees zero drift
|
|
7
|
+
* between the MCP server, the ADS skill scripts, and this CLI.
|
|
8
|
+
*/
|
|
9
|
+
import type { ToolResult } from '../types';
|
|
10
|
+
/**
|
|
11
|
+
* Result of unwrapping an ADS MCP tool response.
|
|
12
|
+
*/
|
|
13
|
+
export type UnwrappedToolResult = {
|
|
14
|
+
/**
|
|
15
|
+
* The parsed data. When the tool returned a JSON string it is parsed; when it returned
|
|
16
|
+
* one or more plain-text blocks they are returned as a joined string (or array of
|
|
17
|
+
* strings for multi-block responses such as `get-all-*`).
|
|
18
|
+
*/
|
|
19
|
+
data: unknown;
|
|
20
|
+
/**
|
|
21
|
+
* True when the underlying tool signalled an error, either via `isError` or by returning
|
|
22
|
+
* a single text block that begins with `Error:` (the convention used by the ADS search
|
|
23
|
+
* tools when nothing matches).
|
|
24
|
+
*/
|
|
25
|
+
isError: boolean;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Invoke an ADS MCP tool handler and unwrap its result into plain data.
|
|
29
|
+
*
|
|
30
|
+
* @param handler - The tool function (e.g. `searchComponentsTool`).
|
|
31
|
+
* @param args - The arguments object matching the tool's zod input schema, or `undefined`
|
|
32
|
+
* for zero-argument tools such as `getAllComponentsTool`.
|
|
33
|
+
*/
|
|
34
|
+
export declare const runTool: ({ handler, args, }: {
|
|
35
|
+
handler: (args?: unknown) => Promise<ToolResult>;
|
|
36
|
+
args?: unknown;
|
|
37
|
+
}) => Promise<UnwrappedToolResult>;
|