@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.
- package/CHANGELOG.md +19 -0
- package/README.md +30 -9
- package/dist/cjs/cli.js +24 -32
- package/dist/cjs/commands/build-manifest.js +48 -0
- package/dist/cjs/commands/cli-metadata.js +31 -0
- package/dist/cjs/commands/definitions.js +97 -18
- package/dist/cjs/commands/get-version.js +24 -0
- package/dist/cjs/output/create-doc-search-results.js +55 -0
- package/dist/cjs/output/format-grouped-results.js +5 -3
- package/dist/cjs/output/format-manifest.js +26 -0
- package/dist/cjs/output/format-results.js +14 -5
- package/dist/es2019/cli.js +23 -31
- package/dist/es2019/commands/build-manifest.js +39 -0
- package/dist/es2019/commands/cli-metadata.js +25 -0
- package/dist/es2019/commands/definitions.js +86 -15
- package/dist/es2019/commands/get-version.js +18 -0
- package/dist/es2019/output/create-doc-search-results.js +42 -0
- package/dist/es2019/output/format-grouped-results.js +5 -3
- package/dist/es2019/output/format-manifest.js +18 -0
- package/dist/es2019/output/format-results.js +14 -5
- package/dist/esm/cli.js +23 -31
- package/dist/esm/commands/build-manifest.js +42 -0
- package/dist/esm/commands/cli-metadata.js +25 -0
- package/dist/esm/commands/definitions.js +97 -18
- package/dist/esm/commands/get-version.js +18 -0
- package/dist/esm/output/create-doc-search-results.js +48 -0
- package/dist/esm/output/format-grouped-results.js +5 -3
- package/dist/esm/output/format-manifest.js +19 -0
- package/dist/esm/output/format-results.js +14 -5
- package/dist/types/commands/build-manifest.d.ts +26 -0
- package/dist/types/commands/cli-metadata.d.ts +8 -0
- package/dist/types/commands/definitions.d.ts +4 -3
- package/dist/types/commands/get-version.d.ts +7 -0
- package/dist/types/commands/types.d.ts +30 -11
- package/dist/types/output/create-doc-search-results.d.ts +22 -0
- package/dist/types/output/format-grouped-results.d.ts +2 -3
- package/dist/types/output/format-manifest.d.ts +4 -0
- package/dist/types/output/format-results.d.ts +1 -2
- package/package.json +1 -1
|
@@ -8,9 +8,8 @@ var _formatResults = require("./format-results");
|
|
|
8
8
|
/**
|
|
9
9
|
* Sectioned compact renderer for grouped (multi-kind) results, e.g. unified `search`.
|
|
10
10
|
*
|
|
11
|
-
* Prints
|
|
12
|
-
*
|
|
13
|
-
* kind.
|
|
11
|
+
* Prints Components, Tokens, Icons, and Docs sections using the per-kind compact renderer. Empty
|
|
12
|
+
* groups are skipped, so one command surfaces whatever kinds match, grouped by kind.
|
|
14
13
|
*/
|
|
15
14
|
|
|
16
15
|
/**
|
|
@@ -29,6 +28,9 @@ var formatGroupedResults = exports.formatGroupedResults = function formatGrouped
|
|
|
29
28
|
}, {
|
|
30
29
|
kind: 'icons',
|
|
31
30
|
title: 'Icons'
|
|
31
|
+
}, {
|
|
32
|
+
kind: 'docs',
|
|
33
|
+
title: 'Docs'
|
|
32
34
|
}];
|
|
33
35
|
var blocks = ["Results (".concat(totalCount, "):")];
|
|
34
36
|
for (var _i = 0, _sections = sections; _i < _sections.length; _i++) {
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
|
|
4
|
+
Object.defineProperty(exports, "__esModule", {
|
|
5
|
+
value: true
|
|
6
|
+
});
|
|
7
|
+
exports.formatManifest = void 0;
|
|
8
|
+
var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
|
|
9
|
+
/**
|
|
10
|
+
* Format a scannable human catalog of the ADS CLI capability manifest.
|
|
11
|
+
*/
|
|
12
|
+
var formatManifest = exports.formatManifest = function formatManifest(data) {
|
|
13
|
+
if ((0, _typeof2.default)(data) !== 'object' || data === null || !('bin' in data) || typeof data.bin !== 'string' || !('version' in data) || typeof data.version !== 'string' || !('invocation' in data) || typeof data.invocation !== 'string' || !('commands' in data) || !Array.isArray(data.commands)) {
|
|
14
|
+
return null;
|
|
15
|
+
}
|
|
16
|
+
var commands = data.commands.flatMap(function (command) {
|
|
17
|
+
if ((0, _typeof2.default)(command) !== 'object' || command === null || !('name' in command) || typeof command.name !== 'string' || !('description' in command) || typeof command.description !== 'string') {
|
|
18
|
+
return [];
|
|
19
|
+
}
|
|
20
|
+
var jsonFlag = 'jsonSupported' in command && command.jsonSupported === true ? ' [--json]' : '';
|
|
21
|
+
return [" ".concat(command.name).concat(jsonFlag, "\n ").concat(command.description)];
|
|
22
|
+
});
|
|
23
|
+
var commandCount = commands.length;
|
|
24
|
+
var commandLabel = commandCount === 1 ? 'command' : 'commands';
|
|
25
|
+
return ["".concat(data.bin, " v").concat(data.version, " \u2014 ").concat(commandCount, " ").concat(commandLabel), '', commands.join('\n'), '', "Run `".concat(data.invocation, " manifest --json` for the full structured manifest.")].join('\n');
|
|
26
|
+
};
|
|
@@ -55,9 +55,8 @@ var truncate = function truncate(text) {
|
|
|
55
55
|
/**
|
|
56
56
|
* Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
|
|
57
57
|
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
* for the whole list, so echoing each row's own name back would just be noise.
|
|
58
|
+
* Used for every `search` result, where the natural next step is to view that match in full.
|
|
59
|
+
* `--all` listings omit it because echoing every row's own name would just be noise.
|
|
61
60
|
*/
|
|
62
61
|
var withFollowUp = function withFollowUp(_ref) {
|
|
63
62
|
var line = _ref.line,
|
|
@@ -122,13 +121,21 @@ var formatIconLine = function formatIconLine(iconResult, showFollowUp) {
|
|
|
122
121
|
});
|
|
123
122
|
};
|
|
124
123
|
|
|
124
|
+
/**
|
|
125
|
+
* Render one foundations-document match without dumping its full Markdown body.
|
|
126
|
+
*/
|
|
127
|
+
var formatDocLine = function formatDocLine(doc, showFollowUp) {
|
|
128
|
+
var summary = doc.summary ? " \u2014 ".concat(doc.summary) : '';
|
|
129
|
+
var line = "".concat(doc.title).concat(summary);
|
|
130
|
+
return showFollowUp ? "".concat(line, "\n \u2192 ads-cli ").concat(doc.followUp) : line;
|
|
131
|
+
};
|
|
132
|
+
|
|
125
133
|
/**
|
|
126
134
|
* Render an array of results as compact lines for the given kind. Returns `null` when the data
|
|
127
135
|
* is not an array (so the caller can fall back to generic JSON rendering).
|
|
128
136
|
*
|
|
129
137
|
* `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
|
|
130
|
-
* row.
|
|
131
|
-
* off so the output stays terse.
|
|
138
|
+
* row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
|
|
132
139
|
*/
|
|
133
140
|
var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref2) {
|
|
134
141
|
var kind = _ref2.kind,
|
|
@@ -149,6 +156,8 @@ var formatCompactResults = exports.formatCompactResults = function formatCompact
|
|
|
149
156
|
return formatTokenLine(entry, showFollowUp);
|
|
150
157
|
case 'icons':
|
|
151
158
|
return formatIconLine(entry, showFollowUp);
|
|
159
|
+
case 'docs':
|
|
160
|
+
return formatDocLine(entry, showFollowUp);
|
|
152
161
|
default:
|
|
153
162
|
return JSON.stringify(entry);
|
|
154
163
|
}
|
package/dist/es2019/cli.js
CHANGED
|
@@ -9,12 +9,15 @@
|
|
|
9
9
|
* `@atlaskit/ads-mcp`, so the MCP server, the ADS skill, and this CLI stay in lock-step.
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
+
import { CLI_DESCRIPTION, globalFlags } from './commands/cli-metadata';
|
|
12
13
|
import { commands } from './commands/definitions';
|
|
13
14
|
import { getCommand } from './commands/get-command';
|
|
15
|
+
import { getVersion } from './commands/get-version';
|
|
14
16
|
import { importToolHandler } from './commands/import-tool-handler';
|
|
15
17
|
import { runTool } from './commands/run-tool';
|
|
16
18
|
import { createErrorEnvelope } from './envelope/create-error-envelope';
|
|
17
19
|
import { createSuccessEnvelope } from './envelope/create-success-envelope';
|
|
20
|
+
import { createDocSearchResults } from './output/create-doc-search-results';
|
|
18
21
|
import { formatGroupedResults } from './output/format-grouped-results';
|
|
19
22
|
import { formatCompactResults } from './output/format-results';
|
|
20
23
|
import { writeHumanError } from './output/write-human-error';
|
|
@@ -24,30 +27,6 @@ import { defaultWriter } from './output/writer';
|
|
|
24
27
|
import { parseArgs } from './parse-args';
|
|
25
28
|
import { ExitCode } from './types';
|
|
26
29
|
|
|
27
|
-
/**
|
|
28
|
-
* Resolve the CLI version from package.json. Kept in a function so a failure to read it never
|
|
29
|
-
* crashes the CLI (it falls back to `0.0.0`).
|
|
30
|
-
*/
|
|
31
|
-
const getVersion = () => {
|
|
32
|
-
try {
|
|
33
|
-
var _pkgJson$version;
|
|
34
|
-
// Read our own package.json at runtime via the package-name subpath. This mirrors
|
|
35
|
-
// the sibling `@atlaskit/ads-mcp` package and is depth-independent, so it resolves
|
|
36
|
-
// correctly in both the in-repo source layout (`src/cli`) and the published build
|
|
37
|
-
// (`dist/cjs/cli`). Requires the `./package.json` subpath in this package's exports.
|
|
38
|
-
// eslint-disable-next-line import/no-extraneous-dependencies, @typescript-eslint/no-var-requires -- this uses require because not all supported node versions use the same import assertions/attributes
|
|
39
|
-
const pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
40
|
-
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
41
|
-
} catch {
|
|
42
|
-
return '0.0.0';
|
|
43
|
-
}
|
|
44
|
-
};
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* One-line description of the CLI, shown at the top of `--help`.
|
|
48
|
-
*/
|
|
49
|
-
const CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
50
|
-
|
|
51
30
|
/**
|
|
52
31
|
* Build the top-level help text from the command registry so it can never drift from the
|
|
53
32
|
* runnable surface.
|
|
@@ -66,7 +45,11 @@ const buildHelpText = () => {
|
|
|
66
45
|
const usageLines = command.usage.split(' | ').map((part, index) => index === 0 ? ` ${part}` : ` | ${part}`).join('\n');
|
|
67
46
|
return `${usageLines}\n ${command.description}`;
|
|
68
47
|
}).join('\n');
|
|
69
|
-
|
|
48
|
+
const globalFlagLines = globalFlags.map(flag => {
|
|
49
|
+
const aliases = flag.alias ? `, -${flag.alias}` : '';
|
|
50
|
+
return ` --${flag.name}${aliases}`.padEnd(18) + flag.description;
|
|
51
|
+
}).join('\n');
|
|
52
|
+
return [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');
|
|
70
53
|
};
|
|
71
54
|
|
|
72
55
|
/**
|
|
@@ -244,7 +227,8 @@ const renderSingleResult = ({
|
|
|
244
227
|
const resultKind = (_command$resultKind = command.resultKind) === null || _command$resultKind === void 0 ? void 0 : _command$resultKind.call(command, input);
|
|
245
228
|
const compact = resultKind ? formatCompactResults({
|
|
246
229
|
kind: resultKind,
|
|
247
|
-
data
|
|
230
|
+
data,
|
|
231
|
+
showFollowUp: command.name === 'search'
|
|
248
232
|
}) : null;
|
|
249
233
|
const human = (_ref = compact !== null && compact !== void 0 ? compact : (_command$formatHuman = command.formatHuman) === null || _command$formatHuman === void 0 ? void 0 : _command$formatHuman.call(command, data)) !== null && _ref !== void 0 ? _ref : null;
|
|
250
234
|
if (human !== null) {
|
|
@@ -273,18 +257,26 @@ const renderGroupedResult = ({
|
|
|
273
257
|
writer
|
|
274
258
|
}) => {
|
|
275
259
|
// Assemble `{ [key]: results }`, coercing "no matches" sub-results to empty arrays so one
|
|
276
|
-
// empty domain does not blank out the others.
|
|
260
|
+
// empty domain does not blank out the others. The guidelines tool returns full Markdown, so
|
|
261
|
+
// summarize its highest-ranked match for search; `docs <query>` remains the detail view.
|
|
277
262
|
const grouped = {};
|
|
278
263
|
for (const {
|
|
279
264
|
key,
|
|
280
265
|
data,
|
|
281
266
|
isError
|
|
282
267
|
} of results) {
|
|
283
|
-
|
|
268
|
+
if (key === 'docs' && !isError && typeof data === 'string' && data.trim() !== '') {
|
|
269
|
+
grouped[key] = createDocSearchResults({
|
|
270
|
+
data,
|
|
271
|
+
query: input.positionals.join(' ')
|
|
272
|
+
});
|
|
273
|
+
} else {
|
|
274
|
+
grouped[key] = isError || !Array.isArray(data) ? [] : data;
|
|
275
|
+
}
|
|
284
276
|
}
|
|
285
277
|
const totalCount = Object.values(grouped).reduce((sum, arr) => sum + arr.length, 0);
|
|
286
278
|
if (totalCount === 0) {
|
|
287
|
-
const message =
|
|
279
|
+
const message = `No components, tokens, icons, or docs found for "${input.positionals.join(' ')}".`;
|
|
288
280
|
if (json) {
|
|
289
281
|
writeJsonEnvelope({
|
|
290
282
|
envelope: createErrorEnvelope({
|
|
@@ -307,8 +299,8 @@ const renderGroupedResult = ({
|
|
|
307
299
|
envelope: createSuccessEnvelope({
|
|
308
300
|
envelopeType: command.envelopeType(input),
|
|
309
301
|
command: command.name,
|
|
310
|
-
// `data` for grouped commands is `{ components, tokens, icons }` (already
|
|
311
|
-
// per group), so `count` is the combined total across groups.
|
|
302
|
+
// `data` for grouped commands is `{ components, tokens, icons, docs }` (already
|
|
303
|
+
// counted per group), so `count` is the combined total across groups.
|
|
312
304
|
data: grouped,
|
|
313
305
|
meta: {
|
|
314
306
|
...meta,
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Build machine-readable metadata for the ADS CLI.
|
|
3
|
+
*
|
|
4
|
+
* The manifest is projected from the same command definitions used for dispatch and help, so it
|
|
5
|
+
* does not duplicate the runnable command surface.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { CLI_BIN_NAME, CLI_DESCRIPTION, CLI_NAME, globalFlags } from './cli-metadata';
|
|
9
|
+
/**
|
|
10
|
+
* Build a serializable capability manifest from the live command registry.
|
|
11
|
+
*/
|
|
12
|
+
export const buildManifest = (commands, version) => ({
|
|
13
|
+
schemaVersion: 1,
|
|
14
|
+
name: CLI_NAME,
|
|
15
|
+
bin: CLI_BIN_NAME,
|
|
16
|
+
version,
|
|
17
|
+
description: CLI_DESCRIPTION,
|
|
18
|
+
invocation: `npx ${CLI_NAME}`,
|
|
19
|
+
commands: commands.map(({
|
|
20
|
+
name,
|
|
21
|
+
description,
|
|
22
|
+
usage,
|
|
23
|
+
arguments: commandArguments,
|
|
24
|
+
flags,
|
|
25
|
+
examples,
|
|
26
|
+
responseTypes
|
|
27
|
+
}) => ({
|
|
28
|
+
name,
|
|
29
|
+
description,
|
|
30
|
+
usage,
|
|
31
|
+
arguments: commandArguments,
|
|
32
|
+
flags,
|
|
33
|
+
examples,
|
|
34
|
+
jsonSupported: true,
|
|
35
|
+
responseTypes
|
|
36
|
+
})),
|
|
37
|
+
globalFlags,
|
|
38
|
+
errorResponseType: 'ads-cli/error'
|
|
39
|
+
});
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared top-level ADS CLI metadata used by help and the capability manifest.
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
export const CLI_NAME = '@atlaskit/ads-cli';
|
|
6
|
+
export const CLI_BIN_NAME = 'ads-cli';
|
|
7
|
+
export const CLI_DESCRIPTION = 'Query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.';
|
|
8
|
+
export const globalFlags = [{
|
|
9
|
+
name: 'json',
|
|
10
|
+
type: 'boolean',
|
|
11
|
+
default: false,
|
|
12
|
+
description: 'Emit a machine-readable JSON envelope on stdout.'
|
|
13
|
+
}, {
|
|
14
|
+
name: 'help',
|
|
15
|
+
type: 'boolean',
|
|
16
|
+
alias: 'h',
|
|
17
|
+
default: false,
|
|
18
|
+
description: 'Show help.'
|
|
19
|
+
}, {
|
|
20
|
+
name: 'version',
|
|
21
|
+
type: 'boolean',
|
|
22
|
+
alias: 'v',
|
|
23
|
+
default: false,
|
|
24
|
+
description: 'Show the CLI version.'
|
|
25
|
+
}];
|
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The command definitions — the single source of truth for the ADS CLI surface.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
4
|
+
* Command dispatch, top-level `--help`, and the self-describing manifest are derived
|
|
5
5
|
* from this one array, so there is no way for the runnable surface and the documented surface
|
|
6
6
|
* to drift apart. Each entry declares:
|
|
7
7
|
*
|
|
8
8
|
* - which `@atlaskit/ads-mcp/tools/*` subpath to import and which handler it exports,
|
|
9
9
|
* - how to turn parsed CLI input (positional terms + flags) into the tool's args object,
|
|
10
|
-
* - the metadata (
|
|
10
|
+
* - the metadata (arguments, flags, response types, and examples) surfaced by `manifest` and
|
|
11
|
+
* `--help`.
|
|
11
12
|
*
|
|
12
13
|
* The CLI is deliberately a thin layer: it never reimplements search ranking or bundles a
|
|
13
14
|
* copy of the dataset. All heavy lifting stays in `@atlaskit/ads-mcp`.
|
|
@@ -15,14 +16,18 @@
|
|
|
15
16
|
|
|
16
17
|
import { accessibilityGuidelines } from '@atlaskit/ads-mcp/a11y-guidelines';
|
|
17
18
|
import { migrationRegistry } from '@atlaskit/ads-mcp/migration-registry';
|
|
19
|
+
import { createDocSearchResults } from '../output/create-doc-search-results';
|
|
18
20
|
import { isDisambiguation } from '../output/disambiguation';
|
|
19
21
|
import { formatComponent } from '../output/format-component';
|
|
20
22
|
import { formatDisambiguation } from '../output/format-disambiguation';
|
|
21
23
|
import { formatDocObject } from '../output/format-doc-object';
|
|
22
24
|
import { formatIcon } from '../output/format-icon';
|
|
23
25
|
import { formatLintRules } from '../output/format-lint-rules';
|
|
26
|
+
import { formatManifest } from '../output/format-manifest';
|
|
24
27
|
import { formatToken } from '../output/format-token';
|
|
25
28
|
import { parseLintRuleRecords } from '../output/parse-lint-rule-records';
|
|
29
|
+
import { buildManifest } from './build-manifest';
|
|
30
|
+
import { getVersion } from './get-version';
|
|
26
31
|
/**
|
|
27
32
|
* Shared `--limit` flag definition reused across the search-style commands.
|
|
28
33
|
*/
|
|
@@ -52,7 +57,7 @@ const parseLimit = flags => {
|
|
|
52
57
|
};
|
|
53
58
|
|
|
54
59
|
/**
|
|
55
|
-
* Map of the
|
|
60
|
+
* Map of the `search --type` variants to their ADS MCP tool exports.
|
|
56
61
|
*/
|
|
57
62
|
const searchKindTools = {
|
|
58
63
|
components: {
|
|
@@ -69,17 +74,22 @@ const searchKindTools = {
|
|
|
69
74
|
importPath: '@atlaskit/ads-mcp/tools/search-icons',
|
|
70
75
|
handlerName: 'searchIconsTool',
|
|
71
76
|
envelopeType: 'search-icons'
|
|
77
|
+
},
|
|
78
|
+
docs: {
|
|
79
|
+
importPath: '@atlaskit/ads-mcp/tools/get-guidelines',
|
|
80
|
+
handlerName: 'getGuidelinesTool',
|
|
81
|
+
envelopeType: 'search-docs'
|
|
72
82
|
}
|
|
73
83
|
};
|
|
74
84
|
/**
|
|
75
|
-
* Accepted `--type` values
|
|
76
|
-
*
|
|
77
|
-
* grouped JSON keys), so the singular input normalises to it here.
|
|
85
|
+
* Accepted `--type` values → the internal {@link SearchKind}. Entity inputs are singular to match
|
|
86
|
+
* their item commands; `docs` matches the dedicated documentation command.
|
|
78
87
|
*/
|
|
79
88
|
const SEARCH_TYPE_VALUES = {
|
|
80
89
|
component: 'components',
|
|
81
90
|
token: 'tokens',
|
|
82
|
-
icon: 'icons'
|
|
91
|
+
icon: 'icons',
|
|
92
|
+
docs: 'docs'
|
|
83
93
|
};
|
|
84
94
|
const isSearchTypeValue = value => value in SEARCH_TYPE_VALUES;
|
|
85
95
|
|
|
@@ -203,6 +213,7 @@ const resolveSearch = ({
|
|
|
203
213
|
const allFlag = {
|
|
204
214
|
name: 'all',
|
|
205
215
|
type: 'boolean',
|
|
216
|
+
default: false,
|
|
206
217
|
description: 'List every entry of this kind instead of looking up a single name.'
|
|
207
218
|
};
|
|
208
219
|
|
|
@@ -292,8 +303,15 @@ const makeItemCommand = ({
|
|
|
292
303
|
name,
|
|
293
304
|
description: `Get details for a single ADS ${name}, or list all with --all.`,
|
|
294
305
|
usage: `${name} <name> | ${name} --all`,
|
|
306
|
+
arguments: [{
|
|
307
|
+
name: 'name',
|
|
308
|
+
type: 'string',
|
|
309
|
+
required: false,
|
|
310
|
+
description: `Exact or fuzzy ADS ${name} name. Omit when using --all.`
|
|
311
|
+
}],
|
|
295
312
|
flags: [allFlag],
|
|
296
313
|
examples: [`${name} ${EXAMPLE_NAME[kind]}`, `${name} --all`],
|
|
314
|
+
responseTypes: [`ads-cli/${name}`, `ads-cli/${listTool.envelopeType}`],
|
|
297
315
|
// `--all` returns an array → render it as the compact per-row list for this kind. A single
|
|
298
316
|
// `<name>` lookup is post-processed by `transform` into either one detail object or a
|
|
299
317
|
// disambiguation marker, both handled by `formatHuman`.
|
|
@@ -379,10 +397,11 @@ const makeItemCommand = ({
|
|
|
379
397
|
};
|
|
380
398
|
|
|
381
399
|
/**
|
|
382
|
-
* Resolver for the unified `search` (no `--type`): fan out to
|
|
383
|
-
* command. The results are grouped by kind
|
|
384
|
-
* single ranked list — each tool ranks its
|
|
385
|
-
* mean duplicating ranking logic here (breaking the
|
|
400
|
+
* Resolver for the unified `search` (no `--type`): fan out to the three entity search tools and
|
|
401
|
+
* foundations documentation search in one command. The results are grouped by kind
|
|
402
|
+
* (components/tokens/icons/docs) rather than merged into a single ranked list — each tool ranks its
|
|
403
|
+
* own domain, and re-ranking across domains would mean duplicating ranking logic here (breaking the
|
|
404
|
+
* zero-drift contract with `@atlaskit/ads-mcp`).
|
|
386
405
|
*/
|
|
387
406
|
const resolveUnifiedSearch = input => {
|
|
388
407
|
const terms = input.positionals;
|
|
@@ -415,25 +434,38 @@ const resolveUnifiedSearch = input => {
|
|
|
415
434
|
key: 'icons',
|
|
416
435
|
...searchKindTools.icons,
|
|
417
436
|
args
|
|
437
|
+
}, {
|
|
438
|
+
key: 'docs',
|
|
439
|
+
...searchKindTools.docs,
|
|
440
|
+
args
|
|
418
441
|
}],
|
|
419
442
|
meta: args
|
|
420
443
|
};
|
|
421
444
|
};
|
|
422
445
|
|
|
423
446
|
/**
|
|
424
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
447
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
425
448
|
*/
|
|
426
449
|
export const commands = [{
|
|
427
450
|
name: 'search',
|
|
428
|
-
description: 'Fuzzy-search ADS components, tokens, and
|
|
451
|
+
description: 'Fuzzy-search ADS components, tokens, icons, and docs together (or narrow results with --type).',
|
|
429
452
|
usage: `search <query...> [--type ${Object.keys(SEARCH_TYPE_VALUES).join('|')}] [--limit N]`,
|
|
453
|
+
arguments: [{
|
|
454
|
+
name: 'query',
|
|
455
|
+
type: 'string',
|
|
456
|
+
required: true,
|
|
457
|
+
variadic: true,
|
|
458
|
+
description: 'One or more terms to search for.'
|
|
459
|
+
}],
|
|
430
460
|
flags: [{
|
|
431
461
|
name: 'type',
|
|
432
462
|
type: 'string',
|
|
433
463
|
alias: 't',
|
|
464
|
+
choices: Object.keys(SEARCH_TYPE_VALUES),
|
|
434
465
|
description: `Narrow the search to a single kind: ${Object.keys(SEARCH_TYPE_VALUES).join(', ')}.`
|
|
435
466
|
}, limitFlag],
|
|
436
|
-
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5'],
|
|
467
|
+
examples: ['search button', 'search space color --type token', 'search add --type icon --limit 5', 'search contrast --type docs'],
|
|
468
|
+
responseTypes: ['ads-cli/search', ...Object.values(searchKindTools).map(tool => `ads-cli/${tool.envelopeType}`)],
|
|
437
469
|
// With `--type`, the result is a single kind (compact per-row rendering). Without it, the
|
|
438
470
|
// result is grouped across all kinds, so there is no single result kind — the grouped
|
|
439
471
|
// formatter handles rendering instead.
|
|
@@ -441,12 +473,19 @@ export const commands = [{
|
|
|
441
473
|
var _resolveSearchType;
|
|
442
474
|
return (_resolveSearchType = resolveSearchType(input.flags)) !== null && _resolveSearchType !== void 0 ? _resolveSearchType : undefined;
|
|
443
475
|
},
|
|
476
|
+
transform: ({
|
|
477
|
+
data,
|
|
478
|
+
input
|
|
479
|
+
}) => resolveSearchType(input.flags) === 'docs' ? createDocSearchResults({
|
|
480
|
+
data,
|
|
481
|
+
query: input.positionals.join(' ')
|
|
482
|
+
}) : data,
|
|
444
483
|
envelopeType: input => {
|
|
445
484
|
const searchType = resolveSearchType(input.flags);
|
|
446
485
|
return searchType ? searchKindTools[searchType].envelopeType : 'search';
|
|
447
486
|
},
|
|
448
487
|
resolve: input => {
|
|
449
|
-
// No `--type`: unified search across all three kinds.
|
|
488
|
+
// No `--type`: unified search across all three entity kinds and foundations docs.
|
|
450
489
|
if (input.flags.type === undefined) {
|
|
451
490
|
return resolveUnifiedSearch(input);
|
|
452
491
|
}
|
|
@@ -480,8 +519,16 @@ export const commands = [{
|
|
|
480
519
|
name: 'lint-rules',
|
|
481
520
|
description: 'Get ADS ESLint lint rules, optionally filtered by term.',
|
|
482
521
|
usage: 'lint-rules [term...] [--limit N]',
|
|
522
|
+
arguments: [{
|
|
523
|
+
name: 'term',
|
|
524
|
+
type: 'string',
|
|
525
|
+
required: false,
|
|
526
|
+
variadic: true,
|
|
527
|
+
description: 'Terms used to filter lint rules.'
|
|
528
|
+
}],
|
|
483
529
|
flags: [limitFlag],
|
|
484
530
|
examples: ['lint-rules', 'lint-rules unsafe', 'lint-rules no-unsafe-style-overrides'],
|
|
531
|
+
responseTypes: ['ads-cli/lint-rules'],
|
|
485
532
|
envelopeType: () => 'lint-rules',
|
|
486
533
|
// Ambiguous fuzzy lookup → render the "did you mean?" list; otherwise print each rule's
|
|
487
534
|
// Markdown `content` verbatim rather than JSON.
|
|
@@ -569,10 +616,18 @@ export const commands = [{
|
|
|
569
616
|
name: 'docs',
|
|
570
617
|
description: 'Read ADS reference docs: foundations, accessibility (a11y), or migrations.',
|
|
571
618
|
usage: `docs <topic...> | docs a11y [${A11Y_TOPICS.join('|')}] | docs migration <${MIGRATION_IDS.join('|')}>`,
|
|
619
|
+
arguments: [{
|
|
620
|
+
name: 'topic',
|
|
621
|
+
type: 'string',
|
|
622
|
+
required: false,
|
|
623
|
+
variadic: true,
|
|
624
|
+
description: 'Foundation terms, an accessibility topic after a11y, or a migration id after migration.'
|
|
625
|
+
}],
|
|
572
626
|
// No `--limit`: every `docs` variant returns a single document (a foundation doc, an a11y
|
|
573
627
|
// guide, or a migration guide), so there is nothing to limit.
|
|
574
628
|
flags: [],
|
|
575
629
|
examples: ['docs spacing', 'docs color contrast', 'docs a11y buttons', 'docs migration motion'],
|
|
630
|
+
responseTypes: ['ads-cli/docs-guidelines', 'ads-cli/docs-a11y', 'ads-cli/docs-migration'],
|
|
576
631
|
envelopeType: input => {
|
|
577
632
|
const namespace = input.positionals[0];
|
|
578
633
|
if (namespace === 'a11y') {
|
|
@@ -680,4 +735,20 @@ export const commands = [{
|
|
|
680
735
|
meta: args
|
|
681
736
|
});
|
|
682
737
|
}
|
|
738
|
+
}, {
|
|
739
|
+
name: 'manifest',
|
|
740
|
+
description: 'Describe every CLI command, argument, flag, and JSON response type.',
|
|
741
|
+
usage: 'manifest',
|
|
742
|
+
arguments: [],
|
|
743
|
+
flags: [],
|
|
744
|
+
examples: ['manifest --json'],
|
|
745
|
+
responseTypes: ['ads-cli/manifest'],
|
|
746
|
+
envelopeType: () => 'manifest',
|
|
747
|
+
formatHuman: formatManifest,
|
|
748
|
+
resolve: () => ({
|
|
749
|
+
data: buildManifest(commands, getVersion()),
|
|
750
|
+
meta: {
|
|
751
|
+
schemaVersion: 1
|
|
752
|
+
}
|
|
753
|
+
})
|
|
683
754
|
}];
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve the CLI version from package.json.
|
|
3
|
+
*
|
|
4
|
+
* A failed package lookup must not prevent the CLI from running, so fall back to the development
|
|
5
|
+
* version used by the package source.
|
|
6
|
+
*/
|
|
7
|
+
export const getVersion = () => {
|
|
8
|
+
try {
|
|
9
|
+
var _pkgJson$version;
|
|
10
|
+
// Read our own package.json at runtime via the package-name subpath. This is depth-independent,
|
|
11
|
+
// so it resolves in both the source layout and the published build.
|
|
12
|
+
// 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
|
|
13
|
+
const pkgJson = require('@atlaskit/ads-cli/package.json');
|
|
14
|
+
return (_pkgJson$version = pkgJson.version) !== null && _pkgJson$version !== void 0 ? _pkgJson$version : '0.0.0';
|
|
15
|
+
} catch {
|
|
16
|
+
return '0.0.0';
|
|
17
|
+
}
|
|
18
|
+
};
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A concise documentation match derived from the Markdown returned by `getGuidelinesTool`.
|
|
3
|
+
*
|
|
4
|
+
* Search only surfaces this summary. The `docs` command remains the detail view for the full
|
|
5
|
+
* Markdown content.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Truncate a one-line description so compact rows stay on a single line.
|
|
10
|
+
*/
|
|
11
|
+
const truncate = (text, max) => text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Remove common Markdown formatting before showing documentation content in one row.
|
|
15
|
+
*/
|
|
16
|
+
const toPlainText = text => text.replace(/!\[[^\]]*]\([^)]*\)/g, '').replace(/\[([^\]]+)]\([^)]*\)/g, '$1').replace(/^\s{0,3}#{1,6}\s+/gm, '').replace(/<[^>]+>/g, ' ').replace(/[*_`~]/g, '').replace(/\s+/g, ' ').trim();
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Turn a full foundations-doc Markdown match into the concise record used by `search`.
|
|
20
|
+
*
|
|
21
|
+
* `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
|
|
22
|
+
* highest-ranked match is represented by the query and a preview of its leading textual content;
|
|
23
|
+
* the full payload remains available through the follow-up `docs <query>` command.
|
|
24
|
+
*/
|
|
25
|
+
export const createDocSearchResults = ({
|
|
26
|
+
data,
|
|
27
|
+
query
|
|
28
|
+
}) => {
|
|
29
|
+
if (typeof data !== 'string' || data.trim() === '') {
|
|
30
|
+
return [];
|
|
31
|
+
}
|
|
32
|
+
const normalizedQuery = query.replace(/\s+/g, ' ').trim();
|
|
33
|
+
const title = normalizedQuery ? `${normalizedQuery.charAt(0).toUpperCase()}${normalizedQuery.slice(1)}` : 'Documentation';
|
|
34
|
+
const preview = toPlainText(data);
|
|
35
|
+
return [{
|
|
36
|
+
title: truncate(title, 80),
|
|
37
|
+
...(preview ? {
|
|
38
|
+
summary: truncate(preview, 100)
|
|
39
|
+
} : {}),
|
|
40
|
+
followUp: `docs ${query}`
|
|
41
|
+
}];
|
|
42
|
+
};
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Sectioned compact renderer for grouped (multi-kind) results, e.g. unified `search`.
|
|
3
3
|
*
|
|
4
|
-
* Prints
|
|
5
|
-
*
|
|
6
|
-
* kind.
|
|
4
|
+
* Prints Components, Tokens, Icons, and Docs sections using the per-kind compact renderer. Empty
|
|
5
|
+
* groups are skipped, so one command surfaces whatever kinds match, grouped by kind.
|
|
7
6
|
*/
|
|
8
7
|
|
|
9
8
|
import { formatCompactResults } from './format-results';
|
|
@@ -25,6 +24,9 @@ export const formatGroupedResults = ({
|
|
|
25
24
|
}, {
|
|
26
25
|
kind: 'icons',
|
|
27
26
|
title: 'Icons'
|
|
27
|
+
}, {
|
|
28
|
+
kind: 'docs',
|
|
29
|
+
title: 'Docs'
|
|
28
30
|
}];
|
|
29
31
|
const blocks = [`Results (${totalCount}):`];
|
|
30
32
|
for (const {
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Format a scannable human catalog of the ADS CLI capability manifest.
|
|
3
|
+
*/
|
|
4
|
+
export const formatManifest = data => {
|
|
5
|
+
if (typeof data !== 'object' || data === null || !('bin' in data) || typeof data.bin !== 'string' || !('version' in data) || typeof data.version !== 'string' || !('invocation' in data) || typeof data.invocation !== 'string' || !('commands' in data) || !Array.isArray(data.commands)) {
|
|
6
|
+
return null;
|
|
7
|
+
}
|
|
8
|
+
const commands = data.commands.flatMap(command => {
|
|
9
|
+
if (typeof command !== 'object' || command === null || !('name' in command) || typeof command.name !== 'string' || !('description' in command) || typeof command.description !== 'string') {
|
|
10
|
+
return [];
|
|
11
|
+
}
|
|
12
|
+
const jsonFlag = 'jsonSupported' in command && command.jsonSupported === true ? ' [--json]' : '';
|
|
13
|
+
return [` ${command.name}${jsonFlag}\n ${command.description}`];
|
|
14
|
+
});
|
|
15
|
+
const commandCount = commands.length;
|
|
16
|
+
const commandLabel = commandCount === 1 ? 'command' : 'commands';
|
|
17
|
+
return [`${data.bin} v${data.version} — ${commandCount} ${commandLabel}`, '', commands.join('\n'), '', `Run \`${data.invocation} manifest --json\` for the full structured manifest.`].join('\n');
|
|
18
|
+
};
|
|
@@ -40,9 +40,8 @@ const truncate = (text, max = 80) => text.length > max ? `${text.slice(0, max -
|
|
|
40
40
|
/**
|
|
41
41
|
* Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
|
|
42
42
|
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
* for the whole list, so echoing each row's own name back would just be noise.
|
|
43
|
+
* Used for every `search` result, where the natural next step is to view that match in full.
|
|
44
|
+
* `--all` listings omit it because echoing every row's own name would just be noise.
|
|
46
45
|
*/
|
|
47
46
|
const withFollowUp = ({
|
|
48
47
|
line,
|
|
@@ -106,13 +105,21 @@ const formatIconLine = (iconResult, showFollowUp) => {
|
|
|
106
105
|
});
|
|
107
106
|
};
|
|
108
107
|
|
|
108
|
+
/**
|
|
109
|
+
* Render one foundations-document match without dumping its full Markdown body.
|
|
110
|
+
*/
|
|
111
|
+
const formatDocLine = (doc, showFollowUp) => {
|
|
112
|
+
const summary = doc.summary ? ` — ${doc.summary}` : '';
|
|
113
|
+
const line = `${doc.title}${summary}`;
|
|
114
|
+
return showFollowUp ? `${line}\n → ads-cli ${doc.followUp}` : line;
|
|
115
|
+
};
|
|
116
|
+
|
|
109
117
|
/**
|
|
110
118
|
* Render an array of results as compact lines for the given kind. Returns `null` when the data
|
|
111
119
|
* is not an array (so the caller can fall back to generic JSON rendering).
|
|
112
120
|
*
|
|
113
121
|
* `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
|
|
114
|
-
* row.
|
|
115
|
-
* off so the output stays terse.
|
|
122
|
+
* row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
|
|
116
123
|
*/
|
|
117
124
|
export const formatCompactResults = ({
|
|
118
125
|
kind,
|
|
@@ -133,6 +140,8 @@ export const formatCompactResults = ({
|
|
|
133
140
|
return formatTokenLine(entry, showFollowUp);
|
|
134
141
|
case 'icons':
|
|
135
142
|
return formatIconLine(entry, showFollowUp);
|
|
143
|
+
case 'docs':
|
|
144
|
+
return formatDocLine(entry, showFollowUp);
|
|
136
145
|
default:
|
|
137
146
|
return JSON.stringify(entry);
|
|
138
147
|
}
|