@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.
@@ -2,10 +2,10 @@
2
2
  "schemaVersion": 1,
3
3
  "version": "1.25.0",
4
4
  "sourceKind": "repository-snapshot",
5
- "sourceRevision": "1c7c921d638a7db72b10c53b264eb2b0a0c3ec9c",
5
+ "sourceRevision": "c9d380a665f17001c406dbb081b1fcd91f6befa7",
6
6
  "sourceDirty": false,
7
- "contentHash": "556790f5c8bb8d702b3db8b5fe8925560bcdad642eb4f28de32d74b8e800401a",
8
- "catalogSha256": "66c94445015341755aebe2a51e2947a4c3a76f796718f337f0eb1a5a81c56fbc",
7
+ "contentHash": "b4069c8284ff843f8824b5685dad688e867eb13622832cedc36cfbe48da584a3",
8
+ "catalogSha256": "63de4489e56aaf268d6363a65f35bd57cede27cd679afba7ae45bcc49ae16500",
9
9
  "skillFiles": {
10
10
  "references/component-guide.md": "a91d47075e1c9fc90e8c4a5160e645a4d6ba7d12903688014cd1a22b0c5ef627",
11
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "Versioned Fine Design docs, code checks and agent setup for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
package/src/cli.mjs CHANGED
@@ -25,6 +25,7 @@ Commands:
25
25
  diff [fromVer] [toVer] Compare component changes and migrations between versions
26
26
  doctor Inspect detected version, available catalogs and bundled Skill
27
27
  runtime [list] Resolve a versioned online UMD runtime or list published versions
28
+ figma <resolve|list> [target] Look up Fine Design library nodes or list Code Connect mappings
28
29
  mcp Start the stdio MCP server
29
30
 
30
31
  Options:
@@ -36,7 +37,7 @@ Options:
36
37
  --force Update managed files or overwrite examples (init and add)
37
38
  --dry-run Preview changes without writing (init, add and runtime --output)
38
39
  --runtime-url <url> Runtime hosting base URL (runtime command only)
39
- --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
40
+ --format <text|json|markdown|html> Output format (markdown: doc/info/token/figma; html: runtime)
40
41
  --section <heading> Doc section heading (exact or case-insensitive)
41
42
  --toc, --summary Show only doc metadata, section headings and example IDs
42
43
  --offset <number> Search pagination offset
@@ -322,10 +323,135 @@ export async function main(argv) {
322
323
  if (!['add', 'runtime'].includes(command) && values.output !== undefined) throw new ToolError('INVALID_ARGUMENT', '--output is only supported for add and runtime.', 2);
323
324
  if (!['init', 'add'].includes(command) && values.force !== undefined) throw new ToolError('INVALID_ARGUMENT', '--force is only supported for init and add.', 2);
324
325
  if (!['init', 'add', 'runtime'].includes(command) && values['dry-run'] !== undefined) throw new ToolError('INVALID_ARGUMENT', '--dry-run is only supported for init, add and runtime --output.', 2);
325
- if (format === 'markdown' && !['doc', 'info', 'token'].includes(command)) {
326
- throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info and token commands.', 2);
326
+ if (format === 'markdown' && !['doc', 'info', 'token', 'figma'].includes(command)) {
327
+ throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info, token and figma commands.', 2);
327
328
  }
328
329
  if (format === 'html' && (command !== 'runtime' || args.length)) throw new ToolError('INVALID_ARGUMENT', 'HTML output format is only supported for runtime resolution.', 2);
330
+ if (command === 'figma') {
331
+ const sub = args[0];
332
+ if (!['resolve', 'list'].includes(sub)) {
333
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design figma <resolve|list> [target] [--format text|json|markdown]', 2);
334
+ }
335
+ if (values.version || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || values['fd-version'] !== undefined) {
336
+ throw new ToolError('INVALID_ARGUMENT', 'Invalid options for figma command. Use --help for usage.', 2);
337
+ }
338
+ if (sub === 'list') {
339
+ if (args.length > 1) {
340
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design figma list [--format text|json|markdown]', 2);
341
+ }
342
+ const { listFigmaComponents } = await import('./core/figma.mjs');
343
+ const result = listFigmaComponents();
344
+ if (format === 'json') {
345
+ console.log(JSON.stringify(result));
346
+ } else if (format === 'markdown') {
347
+ const rows = result.components.map((c) => `| \`${c.component}\` | \`${c.designName}\` | \`${c.nodeId}\` | \`${c.templateId}\` |`);
348
+ console.log([
349
+ `# Fine Design 已连接 Figma 组件 (${result.total})`,
350
+ `文件 Key: \`${result.fileKey}\``,
351
+ '',
352
+ '| 组件 | 设计名称 | Node ID | Code Connect ID |',
353
+ '| --- | --- | --- | --- |',
354
+ ...rows
355
+ ].join('\n'));
356
+ } else {
357
+ const lines = result.components.map((c) => ` ${c.component.padEnd(20)} ${c.nodeId.padEnd(16)} ${c.templateId.padEnd(28)} ${c.designName}`);
358
+ console.log([
359
+ `Fine Design Connected Figma Components (${result.total}):`,
360
+ `File Key: ${result.fileKey}`,
361
+ '',
362
+ ...lines
363
+ ].join('\n'));
364
+ }
365
+ return;
366
+ }
367
+ if (sub === 'resolve') {
368
+ if (args.length !== 2) {
369
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design figma resolve <url-or-nodeId-or-component> [--format text|json|markdown]', 2);
370
+ }
371
+ const target = args[1];
372
+ const { resolveFigmaComponent } = await import('./core/figma.mjs');
373
+ const result = resolveFigmaComponent({ target });
374
+ if (format === 'json') {
375
+ console.log(JSON.stringify(result));
376
+ } else if (format === 'markdown') {
377
+ if (result.matched) {
378
+ console.log([
379
+ `# ${result.component} (\`${result.nodeId}\`) - ${result.designName}`,
380
+ `- **Figma URL**: [${result.nodeId}](${result.url})`,
381
+ `- **Code Connect ID**: \`${result.codeConnect.templateId}\` (\`${result.codeConnect.templateFile}\`)`,
382
+ ...(result.codeConnect.shortcut ? [`- **注意项**: ${result.codeConnect.shortcut}`] : []),
383
+ ...(result.codeConnect.businessInputs ? [`- **业务参数**: ${result.codeConnect.businessInputs}`] : []),
384
+ '',
385
+ '## 导入语句',
386
+ '```tsx',
387
+ ...result.codeConnect.imports,
388
+ '```',
389
+ ...(result.codeConnect.wrapperSignature ? ['', '## 包装函数签名', '```ts', result.codeConnect.wrapperSignature, '```'] : []),
390
+ ...(result.codeConnect.exampleSnippet ? [
391
+ '',
392
+ '## 参考示例',
393
+ ...(result.codeConnect.exampleNodeId ? [`采样节点 ${result.codeConnect.exampleNodeId}`] : []),
394
+ '```tsx',
395
+ ...(result.codeConnect.exampleImports ?? []),
396
+ result.codeConnect.exampleSnippet,
397
+ '```'
398
+ ] : []),
399
+ ...(result.recommendations.length ? ['', '## 最佳实践与避坑指引', ...result.recommendations.map((r) => `- ${r}`)] : []),
400
+ '',
401
+ `> 更多组件 API 详情请运行: \`${result.apiDocHint}\``
402
+ ].join('\n'));
403
+ } else if (result.unmapped) {
404
+ console.log([
405
+ `# ${result.component} (未连接组件)`,
406
+ result.note,
407
+ '',
408
+ `> 代码侧请运行: \`${result.apiDocHint}\``
409
+ ].join('\n'));
410
+ } else {
411
+ console.log([
412
+ `# 未找到匹配组件: "${target}"`,
413
+ result.message,
414
+ ...(result.suggestions ? ['', '推荐搜索:', ...result.suggestions.map((s) => `- ${s}`)] : [])
415
+ ].join('\n'));
416
+ }
417
+ } else {
418
+ if (result.matched) {
419
+ const lines = [
420
+ `Component: ${result.component} (${result.designName})`,
421
+ `Figma Node: ${result.nodeId}`,
422
+ `Figma URL: ${result.url}`,
423
+ `Code Connect ID: ${result.codeConnect.templateId} (${result.codeConnect.templateFile})`,
424
+ 'Imports:',
425
+ ...result.codeConnect.imports.map((i) => ` ${i}`),
426
+ ...(result.codeConnect.shortcut ? [`Shortcut: ${result.codeConnect.shortcut}`] : []),
427
+ ...(result.codeConnect.businessInputs ? [`Business Inputs: ${result.codeConnect.businessInputs}`] : []),
428
+ ...(result.codeConnect.wrapperSignature ? ['Wrapper Signature:', ` ${result.codeConnect.wrapperSignature}`] : []),
429
+ ...(result.codeConnect.exampleSnippet ? [
430
+ result.codeConnect.exampleNodeId ? `Reference Example (sample node ${result.codeConnect.exampleNodeId}):` : 'Reference Example:',
431
+ ...(result.codeConnect.exampleImports ?? []).map((line) => ` ${line}`),
432
+ ` ${result.codeConnect.exampleSnippet.split('\n').join('\n ')}`
433
+ ] : []),
434
+ ...(result.recommendations.length ? ['Recommendations:', ...result.recommendations.map((r) => ` - ${r}`)] : []),
435
+ `API Docs: ${result.apiDocHint}`
436
+ ];
437
+ console.log(lines.join('\n'));
438
+ } else if (result.unmapped) {
439
+ console.log([
440
+ `Component: ${result.component} (Unmapped)`,
441
+ `Note: ${result.note}`,
442
+ `API Docs: ${result.apiDocHint}`
443
+ ].join('\n'));
444
+ } else {
445
+ console.log([
446
+ result.message,
447
+ ...(result.suggestions ? ['Suggestions:', ...result.suggestions.map((s) => ` - ${s}`)] : [])
448
+ ].join('\n'));
449
+ }
450
+ }
451
+ if (!result.matched && !result.unmapped) process.exitCode = 1;
452
+ return;
453
+ }
454
+ }
329
455
  if (command === 'runtime') {
330
456
  const list = args.length === 1 && args[0] === 'list';
331
457
  if ((!list && args.length) || values.version || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || (list && (values['fd-version'] !== undefined || values.project !== undefined))) throw new ToolError('INVALID_ARGUMENT', 'Use runtime [list] with --fd-version and --runtime-url as applicable.', 2);
@@ -47,7 +47,16 @@ export const schemas = {
47
47
  }).strict().refine(({ exampleId, includeAssets }) => exampleId !== undefined || includeAssets === undefined, {
48
48
  path: ['includeAssets'],
49
49
  message: 'includeAssets requires an example ID.'
50
- })
50
+ }),
51
+ resolve_figma_component: z.object({
52
+ target: z.string().min(1).max(2048).optional().describe('Fine Design library node URL, library node ID (e.g. 100:4283), or component name'),
53
+ url: z.string().min(1).max(2048).optional().describe('Mapped node URL in the Fine Design library. Use Figma MCP to locate the main component for a page or instance first.'),
54
+ nodeId: z.string().min(1).max(100).optional().describe('Fine Design library node ID (e.g. "100:4283" or "100-4283")'),
55
+ component: z.string().min(1).max(100).optional().describe('Component name (e.g. "Button", "NextTable", "Dialog")')
56
+ }).strict().refine((data) => data.target || data.url || data.nodeId || data.component, {
57
+ message: 'Provide at least one of target, url, nodeId, or component.'
58
+ }),
59
+ list_figma_components: z.object({}).strict()
51
60
  };
52
61
 
53
62
  export function validateInput(tool, input) {