@atlaskit/ads-cli 0.4.2 → 0.6.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 (48) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +62 -10
  3. package/bin/ads-cli.js +5 -1
  4. package/dist/cjs/atlas-cli.js +4 -1
  5. package/dist/cjs/cli.js +368 -70
  6. package/dist/cjs/commands/build-manifest.js +1 -2
  7. package/dist/cjs/commands/cli-metadata.js +2 -1
  8. package/dist/cjs/commands/definitions.js +100 -16
  9. package/dist/cjs/output/format-disambiguation.js +3 -1
  10. package/dist/cjs/output/format-grouped-results.js +6 -2
  11. package/dist/cjs/output/format-human-result.js +33 -0
  12. package/dist/cjs/output/format-manifest.js +5 -3
  13. package/dist/cjs/output/format-results.js +25 -18
  14. package/dist/cjs/output/write-human-result.js +8 -10
  15. package/dist/es2019/atlas-cli.js +4 -1
  16. package/dist/es2019/cli.js +273 -29
  17. package/dist/es2019/commands/build-manifest.js +1 -2
  18. package/dist/es2019/commands/cli-metadata.js +1 -0
  19. package/dist/es2019/commands/definitions.js +77 -6
  20. package/dist/es2019/output/format-disambiguation.js +3 -2
  21. package/dist/es2019/output/format-grouped-results.js +5 -2
  22. package/dist/es2019/output/format-human-result.js +28 -0
  23. package/dist/es2019/output/format-manifest.js +6 -3
  24. package/dist/es2019/output/format-results.js +25 -18
  25. package/dist/es2019/output/write-human-result.js +8 -9
  26. package/dist/esm/atlas-cli.js +4 -1
  27. package/dist/esm/cli.js +369 -71
  28. package/dist/esm/commands/build-manifest.js +1 -2
  29. package/dist/esm/commands/cli-metadata.js +1 -0
  30. package/dist/esm/commands/definitions.js +100 -16
  31. package/dist/esm/output/format-disambiguation.js +3 -1
  32. package/dist/esm/output/format-grouped-results.js +6 -2
  33. package/dist/esm/output/format-human-result.js +27 -0
  34. package/dist/esm/output/format-manifest.js +5 -3
  35. package/dist/esm/output/format-results.js +26 -18
  36. package/dist/esm/output/write-human-result.js +8 -9
  37. package/dist/types/cli.d.ts +10 -1
  38. package/dist/types/commands/build-manifest.d.ts +1 -2
  39. package/dist/types/commands/cli-metadata.d.ts +1 -0
  40. package/dist/types/commands/types.d.ts +28 -1
  41. package/dist/types/output/format-disambiguation.d.ts +1 -1
  42. package/dist/types/output/format-grouped-results.d.ts +2 -1
  43. package/dist/types/output/format-human-result.d.ts +17 -0
  44. package/dist/types/output/format-manifest.d.ts +2 -1
  45. package/dist/types/output/format-results.d.ts +4 -3
  46. package/dist/types/output/write-human-result.d.ts +2 -2
  47. package/dist/types/parse-args.d.ts +1 -1
  48. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`23b45bcd71b5d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/23b45bcd71b5d) -
8
+ Add an in-process batch command for running multiple ADS CLI queries with independent results,
9
+ using a repeated `--command` flag to introduce each child request.
10
+
11
+ For example:
12
+
13
+ ```sh
14
+ npx @atlaskit/ads-cli batch --command search button --type icon --command token space.200
15
+ ```
16
+
17
+ For readability, put each `--command` group on its own line — the two forms are equivalent:
18
+
19
+ ```sh
20
+ npx @atlaskit/ads-cli batch \
21
+ --command search button --type icon \
22
+ --command token space.200
23
+ ```
24
+
25
+ ## 0.5.0
26
+
27
+ ### Minor Changes
28
+
29
+ - [`34cfe0f138d1c`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/34cfe0f138d1c) -
30
+ Show the active command invocation in ADS CLI help, errors, and follow-up hints. The v2 JSON
31
+ manifest removes the redundant `invocation` field.
32
+
3
33
  ## 0.4.2
4
34
 
5
35
  ### Patch Changes
package/README.md CHANGED
@@ -21,15 +21,16 @@ default; `--json` emits a stable, self-describing envelope for machine consumers
21
21
 
22
22
  The CLI has these commands:
23
23
 
24
- | Command | Description |
25
- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
- | `search <query...>` | **Unified** fuzzy-search across components, tokens, icons, and foundations docs at once. Narrow results with `--type component\|token\|icon\|docs`; 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
- | `manifest` | Describe every command, argument, flag, and JSON response type. Use `--json` for the machine-readable contract. |
24
+ | Command | Description |
25
+ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | `search <query...>` | **Unified** fuzzy-search across components, tokens, icons, and foundations docs at once. Narrow results with `--type component\|token\|icon\|docs`; limit with `--limit N`. |
27
+ | `batch --command <command> [args...]...` | Run multiple ADS CLI queries, including different command types, in one process. Repeat `--command` once per child; each keeps its normal arguments, flags, and response envelope. |
28
+ | `component <name>` | Detail for a single component. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every component. |
29
+ | `token <name>` | Detail for a single token. Exact name → detail; ambiguous → a "did you mean?" list. `--all` lists every token. |
30
+ | `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. |
31
+ | `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. |
32
+ | `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 |
33
+ | `manifest` | Describe every command, argument, flag, and JSON response type. Use `--json` for the machine-readable contract. |
33
34
 
