@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.
- package/CHANGELOG.md +16 -0
- package/README.md +10 -9
- package/data/1.24.9/catalog.json +1 -1
- package/data/1.24.9/manifest.json +2 -2
- package/data/1.25.0/catalog.json +1 -1
- package/data/1.25.0/manifest.json +5 -5
- package/package.json +1 -1
- package/skills/fine-design/SKILL.md +3 -3
- package/skills/fine-design/references/imports-and-setup.md +3 -1
- package/src/cli.mjs +32 -16
- package/src/core/catalog.mjs +63 -18
- package/src/core/contracts.mjs +27 -3
- package/src/core/lint.mjs +16 -11
- package/src/core/version.mjs +16 -0
- package/src/mcp.mjs +40 -6
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"version": "1.25.0",
|
|
4
4
|
"sourceKind": "repository-snapshot",
|
|
5
|
-
"sourceRevision": "
|
|
5
|
+
"sourceRevision": "84cfbf3fb12672498c0a32d0374c9f88a22351ba",
|
|
6
6
|
"sourceDirty": false,
|
|
7
|
-
"contentHash": "
|
|
8
|
-
"catalogSha256": "
|
|
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": "
|
|
12
|
+
"references/imports-and-setup.md": "9a404ad7243f0fa734d34c5fd0106287ededf36bbc1693812917ce9cb9780e40",
|
|
13
13
|
"references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
|
|
14
|
-
"SKILL.md": "
|
|
14
|
+
"SKILL.md": "512ecee9c5208436cda70c56cd691354ab83e2d85115c4bc6f3c1e0658e458ba"
|
|
15
15
|
}
|
|
16
16
|
}
|
package/package.json
CHANGED
|
@@ -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.
|
|
17
|
-
4.
|
|
18
|
-
5. Run the existing build/type check
|
|
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
|
-
-
|
|
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>
|
|
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
|
|
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
|
|
220
|
-
const
|
|
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((
|
|
250
|
-
|
|
251
|
-
|
|
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
|
|
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
|
}
|
package/src/core/catalog.mjs
CHANGED
|
@@ -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
|
-
|
|
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, {
|
|
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
|
-
|
|
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((
|
|
422
|
-
const
|
|
423
|
-
const prevExamples = new
|
|
424
|
-
const
|
|
425
|
-
const prevAliases =
|
|
426
|
-
const
|
|
427
|
-
|
|
428
|
-
|
|
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
|
}
|
package/src/core/contracts.mjs
CHANGED
|
@@ -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]
|
|
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',
|
|
17
|
-
'DialogProps', 'DialogTheme', 'DialogTitleAlign', 'DrawerEdge',
|
|
18
|
-
'
|
|
19
|
-
'
|
|
20
|
-
'
|
|
21
|
-
'
|
|
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', '
|
|
46
|
-
'
|
|
47
|
-
'
|
|
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: [
|
|
281
|
-
|
|
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;
|
package/src/core/version.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
|
30
|
-
const
|
|
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)) }] };
|