@atlaskit/ads-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +134 -0
  3. package/bin/ads-cli.js +40 -0
  4. package/compass.yml +25 -0
  5. package/dist/cjs/cli.js +488 -0
  6. package/dist/cjs/commands/definitions.js +713 -0
  7. package/dist/cjs/commands/get-command.js +19 -0
  8. package/dist/cjs/commands/import-tool-handler.js +57 -0
  9. package/dist/cjs/commands/run-tool.js +106 -0
  10. package/dist/cjs/commands/types.js +1 -0
  11. package/dist/cjs/envelope/create-error-envelope.js +27 -0
  12. package/dist/cjs/envelope/create-success-envelope.js +38 -0
  13. package/dist/cjs/envelope/types.js +1 -0
  14. package/dist/cjs/output/disambiguation.js +31 -0
  15. package/dist/cjs/output/format-component.js +99 -0
  16. package/dist/cjs/output/format-disambiguation.js +29 -0
  17. package/dist/cjs/output/format-doc-object.js +115 -0
  18. package/dist/cjs/output/format-grouped-results.js +55 -0
  19. package/dist/cjs/output/format-icon.js +49 -0
  20. package/dist/cjs/output/format-lint-rules.js +52 -0
  21. package/dist/cjs/output/format-results.js +158 -0
  22. package/dist/cjs/output/format-token.js +39 -0
  23. package/dist/cjs/output/parse-lint-rule-records.js +47 -0
  24. package/dist/cjs/output/write-human-error.js +20 -0
  25. package/dist/cjs/output/write-human-result.js +31 -0
  26. package/dist/cjs/output/write-json-envelope.js +20 -0
  27. package/dist/cjs/output/writer.js +32 -0
  28. package/dist/cjs/parse-args.js +106 -0
  29. package/dist/cjs/types.js +53 -0
  30. package/dist/es2019/cli.js +406 -0
  31. package/dist/es2019/commands/definitions.js +683 -0
  32. package/dist/es2019/commands/get-command.js +9 -0
  33. package/dist/es2019/commands/import-tool-handler.js +22 -0
  34. package/dist/es2019/commands/run-tool.js +73 -0
  35. package/dist/es2019/commands/types.js +0 -0
  36. package/dist/es2019/envelope/create-error-envelope.js +20 -0
  37. package/dist/es2019/envelope/create-success-envelope.js +31 -0
  38. package/dist/es2019/envelope/types.js +0 -0
  39. package/dist/es2019/output/disambiguation.js +21 -0
  40. package/dist/es2019/output/format-component.js +88 -0
  41. package/dist/es2019/output/format-disambiguation.js +22 -0
  42. package/dist/es2019/output/format-doc-object.js +94 -0
  43. package/dist/es2019/output/format-grouped-results.js +51 -0
  44. package/dist/es2019/output/format-icon.js +39 -0
  45. package/dist/es2019/output/format-lint-rules.js +43 -0
  46. package/dist/es2019/output/format-results.js +142 -0
  47. package/dist/es2019/output/format-token.js +31 -0
  48. package/dist/es2019/output/parse-lint-rule-records.js +41 -0
  49. package/dist/es2019/output/write-human-error.js +14 -0
  50. package/dist/es2019/output/write-human-result.js +25 -0
  51. package/dist/es2019/output/write-json-envelope.js +15 -0
  52. package/dist/es2019/output/writer.js +22 -0
  53. package/dist/es2019/parse-args.js +100 -0
  54. package/dist/es2019/types.js +47 -0
  55. package/dist/esm/cli.js +484 -0
  56. package/dist/esm/commands/definitions.js +708 -0
  57. package/dist/esm/commands/get-command.js +13 -0
  58. package/dist/esm/commands/import-tool-handler.js +42 -0
  59. package/dist/esm/commands/run-tool.js +99 -0
  60. package/dist/esm/commands/types.js +0 -0
  61. package/dist/esm/envelope/create-error-envelope.js +21 -0
  62. package/dist/esm/envelope/create-success-envelope.js +31 -0
  63. package/dist/esm/envelope/types.js +0 -0
  64. package/dist/esm/output/disambiguation.js +24 -0
  65. package/dist/esm/output/format-component.js +92 -0
  66. package/dist/esm/output/format-disambiguation.js +22 -0
  67. package/dist/esm/output/format-doc-object.js +108 -0
  68. package/dist/esm/output/format-grouped-results.js +50 -0
  69. package/dist/esm/output/format-icon.js +42 -0
  70. package/dist/esm/output/format-lint-rules.js +46 -0
  71. package/dist/esm/output/format-results.js +151 -0
  72. package/dist/esm/output/format-token.js +32 -0
  73. package/dist/esm/output/parse-lint-rule-records.js +41 -0
  74. package/dist/esm/output/write-human-error.js +13 -0
  75. package/dist/esm/output/write-human-result.js +24 -0
  76. package/dist/esm/output/write-json-envelope.js +14 -0
  77. package/dist/esm/output/writer.js +26 -0
  78. package/dist/esm/parse-args.js +100 -0
  79. package/dist/esm/types.js +47 -0
  80. package/dist/types/cli.d.ts +20 -0
  81. package/dist/types/commands/definitions.d.ts +19 -0
  82. package/dist/types/commands/get-command.d.ts +8 -0
  83. package/dist/types/commands/import-tool-handler.d.ts +14 -0
  84. package/dist/types/commands/run-tool.d.ts +37 -0
  85. package/dist/types/commands/types.d.ts +149 -0
  86. package/dist/types/envelope/create-error-envelope.d.ts +12 -0
  87. package/dist/types/envelope/create-success-envelope.d.ts +16 -0
  88. package/dist/types/envelope/types.d.ts +60 -0
  89. package/dist/types/output/disambiguation.d.ts +50 -0
  90. package/dist/types/output/format-component.d.ts +12 -0
  91. package/dist/types/output/format-disambiguation.d.ts +11 -0
  92. package/dist/types/output/format-doc-object.d.ts +15 -0
  93. package/dist/types/output/format-grouped-results.d.ts +14 -0
  94. package/dist/types/output/format-icon.d.ts +13 -0
  95. package/dist/types/output/format-lint-rules.d.ts +14 -0
  96. package/dist/types/output/format-results.d.ts +24 -0
  97. package/dist/types/output/format-token.d.ts +12 -0
  98. package/dist/types/output/parse-lint-rule-records.d.ts +26 -0
  99. package/dist/types/output/write-human-error.d.ts +11 -0
  100. package/dist/types/output/write-human-result.d.ts +14 -0
  101. package/dist/types/output/write-json-envelope.d.ts +14 -0
  102. package/dist/types/output/writer.d.ts +25 -0
  103. package/dist/types/parse-args.d.ts +29 -0
  104. package/dist/types/types.d.ts +53 -0
  105. package/index.js +31 -0
  106. package/package.json +30 -0
