@finedesign/cli 0.3.1 → 0.5.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.
@@ -2,15 +2,15 @@
2
2
  "schemaVersion": 1,
3
3
  "version": "1.25.0",
4
4
  "sourceKind": "repository-snapshot",
5
- "sourceRevision": "39a9955314410af35f1b6096076dcbdf2cc45e9a",
5
+ "sourceRevision": "84cfbf3fb12672498c0a32d0374c9f88a22351ba",
6
6
  "sourceDirty": false,
7
- "contentHash": "30d2e3ea566ad4fd5eed2f53b6cae59de2030db49d2f90eb81b20b3d85e66e4e",
8
- "catalogSha256": "67db385543fa667b5a81b70f4fe35a01a7d8b2bdc8c7a559ced808babd88c7b0",
7
+ "contentHash": "b7a05ed31474496a1ffdc750cc738b1ad034578a4a828cfe03127520d791bafb",
8
+ "catalogSha256": "8320b9ad699b658b483a1df4992126e9a54f67b3890c2746b6ce7b97862c26fb",
9
9
  "skillFiles": {
10
10
  "references/component-guide.md": "612948840948e65f250998231eaa16fc41e8e27b9c03b19af32571422ca8185a",
11
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
- "references/imports-and-setup.md": "5bd9024770a77ddeb0f4dce94ebd103f327c2513b52f165e371da9c4dbdcd98f",
12
+ "references/imports-and-setup.md": "9a404ad7243f0fa734d34c5fd0106287ededf36bbc1693812917ce9cb9780e40",
13
13
  "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
14
- "SKILL.md": "b8ef63aa9aef7cf6cb8f83556b6c09760fc4707f0466d25eb1fac8f2fed6b2a9"
14
+ "SKILL.md": "512ecee9c5208436cda70c56cd691354ab83e2d85115c4bc6f3c1e0658e458ba"
15
15
  }
16
16
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.3.1",
3
+ "version": "0.5.0",
4
4
  "description": "Read-only, versioned Fine Design documentation for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -13,9 +13,9 @@ Use `/fine-design` for component pages, fixes, and reviews. This folder guides A
13
13
 
14
14
  1. Identify the deliverable and runtime: existing package-based project, standalone browser page, fix, or read-only review. Standalone HTML and embedded pages may use the public CDN runtime without npm or private-registry credentials. Preserve compatible existing components and explicit user choices; follow [imports-and-setup.md](references/imports-and-setup.md) for runtime selection.
15
15
  2. In a package-based project, resolve Fine Design and React versions from installed packages or the lockfile; in this repository use the checked-out package and sources. In browser mode, use the selected runtime manifest and its compatibility evidence rather than requiring an installed package. State unknown versions instead of inventing them or upgrading dependencies to fit examples.
16
- 3. When matching-version data is available, prefer the connected Fine Design MCP tools; otherwise use the local `fine-design` CLI with `--format json` and the exact target component version. Query only the components and examples needed (`list`, `search`, `info <component>` for API tables, `token [component]` for Design Tokens, `doc <component> --toc`, `example <component> <id>`). Check the installed tool's help before using optional commands such as `doctor`, `info`, `token`, `lint`, `diff`, or `doc --toc`; older releases do not provide them. If the version is unknown or unsupported, use matching local documentation/public declarations or verify browser exports and behavior; do not substitute another catalog version. Resolve website pages through [docs-slug-map.md](references/docs-slug-map.md), with remaining compatibility gaps stated.
17
- 4. For ordinary component work, read the relevant sections of [component-guide.md](references/component-guide.md). Consult other references only for the conditions below.
18
- 5. Run the existing build/type check appropriate to the change (plus `fine-design lint <file>` when available) and verify an affected interaction with local test data. Fix introduced failures and recheck. Report actual results and unverified behavior; reviews remain read-only.
16
+ 3. Query only the components needed at the exact target version. Prefer connected Fine Design MCP tools when matching-version data is available, or use the local CLI with `--format json`. Start with `info <component>` or `doc <component> --toc`. Fetch `example <component> <id>` source only when needed. Use `search` for unknown component names and `token` for theming. Check the installed CLI's help for supported commands. If the version is unknown or unsupported, consult matching local declarations/docs or verify browser exports and behavior. Resolve website pages through [docs-slug-map.md](references/docs-slug-map.md).
17
+ 4. Use the relevant sections of [component-guide.md](references/component-guide.md) for component selection and API traps. Consult other references only for the conditions below.
18
+ 5. Run the existing build/type check (plus `fine-design lint <file>` when available) and verify the affected interaction with local test data. Report verified and unverified behavior. Reviews remain read-only.
19
19
 
