@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.
- package/CHANGELOG.md +34 -0
- package/README.md +134 -0
- package/bin/ads-cli.js +40 -0
- package/compass.yml +25 -0
- package/dist/cjs/cli.js +488 -0
- package/dist/cjs/commands/definitions.js +713 -0
- package/dist/cjs/commands/get-command.js +19 -0
- package/dist/cjs/commands/import-tool-handler.js +57 -0
- package/dist/cjs/commands/run-tool.js +106 -0
- package/dist/cjs/commands/types.js +1 -0
- package/dist/cjs/envelope/create-error-envelope.js +27 -0
- package/dist/cjs/envelope/create-success-envelope.js +38 -0
- package/dist/cjs/envelope/types.js +1 -0
- package/dist/cjs/output/disambiguation.js +31 -0
- package/dist/cjs/output/format-component.js +99 -0
- package/dist/cjs/output/format-disambiguation.js +29 -0
- package/dist/cjs/output/format-doc-object.js +115 -0
- package/dist/cjs/output/format-grouped-results.js +55 -0
- package/dist/cjs/output/format-icon.js +49 -0
- package/dist/cjs/output/format-lint-rules.js +52 -0
- package/dist/cjs/output/format-results.js +158 -0
- package/dist/cjs/output/format-token.js +39 -0
- package/dist/cjs/output/parse-lint-rule-records.js +47 -0
- package/dist/cjs/output/write-human-error.js +20 -0
- package/dist/cjs/output/write-human-result.js +31 -0
- package/dist/cjs/output/write-json-envelope.js +20 -0
- package/dist/cjs/output/writer.js +32 -0
- package/dist/cjs/parse-args.js +106 -0
- package/dist/cjs/types.js +53 -0
- package/dist/es2019/cli.js +406 -0
- package/dist/es2019/commands/definitions.js +683 -0
- package/dist/es2019/commands/get-command.js +9 -0
- package/dist/es2019/commands/import-tool-handler.js +22 -0
- package/dist/es2019/commands/run-tool.js +73 -0
- package/dist/es2019/commands/types.js +0 -0
- package/dist/es2019/envelope/create-error-envelope.js +20 -0
- package/dist/es2019/envelope/create-success-envelope.js +31 -0
- package/dist/es2019/envelope/types.js +0 -0
- package/dist/es2019/output/disambiguation.js +21 -0
- package/dist/es2019/output/format-component.js +88 -0
- package/dist/es2019/output/format-disambiguation.js +22 -0
- package/dist/es2019/output/format-doc-object.js +94 -0
- package/dist/es2019/output/format-grouped-results.js +51 -0
- package/dist/es2019/output/format-icon.js +39 -0
- package/dist/es2019/output/format-lint-rules.js +43 -0
- package/dist/es2019/output/format-results.js +142 -0
- package/dist/es2019/output/format-token.js +31 -0
- package/dist/es2019/output/parse-lint-rule-records.js +41 -0
- package/dist/es2019/output/write-human-error.js +14 -0
- package/dist/es2019/output/write-human-result.js +25 -0
- package/dist/es2019/output/write-json-envelope.js +15 -0
- package/dist/es2019/output/writer.js +22 -0
- package/dist/es2019/parse-args.js +100 -0
- package/dist/es2019/types.js +47 -0
- package/dist/esm/cli.js +484 -0
- package/dist/esm/commands/definitions.js +708 -0
- package/dist/esm/commands/get-command.js +13 -0
- package/dist/esm/commands/import-tool-handler.js +42 -0
- package/dist/esm/commands/run-tool.js +99 -0
- package/dist/esm/commands/types.js +0 -0
- package/dist/esm/envelope/create-error-envelope.js +21 -0
- package/dist/esm/envelope/create-success-envelope.js +31 -0
- package/dist/esm/envelope/types.js +0 -0
- package/dist/esm/output/disambiguation.js +24 -0
- package/dist/esm/output/format-component.js +92 -0
- package/dist/esm/output/format-disambiguation.js +22 -0
- package/dist/esm/output/format-doc-object.js +108 -0
- package/dist/esm/output/format-grouped-results.js +50 -0
- package/dist/esm/output/format-icon.js +42 -0
- package/dist/esm/output/format-lint-rules.js +46 -0
- package/dist/esm/output/format-results.js +151 -0
- package/dist/esm/output/format-token.js +32 -0
- package/dist/esm/output/parse-lint-rule-records.js +41 -0
- package/dist/esm/output/write-human-error.js +13 -0
- package/dist/esm/output/write-human-result.js +24 -0
- package/dist/esm/output/write-json-envelope.js +14 -0
- package/dist/esm/output/writer.js +26 -0
- package/dist/esm/parse-args.js +100 -0
- package/dist/esm/types.js +47 -0
- package/dist/types/cli.d.ts +20 -0
- package/dist/types/commands/definitions.d.ts +19 -0
- package/dist/types/commands/get-command.d.ts +8 -0
- package/dist/types/commands/import-tool-handler.d.ts +14 -0
- package/dist/types/commands/run-tool.d.ts +37 -0
- package/dist/types/commands/types.d.ts +149 -0
- package/dist/types/envelope/create-error-envelope.d.ts +12 -0
- package/dist/types/envelope/create-success-envelope.d.ts +16 -0
- package/dist/types/envelope/types.d.ts +60 -0
- package/dist/types/output/disambiguation.d.ts +50 -0
- package/dist/types/output/format-component.d.ts +12 -0
- package/dist/types/output/format-disambiguation.d.ts +11 -0
- package/dist/types/output/format-doc-object.d.ts +15 -0
- package/dist/types/output/format-grouped-results.d.ts +14 -0
- package/dist/types/output/format-icon.d.ts +13 -0
- package/dist/types/output/format-lint-rules.d.ts +14 -0
- package/dist/types/output/format-results.d.ts +24 -0
- package/dist/types/output/format-token.d.ts +12 -0
- package/dist/types/output/parse-lint-rule-records.d.ts +26 -0
- package/dist/types/output/write-human-error.d.ts +11 -0
- package/dist/types/output/write-human-result.d.ts +14 -0
- package/dist/types/output/write-json-envelope.d.ts +14 -0
- package/dist/types/output/writer.d.ts +25 -0
- package/dist/types/parse-args.d.ts +29 -0
- package/dist/types/types.d.ts +53 -0
- package/index.js +31 -0
- package/package.json +30 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# @atlaskit/ads-cli
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [`a5eabf99c6345`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/a5eabf99c6345) -
|
|
8
|
+
Add `@atlaskit/ads-cli`: an npx-runnable CLI to query ADS structured content as a thin, zero-drift
|
|
9
|
+
layer over the `@atlaskit/ads-mcp` tools. Commands:
|
|
10
|
+
- `search <query...>` — unified search across components, tokens, and icons at once (grouped by
|
|
11
|
+
kind); narrow with `--type`.
|
|
12
|
+
- `component <name>` / `token <name>` / `icon <name>` — the detail view for a single item; pass
|
|
13
|
+
`--all` to list every entry of that kind (the icon view includes a copy-paste import).
|
|
14
|
+
- `lint-rules [term...]` — ADS ESLint rules; a fuzzy term that matches several rules shows a "did
|
|
15
|
+
you mean?" list (like the item commands), while a unique/exact match prints the rule's docs
|
|
16
|
+
(`--limit` caps the list).
|
|
17
|
+
- `docs <topic...>` — ADS reference docs: `docs <term>` (foundations), `docs a11y [topic]`
|
|
18
|
+
(accessibility), and `docs migration <id>` (migration guides).
|
|
19
|
+
|
|
20
|
+
Default output is a compact, human-readable view; `--json` emits a stable envelope with documented
|
|
21
|
+
exit codes (0 ok, 1 runtime, 2 usage, 3 not-found).
|
|
22
|
+
|
|
23
|
+
Usage:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
# Unified search across components, tokens, and icons
|
|
27
|
+
npx @atlaskit/ads-cli search button
|
|
28
|
+
|
|
29
|
+
# Detail for a single component (machine-readable envelope)
|
|
30
|
+
npx @atlaskit/ads-cli component Button --json
|
|
31
|
+
|
|
32
|
+
# Read a foundations doc
|
|
33
|
+
npx @atlaskit/ads-cli docs spacing
|
|
34
|
+
```
|
package/README.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# @atlaskit/ads-cli
|
|
2
|
+
|
|
3
|
+
An `npx`-runnable command-line tool to query **Atlassian Design System (ADS) structured content** —
|
|
4
|
+
components, tokens, icons, and guidelines — directly from your terminal.
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
npx @atlaskit/ads-cli search button
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
It is a thin, zero-drift layer over the shared `@atlaskit/ads-mcp/tools/*` exports: the same query
|
|
11
|
+
logic that powers the ADS MCP server and the `atlassian-design-system` agent skill. The CLI never
|
|
12
|
+
reimplements search ranking or bundles its own copy of the dataset — there is one source of truth.
|
|
13
|
+
|
|
14
|
+
## Why
|
|
15
|
+
|
|
16
|
+
Distributing ADS structured content through a CLI lets developers **and coding agents** query
|
|
17
|
+
components from the terminal without configuring an MCP client. Human-readable output is the
|
|
18
|
+
default; `--json` emits a stable, self-describing envelope for machine consumers.
|
|
19
|
+
|
|
20
|
+
## Commands
|
|
21
|
+
|
|
22
|
+
The CLI has these commands:
|
|
23
|
+
|
|
24
|
+
| Command | Description |
|
|
25
|
+
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
|
+
| `search <query...>` | **Unified** fuzzy-search across components, tokens, and icons at once. Narrow with `--type component\|token\|icon`; limit with `--limit N`. |
|
|
27
|
+
| `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
|
|
28
|
+
| `token <name>` | Detail for a single token. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token. |
|
|
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
|
+
| `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
|
+
| `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
|
+
|
|
33
|
+
### Global flags
|
|
34
|
+
|
|
35
|
+
- `--json` — emit a machine-readable JSON envelope on stdout.
|
|
36
|
+
- `--help`, `-h` — show help.
|
|
37
|
+
- `--version`, `-v` — show the CLI version.
|
|
38
|
+
|
|
39
|
+
## Examples
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
# Unified human-readable search — components, tokens, and icons grouped together
|
|
43
|
+
npx @atlaskit/ads-cli search button
|
|
44
|
+
|
|
45
|
+
# Narrow to a single kind
|
|
46
|
+
npx @atlaskit/ads-cli search space color --type token
|
|
47
|
+
|
|
48
|
+
# Detail for a single component, token, or icon
|
|
49
|
+
npx @atlaskit/ads-cli component Avatar
|
|
50
|
+
npx @atlaskit/ads-cli token space.100
|
|
51
|
+
npx @atlaskit/ads-cli icon AddIcon
|
|
52
|
+
|
|
53
|
+
# List every entry of a kind
|
|
54
|
+
npx @atlaskit/ads-cli icon --all
|
|
55
|
+
|
|
56
|
+
# Reference docs — foundations, accessibility, migrations
|
|
57
|
+
npx @atlaskit/ads-cli docs spacing
|
|
58
|
+
npx @atlaskit/ads-cli docs a11y buttons
|
|
59
|
+
npx @atlaskit/ads-cli docs migration motion
|
|
60
|
+
|
|
61
|
+
# Machine-readable envelope for agents / jq
|
|
62
|
+
npx @atlaskit/ads-cli search button --json
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Output contract
|
|
66
|
+
|
|
67
|
+
- **Every command is human-readable by default; `--json` is the only path to structured output.**
|
|
68
|
+
`search` and the `--all` listings print one compact line per result (e.g.
|
|
69
|
+
`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
|
+
- **Lookups never silently guess.** `component`/`token`/`icon <name>` — and a fuzzy
|
|
76
|
+
`lint-rules <term>` — render the entry whose name matches exactly (case-insensitively). If there
|
|
77
|
+
is no exact match but several candidates, they print a `Did you mean?` list (each with a
|
|
78
|
+
`→ ads-cli <command>` follow-up) and exit `0` — under `--json` this is
|
|
79
|
+
`{ "ambiguous": true, "query", "noun", "candidates": [...] }`.
|
|
80
|
+
- **Data is written to stdout only.** Logs, hints, and errors go to **stderr**. This keeps `--json`
|
|
81
|
+
output clean for piping.
|
|
82
|
+
- With `--json`, every success prints a `SuccessEnvelope` and every failure prints an
|
|
83
|
+
`ErrorEnvelope`:
|
|
84
|
+
|
|
85
|
+
```jsonc
|
|
86
|
+
// success — unified search groups data by kind
|
|
87
|
+
{
|
|
88
|
+
"type": "ads-cli/search",
|
|
89
|
+
"command": "search",
|
|
90
|
+
"ok": true,
|
|
91
|
+
"data": { "components": [ /* … */ ], "tokens": [ /* … */ ], "icons": [ /* … */ ] },
|
|
92
|
+
"meta": { "terms": ["button"], "count": 12 }
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// success — a narrowed (--type) or single-tool command returns a flat array
|
|
96
|
+
{
|
|
97
|
+
"type": "ads-cli/search-components",
|
|
98
|
+
"command": "search",
|
|
99
|
+
"ok": true,
|
|
100
|
+
"data": [ /* tool output */ ],
|
|
101
|
+
"meta": { "terms": ["avatar"], "limit": 5, "count": 2 }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// failure
|
|
105
|
+
{
|
|
106
|
+
"type": "ads-cli/error",
|
|
107
|
+
"command": "search",
|
|
108
|
+
"ok": false,
|
|
109
|
+
"error": { "code": "NOT_FOUND", "message": "No ADS components found for 'zzz'." }
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The `type` discriminator (`ads-cli/<command>` or `ads-cli/error`) lets consumers branch without
|
|
114
|
+
re-parsing.
|
|
115
|
+
|
|
116
|
+
## Exit codes
|
|
117
|
+
|
|
118
|
+
| Code | Meaning |
|
|
119
|
+
| ---- | --------------------------------------------------- |
|
|
120
|
+
| `0` | Success. |
|
|
121
|
+
| `1` | Unexpected runtime error. |
|
|
122
|
+
| `2` | Usage error (invalid arguments or unknown command). |
|
|
123
|
+
| `3` | No matching results found. |
|
|
124
|
+
|
|
125
|
+
## Relationship to the ADS MCP server and skill
|
|
126
|
+
|
|
127
|
+
This CLI, the [`@atlaskit/ads-mcp`](../ads-mcp) server, and the `atlassian-design-system` agent
|
|
128
|
+
skill are all thin surfaces over the **same** `@atlaskit/ads-mcp/tools/*` query logic and bundled
|
|
129
|
+
`ComponentMcpPayload[]` dataset. Adding or improving a tool in `ads-mcp` is automatically reflected
|
|
130
|
+
here.
|
|
131
|
+
|
|
132
|
+
> **Note:** An `atlas ads` plugin (for the Atlas CLI) is a separate future distribution path. The
|
|
133
|
+
> `--json` envelope here is intentionally structured so it can be wrapped by that plugin later
|
|
134
|
+
> without changes to this package.
|
package/bin/ads-cli.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/* eslint-disable */
|
|
3
|
+
/* prettier-ignore */
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Executable entrypoint for `npx @atlaskit/ads-cli`.
|
|
7
|
+
*
|
|
8
|
+
* Like `index.js`, this switches between the TypeScript source (when running inside the
|
|
9
|
+
* monorepo) and the built `dist/cjs` output (when installed from npm). It then invokes
|
|
10
|
+
* the exported `run()` function and maps thrown numeric values to process exit codes so
|
|
11
|
+
* commands can signal a specific exit status by throwing a number.
|
|
12
|
+
*/
|
|
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
|
+
if (isDev) {
|
|
21
|
+
// `@atlassian/ts-loader` registers `tsx` require hooks so the TypeScript source
|
|
22
|
+
// (including `.tsx` files and cross-package imports) can be `require`d directly
|
|
23
|
+
// without a pre-build step. Unlike `ts-node`, it supports TS Project References.
|
|
24
|
+
require('@atlassian/ts-loader');
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
require(path.join('..', isDev ? 'src/cli' : 'dist/cjs/cli'))
|
|
28
|
+
.run(process.argv.slice(2))
|
|
29
|
+
.then((exitCode) => {
|
|
30
|
+
// A resolved numeric value is treated as an explicit exit code.
|
|
31
|
+
process.exit(typeof exitCode === 'number' ? exitCode : 0);
|
|
32
|
+
})
|
|
33
|
+
.catch((error) => {
|
|
34
|
+
// A thrown number is treated as an explicit exit code (e.g. usage errors).
|
|
35
|
+
if (typeof error === 'number') {
|
|
36
|
+
process.exit(error);
|
|
37
|
+
}
|
|
38
|
+
console.error(error);
|
|
39
|
+
process.exit(1);
|
|
40
|
+
});
|
package/compass.yml
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
configVersion: 1
|
|
2
|
+
name: '@atlaskit/ads-cli'
|
|
3
|
+
ownerId: ari:cloud:teams::team/814283d6-8695-4329-b2f8-d78b2645722f # Design System Team (ADS)
|
|
4
|
+
labels:
|
|
5
|
+
- platform-code
|
|
6
|
+
- platform-afm
|
|
7
|
+
typeId: OTHER
|
|
8
|
+
fields:
|
|
9
|
+
tier: 4
|
|
10
|
+
lifecycle: Active
|
|
11
|
+
isMonorepoProject: true
|
|
12
|
+
links:
|
|
13
|
+
- name: Root Repository
|
|
14
|
+
type: REPOSITORY
|
|
15
|
+
url: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master
|
|
16
|
+
- name: Slack Channel
|
|
17
|
+
type: CHAT_CHANNEL
|
|
18
|
+
url: https://atlassian.enterprise.slack.com/archives/CFJ9DU39U # #help-design-system
|
|
19
|
+
- name: Ads Cli
|
|
20
|
+
type: REPOSITORY
|
|
21
|
+
url: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master/platform/packages/design-system/ads-cli
|
|
22
|
+
customFields:
|
|
23
|
+
- name: Department
|
|
24
|
+
type: text
|
|
25
|
+
value: Eng - Design System Fundamentals
|