@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
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