20
20
  ## Core Contracts
21
21
 
@@ -2,7 +2,9 @@
2
2
 
3
3
  ## Version And Compatibility
4
4
 
5
- - Choose the runtime first: reuse package imports in an existing React project; use browser/CDN scripts for a requested standalone HTML or embedded page. A missing project `.npmrc` alone does not decide the runtime.
5
+ - Use the private `@fx-ui/fine-design` package for React projects with a build step and a lockfile. Reuse the project's component version, imports and stylesheet setup.
6
+ - Use the public UMD files for a standalone HTML deliverable, a no-build embed or a browser prototype. If a standalone page must keep a version long term, host the complete matching resource set yourself and keep its SRI checks.
7
+ - Use the public `@finedesign/cli` or its MCP for API lookup and lint. An explicit supported version allows queries before either component runtime is installed. A missing project `.npmrc` alone does not decide the runtime.
6
8
  - For package imports, resolve Fine Design, React, and ReactDOM versions from installed packages or the lockfile; a `package.json` range is not an exact version. For browser scripts, use the runtime manifest described below; no local npm installation is required.
7
9
  - In the Fine Design repository, use the checked-out docs, exports, and demos. In consuming projects, prefer matching-version docs and verify uncertain APIs against installed public declarations/exports. Current website content and skill defaults must not override that contract.
8
10
  - If docs are unavailable, use matching local declarations and examples; inspect only unresolved implementation details. State remaining uncertainty. Do not upgrade dependencies merely to fit an example, or infer full React-major compatibility from a permissive peer range.
package/src/cli.mjs CHANGED
@@ -3,11 +3,11 @@ import path from 'node:path';
3
3
  import { fileURLToPath } from 'node:url';
4
4
  import { parseArgs } from 'node:util';
5
5
  import { queryCatalog, getComponentInfo, getComponentTokens, diffCatalogs } from './core/catalog.mjs';
6
+ import { validateInput } from './core/contracts.mjs';
6
7
  import { loadCatalog, readIndex } from './core/data.mjs';
7
- import { resolveVersion } from './core/version.mjs';
8
+ import { resolveLintVersion, resolveVersion } from './core/version.mjs';
8
9
  import { ToolError, errorResult } from './core/errors.mjs';
9
10
  import { listRuntimes, resolveRuntime } from './core/runtime.mjs';
10
- import { lintFiles } from './core/lint.mjs';
11
11
  import html from './core/html.cjs';
12
12
 
13
13
  const help = `Usage: fine-design <command> [arguments] [options]
@@ -18,7 +18,7 @@ Commands:
18
18
  info <component> Show component overview and API/props sections
19
19
  doc <component> Read component documentation
20
20
  token [component] [query] Inspect component or global Design Tokens
21
- example <component> <id> Read source files and asset metadata
21
+ example <component> [id] List examples or read one example's source and asset metadata
22
22
  lint [files-or-dirs...] Scan code for Fine Design API traps and invalid imports
23
23
  diff [fromVer] [toVer] Compare component changes and migrations between versions
24
24
  doctor Inspect detected version, available catalogs and bundled Skill
@@ -28,13 +28,14 @@ Commands:
28
28
  Options:
29
29
  --fd-version <version> Exact Fine Design component version
30
30
  --project <directory> Project used to detect the installed version
31
+ --component <name> Compare only this component (diff command only)
31
32
  --runtime-url <url> Runtime hosting base URL (runtime command only)
32
33
  --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
33
34
  --section <heading> Doc section heading (exact or case-insensitive)
34
35
  --toc, --summary Show only doc metadata, section headings and example IDs
35
36
  --offset <number> Search pagination offset
36
37
  --limit <number> Search page size (1..200, default 20)
37
- --include-assets Include binary base64 and oversized JSON fixture content
38
+ --include-assets Include binary base64 and oversized JSON fixtures (requires example ID)
38
39
  --help Show help
39
40
  --version Show tool version`;
40
41
 
@@ -85,7 +86,7 @@ export async function main(argv) {
85
86
  help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
86
87
  format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
87
88
  offset: { type: 'string' }, limit: { type: 'string' }, 'include-assets': { type: 'boolean' },
88
- 'runtime-url': { type: 'string' }
89
+ 'runtime-url': { type: 'string' }, component: { type: 'string' }
89
90
  }});
90
91
  format = values.format || 'text';
