@atlaskit/ads-cli 0.6.0 → 0.8.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 (38) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +51 -14
  3. package/bin/ads-cli.js +6 -4
  4. package/dist/cjs/cli.js +23 -4
  5. package/dist/cjs/commands/definitions.js +46 -15
  6. package/dist/cjs/commands/normalize-batch-request.js +176 -0
  7. package/dist/cjs/output/compact-results.js +119 -0
  8. package/dist/cjs/output/format-doc-object.js +18 -5
  9. package/dist/cjs/output/format-icon.js +2 -1
  10. package/dist/cjs/output/format-results.js +37 -71
  11. package/dist/cjs/output/format-token.js +19 -5
  12. package/dist/cjs/output/write-json-envelope.js +2 -1
  13. package/dist/es2019/cli.js +23 -4
  14. package/dist/es2019/commands/definitions.js +48 -15
  15. package/dist/es2019/commands/normalize-batch-request.js +142 -0
  16. package/dist/es2019/output/compact-results.js +104 -0
  17. package/dist/es2019/output/format-doc-object.js +12 -4
  18. package/dist/es2019/output/format-icon.js +2 -1
  19. package/dist/es2019/output/format-results.js +37 -66
  20. package/dist/es2019/output/format-token.js +14 -5
  21. package/dist/es2019/output/write-json-envelope.js +2 -1
  22. package/dist/esm/cli.js +23 -4
  23. package/dist/esm/commands/definitions.js +46 -15
  24. package/dist/esm/commands/normalize-batch-request.js +169 -0
  25. package/dist/esm/output/compact-results.js +112 -0
  26. package/dist/esm/output/format-doc-object.js +18 -5
  27. package/dist/esm/output/format-icon.js +2 -1
  28. package/dist/esm/output/format-results.js +37 -71
  29. package/dist/esm/output/format-token.js +19 -5
  30. package/dist/esm/output/write-json-envelope.js +2 -1
  31. package/dist/types/commands/normalize-batch-request.d.ts +16 -0
  32. package/dist/types/commands/types.d.ts +8 -8
  33. package/dist/types/envelope/types.d.ts +3 -2
  34. package/dist/types/output/compact-results.d.ts +41 -0
  35. package/dist/types/output/format-results.d.ts +3 -3
  36. package/dist/types/output/format-token.d.ts +3 -3
  37. package/dist/types/output/write-json-envelope.d.ts +2 -1
  38. package/package.json +2 -2
@@ -1,22 +1,28 @@
1
+ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
1
2
  import _typeof from "@babel/runtime/helpers/typeof";
2
3
  /**
3
4
  * Human-readable renderer for a single ADS design token's detail view.
4
5
  *
5
- * The token dataset is intentionally small — each record has only `name` and `exampleValue` —
6
- * so the detail view adds the actionable `token('…')` usage line on top of those two fields.
7
- * Full structured data remains available via `--json`.
6
+ * Exact token lookups include the full metadata record. The detail view renders its guidance and
7
+ * adds an actionable `token('…')` usage line; the same structured fields remain available via
8
+ * `--json`.
8
9
  */
9
10
 
10
11
  /**
11
12
  * A token payload as returned by `searchTokensTool` / `getAllTokensTool`.
12
13
  */
13
14
 
15
+ var oneLine = function oneLine(text) {
16
+ return text.replace(/\s+/g, ' ').trim();
17
+ };
18
+
14
19
  /**
15
20
  * Render a single token payload as a detail view. Returns `null` when the data is not a
16
21
  * recognisable token object, so the caller can fall back to generic rendering.
17
22
  */