@@ -0,0 +1,149 @@
1
+ /**
2
+ * Types for the ADS CLI command registry.
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.
7
+ */
8
+ /**
9
+ * Parsed CLI input handed to a command's `resolve` function.
10
+ */
11
+ export type CommandInput = {
12
+ /**
13
+ * Positional arguments after the command name (e.g. the search terms).
14
+ */
15
+ positionals: string[];
16
+ /**
17
+ * Parsed `--flag` values (numbers, strings, booleans, or repeated string arrays).
18
+ */
19
+ flags: Record<string, unknown>;
20
+ };
21
+ /**
22
+ * A documented flag for a command, surfaced by `--help`.
23
+ */
24
+ export type CommandFlag = {
25
+ name: string;
26
+ type: 'string' | 'number' | 'boolean' | 'string[]';
27
+ description: string;
28
+ alias?: string;
29
+ default?: string | number | boolean;
30
+ };
31
+ /**
32
+ * A single ADS MCP tool invocation. `importPath`/`handlerName` are used to dynamically import
33
+ * the tool at run time, keeping this package a thin dispatcher over the shared exports.
34
+ */
35
+ export type ToolCall = {
36
+ /**
37
+ * A stable key identifying this call within a multi-tool command. For grouped commands
38
+ * (e.g. unified `search`) this becomes the key in the assembled data object, e.g.
39
+ * `components` / `tokens` / `icons`. Ignored for single-tool commands.
40
+ */
41
+ key: string;
42
+ importPath: string;
43
+ handlerName: string;
44
+ args?: unknown;
45
+ };
46
+ /**
47
+ * The successful result of resolving a command: one or more ADS MCP tool calls.
48
+ *
49
+ * Most commands resolve to a single call. Unified commands (e.g. `search` with no `--type`)
50
+ * resolve to several calls whose unwrapped results are grouped by {@link ToolCall.key} into a
51
+ * single data object. `grouped` controls that assembly:
52
+ * - `grouped: false` (default): single call — `data` is that call's unwrapped result.
53
+ * - `grouped: true`: `data` is `{ [key]: unwrappedResult }` across all calls.
54
+ */
55
+ export type ResolvedCommand = {
56
+ tools: ToolCall[];
57
+ grouped?: boolean;
58
+ meta?: Record<string, unknown>;
59
+ };
60
+ /**
61
+ * A resolution that produces its data directly, without calling any ADS MCP tool.
62
+ *
63
+ * Used for friendly, exit-0 "landing" responses such as bare `docs` (which lists the available
64
+ * doc namespaces instead of erroring). The `data` flows through the same render pipeline as a
65
+ * tool result — `formatHuman` for human output, or the JSON envelope for `--json`.
66
+ */
67
+ export type ResolvedStatic = {
68
+ data: unknown;
69
+ meta?: Record<string, unknown>;
70
+ };
71
+ /**
72
+ * The result of resolving a command: a {@link ResolvedCommand} (one or more tool calls), a
73
+ * {@link ResolvedStatic} (pre-computed data), or a usage error.
74
+ */
75
+ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
76
+ error: string;
77
+ };
78
+ /**
79
+ * 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).
84
+ */
85
+ export type RowKind = 'components' | 'tokens' | 'icons';
86
+ /**
87
+ * A single CLI command definition.
88
+ */
89
+ export type CommandDefinition = {
90
+ /**
91
+ * The command name as typed on the CLI, e.g. `search`.
92
+ */
93
+ name: string;
94
+ /**
95
+ * The compact result kind for human output. When set, the default renderer prints one
96
+ * line per result; when omitted, the command uses the generic fallback (JSON for objects,
97
+ * verbatim for strings — e.g. guideline markdown). May depend on input, so it is a function
98
+ * of {@link CommandInput} (e.g. `search --type tokens` renders as tokens).
99
+ */
100
+ resultKind?: (input: CommandInput) => RowKind | undefined;
101
+ /**
102
+ * One-line summary for `--help`.
103
+ */
104
+ description: string;
105
+ /**
106
+ * Usage string, e.g. `search <query...> [--type components|tokens|icons] [--limit N]`.
107
+ */
108
+ usage: string;
109
+ /**
110
+ * Documented flags.
111
+ */
112
+ flags: CommandFlag[];
113
+ /**
114
+ * Example invocations.
115
+ */
116
+ examples: string[];
117
+ /**
118
+ * The envelope `type` suffix used for this command's JSON output, e.g. `search-components`
119
+ * produces `type: "ads-cli/search-components"`. May depend on input (e.g. `search --type
120
+ * tokens` reports `search-tokens`).
121
+ */
122
+ envelopeType: (input: CommandInput) => string;
123
+ /**
124
+ * Optional human-readable renderer for this command's (non-grouped) result.
125
+ *
126
+ * Commands whose tool returns a single rich object — rather than an array of rows that
127
+ * {@link resultKind} can render — supply this to produce readable text (e.g. a component
128
+ * doc, an a11y guide, or lint-rule markdown) instead of falling back to a raw JSON dump.
129
+ * Returning `null` defers to the generic fallback. Never used for `--json` output.
130
+ */
131
+ formatHuman?: (data: unknown) => string | null;
132
+ /**
133
+ * Optional post-processor applied to a single-tool command's unwrapped result before
134
+ * rendering (both human and `--json`). Used by the item commands (`component`/`token`/`icon`)
135
+ * to turn a ranked candidate list into an exact-match detail or a disambiguation list —
136
+ * without re-ranking (it only *selects* an exact name match from the tool's own results, so
137
+ * the zero-drift contract with `@atlaskit/ads-mcp` holds). Not applied to grouped, static,
138
+ * or error results.
139
+ */
140
+ transform?: ({ data, input }: {
141
+ data: unknown;
142
+ input: CommandInput;
143
+ }) => unknown;
144
+ /**
145
+ * Resolve which ADS MCP tool to run and with what arguments. Returning `{ error }` means
146
+ * the input was invalid (a usage error); the CLI surfaces the message.
147
+ */
148
+ resolve: (input: CommandInput) => ResolveResult;
149
+ };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Builder for the error variant of the CLI's JSON output envelope.
3
+ */
4
+ import type { EnvelopeErrorCode, ErrorEnvelope } from './types';
5
+ /**
6
+ * Build an error envelope for a command.
7
+ */
8
+ export declare const createErrorEnvelope: ({ command, code, message, }: {
9
+ command: string;
10
+ code: EnvelopeErrorCode;
11
+ message: string;
12
+ }) => ErrorEnvelope;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Builder for the success variant of the CLI's JSON output envelope.
3
+ */
4
+ import type { EnvelopeMeta, SuccessEnvelope } from './types';
5
+ /**
6
+ * Build a success envelope for a command.
7
+ *
8
+ * The `type` discriminator is derived from the envelope type name supplied by the command's
9
+ * registry entry. When `data` is an array, `count` is auto-derived into `meta`.
10
+ */
11
+ export declare const createSuccessEnvelope: <Data>({ envelopeType, command, data, meta, }: {
12
+ envelopeType: string;
13
+ command: string;
14
+ data: Data;
15
+ meta?: EnvelopeMeta;
16
+ }) => SuccessEnvelope<Data>;
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Types for the stable JSON envelope emitted when the CLI is run with `--json`.
3
+ *
4
+ * Agents (and a future `atlas ads` plugin) consume this shape, so it must stay stable and
5
+ * self-describing. Every envelope carries a `type` discriminator (`ads-cli/<command>` for
6
+ * success, `ads-cli/error` for failures) so consumers can branch without re-parsing.
7
+ */
8
+ /**
9
+ * Metadata describing how a command was invoked and how many results it produced.
10
+ *
11
+ * This is intentionally open-ended (`[key: string]: unknown`) so individual commands can
12
+ * attach their own context (query terms, limit, requested type, etc.) without a schema
13
+ * change.
14
+ */
15
+ export type EnvelopeMeta = {
16
+ /**
17
+ * Number of top-level results in `data`, when `data` is an array.
18
+ */
19
+ count?: number;
20
+ [key: string]: unknown;
21
+ };
22
+ /**
23
+ * Successful command envelope.
24
+ *
25
+ * `data` holds the (already JSON-parsed where possible) payload returned by the underlying
26
+ * ADS MCP tool.
27
+ */
28
+ export type SuccessEnvelope<Data = unknown> = {
29
+ /**
30
+ * Discriminator, e.g. `ads-cli/search-components`.
31
+ */
32
+ type: string;
33
+ /**
34
+ * The CLI command name that produced this envelope, e.g. `search`.
35
+ */
36
+ command: string;
37
+ ok: true;
38
+ data: Data;
39
+ meta: EnvelopeMeta;
40
+ };
41
+ /**
42
+ * Machine-readable error codes used inside {@link ErrorEnvelope}.
43
+ *
44
+ * These mirror the process exit codes but are surfaced as strings so JSON consumers do not
45
+ * depend on numeric codes.
46
+ */
47
+ export type EnvelopeErrorCode = 'USAGE_ERROR' | 'NOT_FOUND' | 'RUNTIME_ERROR';
48
+ /**
49
+ * Failure envelope. Emitted (with `--json`) when a command cannot complete.
50
+ */
51
+ export type ErrorEnvelope = {
52
+ type: 'ads-cli/error';
53
+ command: string;
54
+ ok: false;
55
+ error: {
56
+ code: EnvelopeErrorCode;
57
+ message: string;
58
+ };
59
+ };
60
+ export type Envelope<Data = unknown> = SuccessEnvelope<Data> | ErrorEnvelope;
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Shared shape and type guard for an "ambiguous lookup" result.
3
+ *
4
+ * When an item command (`component`/`token`/`icon`) is given a name that fuzzy-matches multiple
5
+ * entries and none is an exact name match, the command's `transform` produces one of these
6
+ * instead of a single detail object. Both the human renderer and the `--json` envelope then
7
+ * present a "did you mean?" candidate list rather than silently picking the top fuzzy hit.
8
+ */
9
+ /**
10
+ * A candidate surfaced in a disambiguation result.
11
+ */
12
+ export type DisambiguationCandidate = {
13
+ /**
14
+ * The display name of the candidate (e.g. `ButtonGroup`, `space.100`, `AddIcon`).
15
+ */
16
+ name: string;
17
+ /**
18
+ * Optional secondary detail shown after the name (e.g. the package or example value).
19
+ */
20
+ hint?: string;
21
+ /**
22
+ * The follow-up command that drills into this exact candidate, e.g. `component ButtonGroup`.
23
+ */
24
+ followUp: string;
25
+ };
26
+ /**
27
+ * The marker object a `transform` returns when a lookup is ambiguous.
28
+ */
29
+ export type DisambiguationResult = {
30
+ /**
31
+ * Discriminator so both the type guard and JSON consumers can detect the ambiguous case.
32
+ */
33
+ ambiguous: true;
34
+ /**
35
+ * The term the user searched for.
36
+ */
37
+ query: string;
38
+ /**
39
+ * The command noun (`component`/`token`/`icon`) — used in the prompt copy.
40
+ */
41
+ noun: string;
42
+ /**
43
+ * The ranked candidates the user can choose from.
44
+ */
45
+ candidates: DisambiguationCandidate[];
46
+ };
47
+ /**
48
+ * Narrow an unknown value to a {@link DisambiguationResult}.
49
+ */
50
+ export declare const isDisambiguation: (value: unknown) => value is DisambiguationResult;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Human-readable renderer for a single ADS component's detailed docs.
3
+ *
4
+ * Renders the `component <Name>` view: a readable header, a props table, and the usage examples —
5
+ * instead of dumping the raw JSON payload. Full structured data (including the `designSource` link
6
+ * and untruncated types) remains available via `--json`.
7
+ */
8
+ /**
9
+ * Render a single component payload as detailed, human-readable docs. Returns `null` when the
10
+ * data is not a recognisable component object, so the caller can fall back to generic rendering.
11
+ */
12
+ export declare const formatComponent: (data: unknown) => string | null;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Human-readable renderer for an ambiguous item lookup ("did you mean?").
3
+ */
4
+ import type { DisambiguationResult } from './disambiguation';
5
+ /**
6
+ * Render a "did you mean?" list for an ambiguous lookup.
7
+ *
8
+ * Mirrors the compact search rows (name, optional hint, and a `→ <follow-up>` command) so the
9
+ * output is consistent with `search`, and tells the user how to disambiguate.
10
+ */
11
+ export declare const formatDisambiguation: ({ query, noun, candidates }: DisambiguationResult) => string;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Human-readable renderer for a single "doc object" payload — the shape returned by the
3
+ * accessibility (`docs a11y`) and migration (`docs migration`) tools.
4
+ *
5
+ * These tools return a structured object (title, description, and several labelled lists such
6
+ * as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
7
+ * rather than raw JSON; `--json` still exposes the full structured payload.
8
+ */
9
+ /**
10
+ * Render a doc-object payload as readable text. Handles both the full guide shape (a11y guidance,
11
+ * migration guide — keyed by `title`) and the topic-index shape the a11y tool returns when no
12
+ * topic is given (keyed by `message` + `availableTopics`). Returns `null` when the data is not a
13
+ * recognisable doc object so the caller can fall back to generic rendering.
14
+ */
15
+ export declare const formatDocObject: (data: unknown) => string | null;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Sectioned compact renderer for grouped (multi-kind) results, e.g. unified `search`.
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.
7
+ */
8
+ /**
9
+ * Render grouped results as sectioned compact output.
10
+ */
11
+ export declare const formatGroupedResults: ({ groups, totalCount, }: {
12
+ groups: Record<string, unknown[]>;
13
+ totalCount: number;
14
+ }) => string;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Human-readable renderer for a single ADS icon's detail view.
3
+ *
4
+ * The icon dataset provides `componentName`, `package` (the exact subpath entry-point), and a
5
+ * `usage` note. The detail view surfaces the copy-paste `import` line — the actionable thing a
6
+ * consumer needs — alongside the usage guidance. Full structured data remains available via
7
+ * `--json`.
8
+ */
9
+ /**
10
+ * Render a single icon payload as a detail view. Returns `null` when the data is not a
11
+ * recognisable icon object, so the caller can fall back to generic rendering.
12
+ */
13
+ export declare const formatIcon: (data: unknown) => string | null;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Human-readable renderer for the `lint-rules` payload.
3
+ *
4
+ * `getLintRulesTool` returns one record per matching ESLint rule, each with a `content` field
5
+ * that is already Markdown documentation for the rule. The default output prints that Markdown
6
+ * verbatim (joined across multiple rules) rather than dumping the raw JSON. Full structured data
7
+ * remains available via `--json`.
8
+ */
9
+ /**
10
+ * Render the lint-rules payload as readable Markdown. Handles both the array form (multiple
11
+ * matching rules) and the single-object form. Returns `null` for unrecognised shapes so the
12
+ * caller can fall back to generic rendering.
13
+ */
14
+ export declare const formatLintRules: (data: unknown) => string | null;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Compact, human-readable renderers for the structured search/list results.
3
+ *
4
+ * The underlying ADS MCP tools return rich JSON arrays. Dumping that raw is unreadable at a
5
+ * terminal, so the default (non-`--json`) output renders a compact one line per result. Full
6
+ * structured data remains available via `--json`.
7
+ *
8
+ * Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
9
+ * left to the caller's generic fallback.
10
+ */
11
+ import type { RowKind } from '../commands/types';
12
+ /**
13
+ * Render an array of results as compact lines for the given kind. Returns `null` when the data
14
+ * is not an array (so the caller can fall back to generic JSON rendering).
15
+ *
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.
19
+ */
20
+ export declare const formatCompactResults: ({ kind, data, showFollowUp, }: {
21
+ kind: RowKind;
22
+ data: unknown;
23
+ showFollowUp?: boolean;
24
+ }) => string | null;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Human-readable renderer for a single ADS design token's detail view.
3
+ *
4
+ * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
5
+ * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
6
+ * Full structured data remains available via `--json`.
7
+ */
8
+ /**
9
+ * Render a single token payload as a detail view. Returns `null` when the data is not a
10
+ * recognisable token object, so the caller can fall back to generic rendering.
11
+ */
12
+ export declare const formatToken: (data: unknown) => string | null;
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Shared parser for the `get-lint-rules` payload.
3
+ *
4
+ * `getLintRulesTool` double-encodes its rule records: each is a JSON *string literal* (a bare
5
+ * string for a single match, or an array of such strings for multiple matches), so the generic
6
+ * unwrap yields a value that still looks like JSON. This module undoes that second layer so both
7
+ * the human renderer (`format-lint-rules`) and the `lint-rules` command's disambiguation logic
8
+ * work against real rule objects rather than raw strings.
9
+ */
10
+ /**
11
+ * A single lint-rule record as returned by `getLintRulesTool`. Only the fields the CLI needs are
12
+ * modelled.
13
+ */
14
+ export type LintRule = {
15
+ ruleName?: string;
16
+ description?: string;
17
+ content?: string;
18
+ };
19
+ /**
20
+ * Parse the get-lint-rules payload into rule records, undoing the double-encoded JSON layer.
21
+ *
22
+ * For a single match `data` is one JSON string literal; for multiple matches it is an array whose
23
+ * elements are each a JSON string literal — so parse both the top-level value and every array
24
+ * element. Elements that are not JSON strings are left untouched (callers guard the shape).
25
+ */
26
+ export declare const parseLintRuleRecords: (data: unknown) => LintRule[];
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Human-readable rendering of a command error.
3
+ */
4
+ import type { Writer } from './writer';
5
+ /**
6
+ * Emit a human-readable error to stderr.
7
+ */
8
+ export declare const writeHumanError: ({ message, writer }: {
9
+ message: string;
10
+ writer: Writer;
11
+ }) => void;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Human-readable rendering of a successful command result.
3
+ */
4
+ import type { Writer } from './writer';
5
+ /**
6
+ * Emit a human-readable rendering of a successful result to stdout.
7
+ *
8
+ * Structured data is pretty-printed as JSON (the underlying tools already return rich
9
+ * objects), while plain-string payloads such as guideline markdown are printed verbatim.
10
+ */
11
+ export declare const writeHumanResult: ({ data, writer }: {
12
+ data: unknown;
13
+ writer: Writer;
14
+ }) => void;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Emit the JSON envelope to stdout.
3
+ */
4
+ import type { Envelope } from '../envelope/types';
5
+ import type { Writer } from './writer';
6
+ /**
7
+ * Emit the JSON envelope to stdout.
8
+ *
9
+ * Always pretty-printed for readability; consumers that need compact output can re-serialise.
10
+ */
11
+ export declare const writeJsonEnvelope: ({ envelope, writer, }: {
12
+ envelope: Envelope;
13
+ writer: Writer;
14
+ }) => void;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The output sink abstraction and its default console-backed implementation.
3
+ *
4
+ * Output contract (see README): data goes to stdout ONLY; all logs, hints, and errors go to
5
+ * stderr. Keeping the stdout/stderr split behind this small interface means `--json` output
6
+ * stays clean for piping, and tests can capture output deterministically.
7
+ */
8
+ /**
9
+ * Thin indirection over the console so tests can capture output and so we keep the
10
+ * stdout/stderr split in exactly one place.
11
+ */
12
+ export type Writer = {
13
+ /**
14
+ * Write a line of data to stdout.
15
+ */
16
+ out: (line: string) => void;
17
+ /**
18
+ * Write a line of diagnostics to stderr.
19
+ */
20
+ err: (line: string) => void;
21
+ };
22
+ /**
23
+ * The default writer, backed by `console.log` (stdout) and `console.error` (stderr).
24
+ */
25
+ export declare const defaultWriter: Writer;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Lightweight, dependency-free argument parser for the ADS CLI.
3
+ *
4
+ * We hand-roll parsing (rather than pulling in an argument-parsing library) so that `run(argv)`
5
+ * is deterministic and unit-testable with an explicit argv array, and so the exact flag semantics
6
+ * (value flags vs boolean flags, `--flag=value`, short aliases) stay under our control.
7
+ *
8
+ * The parser produces a normalised {@link ParsedArgs} that the CLI then routes through the
9
+ * command registry.
10
+ */
11
+ export type ParsedArgs = {
12
+ /**
13
+ * The command name (first non-flag token), or undefined if none was given.
14
+ */
15
+ command?: string;
16
+ /**
17
+ * Positional arguments belonging to the command.
18
+ */
19
+ positionals: string[];
20
+ /**
21
+ * Parsed flags. Values may be string, number-like string, boolean, or string[].
22
+ */
23
+ flags: Record<string, unknown>;
24
+ };
25
+ /**
26
+ * Parse an argv array (already stripped of `node` and the script path) into a normalised
27
+ * command + positionals + flags structure.
28
+ */
29
+ export declare const parseArgs: (argv: string[]) => ParsedArgs;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Shared types for the ADS CLI.
3
+ *
4
+ * The CLI is a thin layer over the `@atlaskit/ads-mcp/tools/*` exports. Every underlying
5
+ * tool is an async function that resolves to an MCP-shaped result: `{ content: [...] }`
6
+ * where each content item is a `{ type: 'text', text: string }` block. These types model
7
+ * that contract plus the CLI's own command registry and JSON output envelope.
8
+ */
9
+ /**
10
+ * A single content block returned by an ADS MCP tool. Only the `text` variant is used by
11
+ * the tools this CLI wraps, but we keep the `type` field so the shape stays faithful to
12
+ * the MCP `CallToolResult` contract.
13
+ */
14
+ export type ToolContentItem = {
15
+ type: string;
16
+ text?: string;
17
+ };
18
+ /**
19
+ * The MCP-shaped result returned by every `@atlaskit/ads-mcp/tools/*` handler.
20
+ */
21
+ export type ToolResult = {
22
+ content: ToolContentItem[];
23
+ isError?: boolean;
24
+ };
25
+ /**
26
+ * Any ADS MCP tool handler: takes an optional arguments object and resolves to a
27
+ * {@link ToolResult}. Kept intentionally loose (`unknown` args) because each tool has its
28
+ * own zod input schema; the registry is responsible for building well-formed args.
29
+ */
30
+ export type ToolHandler = (args?: unknown) => Promise<ToolResult>;
31
+ /**
32
+ * Stable, documented process exit codes. Kept as a const enum-like object (not a TS enum)
33
+ * so the values are inlined and easy to assert against in tests.
34
+ */
35
+ export declare const ExitCode: {
36
+ /**
37
+ * Command completed successfully.
38
+ */
39
+ readonly Ok: 0;
40
+ /**
41
+ * An unexpected runtime error occurred while executing a command.
42
+ */
43
+ readonly RuntimeError: 1;
44
+ /**
45
+ * The user supplied invalid arguments or an unknown command.
46
+ */
47
+ readonly UsageError: 2;
48
+ /**
49
+ * The command ran successfully but found no matching results.
50
+ */
51
+ readonly NotFound: 3;
52
+ };
53
+ export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
package/index.js ADDED
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Custom `main` entrypoint that switches between source (in the monorepo) and the
3
+ * built `dist/cjs` output (when published to npm), mirroring the sibling
4
+ * `@atlaskit/codemod-cli` package.
5
+ *
6
+ * When required from inside the monorepo the compiled output does not exist, so we
7
+ * register `@atlassian/ts-loader` (the AFM-blessed `tsx`-based require hook) and load
8
+ * the TypeScript source directly. When installed from npm (e.g. via
9
+ * `npx @atlaskit/ads-cli`) the `tsconfig.json` is stripped by `.npmignore`, so we fall
10
+ * through to the pre-built CommonJS bundle.
11
+ */
12
+ /* eslint-disable global-require, import/no-dynamic-require */
13
+
14
+ const fs = require('fs');
15
+ const path = require('path');
16
+
17
+ // The presence of tsconfig.json indicates we are running from source in the monorepo.
18
+ const isDev = fs.existsSync(path.join(__dirname, 'tsconfig.json'));
19
+
20
+ let entrypoint = path.join(__dirname, 'dist', 'cjs', 'cli');
21
+
22
+ if (isDev) {
23
+ // `@atlassian/ts-loader` registers `tsx` require hooks so the TypeScript source
24
+ // (including `.tsx` files and cross-package imports) can be `require`d directly
25
+ // without a pre-build step. Unlike `ts-node`, it supports TS Project References.
26
+ // eslint-disable-next-line import/no-extraneous-dependencies
27
+ require('@atlassian/ts-loader');
28
+ entrypoint = path.join(__dirname, 'src', 'cli');
29
+ }
30
+
31
+ module.exports = require(entrypoint);
package/package.json ADDED
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "@atlaskit/ads-cli",
3
+ "version": "0.1.0",
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
+ "author": "Atlassian Pty Ltd",
6
+ "license": "Apache-2.0",
7
+ "homepage": "https://atlaskit.atlassian.com/packages/design-system/ads-cli",
8
+ "publishConfig": {
9
+ "registry": "https://registry.npmjs.org/"
10
+ },
11
+ "atlassian": {
12
+ "team": "Design System Team"
13
+ },
14
+ "repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
15
+ "main": "index.js",
16
+ "types": "dist/types/cli.d.ts",
17
+ "atlaskit:src": "src/cli.tsx",
18
+ "bin": "./bin/ads-cli.js",
19
+ "scripts": {
20
+ "start": "./bin/ads-cli.js"
21
+ },
22
+ "dependencies": {
23
+ "@atlaskit/ads-mcp": "^1.7.0",
24
+ "@babel/runtime": "^7.0.0",
25
+ "chalk": "^4.1.2"
26
+ },
27
+ "devDependencies": {
28
+ "@atlassian/ts-loader": "^0.1.0"
29
+ }
30
+ }