91
92
  if (!['text', 'json', 'markdown', 'html'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
@@ -95,6 +96,7 @@ export async function main(argv) {
95
96
  if (command === 'mcp' && args.length === 0 && argv.length === 1) { await (await import('./mcp.mjs')).startMcp(); return; }
96
97
  const summaryFlag = Boolean(values.toc || values.summary);
97
98
  if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 2);
99
+ if (command !== 'diff' && values.component !== undefined) throw new ToolError('INVALID_ARGUMENT', '--component is only supported for diff.', 2);
98
100
  if (format === 'markdown' && !['doc', 'info', 'token'].includes(command)) {
99
101
  throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info and token commands.', 2);
100
102
  }
@@ -216,8 +218,12 @@ export async function main(argv) {
216
218
  if (values.version || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || !['text', 'json'].includes(format)) {
217
219
  throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design lint [files-or-dirs...] [--format text|json]', 2);
218
220
  }
219
- const version = resolveVersion(values['fd-version'], values.project);
220
- const report = lintFiles(loadCatalog(version), args.length ? args : [values.project || process.cwd()]);
221
+ const targets = args.length ? args : [values.project || '.'];
222
+ const version = values.project === undefined
223
+ ? resolveLintVersion(values['fd-version'], targets)
224
+ : resolveVersion(values['fd-version'], values.project);
225
+ const { lintFiles } = await import('./core/lint.mjs');
226
+ const report = lintFiles(loadCatalog(version), targets);
221
227
  if (format === 'json') {
222
228
  console.log(JSON.stringify(report));
223
229
  } else if (!report.diagnostics.length) {
@@ -232,23 +238,29 @@ export async function main(argv) {
232
238
  }
233
239
  if (command === 'diff') {
234
240
  if (values.version || args.length > 2 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || !['text', 'json'].includes(format)) {
235
- throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design diff [fromVersion] [toVersion] [--format text|json]', 2);
241
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design diff [fromVersion] [toVersion] [--component <name>] [--format text|json]', 2);
236
242
  }
243
+ const { component } = validateInput('diff_catalogs', { component: values.component });
237
244
  const available = Object.keys(readIndex().versions).sort();
238
245
  const fromVer = args[0] || available[0];
239
246
  const toVer = args[1] || available.at(-1);
240
- const result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer));
247
+ const result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer), component);
241
248
  if (format === 'json') {
242
249
  console.log(JSON.stringify(result));
243
250
  } else {
244
251
  console.log([
245
- `Fine Design ${result.fromVersion} -> ${result.toVersion}`,
252
+ `Fine Design ${result.fromVersion} -> ${result.toVersion}${result.component ? ` (${result.component})` : ''}`,
246
253
  `Added components (${result.addedComponents.length}): ${result.addedComponents.map((c) => `${c.exports.join('/')} (${c.id})`).join(', ') || 'none'}`,
247
254
  `Removed components (${result.removedComponents.length}): ${result.removedComponents.map((c) => `${c.exports.join('/')} (${c.id})`).join(', ') || 'none'}`,
248
255
  `Updated components (${result.updatedComponents.length}):`,
249
- ...result.updatedComponents.map((c) => ` - ${c.exports.join('/')} (${c.id}):${c.addedSections.length ? ` +sections [${c.addedSections.join(', ')}]` : ''}${c.addedExamples.length ? ` +examples [${c.addedExamples.map((e) => e.id).join(', ')}]` : ''}${c.addedAliases?.length ? ` +aliases [${c.addedAliases.join(', ')}]` : ''}`),
250
- `Recommended migrations:`,
251
- ...result.migrations.map((m) => ` - ${m.legacy} -> ${m.recommended}: ${m.note}`)
256
+ ...result.updatedComponents.map(({ id, exports, ...changes }) => {
257
+ const details = Object.entries(changes).filter(([, items]) => items.length).map(([key, items]) => {
258
+ const label = key.replace(/[A-Z]/g, (letter) => ` ${letter.toLowerCase()}`);
259
+ return ` ${label}: ${items.map((item) => item.id ?? item).join(', ')}`;
260
+ });
261
+ return [` - ${exports.join('/')} (${id})`, ...details].join('\n');
262
+ }),
263
+ ...(result.migrations.length ? ['Recommended migrations:', ...result.migrations.map((m) => ` - ${m.legacy} -> ${m.recommended}: ${m.note}`)] : [])
252
264
  ].join('\n'));
253
265
  }
254
266
  return;
@@ -259,12 +271,12 @@ export async function main(argv) {
259
271
  values.version ||
260
272
  (command === 'search' && args.length > 1) ||
261
273
  (command === 'doc' && args.length !== 1) ||
262
- (command === 'example' && args.length !== 2) ||
274
+ (command === 'example' && (args.length < 1 || args.length > 2)) ||
263
275
  (values.section !== undefined && command !== 'doc') ||
264
276
  ((values.toc !== undefined || values.summary !== undefined) && command !== 'doc') ||
265
277
  (values.section !== undefined && summaryFlag) ||
266
278
  ((values.offset !== undefined || values.limit !== undefined) && command !== 'search') ||
267
- (values['include-assets'] !== undefined && command !== 'example')
279
+ (values['include-assets'] !== undefined && (command !== 'example' || args.length !== 2))
268
280
  ) {
269
281
  throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
270
282
  }
@@ -286,7 +298,6 @@ export async function main(argv) {
286
298
  ...(command === 'example' && { exampleId: args[1], ...(values['include-assets'] !== undefined && { includeAssets: values['include-assets'] }) })
287
299
  })
