@atlaskit/ads-cli 0.1.0 → 0.3.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 (39) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +30 -9
  3. package/dist/cjs/cli.js +24 -32
  4. package/dist/cjs/commands/build-manifest.js +48 -0
  5. package/dist/cjs/commands/cli-metadata.js +31 -0
  6. package/dist/cjs/commands/definitions.js +97 -18
  7. package/dist/cjs/commands/get-version.js +24 -0
  8. package/dist/cjs/output/create-doc-search-results.js +55 -0
  9. package/dist/cjs/output/format-grouped-results.js +5 -3
  10. package/dist/cjs/output/format-manifest.js +26 -0
  11. package/dist/cjs/output/format-results.js +14 -5
  12. package/dist/es2019/cli.js +23 -31
  13. package/dist/es2019/commands/build-manifest.js +39 -0
  14. package/dist/es2019/commands/cli-metadata.js +25 -0
  15. package/dist/es2019/commands/definitions.js +86 -15
  16. package/dist/es2019/commands/get-version.js +18 -0
  17. package/dist/es2019/output/create-doc-search-results.js +42 -0
  18. package/dist/es2019/output/format-grouped-results.js +5 -3
  19. package/dist/es2019/output/format-manifest.js +18 -0
  20. package/dist/es2019/output/format-results.js +14 -5
  21. package/dist/esm/cli.js +23 -31
  22. package/dist/esm/commands/build-manifest.js +42 -0
  23. package/dist/esm/commands/cli-metadata.js +25 -0
  24. package/dist/esm/commands/definitions.js +97 -18
  25. package/dist/esm/commands/get-version.js +18 -0
  26. package/dist/esm/output/create-doc-search-results.js +48 -0
  27. package/dist/esm/output/format-grouped-results.js +5 -3
  28. package/dist/esm/output/format-manifest.js +19 -0
  29. package/dist/esm/output/format-results.js +14 -5
  30. package/dist/types/commands/build-manifest.d.ts +26 -0
  31. package/dist/types/commands/cli-metadata.d.ts +8 -0
  32. package/dist/types/commands/definitions.d.ts +4 -3
  33. package/dist/types/commands/get-version.d.ts +7 -0
  34. package/dist/types/commands/types.d.ts +30 -11
  35. package/dist/types/output/create-doc-search-results.d.ts +22 -0
  36. package/dist/types/output/format-grouped-results.d.ts +2 -3
  37. package/dist/types/output/format-manifest.d.ts +4 -0
  38. package/dist/types/output/format-results.d.ts +1 -2
  39. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.3.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`d678f1fec09ca`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/d678f1fec09ca) -