34
35
  ### Global flags
35
36
 
@@ -47,6 +48,13 @@ npx @atlaskit/ads-cli search contrast
47
48
  npx @atlaskit/ads-cli search space color --type token
48
49
  npx @atlaskit/ads-cli search contrast --type docs
49
50
 
51
+ # Run multiple queries, including different command types, in one process
52
+ npx @atlaskit/ads-cli batch \
53
+ --command component Button \
54
+ --command component Modal \
55
+ --command docs spacing \
56
+ --command search contrast --type docs
57
+
50
58
  # Detail for a single component, token, or icon
51
59
  npx @atlaskit/ads-cli component Avatar
52
60
  npx @atlaskit/ads-cli token space.100
@@ -84,8 +92,16 @@ npx @atlaskit/ads-cli manifest --json
84
92
  is no exact match but several candidates, they print a `Did you mean?` list (each with a
85
93
  `→ ads-cli <command>` follow-up) and exit `0` — under `--json` this is
86
94
  `{ "ambiguous": true, "query", "noun", "candidates": [...] }`.
95
+ - **Batch commands are independent.** Each repeated `--command` starts a tokenized child request;
96
+ `batch` runs those commands concurrently through the existing command registry in one CLI process.
97
+ Each item includes its original tokenized `request`, a `status` (`success`, `ambiguous`, or
98
+ `failure`), and the child command's unchanged success or error `response` envelope. A failed or
99
+ ambiguous child does not discard successful sibling results. A syntactically valid batch exits
100
+ `0`; inspect each item's status or nested envelope.
87
101
  - **Data is written to stdout only.** Logs, hints, and errors go to **stderr**. This keeps `--json`
88
- output clean for piping.
102
+ output clean for piping. `batch` is the one deliberate exception: a child's failure is part of the
103
+ aggregate result rather than a failure of the batch itself, so per-child errors stay inline on
104
+ stdout beside their `Request:` heading instead of being split onto stderr.
89
105
  - **The manifest is derived from the live command registry.** `manifest --json` lists every command,
90
106
  positional argument, flag, example, and success response type without maintaining a separate copy
91
107
  of the CLI surface.
@@ -122,6 +138,42 @@ npx @atlaskit/ads-cli manifest --json
122
138
  "meta": { "terms": ["avatar"], "limit": 5, "count": 2 }
123
139
  }
124
140
 
141
+ // success — batch preserves each child command's existing envelope
142
+ {
143
+ "type": "ads-cli/batch",
144
+ "command": "batch",
145
+ "ok": true,
146
+ "data": [
147
+ {
148
+ "request": ["component", "Button"],
149
+ "status": "success",
150
+ "response": {
151
+ "type": "ads-cli/component",
152
+ "command": "component",
153
+ "ok": true,
154
+ "data": { /* full Button data */ },
155
+ "meta": { "name": "Button" }
156
+ }
157
+ },
158
+ {
159
+ "request": ["docs", "missing-topic"],
160
+ "status": "failure",
161
+ "response": {
162
+ "type": "ads-cli/error",
163
+ "command": "docs",
164
+ "ok": false,
165
+ "error": { "code": "NOT_FOUND", "message": "No guidelines found for missing-topic." }
166
+ }
167
+ }
168
+ ],
169
+ "meta": {
170
+ "succeeded": 1,
171
+ "ambiguous": 0,
172
+ "failed": 1,
173
+ "count": 2
174
+ }
175
+ }
176
+
125
177
  // failure
126
178
  {
127
179
  "type": "ads-cli/error",
package/bin/ads-cli.js CHANGED
@@ -24,8 +24,12 @@ if (isDev) {
24
24
  require('@atlassian/ts-loader');
25
25
  }
26
26
 
27
+ // The AFM repo-root shell shim sets this display-only value because it delegates to this same
28
+ // package entrypoint. Published package runs have no override and advertise their npx command.
29
+ const invocation = process.env.ADS_CLI_DISPLAY_INVOCATION || 'npx @atlaskit/ads-cli';
30
+
27
31
  require(path.join('..', isDev ? 'src/cli' : 'dist/cjs/cli'))
28
- .run(process.argv.slice(2))
32
+ .run(process.argv.slice(2), undefined, { invocation })
29
33
  .then((exitCode) => {
30
34
  // A resolved numeric value is treated as an explicit exit code.
31
35
  process.exit(typeof exitCode === 'number' ? exitCode : 0);
@@ -9,6 +9,7 @@ exports.main = void 0;
9
9
  var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
10
10
  var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
11
11
  var _cli = require("./cli");
12
+ var _cliMetadata = require("./commands/cli-metadata");
12
13
  /**
13
14
  * Process entrypoint for the `atlas ads` distribution.
14
15
  *
@@ -29,7 +30,9 @@ var main = exports.main = /*#__PURE__*/function () {
29
30
  argv = _args.length > 0 && _args[0] !== undefined ? _args[0] : process.argv.slice(2);
30
31
  _context.prev = 1;
31
32
  _context.next = 2;
32
- return (0, _cli.run)(argv);
33
+ return (0, _cli.run)(argv, undefined, {
34
+ invocation: _cliMetadata.CLI_ATLAS_INVOCATION
35
+ });
33
36
  case 2:
34
37
  exitCode = _context.sent;
35
38
  process.exitCode = exitCode;