@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
|
@@ -1,19 +1,20 @@
|
|
|
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`.
|
|
14
15
|
*/
|
|
15
16
|
import type { CommandDefinition } from './types';
|
|
16
17
|
/**
|
|
17
|
-
* The full set of CLI commands. Order here is the order shown by `--help`.
|
|
18
|
+
* The full set of CLI commands. Order here is the order shown by `manifest` and `--help`.
|
|
18
19
|
*/
|
|
19
20
|
export declare const commands: CommandDefinition[];
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Types for the ADS CLI command registry.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* from the single set of {@link CommandDefinition}s, so the runnable
|
|
6
|
-
*
|
|
4
|
+
* Command dispatch, the top-level `--help` text, and the self-describing `manifest` command are
|
|
5
|
+
* derived from the single set of {@link CommandDefinition}s, so the runnable and documented
|
|
6
|
+
* surfaces cannot drift apart.
|
|
7
7
|
*/
|
|
8
8
|
/**
|
|
9
9
|
* Parsed CLI input handed to a command's `resolve` function.
|
|
@@ -19,7 +19,18 @@ export type CommandInput = {
|
|
|
19
19
|
flags: Record<string, unknown>;
|
|
20
20
|
};
|
|
21
21
|
/**
|
|
22
|
-
* A documented
|
|
22
|
+
* A documented positional argument for a command, surfaced by `manifest`.
|
|
23
|
+
*/
|
|
24
|
+
export type CommandArgument = {
|
|
25
|
+
name: string;
|
|
26
|
+
type: 'string';
|
|
27
|
+
description: string;
|
|
28
|
+
required: boolean;
|
|
29
|
+
variadic?: boolean;
|
|
30
|
+
choices?: string[];
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* A documented flag for a command, surfaced by `manifest` and `--help`.
|
|
23
34
|
*/
|
|
24
35
|
export type CommandFlag = {
|
|
25
36
|
name: string;
|
|
@@ -27,6 +38,7 @@ export type CommandFlag = {
|
|
|
27
38
|
description: string;
|
|
28
39
|
alias?: string;
|
|
29
40
|
default?: string | number | boolean;
|
|
41
|
+
choices?: string[];
|
|
30
42
|
};
|
|
31
43
|
/**
|
|
32
44
|
* A single ADS MCP tool invocation. `importPath`/`handlerName` are used to dynamically import
|
|
@@ -36,7 +48,7 @@ export type ToolCall = {
|
|
|
36
48
|
/**
|
|
37
49
|
* A stable key identifying this call within a multi-tool command. For grouped commands
|
|
38
50
|
* (e.g. unified `search`) this becomes the key in the assembled data object, e.g.
|
|
39
|
-
* `components` / `tokens` / `icons`. Ignored for single-tool commands.
|
|
51
|
+
* `components` / `tokens` / `icons` / `docs`. Ignored for single-tool commands.
|
|
40
52
|
*/
|
|
41
53
|
key: string;
|
|
42
54
|
importPath: string;
|
|
@@ -77,12 +89,11 @@ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
|
|
|
77
89
|
};
|
|
78
90
|
/**
|
|
79
91
|
* The kind of *listable row* a command renders, used by the default (non-`--json`) formatter to
|
|
80
|
-
* pick a compact per-row renderer.
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
* generic fallback (pretty-printed JSON for objects, verbatim text for strings).
|
|
92
|
+
* pick a compact per-row renderer. Search results include concise documentation matches, while
|
|
93
|
+
* standalone docs, a11y, and lint-rules commands render their full content via
|
|
94
|
+
* {@link CommandDefinition.formatHuman} or the generic fallback.
|
|
84
95
|
*/
|
|
85
|
-
export type RowKind = 'components' | 'tokens' | 'icons';
|
|
96
|
+
export type RowKind = 'components' | 'tokens' | 'icons' | 'docs';
|
|
86
97
|
/**
|
|
87
98
|
* A single CLI command definition.
|
|
88
99
|
*/
|
|
@@ -99,13 +110,17 @@ export type CommandDefinition = {
|
|
|
99
110
|
*/
|
|
100
111
|
resultKind?: (input: CommandInput) => RowKind | undefined;
|
|
101
112
|
/**
|
|
102
|
-
* One-line summary for `--help`.
|
|
113
|
+
* One-line summary for `manifest` and `--help`.
|
|
103
114
|
*/
|
|
104
115
|
description: string;
|
|
105
116
|
/**
|
|
106
117
|
* Usage string, e.g. `search <query...> [--type components|tokens|icons] [--limit N]`.
|
|
107
118
|
*/
|
|
108
119
|
usage: string;
|
|
120
|
+
/**
|
|
121
|
+
* Structured positional argument metadata for agent discovery.
|
|
122
|
+
*/
|
|
123
|
+
arguments: CommandArgument[];
|
|
109
124
|
/**
|
|
110
125
|
* Documented flags.
|
|
111
126
|
*/
|
|
@@ -114,6 +129,10 @@ export type CommandDefinition = {
|
|
|
114
129
|
* Example invocations.
|
|
115
130
|
*/
|
|
116
131
|
examples: string[];
|
|
132
|
+
/**
|
|
133
|
+
* Full success-envelope `type` discriminators this command can emit with `--json`.
|
|
134
|
+
*/
|
|
135
|
+
responseTypes: string[];
|
|
117
136
|
/**
|
|
118
137
|
* The envelope `type` suffix used for this command's JSON output, e.g. `search-components`
|
|
119
138
|
* produces `type: "ads-cli/search-components"`. May depend on input (e.g. `search --type
|
|
@@ -0,0 +1,22 @@
|
|
|
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
|
+
export type DocSearchResult = {
|
|
8
|
+
title: string;
|
|
9
|
+
summary?: string;
|
|
10
|
+
followUp: string;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Turn a full foundations-doc Markdown match into the concise record used by `search`.
|
|
14
|
+
*
|
|
15
|
+
* `getGuidelinesTool` currently returns Markdown rather than structured search metadata. Its
|
|
16
|
+
* highest-ranked match is represented by the query and a preview of its leading textual content;
|
|
17
|
+
* the full payload remains available through the follow-up `docs <query>` command.
|
|
18
|
+
*/
|
|
19
|
+
export declare const createDocSearchResults: ({ data, query, }: {
|
|
20
|
+
data: unknown;
|
|
21
|
+
query: string;
|
|
22
|
+
}) => DocSearchResult[];
|
|
@@ -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
|
* Render grouped results as sectioned compact output.
|
|
@@ -14,8 +14,7 @@ import type { RowKind } from '../commands/types';
|
|
|
14
14
|
* is not an array (so the caller can fall back to generic JSON rendering).
|
|
15
15
|
*
|
|
16
16
|
* `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
|
|
17
|
-
* row.
|
|
18
|
-
* off so the output stays terse.
|
|
17
|
+
* row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
|
|
19
18
|
*/
|
|
20
19
|
export declare const formatCompactResults: ({ kind, data, showFollowUp, }: {
|
|
21
20
|
kind: RowKind;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/ads-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "An npx-runnable command-line tool to query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.",
|
|
5
5
|
"author": "Atlassian Pty Ltd",
|
|
6
6
|
"license": "Apache-2.0",
|