8
+ Include concise, query-labelled foundations docs in unified search results, with leading-text
9
+ previews, docs filtering, and detail commands. For example:
10
+
11
+ ```sh
12
+ npx @atlaskit/ads-cli search contrast --type docs
13
+ ```
14
+
15
+ ## 0.2.0
16
+
17
+ ### Minor Changes
18
+
19
+ - [`f37252516ee5d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f37252516ee5d) -
20
+ Add a `manifest` command for discovering ADS CLI commands in human-readable or JSON format.
21
+
3
22
  ## 0.1.0
4
23
 
5
24
  ### Minor Changes
package/README.md CHANGED
@@ -23,12 +23,13 @@ The CLI has these commands:
23
23
 
24
24
  | Command | Description |
25
25
  | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
- | `search <query...>` | **Unified** fuzzy-search across components, tokens, and icons at once. Narrow with `--type component\|token\|icon`; limit with `--limit N`. |
26
+ | `search <query...>` | **Unified** fuzzy-search across components, tokens, icons, and foundations docs at once. Narrow results with `--type component\|token\|icon\|docs`; limit with `--limit N`. |
27
27
  | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
28
28
  | `token <name>` | Detail for a single token. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token. |
29
29
  | `icon <name>` | Detail for a single icon (with a copy-paste import). Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every icon. |
30
30
  | `lint-rules [term...]` | ADS ESLint rules. A term that matches one rule (exactly or uniquely) prints its docs; several matches show a "did you mean?" list. Bare `lint-rules` prints every rule; `--limit N` caps the candidate list. |
31
31
  | `docs <topic...>` | Read ADS reference docs. Three forms:<br>• `docs <term...>` — foundations guidelines (spacing, color, …)<br>• `docs a11y [topic]` — accessibility guidance (optional topic e.g. `buttons`, `forms`, `colors`)<br>• `docs migration <id>` — a structured migration guide |
32
+ | `manifest` | Describe every command, argument, flag, and JSON response type. Use `--json` for the machine-readable contract. |
32
33
 
33
34
  ### Global flags
34
35
 
@@ -39,11 +40,12 @@ The CLI has these commands:
39
40
  ## Examples
40
41
 
41
42
  ```sh
42
- # Unified human-readable search — components, tokens, and icons grouped together
43
- npx @atlaskit/ads-cli search button
43
+ # Unified human-readable search — components, tokens, icons, and docs grouped together
44
+ npx @atlaskit/ads-cli search contrast
44
45
 
45
46
  # Narrow to a single kind
46
47
  npx @atlaskit/ads-cli search space color --type token
48
+ npx @atlaskit/ads-cli search contrast --type docs
47
49
 
48
50
  # Detail for a single component, token, or icon
49
51
  npx @atlaskit/ads-cli component Avatar
@@ -60,6 +62,9 @@ npx @atlaskit/ads-cli docs migration motion
60
62
 
61
63
  # Machine-readable envelope for agents / jq
62
64
  npx @atlaskit/ads-cli search button --json
65
+
66
+ # Discover the complete CLI contract
67
+ npx @atlaskit/ads-cli manifest --json
63
68
  ```
64
69
 
65
70
  ## Output contract
@@ -67,11 +72,13 @@ npx @atlaskit/ads-cli search button --json
67
72
  - **Every command is human-readable by default; `--json` is the only path to structured output.**
68
73
  `search` and the `--all` listings print one compact line per result (e.g.
69
74
  `Avatar @atlaskit/avatar (42 props, 1 example)`), and unified `search` groups results into
70
- `Components` / `Tokens` / `Icons` sections with a `→ ads-cli component Avatar` follow-up hint per
71
- row. `component`/`token`/`icon` print a readable detail view (the icon view includes a copy-paste
72
- `import` line); `docs` (foundations, `a11y`, and `migration`) and `lint-rules` print
73
- prose/Markdown. A raw JSON dump is only ever a last-resort fallback for an unrecognised shape. For
74
- the **full structured payload**, use `--json`.
75
+ `Components` / `Tokens` / `Icons` / `Docs` sections. Every `search` row includes a follow-up
76
+ command, such as `→ ads-cli component Avatar` or `→ ads-cli docs contrast`; this also applies to
77
+ narrowed `search --type` output. Documentation search results stay concise, while `docs <query>`
78
+ prints the full matched Markdown. `component`/`token`/`icon` print a readable detail view (the
79
+ icon view includes a copy-paste `import` line); `docs` (`foundations`, `a11y`, and `migration`)
80
+ and `lint-rules` print prose/Markdown. A raw JSON dump is only ever a last-resort fallback for an
81
+ unrecognised shape. For the **full structured payload**, use `--json`.
75
82
  - **Lookups never silently guess.** `component`/`token`/`icon <name>` — and a fuzzy
76
83
  `lint-rules <term>` — render the entry whose name matches exactly (case-insensitively). If there
77
84
  is no exact match but several candidates, they print a `Did you mean?` list (each with a
@@ -79,6 +86,9 @@ npx @atlaskit/ads-cli search button --json
79
86
  `{ "ambiguous": true, "query", "noun", "candidates": [...] }`.
80
87
  - **Data is written to stdout only.** Logs, hints, and errors go to **stderr**. This keeps `--json`
81
88
  output clean for piping.
89
+ - **The manifest is derived from the live command registry.** `manifest --json` lists every command,
90
+ positional argument, flag, example, and success response type without maintaining a separate copy
91
+ of the CLI surface.
82
92
  - With `--json`, every success prints a `SuccessEnvelope` and every failure prints an
83
93
  `ErrorEnvelope`:
84
94
 
@@ -88,7 +98,18 @@ npx @atlaskit/ads-cli search button --json
88
98
  "type": "ads-cli/search",
89
99
  "command": "search",
90
100
  "ok": true,
91
- "data": { "components": [ /* … */ ], "tokens": [ /* … */ ], "icons": [ /* … */ ] },
101
+ "data": {
102
+ "components": [ /* … */ ],
103
+ "tokens": [ /* … */ ],
104
+ "icons": [ /* … */ ],
105
+ "docs": [
106
+ {
107
+ "title": "Button",
108
+ "summary": "A concise preview of the leading textual content.",
109
+ "followUp": "docs button"
110
+ }
111
+ ]
112
+ },
92
113
  "meta": { "terms": ["button"], "count": 12 }
93
114
  }
94
115
 
package/dist/cjs/cli.js CHANGED
@@ -8,12 +8,15 @@ exports.run = void 0;
8
8
  var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
9
9
  var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
10
10
  var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
11
+ var _cliMetadata = require("./commands/cli-metadata");
11
12
  var _definitions = require("./commands/definitions");
12
13
  var _getCommand = require("./commands/get-command");
14
+ var _getVersion = require("./commands/get-version");
13
15
  var _importToolHandler = require("./commands/import-tool-handler");
14
16
  var _runTool = require("./commands/run-tool");
15
17
  var _createErrorEnvelope = require("./envelope/create-error-envelope");
16
18
  var _createSuccessEnvelope = require("./envelope/create-success-envelope");
19
+ var _createDocSearchResults = require("./output/create-doc-search-results");
17
20
  var _formatGroupedResults = require("./output/format-grouped-results");
18
21
  var _formatResults = require("./output/format-results");
19
22
  var _writeHumanError = require("./output/write-human-error");
@@ -36,30 +39,6 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
36
39
  * It never reimplements search ranking or bundles a dataset copy — all query logic lives in
37
40
  * `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
38
41
  */
39
- /**
40
- * Resolve the CLI version from package.json. Kept in a function so a failure to read it never
41
- * crashes the CLI (it falls back to `0.0.0`).
42
- */
43
- var getVersion = function getVersion() {
44
- try {
45
- var _pkgJson$version;
46
- // Read our own package.json at runtime via the package-name subpath. This mirrors
47
- // the sibling `@atlaskit/ads-mcp` package and is depth-independent, so it resolves
48
- // correctly in both the in-repo source layout (`src/cli`) and the published build
49
- // (`dist/cjs/cli`). Requires the `./package.json` subpath in this package's exports.
50
- // 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
51
- var pkgJson = require('@atlaskit/ads-cli/package.json');
52
- return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
53
- } catch (_unused) {
54
- return '0.0.0';
55
- }
56
- };
57
-
58
- /**
59
- * One-line description of the CLI, shown at the top of `--help`.
60
- */
61
- var CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
62
-
63
42
  /**
64
43
  * Build the top-level help text from the command registry so it can never drift from the
65
44
  * runnable surface.
@@ -80,7 +59,11 @@ var buildHelpText = function buildHelpText() {
80
59
  }).join('\n');
81
60
  return "".concat(usageLines, "\n ").concat(command.description);
82
61
  }).join('\n');
83
- 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');
62
+ var globalFlagLines = _cliMetadata.globalFlags.map(function (flag) {
63
+ var aliases = flag.alias ? ", -".concat(flag.alias) : '';
64
+ return " --".concat(flag.name).concat(aliases).padEnd(18) + flag.description;
65
+ }).join('\n');
66
+ return [_cliMetadata.CLI_DESCRIPTION, '', 'Usage', ' $ npx @atlaskit/ads-cli <command> [options]', '', 'Commands', commandLines, '', 'Global options', globalFlagLines, '', 'Examples', ' $ npx @atlaskit/ads-cli search contrast # unified: components, tokens, icons & docs', ' $ npx @atlaskit/ads-cli search button --type component', ' $ npx @atlaskit/ads-cli search contrast --type docs', ' $ 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', ' $ npx @atlaskit/ads-cli manifest --json # machine-readable CLI contract'].join('\n');
84
67
  };
85
68
 
86
69
  /**
@@ -287,7 +270,8 @@ var renderSingleResult = function renderSingleResult(_ref4) {
287
270
  var resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
288
271
  var compact = resultKind ? (0, _formatResults.formatCompactResults)({
289
272
  kind: resultKind,
290
- data: data
273
+ data: data,
274
+ showFollowUp: command.name === 'search'
291
275
  }) : null;
292
276
  var human = (_ref5 = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref5 !== void 0 ? _ref5 : null;
293
277
  if (human !== null) {
@@ -315,7 +299,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
315
299
  json = _ref6.json,
316
300
  writer = _ref6.writer;
317
301
  // Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
318
- // empty domain does not blank out the others.
302
+ // empty domain does not blank out the others. The guidelines tool returns full Markdown, so
303
+ // summarize its highest-ranked match for search; `docs <query>` remains the detail view.
319
304
  var grouped = {};
320
305
  var _iterator = _createForOfIteratorHelper(results),
321
306
  _step;
@@ -325,7 +310,14 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
325
310
  key = _step$value.key,
326
311
  data = _step$value.data,
327
312
  isError = _step$value.isError;
328
- grouped[key] = isError || !Array.isArray(data) ? [] : data;
313
+ if (key === 'docs' && !isError && typeof data === 'string' && data.trim() !== '') {
314
+ grouped[key] = (0, _createDocSearchResults.createDocSearchResults)({
315
+ data: data,
316
+ query: input.positionals.join(' ')
317
+ });
318
+ } else {
319
+ grouped[key] = isError || !Array.isArray(data) ? [] : data;
320
+ }
329
321
  }
330
322
  } catch (err) {
331
323
  _iterator.e(err);
@@ -336,7 +328,7 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
336
328
  return sum + arr.length;
337
329
  }, 0);
338
330
  if (totalCount === 0) {
339
- var message = 'No components, tokens, or icons found.';
331
+ var message = "No components, tokens, icons, or docs found for \"".concat(input.positionals.join(' '), "\".");
340
332
  if (json) {
341
333
  (0, _writeJsonEnvelope.writeJsonEnvelope)({
342
334
  envelope: (0, _createErrorEnvelope.createErrorEnvelope)({
@@ -359,8 +351,8 @@ var renderGroupedResult = function renderGroupedResult(_ref6) {
359
351
  envelope: (0, _createSuccessEnvelope.createSuccessEnvelope)({
360
352
  envelopeType: command.envelopeType(input),
361
353
  command: command.name,
362
- // `data` for grouped commands is `{ components, tokens, icons }` (already counted
363
- // per group), so `count` is the combined total across groups.
354
+ // `data` for grouped commands is `{ components, tokens, icons, docs }` (already
355
+ // counted per group), so `count` is the combined total across groups.
364
356
  data: grouped,
365
357
  meta: _objectSpread(_objectSpread({}, meta), {}, {
366
358
  count: totalCount
@@ -409,7 +401,7 @@ var run = exports.run = /*#__PURE__*/function () {
409
401
  _context3.next = 1;
410
402
  break;
411
403
  }
412
- writer.out(getVersion());
404
+ writer.out((0, _getVersion.getVersion)());
413
405
  return _context3.abrupt("return", _types.ExitCode.Ok);
414
406
  case 1:
415
407
  if (!(flags.help === true || command === undefined)) {
@@ -0,0 +1,48 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.buildManifest = void 0;
7
+ var _cliMetadata = require("./cli-metadata");
8
+ /**
9
+ * Build machine-readable metadata for the ADS CLI.
10
+ *
11
+ * The manifest is projected from the same command definitions used for dispatch and help, so it
12
+ * does not duplicate the runnable command surface.
13
+ */
14
+
15
+ /**
16
+ * Build a serializable capability manifest from the live command registry.
17
+ */
18
+ var buildManifest = exports.buildManifest = function buildManifest(commands, version) {
19
+ return {
20
+ schemaVersion: 1,
21
+ name: _cliMetadata.CLI_NAME,
22
+ bin: _cliMetadata.CLI_BIN_NAME,
23
+ version: version,
24
+ description: _cliMetadata.CLI_DESCRIPTION,
25
+ invocation: "npx ".concat(_cliMetadata.CLI_NAME),
26
+ commands: commands.map(function (_ref) {
27
+ var name = _ref.name,
28
+ description = _ref.description,
29
+ usage = _ref.usage,
30
+ commandArguments = _ref.arguments,
31
+ flags = _ref.flags,
32
+ examples = _ref.examples,
33
+ responseTypes = _ref.responseTypes;
34
+ return {
35
+ name: name,
36
+ description: description,
37
+ usage: usage,
38
+ arguments: commandArguments,
39
+ flags: flags,
40
+ examples: examples,
41
+ jsonSupported: true,
42
+ responseTypes: responseTypes
43
+ };
44
+ }),
45
+ globalFlags: _cliMetadata.globalFlags,
46
+ errorResponseType: 'ads-cli/error'
47
+ };
48
+ };
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.globalFlags = exports.CLI_NAME = exports.CLI_DESCRIPTION = exports.CLI_BIN_NAME = void 0;
7
+ /**
8
+ * Shared top-level ADS CLI metadata used by help and the capability manifest.
9
+ */
10
+
11
+ var CLI_NAME = exports.CLI_NAME = '@atlaskit/ads-cli';
12
+ var CLI_BIN_NAME = exports.CLI_BIN_NAME = 'ads-cli';
13
+ var CLI_DESCRIPTION = exports.CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
14
+ var globalFlags = exports.globalFlags = [{
15
+ name: 'json',
16
+ type: 'boolean',
17
+ default: false,
18
+ description: 'Emit a machine-readable JSON envelope on stdout.'
19
+ }, {
20
+ name: 'help',
21
+ type: 'boolean',
22
+ alias: 'h',
23
+ default: false,
24
+ description: 'Show help.'
25
+ }, {
26
+ name: 'version',
27
+ type: 'boolean',
28
+ alias: 'v',
29
+ default: false,
30
+ description: 'Show the CLI version.'
31
+ }];
@@ -7,29 +7,35 @@ Object.defineProperty(exports, "__esModule", {
7
7
  exports.commands = void 0;
8
8
  var _toArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toArray"));
9
9
  var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
10
+ var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
10
11
  var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
11
12
  var _a11yGuidelines = require("@atlaskit/ads-mcp/a11y-guidelines");
12
13
  var _migrationRegistry = require("@atlaskit/ads-mcp/migration-registry");
14
+ var _createDocSearchResults = require("../output/create-doc-search-results");
13
15
  var _disambiguation = require("../output/disambiguation");
14
16
  var _formatComponent = require("../output/format-component");
15
17
  var _formatDisambiguation = require("../output/format-disambiguation");
16
18
  var _formatDocObject = require("../output/format-doc-object");
17
19
  var _formatIcon = require("../output/format-icon");
18
20
  var _formatLintRules = require("../output/format-lint-rules");
21
+ var _formatManifest = require("../output/format-manifest");
19
22
  var _formatToken = require("../output/format-token");
20
23
  var _parseLintRuleRecords = require("../output/parse-lint-rule-records");
24
+ var _buildManifest = require("./build-manifest");
25
+ var _getVersion = require("./get-version");
21
26
  function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
22
27
  function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
23
28
  function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; } /**
24
29
  * The command definitions — the single source of truth for the ADS CLI surface.
25
30
  *
26
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
31
+ * Command dispatch, top-level `--help`, and the self-describing manifest are derived
27
32
  * from this one array, so there is no way for the runnable surface and the documented surface
28
33
  * to drift apart. Each entry declares:
29
34
  *
30
35
  * - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
31
36
  * - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
32
- * - the metadata (description, flags, examples) surfaced by `--help`.
37
+ * - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
38
+ * `--help`.
33
39
  *
34
40
  * The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
35
41
  * copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
@@ -63,7 +69,7 @@ var parseLimit = function parseLimit(flags) {
63
69
  };
64
70
 
65
71
  /**
66
- * Map of the three `search --type` variants to their ADS MCP tool exports.
72
+ * Map of the `search --type` variants to their ADS MCP tool exports.
67
73
  */
68
74
  var searchKindTools = {
69
75
  components: {
@@ -80,17 +86,22 @@ var searchKindTools = {
80
86
  importPath: '@atlaskit/ads-mcp/tools/search-icons',
81
87
  handlerName: 'searchIconsTool',
82
88
  envelopeType: 'search-icons'
89
+ },
90
+ docs: {
91
+ importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
92
+ handlerName: 'getGuidelinesTool',
93
+ envelopeType: 'search-docs'
83
94
  }
84
95
  };
85
96
  /**
86
- * Accepted `--type` values (singular, matching the item command names) → the internal (plural)
87
- * {@link SearchKind}. Everything downstream keys off the plural `SearchKind` (envelope types,
88
- * grouped JSON keys), so the singular input normalises to it here.
97
+ * Accepted `--type` values → the internal {@link SearchKind}. Entity inputs are singular to match
98
+ * their item commands; `docs` matches the dedicated documentation command.
89
99
  */
90
100
  var SEARCH_TYPE_VALUES = {
91
101
  component: 'components',
92
102
  token: 'tokens',
93
- icon: 'icons'
103
+ icon: 'icons',
104
+ docs: 'docs'
94
105
  };
95
106
  var isSearchTypeValue = function isSearchTypeValue(value) {
96
107
  return value in SEARCH_TYPE_VALUES;
@@ -217,6 +228,7 @@ var resolveSearch = function resolveSearch(_ref2) {
217
228
  var allFlag = {
218
229
  name: 'all',
219
230
  type: 'boolean',
231
+ default: false,
220
232
  description: 'List every entry of this kind instead of looking up a single name.'
221
233
  };
222
234
 
@@ -311,8 +323,15 @@ var makeItemCommand = function makeItemCommand(_ref3) {
311
323
  name: name,
312
324
  description: "Get details for a single ADS ".concat(name, ", or list all with --all."),
313
325
  usage: "".concat(name, " <name> | ").concat(name, " --all"),
326
+ arguments: [{
327
+ name: 'name',
328
+ type: 'string',
329
+ required: false,
330
+ description: "Exact or fuzzy ADS ".concat(name, " name. Omit when using --all.")
331
+ }],
314
332
  flags: [allFlag],
315
333
  examples: ["".concat(name, " ").concat(EXAMPLE_NAME[kind]), "".concat(name, " --all")],
334
+ responseTypes: ["ads-cli/".concat(name), "ads-cli/".concat(listTool.envelopeType)],
316
335
  // `--all` returns an array → render it as the compact per-row list for this kind. A single
317
336
  // `<name>` lookup is post-processed by `transform` into either one detail object or a
318
337
  // disambiguation marker, both handled by `formatHuman`.
@@ -403,10 +422,11 @@ var makeItemCommand = function makeItemCommand(_ref3) {
403
422
  };
404
423
 
405
424
  /**
406
- * Resolver for the unified `search` (no `--type`): fan out to all three search tools in one
407
- * command. The results are grouped by kind (components/tokens/icons) rather than merged into a
408
- * single ranked list — each tool ranks its own domain, and re-ranking across domains would
409
- * mean duplicating ranking logic here (breaking the zero-drift contract with `@atlaskit/ads-mcp`).
425
+ * Resolver for the unified `search` (no `--type`): fan out to the three entity search tools and
426
+ * foundations documentation search in one command. The results are grouped by kind
427
+ * (components/tokens/icons/docs) rather than merged into a single ranked list — each tool ranks its
428
+ * own domain, and re-ranking across domains would mean duplicating ranking logic here (breaking the
429
+ * zero-drift contract with `@atlaskit/ads-mcp`).
410
430
  */
411
431
  var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
412
432
  var terms = input.positionals;
@@ -438,25 +458,40 @@ var resolveUnifiedSearch = function resolveUnifiedSearch(input) {
438
458
  key: 'icons'
439
459
  }, searchKindTools.icons), {}, {
440
460
  args: args
461
+ }), _objectSpread(_objectSpread({
462
+ key: 'docs'
463
+ }, searchKindTools.docs), {}, {
464
+ args: args
441
465
  })],
442
466
  meta: args
443
467
  };
444
468
  };
445
469
 
446
470
  /**
447
- * The full set of CLI commands. Order here is the order shown by `--help`.
471
+ * The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
448
472
  */
449
473
  var commands = exports.commands = [{
450
474
  name: 'search',
451
- description: 'Fuzzy-search ADS components, tokens, and icons together (or narrow with --type).',
475
+ description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type).',
452
476
  usage: "search <query...> [--type ".concat(Object.keys(SEARCH_TYPE_VALUES).join('|'), "] [--limit N]"),
477
+ arguments: [{
478
+ name: 'query',
479
+ type: 'string',
480
+ required: true,
481
+ variadic: true,
482
+ description: 'One or more terms to search for.'
483
+ }],
453
484
  flags: [{
454
485
  name: 'type',
455
486
  type: 'string',
456
487
  alias: 't',
488
+ choices: Object.keys(SEARCH_TYPE_VALUES),
457
489
  description: "Narrow the search to a single kind: ".concat(Object.keys(SEARCH_TYPE_VALUES).join(', '), ".")
458
490
  }, limitFlag],
459
- examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
491
+ examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5', 'search contrast --type docs'],
492
+ responseTypes: ['ads-cli/search'].concat((0, _toConsumableArray2.default)(Object.values(searchKindTools).map(function (tool) {
493
+ return "ads-cli/".concat(tool.envelopeType);
494
+ }))),
460
495
  // With `--type`, the result is a single kind (compact per-row rendering). Without it, the
461
496
  // result is grouped across all kinds, so there is no single result kind — the grouped
462
497
  // formatter handles rendering instead.
@@ -464,12 +499,20 @@ var commands = exports.commands = [{
464
499
  var _resolveSearchType;
465
500
  return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
466
501
  },
502
+ transform: function transform(_ref5) {
503
+ var data = _ref5.data,
504
+ input = _ref5.input;
505
+ return resolveSearchType(input.flags) === 'docs' ? (0, _createDocSearchResults.createDocSearchResults)({
506
+ data: data,
507
+ query: input.positionals.join(' ')
508
+ }) : data;
509
+ },
467
510
  envelopeType: function envelopeType(input) {
468
511
  var searchType = resolveSearchType(input.flags);
469
512
  return searchType ? searchKindTools[searchType].envelopeType : 'search';
470
513
  },
471
514
  resolve: function resolve(input) {
472
- // No `--type`: unified search across all three kinds.
515
+ // No `--type`: unified search across all three entity kinds and foundations docs.
473
516
  if (input.flags.type === undefined) {
474
517
  return resolveUnifiedSearch(input);
475
518
  }
@@ -503,8 +546,16 @@ var commands = exports.commands = [{
503
546
  name: 'lint-rules',
504
547
  description: 'Get ADS ESLint lint rules, optionally filtered by term.',
505
548
  usage: 'lint-rules [term...] [--limit N]',
549
+ arguments: [{
550
+ name: 'term',
551
+ type: 'string',
552
+ required: false,
553
+ variadic: true,
554
+ description: 'Terms used to filter lint rules.'
555
+ }],
506
556
  flags: [limitFlag],
507
557
  examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
558
+ responseTypes: ['ads-cli/lint-rules'],
508
559
  envelopeType: function envelopeType() {
509
560
  return 'lint-rules';
510
561
  },
@@ -517,9 +568,9 @@ var commands = exports.commands = [{
517
568
  // shows that rule's docs, but several matches with no exact name surface a disambiguation
518
569
  // list instead of dumping every rule's full Markdown. Skipped for bare `lint-rules` (which
519
570
  // intentionally returns every rule's content).
520
- transform: function transform(_ref5) {
521
- var data = _ref5.data,
522
- input = _ref5.input;
571
+ transform: function transform(_ref6) {
572
+ var data = _ref6.data,
573
+ input = _ref6.input;
523
574
  var terms = input.positionals;
524
575
  if (terms.length === 0) {
525
576
  return data;
@@ -597,10 +648,18 @@ var commands = exports.commands = [{
597
648
  name: 'docs',
598
649
  description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
599
650
  usage: "docs <topic...> | docs a11y [".concat(A11Y_TOPICS.join('|'), "] | docs migration <").concat(MIGRATION_IDS.join('|'), ">"),
651
+ arguments: [{
652
+ name: 'topic',
653
+ type: 'string',
654
+ required: false,
655
+ variadic: true,
656
+ description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
657
+ }],
600
658
  // No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
601
659
  // guide, or a migration guide), so there is nothing to limit.
602
660
  flags: [],
603
661
  examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
662
+ responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
604
663
  envelopeType: function envelopeType(input) {
605
664
  var namespace = input.positionals[0];
606
665
  if (namespace === 'a11y') {
@@ -710,4 +769,24 @@ var commands = exports.commands = [{
710
769
  meta: args
711
770
  });
712
771
  }
772
+ }, {
773
+ name: 'manifest',
774
+ description: 'Describe every CLI command, argument, flag, and JSON response type.',
775
+ usage: 'manifest',
776
+ arguments: [],
777
+ flags: [],
778
+ examples: ['manifest --json'],
779
+ responseTypes: ['ads-cli/manifest'],
780
+ envelopeType: function envelopeType() {
781
+ return 'manifest';
782
+ },
783
+ formatHuman: _formatManifest.formatManifest,
784
+ resolve: function resolve() {
785
+ return {
786
+ data: (0, _buildManifest.buildManifest)(commands, (0, _getVersion.getVersion)()),
787
+ meta: {
788
+ schemaVersion: 1
789
+ }
790
+ };
791
+ }
713
792
  }];
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.getVersion = void 0;
7
+ /**
8
+ * Resolve the CLI version from package.json.
9
+ *
10
+ * A failed package lookup must not prevent the CLI from running, so fall back to the development
11
+ * version used by the package source.
12
+ */
13
+ var getVersion = exports.getVersion = function getVersion() {
14
+ try {
15
+ var _pkgJson$version;
16
+ // Read our own package.json at runtime via the package-name subpath. This is depth-independent,
17
+ // so it resolves in both the source layout and the published build.
18
+ // 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
19
+ var pkgJson = require('@atlaskit/ads-cli/package.json');
20
+ return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
21
+ } catch (_unused) {
22
+ return '0.0.0';
23
+ }
24
+ };
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+
3
+ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
4
+ Object.defineProperty(exports, "__esModule", {
5
+ value: true
6
+ });
7
+ exports.createDocSearchResults = void 0;
8
+ var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
9
+ function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
10
+ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
11
+ /**
12
+ * A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
13
+ *
14
+ * Search only surfaces this summary. The `docs` command remains the detail view for the full
15
+ * Markdown content.
16
+ */
17
+
18
+ /**
19
+ * Truncate a one-line description so compact rows stay on a single line.
20
+ */
21
+ var truncate = function truncate(text, max) {
22
+ return text.length > max ? "".concat(text.slice(0, max - 1).trimEnd(), "\u2026") : text;
23
+ };
24
+
25
+ /**
26
+ * Remove common Markdown formatting before showing documentation content in one row.
27
+ */
28
+ var toPlainText = function toPlainText(text) {
29
+ return text.replace(/!\[[^\]]*]\([^)]*\)/g, '').replace(/\[([^\]]+)]\([^)]*\)/g, '$1').replace(/^\s{0,3}#{1,6}\s+/gm, '').replace(/<[^>]+>/g, ' ').replace(/[*_`~]/g, '').replace(/\s+/g, ' ').trim();
30
+ };
31
+
32
+ /**
33
+ * Turn a full foundations-doc Markdown match into the concise record used by `search`.
34
+ *
35
+ * `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
36
+ * highest-ranked match is represented by the query and a preview of its leading textual content;
37
+ * the full payload remains available through the follow-up `docs <query>` command.
38
+ */
39
+ var createDocSearchResults = exports.createDocSearchResults = function createDocSearchResults(_ref) {
40
+ var data = _ref.data,
41
+ query = _ref.query;
42
+ if (typeof data !== 'string' || data.trim() === '') {
43
+ return [];
44
+ }
45
+ var normalizedQuery = query.replace(/\s+/g, ' ').trim();
46
+ var title = normalizedQuery ? "".concat(normalizedQuery.charAt(0).toUpperCase()).concat(normalizedQuery.slice(1)) : 'Documentation';
47
+ var preview = toPlainText(data);
48
+ return [_objectSpread(_objectSpread({
49
+ title: truncate(title, 80)
50
+ }, preview ? {
51
+ summary: truncate(preview, 100)
52
+ } : {}), {}, {
53
+ followUp: "docs ".concat(query)
54
+ })];
55
+ };