@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
@@ -1,19 +1,20 @@
1
1
  /**
2
2
  * The command definitions — the single source of truth for the ADS CLI surface.
3
3
  *
4
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
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 (description, flags, examples) surfaced by `--help`.
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[];
@@ -0,0 +1,7 @@
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 declare const getVersion: () => string;
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Types for the ADS CLI command registry.
3
3
  *
4
- * Both command dispatch and the top-level `--help` text (in `cli.tsx`) are derived
5
- * from the single set of {@link CommandDefinition}s, so the runnable surface and the
6
- * documented surface can never drift apart.
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 flag for a command, surfaced by `--help`.
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. Scoped to the entity types the CLI returns as arrays of rows
81
- * (components, tokens, icons); it is intentionally NOT used for single-rich-object commands like
82
- * docs, a11y, or lint-rules — those render via {@link CommandDefinition.formatHuman} or the
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 a Components section, then Tokens, then Icons — reusing the per-kind compact renderer
5
- * for each. Empty groups are skipped, so one command surfaces whatever kinds match, grouped by
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.
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Format a scannable human catalog of the ADS CLI capability manifest.
3
+ */
4
+ export declare const formatManifest: (data: unknown) => string | null;
@@ -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. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
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.1.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",