18
23
  export var formatToken = function formatToken(data) {
19
- // `token <name>` reuses token search with limit 1, so `data` is a one-element array.
24
+ var _token$usageGuideline, _token$usageGuideline2, _token$usage;
25
+ // `token <name>` returns a ranked candidate array; the command transform selects the detail.
20
26
  var token = Array.isArray(data) ? data[0] : data;
21
27
  if (!token || _typeof(token) !== 'object' || typeof token.name !== 'string') {
22
28
  return null;
@@ -25,8 +31,16 @@ export var formatToken = function formatToken(data) {
25
31
  if (token.exampleValue) {
26
32
  sections.push('', "Example value: ".concat(token.exampleValue));
27
33
  }
34
+ if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
35
+ sections.push('', 'Guidelines:', " ".concat(oneLine(token.usageGuidelines.usage)));
36
+ }
37
+ if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline2 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline2 !== void 0 && _token$usageGuideline2.length) {
38
+ sections.push.apply(sections, ['', 'CSS properties:'].concat(_toConsumableArray(token.usageGuidelines.cssProperties.map(function (item) {
39
+ return " ".concat(item);
40
+ }))));
41
+ }
28
42
 
29
43
  // The actionable bit: how to consume the token from `@atlaskit/tokens`.
30
- sections.push('', 'Usage:', " token('".concat(token.name, "')"));
44
+ sections.push('', 'Usage:', " ".concat((_token$usage = token.usage) !== null && _token$usage !== void 0 ? _token$usage : "token('".concat(token.name, "')")));
31
45
  return sections.join('\n');
32
46
  };
@@ -5,7 +5,8 @@
5
5
  /**
6
6
  * Emit the JSON envelope to stdout.
7
7
  *
8
- * Always pretty-printed for readability; consumers that need compact output can re-serialise.
8
+ * JSON output is pretty-printed for terminal readability. Its retrieval payload stays compact
9
+ * because search and list commands project the MCP response before it reaches this serializer.
9
10
  */