288
300
  };
289
- const { validateInput } = await import('./core/contracts.mjs');
290
301
  validateInput(tools[command], input);
291
302
  const result = queryCatalog(loadCatalog(version), tools[command], input);
292
303
  if (format === 'json') {
@@ -326,6 +337,11 @@ ${result.sections ? `Sections: ${result.sections.join(', ') || 'none'}\n` : ''}E
326
337
  ...(result.suggestions || [])
327
338
  ];
328
339
  console.log(lines.join('\n'));
340
+ } else if (args[1] === undefined) {
341
+ console.log([
342
+ `Examples for ${result.component} (Fine Design ${result.version}):`,
343
+ ...(result.examples.length ? result.examples.map(({ id, title }) => ` ${id}: ${title}`) : [' none'])
344
+ ].join('\n'));
329
345
  } else {
330
346
  console.log(JSON.stringify(result, null, 2));
331
347
  }
@@ -1,3 +1,4 @@
1
+ import { isDeepStrictEqual } from 'node:util';
1
2
  import { ToolError } from './errors.mjs';
2
3
  import { validateInput } from './contracts.mjs';
3
4
  import { sha256 } from './data.mjs';
@@ -67,10 +68,10 @@ export function suggestSimilarComponents(catalog, rawQuery, limit = 3) {
67
68
  }
68
69
  }
69
70
 
70
- return candidates
71
+ const labels = candidates
71
72
  .sort((a, b) => b.score - a.score || a.label.localeCompare(b.label))
72
- .slice(0, limit)
73
73
  .map((item) => item.label);
74
+ return [...new Set(labels)].slice(0, limit);
74
75
  }
75
76
 
76
77
  function sourceMetadata(catalog) {
@@ -267,9 +268,20 @@ export function queryCatalog(catalog, tool, args) {
267
268
  };
268
269
  }
