@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,22 @@
1
+ function _tsRewriteRelativeImportExtensions(t, e) { return "string" == typeof t && /^\.\.?\//.test(t) ? t.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+)?)\.([cm]?)ts$/i, function (t, s, r, n, o) { return s ? e ? ".jsx" : ".js" : !r || n && o ? r + n + "." + o.toLowerCase() + "js" : t; }) : t; }
2
+ /**
3
+ * Dynamic-import indirection used to load an ADS MCP tool handler by subpath.
4
+ */
5
+
6
+ /**
7
+ * Load an ADS MCP tool handler by subpath.
8
+ *
9
+ * Exposed as a single function so tests can mock it and assert which tool a command
10
+ * dispatched to, and so the dynamic `import()` lives in exactly one place.
11
+ */
12
+ export const importToolHandler = async ({
13
+ importPath,
14
+ handlerName
15
+ }) => {
16
+ const mod = await import( /* webpackChunkName: "@atlaskit-internal_ads-cli-tool" */_tsRewriteRelativeImportExtensions(importPath));
17
+ const handler = mod[handlerName];
18
+ if (typeof handler !== 'function') {
19
+ throw new Error(`Tool handler "${handlerName}" not found in "${importPath}".`);
20
+ }
21
+ return handler;
22
+ };
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Generic runner that invokes a single `@atlaskit/ads-mcp/tools/*` handler and unwraps its
3
+ * MCP-shaped result into plain data.
4
+ *
5
+ * This is the one place the CLI actually talks to the shared ADS query logic. Keeping the
6
+ * dispatch here (rather than reimplementing search/ranking) is what guarantees zero drift
7
+ * between the MCP server, the ADS skill scripts, and this CLI.
8
+ */
9
+
10
+ /**
11
+ * Result of unwrapping an ADS MCP tool response.
12
+ */
13
+
14
+ /**
15
+ * The ADS search tools signal "no results" by returning a single text block that starts
16
+ * with `Error:`. Detect that so the CLI can map it to a NOT_FOUND exit code.
17
+ */
18
+ const isErrorText = text => text.trimStart().startsWith('Error:');
19
+
20
+ /**
21
+ * Attempt to JSON-parse a string, returning the original string on failure. Mirrors the
22
+ * `try { JSON.parse } catch { raw }` pattern used by the existing skill scripts.
23
+ */
24
+ const tryParseJson = text => {
25
+ try {
26
+ return JSON.parse(text);
27
+ } catch {
28
+ return text;
29
+ }
30
+ };
31
+
32
+ /**
33
+ * Extract the text blocks from an MCP tool result.
34
+ */
35
+ const getTextBlocks = result => result.content.filter(item => item.type === 'text' && typeof item.text === 'string').map(item => item.text);
36
+
37
+ /**
38
+ * Invoke an ADS MCP tool handler and unwrap its result into plain data.
39
+ *
40
+ * @param handler - The tool function (e.g. `searchComponentsTool`).
41
+ * @param args - The arguments object matching the tool's zod input schema, or `undefined`
42
+ * for zero-argument tools such as `getAllComponentsTool`.
43
+ */
44
+ export const runTool = async ({
45
+ handler,
46
+ args
47
+ }) => {
48
+ const result = await handler(args);
49
+ const textBlocks = getTextBlocks(result);
50
+
51
+ // A single text block is the common case (search tools, guidelines). Multiple blocks are
52
+ // returned by the `get-all-*` tools, which emit one JSON object per entry.
53
+ if (textBlocks.length === 0) {
54
+ return {
55
+ data: null,
56
+ isError: Boolean(result.isError)
57
+ };
58
+ }
59
+ if (textBlocks.length === 1) {
60
+ const text = textBlocks[0];
61
+ return {
62
+ data: tryParseJson(text),
63
+ isError: Boolean(result.isError) || isErrorText(text)
64
+ };
65
+ }
66
+
67
+ // Multiple blocks: parse each independently so `list components --json` yields an array
68
+ // of objects rather than a single concatenated string.
69
+ return {
70
+ data: textBlocks.map(tryParseJson),
71
+ isError: Boolean(result.isError)
72
+ };
73
+ };
File without changes
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Builder for the error variant of the CLI's JSON output envelope.
3
+ */
4
+
5
+ /**
6
+ * Build an error envelope for a command.
7
+ */
8
+ export const createErrorEnvelope = ({
9
+ command,
10
+ code,
11
+ message
12
+ }) => ({
13
+ type: 'ads-cli/error',
14
+ command,
15
+ ok: false,
16
+ error: {
17
+ code,
18
+ message
19
+ }
20
+ });
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Builder for the success variant of the CLI's JSON output envelope.
3
+ */
4
+
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 const createSuccessEnvelope = ({
12
+ envelopeType,
13
+ command,
14
+ data,
15
+ meta = {}
16
+ }) => {
17
+ // Automatically compute `count` for array payloads so consumers get it for free.
18
+ const count = Array.isArray(data) ? data.length : meta.count;
19
+ return {
20
+ type: `ads-cli/${envelopeType}`,
21
+ command,
22
+ ok: true,
23
+ data,
24
+ meta: {
25
+ ...meta,
26
+ ...(count === undefined ? {} : {
27
+ count
28
+ })
29
+ }
30
+ };
31
+ };
File without changes
@@ -0,0 +1,21 @@
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
+ /**
11
+ * A candidate surfaced in a disambiguation result.
12
+ */
13
+
14
+ /**
15
+ * The marker object a `transform` returns when a lookup is ambiguous.
16
+ */
17
+
18
+ /**
19
+ * Narrow an unknown value to a {@link DisambiguationResult}.
20
+ */
21
+ export const isDisambiguation = value => typeof value === 'object' && value !== null && value.ambiguous === true;
@@ -0,0 +1,88 @@
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
+ /**
10
+ * One prop entry as returned by `searchComponentsTool`. Only the fields the detailed view needs
11
+ * are modelled; anything else is ignored.
12
+ */
13
+
14
+ /**
15
+ * A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
16
+ */
17
+
18
+ /**
19
+ * Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
20
+ */
21
+ const oneLine = text => text.replace(/\s+/g, ' ').trim();
22
+
23
+ /**
24
+ * Render the props section as an aligned two-column list: `name type`, with the description on
25
+ * a wrapped continuation line. Returns an empty array when there are no props.
26
+ */
27
+ const formatProps = props => {
28
+ if (props.length === 0) {
29
+ return ['Props: none'];
30
+ }
31
+
32
+ // Align the type column to the longest prop name for readability.
33
+ const longestName = props.reduce((max, prop) => {
34
+ var _prop$name;
35
+ return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
36
+ }, 0);
37
+ const rows = props.flatMap(prop => {
38
+ var _prop$name2;
39
+ const name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
40
+ const type = prop.type ? oneLine(prop.type) : '';
41
+ const header = ` ${name} ${type}`.trimEnd();
42
+ const description = prop.description ? ` ${oneLine(prop.description)}` : null;
43
+ return description ? [header, description] : [header];
44
+ });
45
+ return [`Props (${props.length}):`, ...rows];
46
+ };
47
+
48
+ /**
49
+ * Render the examples section. Each example is a code snippet string; they are printed verbatim
50
+ * inside a fenced block so they can be copy-pasted.
51
+ */
52
+ const formatExamples = examples => {
53
+ if (examples.length === 0) {
54
+ return [];
55
+ }
56
+ const blocks = examples.map((example, index) => {
57
+ const code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
58
+ return [`Example ${index + 1}:`, '```tsx', code, '```'].join('\n');
59
+ });
60
+ return [`Examples (${examples.length}):`, '', ...blocks];
61
+ };
62
+
63
+ /**
64
+ * Render a single component payload as detailed, human-readable docs. Returns `null` when the
65
+ * data is not a recognisable component object, so the caller can fall back to generic rendering.
66
+ */
67
+ export const formatComponent = data => {
68
+ var _component$props, _component$examples, _component$designSour;
69
+ // `component <name>` reuses component search with limit 1, so `data` is a one-element array.
70
+ const component = Array.isArray(data) ? data[0] : data;
71
+ if (!component || typeof component !== 'object' || typeof component.name !== 'string') {
72
+ return null;
73
+ }
74
+ const header = component.package ? `${component.name} (${component.package})` : component.name;
75
+ const sections = [header, '='.repeat(header.length), '', ...formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : [])];
76
+ const examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
77
+ if (examples.length > 0) {
78
+ sections.push('', ...examples);
79
+ }
80
+
81
+ // Render the design link from the `figmaUrl` inside `designSource`. Only emit the line when a
82
+ // URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
83
+ // `Design: undefined`.
84
+ if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
85
+ sections.push('', `Design: ${component.designSource.figmaUrl}`);
86
+ }
87
+ return sections.join('\n');
88
+ };
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Human-readable renderer for an ambiguous item lookup ("did you mean?").
3
+ */
4
+
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 const formatDisambiguation = ({
12
+ query,
13
+ noun,
14
+ candidates
15
+ }) => {
16
+ const header = `Multiple ${noun}s match "${query}". Did you mean one of these?`;
17
+ const rows = candidates.map(candidate => {
18
+ const hint = candidate.hint ? ` ${candidate.hint}` : '';
19
+ return ` ${candidate.name}${hint}\n → ads-cli ${candidate.followUp}`;
20
+ });
21
+ return [header, '', ...rows].join('\n');
22
+ };
@@ -0,0 +1,94 @@
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
+ /**
11
+ * Convert a camelCase / snake_case field key into a human "Title Case" heading,
12
+ * e.g. `bestPractices` → `Best Practices`, `additionalResources` → `Additional Resources`.
13
+ */
14
+ const humanizeKey = key => key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').replace(/\b\w/g, char => char.toUpperCase()).trim();
15
+
16
+ /**
17
+ * Collapse whitespace so list items and inline values stay readable on their own lines.
18
+ */
19
+ const oneLine = text => text.replace(/\s+/g, ' ').trim();
20
+
21
+ /**
22
+ * Render a single list item. Strings are collapsed to one line. Objects that look like a code
23
+ * example (`title` + `code`/`before`/`after`) are rendered as a titled fenced block so the
24
+ * snippet stays copy-pasteable; any other object falls back to compact JSON so no data is lost.
25
+ */
26
+ const formatListItem = item => {
27
+ if (typeof item === 'string') {
28
+ return ` - ${oneLine(item)}`;
29
+ }
30
+ if (item !== null && typeof item === 'object') {
31
+ const record = item;
32
+ const title = typeof record.title === 'string' ? record.title : null;
33
+ const code = ['code', 'before', 'after'].find(key => typeof record[key] === 'string');
34
+ if (title && code) {
35
+ const description = typeof record.description === 'string' ? `\n ${oneLine(record.description)}` : '';
36
+ return ` - ${title}${description}\n \`\`\`tsx\n${record[code]}\n \`\`\``;
37
+ }
38
+ if (title) {
39
+ return ` - ${title}`;
40
+ }
41
+ }
42
+
43
+ // Unknown object shape: keep the data rather than drop it.
44
+ return ` - ${JSON.stringify(item)}`;
45
+ };
46
+
47
+ /**
48
+ * Keys that identify the record or provide its header/description — rendered as the header or
49
+ * skipped, never as their own labelled section. `message` is the header used by the "index"
50
+ * response the a11y tool returns when no topic is supplied (it has no `title`).
51
+ */
52
+ const IDENTITY_KEYS = new Set(['topic', 'migration', 'title', 'message', 'description']);
53
+
54
+ /**
55
+ * Render a doc-object payload as readable text. Handles both the full guide shape (a11y guidance,
56
+ * migration guide — keyed by `title`) and the topic-index shape the a11y tool returns when no
57
+ * topic is given (keyed by `message` + `availableTopics`). Returns `null` when the data is not a
58
+ * recognisable doc object so the caller can fall back to generic rendering.
59
+ */
60
+ export const formatDocObject = data => {
61
+ if (data === null || typeof data !== 'object' || Array.isArray(data)) {
62
+ return null;
63
+ }
64
+ const record = data;
65
+
66
+ // Derive a header from `title` (full guide) or `message` (topic index). Without either, this
67
+ // is not a doc object we can render sensibly, so defer to the generic fallback.
68
+ const header = typeof record.title === 'string' ? record.title : record.message;
69
+ if (typeof header !== 'string' || !header) {
70
+ return null;
71
+ }
72
+ const sections = [header, '='.repeat(header.length)];
73
+ if (typeof record.description === 'string' && record.description) {
74
+ sections.push('', oneLine(record.description));
75
+ }
76
+
77
+ // Render every remaining field in declaration order: strings as `Label: value`, arrays as a
78
+ // labelled bulleted list. Identity/header fields are skipped (handled above).
79
+ for (const [key, value] of Object.entries(record)) {
80
+ if (IDENTITY_KEYS.has(key)) {
81
+ continue;
82
+ }
83
+ const label = humanizeKey(key);
84
+ if (Array.isArray(value)) {
85
+ if (value.length === 0) {
86
+ continue;
87
+ }
88
+ sections.push('', `${label}:`, ...value.map(formatListItem));
89
+ } else if (typeof value === 'string' && value) {
90
+ sections.push('', `${label}: ${oneLine(value)}`);
91
+ }
92
+ }
93
+ return sections.join('\n');
94
+ };
@@ -0,0 +1,51 @@
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
+ import { formatCompactResults } from './format-results';
10
+
11
+ /**
12
+ * Render grouped results as sectioned compact output.
13
+ */
14
+ export const formatGroupedResults = ({
15
+ groups,
16
+ totalCount
17
+ }) => {
18
+ // Fixed display order, with human-friendly section titles.
19
+ const sections = [{
20
+ kind: 'components',
21
+ title: 'Components'
22
+ }, {
23
+ kind: 'tokens',
24
+ title: 'Tokens'
25
+ }, {
26
+ kind: 'icons',
27
+ title: 'Icons'
28
+ }];
29
+ const blocks = [`Results (${totalCount}):`];
30
+ for (const {
31
+ kind,
32
+ title
33
+ } of sections) {
34
+ var _groups$kind;
35
+ const entries = (_groups$kind = groups[kind]) !== null && _groups$kind !== void 0 ? _groups$kind : [];
36
+ if (entries.length === 0) {
37
+ continue;
38
+ }
39
+ // Reuse the single-kind compact renderer with drill-in follow-ups enabled (this is the
40
+ // unified `search` view), then strip its own "Results (n):" header and following blank
41
+ // line so the grouped output uses the section title instead.
42
+ const rendered = formatCompactResults({
43
+ kind,
44
+ data: entries,
45
+ showFollowUp: true
46
+ });
47
+ const body = rendered ? rendered.split('\n').slice(2).join('\n') : '';
48
+ blocks.push('', `${title} (${entries.length}):`, '', body);
49
+ }
50
+ return blocks.join('\n');
51
+ };
@@ -0,0 +1,39 @@
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
+ /**
11
+ * An icon payload as returned by `searchIconsTool` / `getAllIconsTool`.
12
+ */
13
+
14
+ /**
15
+ * Collapse whitespace/newlines so the usage note stays readable on its own line.
16
+ */
17
+ const oneLine = text => text.replace(/\s+/g, ' ').trim();
18
+
19
+ /**
20
+ * Render a single icon payload as a detail view. Returns `null` when the data is not a
21
+ * recognisable icon object, so the caller can fall back to generic rendering.
22
+ */
23
+ export const formatIcon = data => {
24
+ // `icon <name>` reuses icon search with limit 1, so `data` is a one-element array.
25
+ const icon = Array.isArray(data) ? data[0] : data;
26
+ if (!icon || typeof icon !== 'object' || typeof icon.componentName !== 'string') {
27
+ return null;
28
+ }
29
+ const sections = [icon.componentName, '='.repeat(icon.componentName.length)];
30
+ if (icon.package) {
31
+ sections.push('', `Package: ${icon.package}`);
32
+ // The actionable bit: the barrel-correct import for this icon.
33
+ sections.push('', 'Import:', ` import ${icon.componentName} from '${icon.package}';`);
34
+ }
35
+ if (icon.usage) {
36
+ sections.push('', `Usage: ${oneLine(icon.usage)}`);
37
+ }
38
+ return sections.join('\n');
39
+ };
@@ -0,0 +1,43 @@
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
+ import { parseLintRuleRecords } from './parse-lint-rule-records';
11
+
12
+ /**
13
+ * True when a value looks like a lint-rule record (an object carrying at least one known field).
14
+ */
15
+ const isLintRuleRecord = rule => rule !== null && typeof rule === 'object' && ('content' in rule || 'ruleName' in rule || 'description' in rule);
16
+
17
+ /**
18
+ * Render a single rule: prefer its Markdown `content`; fall back to `ruleName` + `description`
19
+ * when no content is present.
20
+ */
21
+ const formatRule = rule => {
22
+ var _rule$ruleName;
23
+ if (typeof rule.content === 'string' && rule.content.trim()) {
24
+ return rule.content.trim();
25
+ }
26
+ const name = (_rule$ruleName = rule.ruleName) !== null && _rule$ruleName !== void 0 ? _rule$ruleName : '(unknown rule)';
27
+ return rule.description ? `# ${name}\n\n${rule.description}` : `# ${name}`;
28
+ };
29
+
30
+ /**
31
+ * Render the lint-rules payload as readable Markdown. Handles both the array form (multiple
32
+ * matching rules) and the single-object form. Returns `null` for unrecognised shapes so the
33
+ * caller can fall back to generic rendering.
34
+ */
35
+ export const formatLintRules = data => {
36
+ const rules = parseLintRuleRecords(data);
37
+ if (rules.length === 0 || !rules.every(isLintRuleRecord)) {
38
+ return null;
39
+ }
40
+
41
+ // Separate multiple rules with a horizontal rule so they read as distinct docs.
42
+ return rules.map(formatRule).join('\n\n---\n\n');
43
+ };
@@ -0,0 +1,142 @@
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
+
12
+ /**
13
+ * A component result as returned by `searchComponentsTool` / `getAllComponentsTool`.
14
+ * Only the fields the compact view needs are modelled; others are ignored.
15
+ */
16
+
17
+ /**
18
+ * A token result as returned by `searchTokensTool` / `getAllTokensTool`.
19
+ */
20
+
21
+ /**
22
+ * An icon result as returned by `searchIconsTool` / `getAllIconsTool`.
23
+ */
24
+
25
+ /**
26
+ * Count helper that is safe against non-array / missing fields.
27
+ */
28
+ const countOf = value => Array.isArray(value) ? value.length : 0;
29
+
30
+ /**
31
+ * Pluralise a `count`-prefixed noun, e.g. `1 prop` / `2 props`.
32
+ */
33
+ const pluralize = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
34
+
35
+ /**
36
+ * Truncate a one-line description so compact rows stay on a single line.
37
+ */
38
+ const truncate = (text, max = 80) => text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
39
+
40
+ /**
41
+ * Append a `→ ads-cli <command> <name>` drill-in hint beneath a row.
42
+ *
43
+ * Only used in unified `search`, where a row is one of many mixed results and the natural next
44
+ * step is to view that one in full. Single-kind listings (`--all`, `--type`) omit it — you asked
45
+ * for the whole list, so echoing each row's own name back would just be noise.
46
+ */
47
+ const withFollowUp = ({
48
+ line,
49
+ command,
50
+ name,
51
+ showFollowUp
52
+ }) => showFollowUp ? `${line}\n → ads-cli ${command} ${name}` : line;
53
+
54
+ /**
55
+ * Render one component as a compact line.
56
+ *
57
+ * No `[kind]` tag is added: every caller renders a single kind at a time — a single-kind command
58
+ * (`--all`, `--type`) or a titled section of grouped `search` — so the kind is always clear from
59
+ * context and a tag would just be noise.
60
+ */
61
+ const formatComponentLine = (component, showFollowUp) => {
62
+ var _component$name;
63
+ const name = (_component$name = component.name) !== null && _component$name !== void 0 ? _component$name : '(unknown)';
64
+ const pkg = component.package ? ` ${component.package}` : '';
65
+ const propCount = countOf(component.props);
66
+ const exampleCount = countOf(component.examples);
67
+ const meta = [pluralize(propCount, 'prop'), pluralize(exampleCount, 'example')].join(', ');
68
+ return withFollowUp({
69
+ line: `${name}${pkg} (${meta})`,
70
+ command: 'component',
71
+ name,
72
+ showFollowUp
73
+ });
74
+ };
75
+
76
+ /**
77
+ * Render one token as a compact `name = value` line.
78
+ */
79
+ const formatTokenLine = (tokenResult, showFollowUp) => {
80
+ var _tokenResult$name;
81
+ const name = (_tokenResult$name = tokenResult.name) !== null && _tokenResult$name !== void 0 ? _tokenResult$name : '(unknown)';
82
+ // Some token values (e.g. motion easing curves) are very long; truncate so each token stays
83
+ // on a single readable line. The full value is always available via `--json`.
84
+ const line = tokenResult.exampleValue ? `${name} = ${truncate(tokenResult.exampleValue)}` : name;
85
+ return withFollowUp({
86
+ line,
87
+ command: 'token',
88
+ name,
89
+ showFollowUp
90
+ });
91
+ };
92
+
93
+ /**
94
+ * Render one icon as a compact line with its import package and short usage note.
95
+ */
96
+ const formatIconLine = (iconResult, showFollowUp) => {
97
+ var _iconResult$component;
98
+ const name = (_iconResult$component = iconResult.componentName) !== null && _iconResult$component !== void 0 ? _iconResult$component : '(unknown)';
99
+ const pkg = iconResult.package ? ` ${iconResult.package}` : '';
100
+ const usage = iconResult.usage ? ` — ${truncate(iconResult.usage)}` : '';
101
+ return withFollowUp({
102
+ line: `${name}${pkg}${usage}`,
103
+ command: 'icon',
104
+ name,
105
+ showFollowUp
106
+ });
107
+ };
108
+
109
+ /**
110
+ * Render an array of results as compact lines for the given kind. Returns `null` when the data
111
+ * is not an array (so the caller can fall back to generic JSON rendering).
112
+ *
113
+ * `showFollowUp` (default `false`) adds a `→ ads-cli <command> <name>` drill-in hint beneath each
114
+ * row. It is enabled only by unified `search`; single-kind listings (`--all`, `--type`) leave it
115
+ * off so the output stays terse.
116
+ */
117
+ export const formatCompactResults = ({
118
+ kind,
119
+ data,
120
+ showFollowUp = false
121
+ }) => {
122
+ if (!Array.isArray(data)) {
123
+ return null;
124
+ }
125
+ if (data.length === 0) {
126
+ return 'No results.';
127
+ }
128
+ const lines = data.map(entry => {
129
+ switch (kind) {
130
+ case 'components':
131
+ return formatComponentLine(entry, showFollowUp);
132
+ case 'tokens':
133
+ return formatTokenLine(entry, showFollowUp);
134
+ case 'icons':
135
+ return formatIconLine(entry, showFollowUp);
136
+ default:
137
+ return JSON.stringify(entry);
138
+ }
139
+ });
140
+ const header = `Results (${data.length}):`;
141
+ return [header, '', ...lines].join('\n');
142
+ };