10
11
  export var writeJsonEnvelope = function writeJsonEnvelope(_ref) {
11
12
  var envelope = _ref.envelope,
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Normalise one batch child request without involving a shell.
3
+ *
4
+ * The canonical form is already-tokenized argv, for example
5
+ * `['search', 'Grid', '--type', 'component']`. For compatibility with agent-generated commands,
6
+ * the first token may instead contain a complete request, for example `['search Grid', '--type',
7
+ * 'component']`. Only that first token is split; trailing tokens have already been tokenized by the
8
+ * caller and must remain unchanged so multi-word arguments keep their boundaries.
9
+ */
10
+ type NormalizedBatchRequest = {
11
+ argv: string[];
12
+ } | {
13
+ error: string;
14
+ };
15
+ export declare const normalizeBatchRequest: (argv: string[]) => NormalizedBatchRequest;
16
+ export {};
@@ -104,10 +104,10 @@ export type ResolveResult = ResolvedCommand | ResolvedStatic | {
104
104
  error: string;
105
105
  };
106
106
  /**
107
- * The kind of *listable row* a command renders, used by the default (non-`--json`) formatter to
108
- * pick a compact per-row renderer. Search results include concise documentation matches, while
109
- * standalone docs, a11y, and lint-rules commands render their full content via
110
- * {@link CommandDefinition.formatHuman} or the generic fallback.
107
+ * The kind of *listable row* a command returns. Search and list results use it to create the shared
108
+ * compact projection consumed by both human and `--json` output. Standalone docs, a11y, and
109
+ * lint-rules commands render their full content via {@link CommandDefinition.formatHuman} or the
110
+ * generic fallback.
111
111
  */
112
112
  export type RowKind = 'components' | 'tokens' | 'icons' | 'docs';
113
113
  /**
@@ -130,10 +130,10 @@ export type CommandDefinition = {
130
130
  */
131
131
  name: string;
132
132
  /**
133
- * The compact result kind for human output. When set, the default renderer prints one
134
- * line per result; when omitted, the command uses the generic fallback (JSON for objects,
135
- * verbatim for strings — e.g. guideline markdown). May depend on input, so it is a function
136
- * of {@link CommandInput} (e.g. `search --type tokens` renders as tokens).
133
+ * The compact result kind for search/list output. When set, both JSON and the default human
134
+ * renderer consume the same bounded record per result. When omitted, the command uses its detail
135
+ * renderer or generic fallback. May depend on input, so it is a function of
136
+ * {@link CommandInput} (e.g. `search --type tokens` renders as tokens).
137
137
  */
138
138
  resultKind?: (input: CommandInput) => RowKind | undefined;
139
139
  /**
@@ -22,8 +22,9 @@ export type EnvelopeMeta = {
22
22
  /**
23
23
  * Successful command envelope.
24
24
  *
25
- * `data` holds the (already JSON-parsed where possible) payload returned by the underlying
26
- * ADS MCP tool.
25
+ * `data` holds the command's output payload. Search and list commands project underlying MCP data
26
+ * into the same compact records shown by human output; exact detail commands retain their detailed
27
+ * records.
27
28
  */
28
29
  export type SuccessEnvelope<Data = unknown> = {
29
30
  /**
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Shared compact projections for ADS search and list results.
3
+ *
4
+ * Human-readable rows and `--json` responses both consume these records. Keeping the projection in
5
+ * one place prevents the machine-readable output from silently expanding back to the underlying
6
+ * MCP payload (for example, every component prop and example during discovery).
7
+ */
8
+ import type { RowKind } from '../commands/types';
9
+ export type CompactComponentResult = {
10
+ name: string;
11
+ package?: string;
12
+ propCount: number;
13
+ exampleCount: number;
14
+ followUp?: string;
15
+ };
16
+ export type CompactTokenResult = {
17
+ name: string;
18
+ exampleValue?: string;
19
+ followUp?: string;
20
+ };
21
+ export type CompactIconResult = {
22
+ componentName: string;
23
+ package?: string;
24
+ usage?: string;
25
+ followUp?: string;
26
+ };
27
+ export type CompactDocResult = {
28
+ title: string;
29
+ summary?: string;
30
+ followUp?: string;
31
+ };
32
+ export type CompactResult = CompactComponentResult | CompactTokenResult | CompactIconResult | CompactDocResult;
33
+ /**
34
+ * Project raw MCP rows into the compact records shared by human and JSON output. The function is
35
+ * idempotent so batch rendering can safely receive child envelopes that were already compacted.
36
+ */
37
+ export declare const compactResults: ({ kind, data, showFollowUp, }: {
38
+ kind: RowKind;
39
+ data: unknown;
40
+ showFollowUp?: boolean;
41
+ }) => CompactResult[] | null;
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Compact, human-readable renderers for the structured search/list results.
3
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`.
4
+ * The underlying ADS MCP tools return rich JSON arrays. Search and list commands first project
5
+ * those arrays into shared compact records, then both human and `--json` output consume the same
6
+ * data. Exact detail commands retain the full structured payload.
7
7
  *
8
8
  * Anything this module does not recognise (e.g. guideline markdown, the `plan` payload) is
9
9
  * left to the caller's generic fallback.
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Human-readable renderer for a single ADS design token's detail view.
3
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`.
4
+ * Exact token lookups include the full metadata record. The detail view renders its guidance and
5
+ * adds an actionable `token('…')` usage line; the same structured fields remain available via
6
+ * `--json`.
7
7
  */
8
8
  /**
9
9
  * Render a single token payload as a detail view. Returns `null` when the data is not a
@@ -6,7 +6,8 @@ import type { Writer } from './writer';
6
6
  /**
7
7
  * Emit the JSON envelope to stdout.
8
8
  *
9
- * Always pretty-printed for readability; consumers that need compact output can re-serialise.
9
+ * JSON output is pretty-printed for terminal readability. Its retrieval payload stays compact
10
+ * because search and list commands project the MCP response before it reaches this serializer.
10
11
  */
11
12
  export declare const writeJsonEnvelope: ({ envelope, writer, }: {
12
13
  envelope: Envelope;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.6.0",
3
+ "version": "0.8.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",
@@ -31,7 +31,7 @@
31
31
  "release:atlas:promote": "bash scripts/atlas/promote-stable.sh"
32
32
  },
33
33
  "dependencies": {
34
- "@atlaskit/ads-mcp": "^1.7.0",
34
+ "@atlaskit/ads-mcp": "^1.8.0",
35
35
  "@babel/runtime": "^7.0.0",
36
36
  "chalk": "^4.1.2"
37
37
  },