269
270
  if (tool === 'get_component_example') {
271
+ if (args.exampleId === undefined) {
272
+ return {
273
+ ...source,
274
+ component: component.id,
275
+ examples: component.examples.map(({ id, title }) => ({ id, title }))
276
+ };
277
+ }
270
278
  const example = component.examples.find((item) => item.id === args.exampleId);
271
- if (!example)
272
- throw new ToolError('EXAMPLE_NOT_FOUND', 'Unknown example.', 4, { availableExamples: component.examples.map((item) => item.id) });
279
+ if (!example) {
280
+ throw new ToolError('EXAMPLE_NOT_FOUND', 'Unknown example.', 4, {
281
+ availableExamples: component.examples.map((item) => item.id),
282
+ suggestions: [`Use example ${component.exports[0]} to list available example IDs.`]
283
+ });
284
+ }
273
285
  const files = example.files.map((file) => {
274
286
  if (file.encoding === 'base64') {
275
287
  const { content, ...metadata } = file;
@@ -405,31 +417,62 @@ export function getComponentTokens(catalog, { component: rawComponent, query = '
405
417
  };
406
418
  }
407
419
 
408
- export function diffCatalogs(fromCatalog, toCatalog) {
420
+ function comparableMarkdown(markdown) {
421
+ // Historical catalogs use aligned Markdown tables. Preserve whitespace in fenced examples.
422
+ return markdown.replace(/^(`{3,}|~{3,})[^\r\n]*\r?\n[\s\S]*?^\1[ \t]*$|^\|[^\r\n]*\|$/gm, (line, fence) => {
423
+ if (fence) return line;
424
+ if (/^\|(?:[ \t]*:?-+:?[ \t]*\|)+$/.test(line)) return line.replace(/[ \t]+/g, '').replace(/-+/g, '---');
425
+ return line.replace(/(?<!\\)\|[ \t]+/g, '|').replace(/[ \t]+(?=(?<!\\)\|)/g, '');
426
+ });
427
+ }
428
+
429
+ function sectionContent(sections, name) {
430
+ return sections.filter(({ heading }) => heading === name).map(({ markdown }) => comparableMarkdown(markdown));
431
+ }
432
+
433
+ export function diffCatalogs(fromCatalog, toCatalog, component) {
409
434
  const fromMap = new Map(fromCatalog.components.map((c) => [c.id, c]));
410
435
  const toMap = new Map(toCatalog.components.map((c) => [c.id, c]));
436
+ const componentId = component === undefined ? undefined : resolveComponentOrThrow({
437
+ components: [...toCatalog.components, ...fromCatalog.components]
438
+ }, component).id;
411
439
  const addedComponents = [];
412
440
  const removedComponents = [];
413
441
  const updatedComponents = [];
442
+ const exampleSummary = ({ id, title }) => ({ id, title });
414
443
 
415
444
  for (const [id, comp] of toMap) {
445
+ if (componentId && id !== componentId) continue;
416
446
  if (!fromMap.has(id)) {
417
447
  addedComponents.push({ id, exports: comp.exports, description: comp.description });
418
448
  continue;
419
449
  }
420
450
  const prev = fromMap.get(id);
421
- const prevSections = new Set(prev.sections.map((s) => s.heading));
422
- const addedSections = comp.sections.map((s) => s.heading).filter((h) => !prevSections.has(h));
423
- const prevExamples = new Set(prev.examples.map((e) => e.id));
424
- const addedExamples = comp.examples.filter((e) => !prevExamples.has(e.id)).map((e) => ({ id: e.id, title: e.title }));
425
- const prevAliases = new Set(prev.aliases || []);
426
- const addedAliases = (comp.aliases || []).filter((a) => !prevAliases.has(a));
427
- if (addedSections.length > 0 || addedExamples.length > 0 || addedAliases.length > 0) {
428
- updatedComponents.push({ id, exports: comp.exports, addedSections, addedExamples, addedAliases });
451
+ const prevSections = new Set(prev.sections.map(({ heading }) => heading));
452
+ const nextSections = new Set(comp.sections.map(({ heading }) => heading));
453
+ const prevExamples = new Map(prev.examples.map((example) => [example.id, example]));
454
+ const nextExamples = new Set(comp.examples.map((example) => example.id));
455
+ const prevAliases = prev.aliases || [];
456
+ const nextAliases = comp.aliases || [];
457
+ const changes = {
458
+ addedSections: [...nextSections].filter((heading) => !prevSections.has(heading)),
459
+ removedSections: [...prevSections].filter((heading) => !nextSections.has(heading)),
460
+ // The generated demo index changed format between snapshots; compare the underlying examples below.
461
+ changedSections: [...nextSections].filter((heading) => heading !== '代码演示' && prevSections.has(heading)
462
+ && !isDeepStrictEqual(sectionContent(prev.sections, heading), sectionContent(comp.sections, heading))),
463
+ addedExamples: comp.examples.filter((example) => !prevExamples.has(example.id)).map(exampleSummary),
464
+ removedExamples: prev.examples.filter((example) => !nextExamples.has(example.id)).map(exampleSummary),
465
+ changedExamples: comp.examples.filter((example) => prevExamples.has(example.id)
466
+ && !isDeepStrictEqual(prevExamples.get(example.id), example)).map(exampleSummary),
467
+ addedAliases: nextAliases.filter((alias) => !prevAliases.includes(alias)),
468
+ removedAliases: prevAliases.filter((alias) => !nextAliases.includes(alias))
469
+ };
470
+ if (Object.values(changes).some((items) => items.length)) {
471
+ updatedComponents.push({ id, exports: comp.exports, ...changes });
429
472
  }
430
473
  }
431
474
  for (const [id, comp] of fromMap) {
432
- if (!toMap.has(id)) {
475
+ if ((!componentId || id === componentId) && !toMap.has(id)) {
433
476
  removedComponents.push({ id, exports: comp.exports });
434
477
  }
435
478
  }
@@ -437,13 +480,15 @@ export function diffCatalogs(fromCatalog, toCatalog) {
437
480
  return {
438
481
  fromVersion: fromCatalog.version,
439
482
  toVersion: toCatalog.version,
483
+ ...(componentId ? { component: componentId } : {}),
440
484
  addedComponents,
441
485
  removedComponents,
442
486
  updatedComponents,
443
487
  migrations: [
444
- { legacy: 'Table / DataTable', recommended: 'NextTable', note: 'Use <NextTable> with declarative <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children.' },
445
- { legacy: 'Cascader', recommended: 'MCascader', note: 'Legacy Cascader has no online docs page; prefer MCascader for new pages.' },
446
- { legacy: 'Dialog.onCloseBtnClick', recommended: 'Dialog.onCancel', note: 'onCloseBtnClick is deprecated and fires alongside onCancel when clicking the close button.' }
447
- ]
488
+ { components: ['table', 'data-table', 'next-table'], legacy: 'Table / DataTable', recommended: 'NextTable', note: 'Use <NextTable> with declarative <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children.' },
489
+ { components: ['cascader', 'm-cascader'], legacy: 'Cascader', recommended: 'MCascader', note: 'Legacy Cascader has no online docs page; prefer MCascader for new pages.' },
490
+ { components: ['dialog'], legacy: 'Dialog.onCloseBtnClick', recommended: 'Dialog.onCancel', note: 'onCloseBtnClick is deprecated and fires alongside onCancel when clicking the close button.' }
491
+ ].filter(({ components }) => !componentId || components.includes(componentId))
492
+ .map(({ components, ...migration }) => migration)
448
493
  };
449
494
  }
@@ -16,18 +16,42 @@ export const schemas = {
16
16
  section: z.string().min(1).max(200).optional(),
17
17
  summary: z.boolean().optional().describe('Return only metadata, section headings and example IDs without full markdown.')
18
18
  }).strict(),
19
+ get_component_info: z.object({
20
+ version,
21
+ component
22
+ }).strict(),
23
+ get_component_tokens: z.object({
24
+ version,
25
+ component: component.optional(),
26
+ query: z.string().max(200).optional()
27
+ }).strict(),
28
+ diff_catalogs: z.object({
29
+ version: version.optional(),
30
+ fromVersion: version.optional(),
31
+ toVersion: version.optional(),
32
+ component: component.optional().describe('Limit the comparison to one component, resolved by ID, export or alias.')
33
+ }).strict(),
34
+ lint_files: z.object({
35
+ version: version.optional(),
36
+ paths: z.array(z.string().min(1).max(1024)).optional(),
37
+ files: z.array(z.string().min(1).max(1024)).optional(),
38
+ path: z.string().min(1).max(1024).optional()
39
+ }).strict(),
19
40
  list_browser_runtimes: z.object({ runtimeURL: z.string().max(2048).optional() }).strict(),
20
41
  get_browser_runtime: z.object({ version, runtimeURL: z.string().max(2048).optional() }).strict(),
21
42
  get_component_example: z.object({
22
43
  version,
23
44
  component,
24
- exampleId: z.string().min(1).max(200),
45
+ exampleId: z.string().min(1).max(200).optional().describe('Omit to list available example IDs and titles.'),
25
46
  includeAssets: z.boolean().optional().describe('Include binary asset content as base64 and full oversized JSON fixture content; default returns metadata/preview for large assets.')
26
- }).strict()
47
+ }).strict().refine(({ exampleId, includeAssets }) => exampleId !== undefined || includeAssets === undefined, {
48
+ path: ['includeAssets'],
49
+ message: 'includeAssets requires an example ID.'
50
+ })
27
51
  };
28
52
 
29
53
  export function validateInput(tool, input) {
30
- const result = schemas[tool]?.safeParse(input);
54
+ const result = Object.hasOwn(schemas, tool) ? schemas[tool].safeParse(input) : undefined;
31
55
  if (!result?.success) {
32
56
  throw new ToolError('INVALID_ARGUMENT', result?.error.issues.map((issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`).join('; ') || `Unknown tool: ${tool}`, 2);
33
57
  }
package/src/core/lint.mjs CHANGED
@@ -13,12 +13,13 @@ const KNOWN_TYPE_EXPORTS = new Set([
13
13
  'BadgeProps', 'ButtonGroupProps', 'ButtonHTMLType', 'ButtonProps', 'ButtonSize', 'ButtonType',
14
14
  'CheckGroupDirection', 'CheckGroupProps', 'CheckProps', 'ComboCheckProps',
15
15
  'ComboDropdownAsyncParams', 'ComboDropdownGroupItem', 'ComboDropdownItem', 'ComboProps',
16
- 'DatePickerMode', 'DatePickerProps', 'DatetimeProps', 'DialogAnimation', 'DialogImperativeProps',
17
- 'DialogProps', 'DialogTheme', 'DialogTitleAlign', 'DrawerEdge', 'DrawerPlacement', 'DrawerProps',
18
- 'FileItem', 'FilePreviewActionProps', 'FilePreviewFileActionsRender', 'FilePreviewFileActionsRenderInfo',
19
- 'FilePreviewProps', 'FormItemProps', 'FormLayout', 'FormProps', 'IRuleDescriptor',
20
- 'InputCountConfig', 'InputCountInfo', 'InputProps', 'InputRef', 'InputSize', 'InputState',
21
- 'InputValue', 'TextAreaProps', 'InputNumberControlInfo', 'InputNumberControlTooltip',
16
+ 'CustomSvgIconProps', 'DatePickerMode', 'DatePickerProps', 'DatetimeProps', 'DialogAnimation',
17
+ 'DialogImperativeProps', 'DialogProps', 'DialogTheme', 'DialogTitleAlign', 'DrawerEdge',
18
+ 'DrawerPlacement', 'DrawerProps', 'FileItem', 'FilePreviewActionProps',
19
+ 'FilePreviewFileActionsRender', 'FilePreviewFileActionsRenderInfo', 'FilePreviewProps',
20
+ 'FormItemProps', 'FormLayout', 'FormProps', 'IRuleDescriptor', 'InputCountConfig',
21
+ 'InputCountInfo', 'InputProps', 'InputRef', 'InputSize', 'InputState', 'InputValue',
22
+ 'TextAreaProps', 'InputNumberControlInfo', 'InputNumberControlTooltip',
22
23
  'InputNumberControlTooltipProps', 'InputNumberProps', 'InputNumberRef', 'InputNumberSize',
23
24
  'InputNumberState', 'InputNumberStep', 'InputNumberValidationProps', 'InputNumberValue',
24
25
  'LabelProps', 'ListProps', 'PaginationProps', 'PaginationThemeType', 'RadioGroupDirection',
@@ -42,9 +43,10 @@ const KNOWN_TYPE_EXPORTS = new Set([
42
43
  'DropdownButtonType', 'DropdownProps', 'ImageProps', 'NavigationDividerProps',
43
44
  'NavigationItemGroupProps', 'NavigationItemProps', 'NavigationItemType', 'NavigationProps',
44
45
  'NavigationTheme', 'SubNavigationProps', 'SelectDisplayValueType', 'SelectProps',
45
- 'SliderRangeProps', 'SliderRef', 'SliderSingleProps', 'TreeSelectProps', 'TreeTagProps',
46
- 'TypographyProps', 'TIMEZONE_KEY', 'NextTableCellProps', 'NextTableColumnGroupProps',
47
- 'NextTableColumnProps', 'NextTableHeaderCellProps', 'NextTableProps'
46
+ 'SliderRangeProps', 'SliderRef', 'SliderSingleProps', 'SvgIconProps', 'TreeSelectProps',
47
+ 'TreeTagProps', 'TypographyProps', 'TIMEZONE_KEY', 'NextTableCellProps',
48
+ 'NextTableColumnGroupProps', 'NextTableColumnProps', 'NextTableHeaderCellProps',
49
+ 'NextTableProps'
48
50
  ]);
49
51
 
50
52
  const EXTRA_VALUE_EXPORTS = new Set([
@@ -277,8 +279,11 @@ export function lintFiles(catalog, targets = ['.']) {
277
279
  try {
278
280
  ast = parse(source.content, {
279
281
  sourceType: 'unambiguous', startLine: source.startLine, attachComment: false,
280
- plugins: [...(typescript ? [['typescript', { dts: /\.d\.[cm]?ts$/i.test(file) }]] : []),
281
- ...(!typescript || /tsx$/i.test(file) ? ['jsx'] : [])]
282
+ plugins: [
283
+ 'decorators-legacy',
284
+ ...(typescript ? [['typescript', { dts: /\.d\.[cm]?ts$/i.test(file) }]] : []),
285
+ ...(!typescript || /tsx$/i.test(file) ? ['jsx'] : [])
286
+ ]
282
287
  });
283
288
  } catch (error) {
284
289
  if (!(error instanceof SyntaxError)) throw error;
@@ -36,3 +36,19 @@ export function resolveVersion(explicit, project = process.cwd()) {
36
36
  'Reuse existing npm credentials with --userconfig=/absolute/path/to/.npmrc; configuration may also come from user/global files or environment variables. See README installation troubleshooting.'
37
37
  ] });
38
38
  }
39
+
40
+ export function resolveLintVersion(explicit, targets) {
41
+ if (explicit !== undefined) return explicit;
42
+ const versions = new Set(targets.map((target) => {
43
+ const filename = path.resolve(target);
44
+ const stat = fs.statSync(filename, { throwIfNoEntry: false });
45
+ if (!stat) throw new ToolError('INVALID_ARGUMENT', `Lint target does not exist: ${target}`, 2);
46
+ const resolved = fs.realpathSync(filename);
47
+ return resolveVersion(undefined, stat.isDirectory() ? resolved : path.dirname(resolved));
48
+ }));
49
+ if (versions.size > 1) {
50
+ throw new ToolError('INVALID_ARGUMENT', 'Lint targets use different Fine Design versions. Specify an exact version or lint them separately.', 2);
51
+ }
52
+ const [version] = versions;
53
+ return version;
54
+ }
package/src/mcp.mjs CHANGED
@@ -3,11 +3,19 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
3
3
  import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
4
4
  import fs from 'node:fs';
5
5
  import { z } from 'zod';
6
- import { queryCatalog } from './core/catalog.mjs';
7
- import { loadCatalog } from './core/data.mjs';
6
+ import { queryCatalog, getComponentInfo, getComponentTokens, diffCatalogs } from './core/catalog.mjs';
7
+ import { loadCatalog, readIndex } from './core/data.mjs';
8
8
  import { schemas, validateInput } from './core/contracts.mjs';
9
9
  import { errorResult } from './core/errors.mjs';
10
10
  import { listRuntimes, resolveRuntime } from './core/runtime.mjs';
11
+ import { resolveLintVersion } from './core/version.mjs';
12
+
13
+ const aliases = {
14
+ info: 'get_component_info',
15
+ token: 'get_component_tokens',
16
+ diff: 'diff_catalogs',
17
+ lint: 'lint_files'
18
+ };
11
19
 
12
20
  export async function startMcp() {
13
21
  const packageInfo = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -15,7 +23,11 @@ export async function startMcp() {
15
23
  const descriptions = {
16
24
  search_components: 'Search components, subcomponents and built-in icons; use nextOffset to browse subsequent pages.',
17
25
  get_component_doc: 'Read component documentation, or pass summary: true to list section headings and example IDs first.',
18
- get_component_example: 'Read example source files, dependencies and asset metadata. Set includeAssets to include binary base64 and oversized JSON fixture content.',
26
+ get_component_info: 'Show component overview, exports, aliases and API/props table sections.',
27
+ get_component_tokens: 'Inspect component or global Design Tokens and their default values.',
28
+ diff_catalogs: 'Compare documentation sections, examples, aliases and migration guidance between versions, optionally for one component.',
29
+ lint_files: 'Scan code for Fine Design API traps. Pass an exact version if it cannot be detected from the targets.',
30
+ get_component_example: 'List example IDs and titles, or pass exampleId to read source, dependencies and asset metadata. Set includeAssets with exampleId to include large assets.',
19
31
  list_browser_runtimes: 'Read the one currently hosted UMD version from its online manifest. Requires network access.',
20
32
  get_browser_runtime: 'Resolve an exact component version to versioned current UMD URLs and SRI loading tags. Requires network access; never falls back to another version.'
21
33
  };
@@ -25,9 +37,31 @@ export async function startMcp() {
25
37
  })) }));
26
38
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
27
39
  try {
28
- const { name, arguments: input } = request.params;
29
- const args = validateInput(name, input);
30
- const result = name === 'get_browser_runtime' ? await resolveRuntime(args) : name === 'list_browser_runtimes' ? await listRuntimes(args.runtimeURL) : queryCatalog(loadCatalog(args.version), name, args);
40
+ const { name, arguments: input = {} } = request.params;
41
+ const toolName = Object.hasOwn(aliases, name) ? aliases[name] : name;
42
+ const args = validateInput(toolName, input);
43
+ let result;
44
+ if (toolName === 'get_browser_runtime') {
45
+ result = await resolveRuntime(args);
46
+ } else if (toolName === 'list_browser_runtimes') {
47
+ result = await listRuntimes(args.runtimeURL);
48
+ } else if (toolName === 'get_component_info') {
49
+ result = getComponentInfo(loadCatalog(args.version), args);
50
+ } else if (toolName === 'get_component_tokens') {
51
+ result = getComponentTokens(loadCatalog(args.version), args);
52
+ } else if (toolName === 'diff_catalogs') {
53
+ const available = Object.keys(readIndex().versions).sort();
54
+ const fromVer = args.fromVersion || args.version || available[0];
55
+ const toVer = args.toVersion || available.at(-1);
56
+ result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer), args.component);
57
+ } else if (toolName === 'lint_files') {
58
+ const targets = args.paths?.length ? args.paths : args.files?.length ? args.files : args.path ? [args.path] : ['.'];
59
+ const version = resolveLintVersion(args.version, targets);
60
+ const { lintFiles } = await import('./core/lint.mjs');
61
+ result = lintFiles(loadCatalog(version), targets);
62
+ } else {
63
+ result = queryCatalog(loadCatalog(args.version), toolName, args);
64
+ }
31
65
  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
32
66
  } catch (error) {
33
67
  return { isError: true, content: [{ type: 'text', text: JSON.stringify(errorResult(error)) }] };