@finedesign/cli 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,138 @@
1
+ import fs from 'node:fs';
2
+ import { ToolError } from './errors.mjs';
3
+
4
+ const figmaData = JSON.parse(fs.readFileSync(new URL('./figma-data.json', import.meta.url), 'utf8'));
5
+
6
+ export function normalizeNodeId(nodeId) {
7
+ if (!nodeId || typeof nodeId !== 'string') return null;
8
+ const trimmed = nodeId.trim();
9
+ const match = trimmed.match(/^(\d+)[:-](\d+)$/);
10
+ return match ? `${match[1]}:${match[2]}` : null;
11
+ }
12
+
13
+ export function parseFigmaUrl(value) {
14
+ try {
15
+ const url = new URL(value);
16
+ if (!['http:', 'https:'].includes(url.protocol) || !['figma.com', 'www.figma.com'].includes(url.hostname)) return null;
17
+ const path = url.pathname.match(/^\/(?:design|file)\/([a-z\d]+)(?:\/branch\/([a-z\d]+))?(?:\/|$)/i);
18
+ if (!path) return null;
19
+ return { fileKey: path[2] || path[1], nodeId: normalizeNodeId(url.searchParams.get('node-id')) };
20
+ } catch {
21
+ return null;
22
+ }
23
+ }
24
+
25
+ function matchedResult(match, query) {
26
+ return {
27
+ matched: true,
28
+ query,
29
+ component: match.component,
30
+ designName: match.designName,
31
+ nodeId: match.nodeId,
32
+ url: match.url,
33
+ fileKey: figmaData.fileKey,
34
+ codeConnect: {
35
+ templateId: match.templateId,
36
+ templateFile: match.file,
37
+ source: match.source,
38
+ imports: match.imports,
39
+ connectedComponent: match.connectedComponent,
40
+ wrapperSignature: match.wrapperSignature,
41
+ shortcut: match.shortcut,
42
+ businessInputs: match.businessInputs,
43
+ exampleSnippet: match.exampleSnippet,
44
+ exampleNodeId: match.exampleNodeId,
45
+ exampleImports: match.exampleImports
46
+ },
47
+ designProperties: match.properties,
48
+ recommendations: match.recommendations,
49
+ apiDocHint: `fine-design info ${match.component.split('.')[0]}`
50
+ };
51
+ }
52
+
53
+ export function resolveFigmaComponent(input = {}) {
54
+ const target = (input.target || input.url || input.nodeId || input.component || '').trim();
55
+ if (!target) {
56
+ throw new ToolError('INVALID_ARGUMENT', 'Target URL, node ID, or component name is required.', 2);
57
+ }
58
+
59
+ const isUrl = (!input.target && !!input.url) || /^[a-z][a-z\d+.-]*:\/\//i.test(target);
60
+ const url = isUrl ? parseFigmaUrl(target) : null;
61
+ if (isUrl && url?.fileKey !== figmaData.fileKey) {
62
+ return {
63
+ matched: false,
64
+ query: { input: target },
65
+ message: `Use a Figma design or file URL from the Fine Design library (${figmaData.fileKey}). For a project design, use Figma MCP to locate the library's main component first.`
66
+ };
67
+ }
68
+ const nodeId = isUrl ? url.nodeId : normalizeNodeId(target);
69
+ if (isUrl || nodeId || (!input.target && input.nodeId)) {
70
+ const query = { input: target, nodeId };
71
+ const match = figmaData.mappings.find((m) => m.nodeId === nodeId);
72
+ if (match) return matchedResult(match, query);
73
+ return {
74
+ matched: false,
75
+ query,
76
+ message: 'No mapped library node found. Use Figma MCP to locate the main component for a page, instance or variant, then query its URL or node ID.'
77
+ };
78
+ }
79
+
80
+ const searchName = target.toLowerCase().replace(/[-_\s]/g, '');
81
+ const canonicalName = (Object.hasOwn(figmaData.aliases, searchName) ? figmaData.aliases[searchName] : target).toLowerCase();
82
+
83
+ // Check known unmapped notes
84
+ for (const [unmappedName, note] of Object.entries(figmaData.unmappedNotes)) {
85
+ const unmappedLower = unmappedName.toLowerCase();
86
+ if (unmappedLower === searchName || unmappedLower === canonicalName) {
87
+ return {
88
+ matched: false,
89
+ unmapped: true,
90
+ component: unmappedName,
91
+ note,
92
+ fileKey: figmaData.fileKey,
93
+ apiDocHint: `fine-design info ${unmappedName}`
94
+ };
95
+ }
96
+ }
97
+
98
+ const exact = figmaData.mappings.filter((m) => m.component.toLowerCase() === canonicalName);
99
+ const primaryNodeId = figmaData.primaryLinks[exact[0]?.component];
100
+ const matchedEntry = exact.find((m) => m.nodeId === primaryNodeId) ?? exact[0]
101
+ ?? figmaData.mappings.find((m) => m.component.toLowerCase().replace(/[-_\s.]/g, '') === searchName)
102
+ ?? (searchName && figmaData.mappings.find((m) => m.designName.toLowerCase().includes(searchName) || m.component.toLowerCase().includes(searchName)));
103
+ if (matchedEntry) {
104
+ return matchedResult(matchedEntry, { input: target, component: matchedEntry.component });
105
+ }
106
+
107
+ // Suggestions when not matched
108
+ const suggestions = figmaData.mappings
109
+ .filter((m) => searchName && m.component.toLowerCase().includes(searchName.slice(0, 3)))
110
+ .map((m) => `${m.component} (${m.designName})`)
111
+ .slice(0, 5);
112
+
113
+ return {
114
+ matched: false,
115
+ query: { input: target },
116
+ message: `No matching Fine Design component found for "${target}".`,
117
+ ...(suggestions.length ? { suggestions } : {})
118
+ };
119
+ }
120
+
121
+ export function listFigmaComponents() {
122
+ return {
123
+ total: figmaData.mappings.length,
124
+ fileKey: figmaData.fileKey,
125
+ indexNodeId: figmaData.indexNodeId,
126
+ components: figmaData.mappings.map((m) => ({
127
+ component: m.component,
128
+ designName: m.designName,
129
+ nodeId: m.nodeId,
130
+ url: m.url,
131
+ templateId: m.templateId,
132
+ templateFile: m.file,
133
+ imports: m.imports,
134
+ shortcut: m.shortcut,
135
+ businessInputs: m.businessInputs
136
+ }))
137
+ };
138
+ }
package/src/mcp.mjs CHANGED
@@ -29,7 +29,9 @@ export async function startMcp() {
29
29
  lint_files: 'Scan code for Fine Design API traps. Pass an exact version if it cannot be detected from the targets.',
30
30
  get_component_example: 'List example IDs and titles, or pass exampleId to read source, dependencies and asset metadata. Version is optional. Set includeAssets with exampleId to include large assets.',
31
31
  list_browser_runtimes: 'Read the one currently hosted UMD version from its online manifest. Requires network access.',
32
- get_browser_runtime: 'Resolve a component version to versioned current UMD URLs and SRI loading tags. Version is optional (defaults to hosted version). Requires network access; never falls back to another version.'
32
+ get_browser_runtime: 'Resolve a component version to versioned current UMD URLs and SRI loading tags. Version is optional (defaults to hosted version). Requires network access; never falls back to another version.',
33
+ resolve_figma_component: 'Look up a Fine Design library node URL, library node ID, or component name in the offline Code Connect snapshot. Use Figma MCP first for page, frame, or instance links.',
34
+ list_figma_components: 'List all Figma-connected Fine Design components, node IDs, and Code Connect template IDs.'
33
35
  };
34
36
  server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: Object.entries(schemas).map(([name, schema]) => ({
35
37
  name, description: descriptions[name], inputSchema: z.toJSONSchema(schema, { target: 'draft-07' }),
@@ -61,6 +63,12 @@ export async function startMcp() {
61
63
  const version = resolveLintVersion(args.version, targets);
62
64
  const { lintFiles } = await import('./core/lint.mjs');
63
65
  result = lintFiles(loadCatalog(version), targets);
66
+ } else if (toolName === 'resolve_figma_component') {
67
+ const { resolveFigmaComponent } = await import('./core/figma.mjs');
68
+ result = resolveFigmaComponent(args);
69
+ } else if (toolName === 'list_figma_components') {
70
+ const { listFigmaComponents } = await import('./core/figma.mjs');
71
+ result = listFigmaComponents();
64
72
  } else {
65
73
  const ver = resolveMcpVersion(args.version);
66
74
  result = queryCatalog(loadCatalog(ver), toolName, { ...args, version: ver });