@finedesign/cli 0.7.0 → 0.8.1

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,17 +2,15 @@
2
2
  "schemaVersion": 1,
3
3
  "version": "1.25.0",
4
4
  "sourceKind": "repository-snapshot",
5
- "sourceRevision": "1c7c921d638a7db72b10c53b264eb2b0a0c3ec9c",
5
+ "sourceRevision": "92a59ee18e00b27b76e666638c27534e2f3be53a",
6
6
  "sourceDirty": false,
7
- "contentHash": "556790f5c8bb8d702b3db8b5fe8925560bcdad642eb4f28de32d74b8e800401a",
8
- "catalogSha256": "66c94445015341755aebe2a51e2947a4c3a76f796718f337f0eb1a5a81c56fbc",
7
+ "contentHash": "4bbd31b489ef7fbe290d88499038147053f7dd148a502ba5553e6bf1dce6b7f7",
8
+ "catalogSha256": "118ce4717d01727ee24291b62aa06ee1740cbd129bebb18734fbcaa4e1b045e3",
9
9
  "skillFiles": {
10
- "references/component-guide.md": "a91d47075e1c9fc90e8c4a5160e645a4d6ba7d12903688014cd1a22b0c5ef627",
10
+ "references/component-guide.md": "e48d32c664034bae5cf3aaf2d8c294f99e3374645e2b8482844e79e82b8548b6",
11
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
- "references/imports-and-setup.md": "12278a80918a003a2285da510a77e77521a2771d47ae7bd0c8ea3f9a181d8398",
13
- "references/standalone-task-page.md": "97f05c06e1a4e7a9517d53ed6a358d9515d799e1b8c8731cbd50ccf060f3eaea",
14
- "references/task-list.js": "8e9f7daea7b8a003b0eb4cc1fc510b4a2d37f6812c846c882c01fa23be5adf19",
12
+ "references/imports-and-setup.md": "012baad54842ba16f4b770295f3f9beabcd090ecbcee78dade9c663e740edd3c",
15
13
  "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
16
- "SKILL.md": "ad0bb8cf8a588b28e06a2a786483cb54124198a1e2bdf2e99a4c178147cd7968"
14
+ "SKILL.md": "e1024432c8b37d88057cfd851d40d3f1747b8b0354d12f9c4d510810757d62c8"
17
15
  }
18
16
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
4
4
  "description": "Versioned Fine Design docs, code checks and agent setup for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -31,5 +31,4 @@ Use the project-local `npx fine-design` when installed, otherwise the global `fi
31
31
  | Condition | Reference |
32
32
  | --- | --- |
33
33
  | Version mismatch, installation failures, unavailable docs, imports, or standalone setup | [imports-and-setup.md](references/imports-and-setup.md) |
34
- | New standalone table with filters, pagination and draft editing, or offline runtime export | [standalone-task-page.md](references/standalone-task-page.md) |
35
34
  | Theme, dark mode, or scoped themes | [theme-and-dark-mode.md](references/theme-and-dark-mode.md) |
@@ -67,6 +67,6 @@ render: (_value, record) => {
67
67
  - Verify affected behavior: change a filter from a later page; cancel then confirm removal; submit an invalid draft; cancel an edit; save and reopen another row. Choose checks for the actual change rather than testing every example.
68
68
  - Check business wording against actual predicates (calendar week versus rolling days), ensure actions report real results, and verify keyboard access to filters, cards and actions. New multi-project records must select or inherit the intended project. CLI lint does not verify these business contracts.
69
69
 
70
- For standalone HTML, see the bundled [task page](standalone-task-page.md). Use shared semantic tokens for page surfaces/text instead of recoloring every component; select exact theme tokens through `token` when needed.
70
+ Use shared semantic tokens for page surfaces/text instead of recoloring every component; select exact theme tokens through `token` when needed.
71
71
 
72
72
  For full page patterns in this repository, consult `playground/product-list/index.tsx`. Outside it, reuse local project examples. These are references, not dependencies for single-file outputs.
@@ -56,7 +56,7 @@ Run `npx -y @finedesign/cli runtime list --format json` first and check its exit
56
56
  3. The host retains only the current release files. Old URLs may disappear on upgrade; save matching resources yourself for long-lived standalone pages. Do not claim historical runtime availability from the CLI's offline catalog.
57
57
  4. If the manifest cannot be retrieved, report the failure and use an explicitly selected verified host or previously saved matching resources. The old unversioned website resources have been removed; do not fall back to them or substitute another component version.
58
58
 
59
- For offline or CSP-restricted previews, use `fine-design runtime --fd-version <exact-version> --output ./demo` with a new destination directory. `--dry-run --format json` previews file paths. The export verifies sizes/SHA-256 before writing local resources, preserves SRI and records their remote provenance in `runtime-lock.json`; it also includes a working [task page](standalone-task-page.md). Initial export needs network access; subsequent pages reference only local resources. The host must still permit page scripts/styles. Existing destinations are rejected rather than overwritten.
59
+ For offline or CSP-restricted previews, use `fine-design runtime --fd-version <exact-version> --output ./demo` with a new destination directory. `--dry-run --format json` previews file paths. The export verifies sizes/SHA-256 before writing local resources, preserves SRI and records their remote provenance in `runtime-lock.json`. Initial export needs network access; subsequent pages reference only local resources. The host must still permit page scripts/styles. Existing destinations are rejected rather than overwritten.
60
60
 
61
61
  Load `fineDesignCss`, then `react`, `reactDOM`, `fineDesign`. Pin exact URLs and integrity in generated HTML and use `crossorigin="anonymous"`; the host must provide CORS. Do not drop SRI from a selected versioned runtime to hide an error. Avoid async scripts and conflicting second React instances. If an embedding host lacks compatible React globals, use a separate document/iframe.
62
62
 
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) {